Mark Huang Thierry Parmentelat Princeton University This document describes the design, installation, and administration of MyPLC, a complete PlanetLab Central (PLC) portable installation. This document assumes advanced knowledge of the PlanetLab architecture and Linux system administration. 1.0 April 7, 2006 MLH Initial draft. 1.1 July 19, 2006 MLH Add development environment. 1.2 August 18, 2006 TPT Review section on configuration and introduce plc-config-tty. Present implementation details last. 1.3 May 9, 2008 TPT Review for 4.2 : focus on new packaging myplc-native. Removed deprecated myplc-devel.

MyPLC is a complete PlanetLab Central (PLC) portable installation. The default installation consists of a web server, an XML-RPC API server, a boot server, and a database server: the core components of PLC. The installation is customized through an easy-to-use graphical interface. All PLC services are started up and shut down through a single script installed on the host system.

MyPLC architecture

This document focuses on the new packaging named myplc-native as introduced in the 4.2 release of PlanetLab. The former, chroot-based, packaging known as simply myplc might still be present in this release but its usage is not recommended anymore. With 4.2, the general architecture of the build system has drastically changed as well. Rather than providing a static chroot image for building the software, that was formerly known as myplc-devel, the current paradigm is to create a fresh vserver and to rely on yum to install all needed development tools. More details on how to set up such an environment can be found at that describes how to turn a CentOS5 box into a vserver-capable host system.

The recommended way to deploy MyPLC relies on vserver. Here again, please refer to for how to set up such en environment. As of PlanetLab 4.2, the recommended Linux distribution here is CentOS5, because there are publicly available resources that allow a smooth setup. As of PlanetLab 4.2, the current focus is on Fedora 8. This means that you should create a fresh Fedora 8 vserver in your vserver-capable CentOS box, and perform all subsequent installations from that place as described below. Although you might find builds for other Linux distributions, it is recommended for new users to use this particular variant. It is also possible to perform these installations from a fresh Fedora 8 installation. However, having a vserver-capable box instead provides much more flexibility and is thus recommended, in particular in terms of future upgrades of the system. In addition, there have been numerous reports that SELINUX should be turned off for running myplc in former releases. This is part of the instructions provided to set up vserver, and please keep this in mind if you plan on running MyPLC in a dedicated Fedora 8 box. Last, you need to check your firewall configuration(s) since it is required, of course, to open up the http and https ports, so as to accept connections from the managed nodes and from the users desktops, and possibly ssh as well.

The following locations are entry points for locating the build you plan on using. is maintained by the PlanetLab team at Princeton University. is maintained by the OneLab team at INRIA. There are currently two so-called PlanetLab Distributions known as planetlab and onelab. planet-lab.org generally builds only the planetlab flavour, while both flavours are generally available at one-lab.org.

Once you've located the build you want to use, it is strongly advised to assign this vserver a unique IP address, and to avoid sharing the hosting box's one. To that end, the typical sentence for creating such a vserver would be: In this example, we have chosen to use a planetlab flavour, based on rc2.1lab, for i386 (this is what the final 32 stands for).

If you do not use the convenience script mentioned above, you need to create an entry in your yum configuration: myplc.repo [myplc] name= MyPLC baseurl=http://build.one-lab.org/4.2/planetlab-4.2-rc2.1lab-f8-32/RPMS enabled=1 gpgcheck=0 ^D [myvserver] #]]>

To actually install myplc at that stage, just run: The below explains in details the installation strategy and the miscellaneous files and directories involved.

On a Red Hat or Fedora host system, it is customary to use the service command to invoke System V init scripts. As the examples suggest, the service must be started as root: In , we provide greater details that might be helpful in the case where the service does not seem to take off correctly. Like all other registered System V init services, MyPLC is started and shut down automatically when your host system boots and powers off. You may disable automatic startup by invoking the chkconfig command on a Red Hat or Fedora host system:

