Purpose and Description

In an effort to make PlanetLab easier to use, tha PlanetLab Application Manager is designed to help deploy, monitor, and run applications on PlanetLab. The package gives you the ability to centrally manage, install, upgrade, start, stop, and monitor of applications on a PlanetLab slice. While there are many tools to help install nodes, this package also focuses on monitoring and controlling an installed application.

There are two major components, the server-side and the client-side. The server-side requires access to a PostgreSQL database (with a little work, you could change it to MySQL) and a PHP enabled web server. The primary user interface is via the web. The client-side scripts are all shell scripts that run under bash. The server-side requires little configuration once the pre-requisite software is installed. Unfortunately the client-side shell scripts are more complicated since they require customization.

Installation and customization instructions are included in READMEs in the tar files. This page describes the logical operation of the system, i.e. the rules it enforces/follows, and how to use the web interface

If you would like to use our server-side installation (on appmanager.berkeley.intel-research.net) please contact me at huebsch@cs.berkeley.edu. Please note that we may stop supporting our server-side installation at any time and it comes with zero guarantees.

Live Demo

Download and Installation

To help us understand who is using PIER please complete the following questions (truthfully!):

The server scripts require a web server with PHP to operate! A README file in each download includes instructions for installation and configuration.

Client Operation

Client operation on nodes centers around one script, statusCheck.sh. In the latest release the script will run as a daemon, however it should be executed periodically (by CRON) on each PlanetLab node you are using. It is safe to start multiple instances of the script, all but one will automatically exit. The script is intentionally killed by the install scripts so that it, too, can be upgraded. The script will perform one transaction will the server, it reports its current status and receives instructions on what it should do every so often (as determined by the server) or whenever the local status changes (i.e. the application dies or the build changes).

A node (client) can report its status as either online or offline (There is also states for starting, stopping, and restarting but these are not commonly used. The server can instruct it to go online, offline, hold its current status, or restart. The server can also send parameters which should be passed to the application when starting. If the client can not contact the server, it will act the same as a hold command and try again later.

A second important client script is used for installing nodes. That script will contact the server and retrieve one IP address at a time for a node that requires installation. Multiple instances of the installation script can run simultaneously from one or many machines. Installation includes rsync'ing a directory, setting up crond to start, and installing a cron job for the status script described above.

Server Operation

Most of the node control can be performed through the web interface powered by the server. The server handles the following tasks.

List of PlanetLab Nodes: The server must maintain an accurate list of nodes available on PlanetLab. There are two convenience functions for this purpose:

1. Rebuild Node Listing - The three node-name lists (alpha, beta, and production) from PlanetLab's website are retrieved. Each node-name is resolved to an IP address. If the node-name does not resolve, the name is not added or updated in the database. If the node-name is already in the database, the IP address and node type (production, alpha, beta) designation is updated. If the node is not in the database it is added. If the IP address of the node is already in the database and appears under a different node, the node is ignored and not processed. The node will be eventually added once the other node-name using that IP address changes. At no time do two nodes have the same IP address. Nodes that are not on any of the PlanetLab lists are marked for deletion and are no longer displayed.
2. Remove Old Nodes - Nodes that have been marked for deletion are actually removed from the database. This is a separate step in case the PlanetLab are obviously in error and changes need to be backed out using human intervention.

Dynamic Slice Control: For each application there is a list of nodes being used. In order to actually use the nodes, you must assign those nodes to your slice via the dynamic slice control tools on PlanetLab. The server can automatically do this for you through the PlanetLab's XML-RPC interface. You must supply your clear-text PlanetLab Web site password to use this functionality. The password is NEVER displayed on the website no matter who you are, but is stored in clear-text in the database.

1. Assign Nodes on PLC - This function will first retrieve a list of nodes already assigned to your slice, then find nodes selected for your application and not already assigned. A separate RPC call will then be made to assign any remaining nodes to your slice.
2. UnAssign Nodes on PLC - This is does the reverse of the above function. Technically you will not experience anything bad if you do not execute this function, but you should to remain a community-friendly member of the PlanetLab community and release unused resources.

Software Installation: The server does not directly perform any installations. Instead when a node is due for installation, its IP will be handed out to a client script. The following rules are used to decide whether a node requires installation:

• The node was last successfully installed greater than the Intra-Install Interval.
• The node started but not finished an installation greater than the Max Install Time.
• The last node installed was a failure and occurred more than Min Install Delay ago.
• On the last status check from the node, the node's build number was less than the current build, and it has been longer than Min Install Delay since that last install attempt.
• The node has not reported its status with the past Error Interval and it has been at least Min Install Delay since the last install attempt.
• The node was specifically requested to be installed. (This is the "I" action on the web interface)

Controlling Applications & State of Nodes: Nodes are given instructions every time they contact the server to report their status (Call Home), usually every 5-30 minutes. When they report their status, the database will record the current state (online, offline, etc.) and the build number reported by the node. Users can adjust how often a node calls home through the web interface. It is suggested that during normal operation, you use a call home delay around 20-30 minutes. If you are doing active developement and need to turn nodes on and off with small delays, then a shorter call home delay is appropriate. Regardless of the call home delay, nodes will report their status anytime it changes (up to once a minute using the predefined values). Nodes that do not report within the No Response Interval from when they were expected (last time they called home + call home delay) are considered unresponsive which can indicate they are overloaded or down. If the node does not report within the Error Interval after the expected contact time, the node is considered down.

After recording the current state, the database will then send the node instructions. This includes the requested state, a delay before implementing the change, parameters to pass to the start script if appropriate, and when to next call home. The requested states can be:

• Online (S) - Start if not running
• Offline (K) - Stop
• Restart (R) - Stop then Start
• Hold (H) - Do not change (useful for seeing how long an application can remain in the online state

FAQ