After verifying that MyPLC is working correctly, shut it down and begin changing some of the default variable values. Shut down MyPLC with service plc stop (see ). The preferred option for changing the configuration is to use the plc-config-tty tool. The full set of applicable variables is described in , but using the u guides you to the most useful ones. Here is sample session: # plc-config-tty Enter command (u for usual changes, w to save, ? for help) u == PLC_NAME : [PlanetLab Test] OneLab == PLC_SLICE_PREFIX : [pl] thone == PLC_ROOT_USER : [root@localhost.localdomain] root@onelab-plc.inria.fr == PLC_ROOT_PASSWORD : [root] plain-passwd == PLC_MAIL_ENABLED : [false] true == PLC_MAIL_SUPPORT_ADDRESS : [root+support@localhost.localdomain] support@one-lab.org == PLC_BOOT_HOST : [localhost.localdomain] onelab-plc.inria.fr == PLC_NET_DNS1 : [127.0.0.1] 138.96.250.248 == PLC_NET_DNS2 : [None] 138.96.250.249 Enter command (u for usual changes, w to save, ? for help) w Wrote /etc/planetlab/configs/site.xml Merged /etc/planetlab/default_config.xml and /etc/planetlab/configs/site.xml into /etc/planetlab/plc_config.xml You might want to type 'r' (restart plc) or 'q' (quit) Enter command (u for usual changes, w to save, ? for help) r ==================== Stopping plc ... ==================== Starting plc ... Enter command (u for usual changes, w to save, ? for help) q [myvserver] # ]]> The variables that you should change immediately are: PLC_NAME: Change this to the name of your PLC installation. PLC_SLICE_PREFIX: Pick some reasonable, short value; this is especially crucial if you plan on federating with other PLCs. PLC_ROOT_PASSWORD: Change this to a more secure password. PLC_MAIL_SUPPORT_ADDRESS: Change this to the e-mail address at which you would like to receive support requests. PLC_DB_HOST, PLC_API_HOST, PLC_WWW_HOST, PLC_BOOT_HOST, Change all of these to the preferred FQDN address of your host system. The corresponding *_IP values can be safely ignored if the FQDN can be resolved through DNS. After changing these variables, make sure that you save (w) and restart your plc (r), as shown in the above example. You should notice that the password of the default administrator account is no longer root, and that the default site name includes the name of your PLC installation instead of PlanetLab. As a side effect of these changes, the ISO images for the boot CDs now have new names, so that you can freely remove the ones names after 'PlanetLab Test', which is the default value of PLC_NAME If you used the above method method for configuring, you can skip to . As an alternative to using plc-config-tty, you may also use a text editor, but this requires some understanding on how the configuration files are used within myplc. The default configuration is stored in a file named /etc/planetlab/default_config.xml, that is designed to remain intact. You may store your local changes in a file named /etc/planetlab/configs/site.xml, that gets loaded on top of the defaults. The resulting complete configuration is stored in the file /etc/planetlab/plc_config.xml that is used as the reference. If you use this strategy, be sure to issue the following command to refresh this file: The defaults configuration file is a self-documenting configuration file written in XML. Variables are divided into categories. Variable identifiers must be alphanumeric, plus underscore. A variable is referred to canonically as the uppercase concatenation of its category identifier, an underscore, and its variable identifier. Thus, a variable with an id of slice_prefix in the plc category is referred to canonically as PLC_SLICE_PREFIX. The reason for this convention is that during MyPLC startup, plc_config.xml is translated into several different languages—shell, PHP, and Python—so that scripts written in each of these languages can refer to the same underlying configuration. Most MyPLC scripts are written in shell, so the convention for shell variables predominates.

Now that myplc is up and running, you can connect to the web site that by default runs on port 80. You can either directly use the default administrator user that you configured in PLC_ROOT_USER and PLC_ROOT_PASSWORD, or create a real user through the 'Joining' tab. Do not forget to select both PI and tech roles, and to select the only site created at this stage. Login as the administrator to enable this user, then login as the real user.

Install your first node by clicking Add Node under the Nodes tab. Fill in all the appropriate details, then click Add. Download the node's boot material, please refer to for more details about this stage. Please keep in mind that this boot medium is customized for your particular instance, and contains details such as the host that your configured as PLC_BOOT_HOST), or the SSL certificate of your boot server that might expire. So changes in your configuration may require you to replace all your boot CD's.

You may administer nodes as root by using the SSH key stored in /etc/planetlab/root_ssh_key.rsa. [myvserver] # ssh -i /etc/planetlab/root_ssh_key.rsa root@node From the node's root context, besides the standard Linux log files located in /var/log, several other files can give you clues about any problems with active processes: /var/log/nm: The log file for the Node Manager. /vservers/slicename/var/log/nm: The log file for the Node Manager operations that perform within the slice's vserver.

Create a slice by clicking Create Slice under the Slices tab. Fill in all the appropriate details, then click Create. Add nodes to the slice by clicking Manage Nodes on the Slice Details page for the slice. Slice creation is performed by the NodeManager. In some particular cases you may wish to restart it manually, here is how to do this:

During service startup described in , observe the output of this command for any failures. If no failures occur, you should see output similar to the following. Please note that as of this writing, with 4.2 the system logger step might fail, this is harmless! A complete log file of the startup process may be found at /var/log/boot.log. Possible reasons for failure of each step include: Starting database server: If this step fails, check /var/log/pgsql and /var/log/boot.log. The most common reason for failure is that the default PostgreSQL port, TCP port 5432, is already in use. Check that you are not running a PostgreSQL server on the host system. Starting web server: If this step fails, check /var/log/httpd/error_log and /var/log/boot.log for obvious errors. The most common reason for failure is that the default web ports, TCP ports 80 and 443, are already in use. Check that you are not running a web server on the host system. Bootstrapping the database: If this step fails, it is likely that the previous step (Starting web server) also failed. Another reason that it could fail is if PLC_API_HOST (see ) does not resolve to the host on which the API server has been enabled. By default, all services, including the API server, are enabled and run on the same host, so check that PLC_API_HOST is either localhost or resolves to a local IP address. Also check that PLC_ROOT_USER looks like an e-mail address. Starting crond: If this step fails, it is likely that the previous steps (Starting web server and Bootstrapping the database) also failed. If not, check /var/log/boot.log for obvious errors. This step starts the cron service and generates the initial set of XML files that the Slice Creation Service uses to determine slice state. If no failures occur, then MyPLC should be active with a default configuration. Open a web browser on the host system and visit http://localhost/, which should bring you to the front page of your PLC installation. The default password for the administrator account root@localhost.localdomain (set by PLC_ROOT_USER) is root (set by PLC_ROOT_PASSWORD).

The various places where is stored the persistent information pertaining to your own deployment are /etc/planetlab: This directory contains the configuration files, keys, and certificates that define your MyPLC installation. /var/lib/pgsql: This directory contains PostgreSQL database files. /var/www/html/boot: This directory contains the Boot Manager, customized for your MyPLC installation, and its data files. /var/www/html/download: This directory contains Boot CD images, customized for your MyPLC installation. /var/www/html/install-rpms: This directory is where you should install node package updates, if any. By default, nodes are installed from the tarball located at /var/www/html/boot/PlanetLab-Bootstrap.tar.bz2, which is pre-built from the latest PlanetLab Central sources, and installed as part of your MyPLC installation. However, nodes will attempt to install any newer RPMs located in /var/www/html/install-rpms/planetlab, after initial installation and periodically thereafter. You must run command to update the yum caches in this directory after installing a new RPM. If you wish to upgrade all your nodes RPMs from a more recent build, you should take advantage of the noderepo RPM, as described in

Please refer to the following resources for setting up a build environment: will get you started for setting up vserver, launching a nightly build or running the build manually. and in particular the various README files, provide some help on how to use advanced features of the build.

Listed below is the set of standard configuration variables together with their default values, as defined in the template /etc/planetlab/default_config.xml. This information is available online within plc-config-tty, e.g.: List of the myplc configuration variables: &Variables; MarkHuang