X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=doc%2Fmyplc.xml;h=4522b6be446b727aa21733ad3f61e499d5210f09;hb=12d99e092de9c51ffddb5d04372c339fb79dbc21;hp=e1d8080b6d96e06221ab8e5fd01f220c0532ec83;hpb=764a83703635ce879647b40eb277baaeb6209b61;p=myplc.git diff --git a/doc/myplc.xml b/doc/myplc.xml index e1d8080..4522b6b 100644 --- a/doc/myplc.xml +++ b/doc/myplc.xml @@ -38,6 +38,15 @@ MLH Add development environment. + + 1.2 + August 18, 2006 + TPT + + Review section on configuration and introduce plc-config-tty. + Present implementation details last. + + @@ -107,7 +116,7 @@ some known limitations to this, so here are a couple notes as a recommended reading before you proceed with the installation. - As of August 2006 9 (i.e myplc-0.5) : + As of 17 August 2006 (i.e myplc-0.5-2) : The software is vastly based on Fedora @@ -137,276 +146,155 @@ need to check your firewall configuration since you need, of course, to open up the http and https ports, so as to accept connections from - the managed nodes, and from the users desktops. + the managed nodes and from the users desktops.
- Installation + Installating and using MyPLC Though internally composed of commodity software subpackages, MyPLC should be treated as a monolithic software application. MyPLC is distributed as single RPM package that has no external dependencies, allowing it to be installed on - practically any Linux 2.6 based distribution: + practically any Linux 2.6 based distribution. - +
Installing MyPLC. - - - - MyPLC installs the following files and directories: - - - - /plc/root.img: The main - root filesystem of the MyPLC application. This file is an - uncompressed ext3 filesystem that is loopback mounted on - /plc/root when MyPLC starts. This - filesystem, even when mounted, should be treated as an opaque - binary that can and will be replaced in its entirety by any - upgrade of MyPLC. - - /plc/root: The mount point - for /plc/root.img. Once the root filesystem - is mounted, all MyPLC services run in a - chroot jail based in this - directory. - - - /plc/data: The directory where user - data and generated files are stored. This directory is bind - mounted onto /plc/root/data so that it is - accessible as /data from within the - chroot jail. Files in this directory are - marked with %config(noreplace) in the - RPM. That is, during an upgrade of MyPLC, if a file has not - changed since the last installation or upgrade of MyPLC, it is - subject to upgrade and replacement. If the file has changed, - the new version of the file will be created with a - .rpmnew extension. Symlinks within the - MyPLC root filesystem ensure that the following directories - (relative to /plc/root) are stored - outside the MyPLC filesystem image: - - - /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/alpina-logs: This - directory contains node installation logs. - - /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 yum-arch and - createrepo to update the - yum caches in this directory after - installing a new RPM. PlanetLab Central cannot support any - changes to this directory. - - /var/www/html/xml: This - directory contains various XML files that the Slice Creation - Service uses to determine the state of slices. These XML - files are refreshed periodically by cron - jobs running in the MyPLC root. - - - - - /etc/init.d/plc: This file - is a System V init script installed on your host filesystem, - that allows you to start up and shut down MyPLC with a single - command. On a Red Hat or Fedora host system, it is customary to - use the service command to invoke System V - init scripts: - - - Starting and stopping MyPLC. - - - - - 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: - - - Disabling automatic startup of MyPLC. - - - - - - /etc/sysconfig/plc: This - file is a shell script fragment that defines the variables - PLC_ROOT and PLC_DATA. By default, - the values of these variables are /plc/root - and /plc/data, respectively. If you wish, - you may move your MyPLC installation to another location on your - host filesystem and edit the values of these variables - appropriately, but you will break the RPM upgrade - process. PlanetLab Central cannot support any changes to this - file. - - /etc/planetlab: This - symlink to /plc/data/etc/planetlab is - installed on the host system for convenience. + + If your distribution supports RPM: + + + If your distribution does not support RPM: + -
-
- Quickstart + The below explains in + details the installation strategy and the miscellaneous files and + directories involved. + +
- Once installed, start MyPLC (see ). MyPLC must be started as - root. Observe the output of this command for any failures. If no - failures occur, you should see output similar to the - following: +
QuickStart - - A successful MyPLC startup. + 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: - + Starting MyPLC: + + + Stopping MyPLC: + - If /plc/root is mounted successfully, a - complete log file of the startup process may be found at - /plc/root/var/log/boot.log. Possible reasons - for failure of each step include: - - - Mounting PLC: If this step - fails, first ensure that you started MyPLC as root. Check - /etc/sysconfig/plc to ensure that - PLC_ROOT and PLC_DATA refer to the - right locations. You may also have too many existing loopback - mounts, or your kernel may not support loopback mounting, bind - mounting, or the ext3 filesystem. Try freeing at least one - loopback device, or re-compiling your kernel to support loopback - mounting, bind mounting, and the ext3 filesystem. If you see an - error similar to Permission denied while trying to open - /plc/root.img, then SELinux may be enabled. See above for details. - - Starting database server: If - this step fails, check - /plc/root/var/log/pgsql and - /plc/root/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. + In , we provide greater + details that might be helpful in the case where the service does + not seem to take off correctly. - Starting web server: If this - step fails, check - /plc/root/var/log/httpd/error_log and - /plc/root/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. + 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: - 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. + Disabling automatic startup of MyPLC. + + Re-enabling automatic startup of MyPLC. + - 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 - /plc/root/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 password of the - default administrator account - root@localhost.localdomain (set by - PLC_ROOT_USER) is root (set by - PLC_ROOT_PASSWORD). +
-
+
Changing the configuration 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 ). With a text - editor, open the file - /etc/planetlab/plc_config.xml. This 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 + (see ). + + The preferred option for changing the configuration is to + use the plc-config-tty tool. This tool comes + with the root image, so you need to have it mounted first. The + full set of applicable variables is described in , but using the u + guides you to the most useful ones. Note that if you + plan on federating with other PLCs, it is strongly + recommended that you change the PLC_NAME + and PLC_SLICE_PREFIX + settings. + Here is sample session: + + + Using plc-config-tty for configuration: + # plc-config-tty +Config file /etc/planetlab/configs/site.xml located under a non-existing directory +Want to create /etc/planetlab/configs [y]/n ? y +Created directory /etc/planetlab/configs +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 + # exit +# +]]> + + + If you used this method for configuring, you can skip to + the . 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 any file located in the configs/ + sub-directory, that are loaded on top of the defaults. Finally + the file /etc/planetlab/plc_config.xml is + loaded, and the resulting configuration is stored in the latter + file, that is used as a reference. + + Using a separate file for storing local changes only, as + plc-config-tty does, is not a workable option + with a text editor because it would involve tedious xml + re-assembling. So your local changes should go in + /etc/planetlab/plc_config.xml. Be warned + however that any change you might do this way could be lost if + you use plc-config-tty later on. + + This 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. @@ -440,13 +328,30 @@ PLC: Signing node packages: [ OK ] system. - After changing these variables, save the file, then - restart MyPLC with service plc start. 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. -
+ After changing these variables, + save the file, then restart MyPLC with service plc + start. 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 +
+ +
Login as a real user + + 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. +
Installing nodes @@ -542,6 +447,218 @@ ssh -i /etc/planetlab/root_ssh_key.rsa root@node \ vserver pl_conf exec service pl_conf restart]]>
+ +
+ Understanding the startup sequence + + 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: + + + A successful MyPLC startup. + + + + + If /plc/root is mounted successfully, a + complete log file of the startup process may be found at + /plc/root/var/log/boot.log. Possible reasons + for failure of each step include: + + + Mounting PLC: If this step + fails, first ensure that you started MyPLC as root. Check + /etc/sysconfig/plc to ensure that + PLC_ROOT and PLC_DATA refer to the + right locations. You may also have too many existing loopback + mounts, or your kernel may not support loopback mounting, bind + mounting, or the ext3 filesystem. Try freeing at least one + loopback device, or re-compiling your kernel to support loopback + mounting, bind mounting, and the ext3 filesystem. If you see an + error similar to Permission denied while trying to open + /plc/root.img, then SELinux may be enabled. See above for details. + + Starting database server: If + this step fails, check + /plc/root/var/log/pgsql and + /plc/root/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 + /plc/root/var/log/httpd/error_log and + /plc/root/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 + /plc/root/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 password of the + default administrator account + root@localhost.localdomain (set by + PLC_ROOT_USER) is root (set by + PLC_ROOT_PASSWORD). +
+ +
Files and directories + involved in <emphasis>myplc</emphasis> + MyPLC installs the following files and directories: + + + + /plc/root.img: The main + root filesystem of the MyPLC application. This file is an + uncompressed ext3 filesystem that is loopback mounted on + /plc/root when MyPLC starts. This + filesystem, even when mounted, should be treated as an opaque + binary that can and will be replaced in its entirety by any + upgrade of MyPLC. + + /plc/root: The mount point + for /plc/root.img. Once the root filesystem + is mounted, all MyPLC services run in a + chroot jail based in this + directory. + + + /plc/data: The directory where user + data and generated files are stored. This directory is bind + mounted onto /plc/root/data so that it is + accessible as /data from within the + chroot jail. Files in this directory are + marked with %config(noreplace) in the + RPM. That is, during an upgrade of MyPLC, if a file has not + changed since the last installation or upgrade of MyPLC, it is + subject to upgrade and replacement. If the file has changed, + the new version of the file will be created with a + .rpmnew extension. Symlinks within the + MyPLC root filesystem ensure that the following directories + (relative to /plc/root) are stored + outside the MyPLC filesystem image: + + + /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/alpina-logs: This + directory contains node installation logs. + + /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 yum-arch and + createrepo to update the + yum caches in this directory after + installing a new RPM. PlanetLab Central cannot support any + changes to this directory. + + /var/www/html/xml: This + directory contains various XML files that the Slice Creation + Service uses to determine the state of slices. These XML + files are refreshed periodically by cron + jobs running in the MyPLC root. + + /root: this is the + location of the root-user's homedir, and for your + convenience is stored under /data so + that your local customizations survive across + updates - this feature is inherited from the + myplc-devel package, where it is probably + more useful. + + + + + + /etc/init.d/plc: This file + is a System V init script installed on your host filesystem, + that allows you to start up and shut down MyPLC with a single + command, as described in . + + + /etc/sysconfig/plc: This + file is a shell script fragment that defines the variables + PLC_ROOT and PLC_DATA. By default, + the values of these variables are /plc/root + and /plc/data, respectively. If you wish, + you may move your MyPLC installation to another location on your + host filesystem and edit the values of these variables + appropriately, but you will break the RPM upgrade + process. PlanetLab Central cannot support any changes to this + file. + + /etc/planetlab: This + symlink to /plc/data/etc/planetlab is + installed on the host system for convenience. + +
@@ -574,18 +691,34 @@ vserver pl_conf exec service pl_conf restart]]> chroot jail should not be modified directly, as they are subject to upgrade. - - Installing the MyPLC development environment. - - + If your distribution supports RPM: + + + If your distribution does not support RPM: + + +
-# If your distribution does not support RPM -cd /tmp -wget http://build.planet-lab.org/build/myplc-0_4-rc2/RPMS/i386/myplc-devel-0.4-2.planetlab.i386.rpm -cd / -rpm2cpio /tmp/myplc-devel-0.4-2.planetlab.i386.rpm | cpio -diu]]> - +
+ Configuration + + The default configuration should work as-is on most + sites. Configuring the development package can be achieved in a + similar way as for myplc, as described in + . plc-config-tty supports a + -d option for supporting the + myplc-devel case, that can be useful in a + context where it would not guess it by itself. Refer to for a list of variables. +
+ +
Files and directories + involved in <emphasis>myplc-devl</emphasis> The MyPLC development environment installs the following files and directories: @@ -637,8 +770,12 @@ rpm2cpio /tmp/myplc-devel-0.4-2.planetlab.i386.rpm | cpio -diu]]> for more information about executing builds. - - + + /root: this is the + location of the root-user's homedir, and for your + convenience is stored under /data so + that your local customizations survive across + updates. /etc/init.d/plc-devel: This file is @@ -688,12 +825,12 @@ rpm2cpio /tmp/myplc-devel-0.4-2.planetlab.i386.rpm | cpio -diu]]> Setting up a local Fedora Core 4 repository. - +# for repo in core/4/i386/os core/updates/4/i386 extras/4/i386 ; do +> wget -m -nH --cut-dirs=3 http://coblitz.planet-lab.org/pub/fedora/linux/$repo +> done]]> Change the repository URI and --cut-dirs @@ -716,6 +853,15 @@ done]]> repository, eases the task of rebuilding PlanetLab source code. + Before you try building MyPLC, you might check the + configuration, in a file named + plc_config.xml that relies on a very + similar model as MyPLC, located in + /etc/planetlab within the chroot jail, or + in /plc/devel/data/etc/planetlab from the + root context. The set of applicable variables is described in + . + To build MyPLC, or any PlanetLab source code module, from within the MyPLC development environment, execute the following commands as root: @@ -772,12 +918,14 @@ make -C $DATE]]> Because the CVS repository is not automatically upgraded, if you wish to keep your local repository synchronized with the public PlanetLab repository, it is highly recommended that you - use CVS's support for vendor - branches to track changes. Vendor branches ease the task - of merging upstream changes with your local modifications. To - import a new snapshot into your local repository (for example, - if you have just upgraded from + use CVS's support for vendor branches to track changes, as + described here + and here. + Vendor branches ease the task of merging upstream changes with + your local modifications. To import a new snapshot into your + local repository (for example, if you have just upgraded from myplc-devel-0.4-2 to myplc-devel-0.4-3 and you notice the new repository in /plc/devel/data/cvs-0.4-3), @@ -805,19 +953,24 @@ cvs -d /cvs rtag before-myplc-0_4-3-merge TMP=$(mktemp -d /data/export.XXXXXX) pushd $TMP cvs -d /data/cvs-0.4-3 export -r HEAD . -cvs -d /cvs import -m "PlanetLab sources from myplc-0.4-3" -ko -I ! . planetlab myplc-0_4-3 +cvs -d /cvs import -m "Merging myplc-0.4-3" -ko -I ! . planetlab myplc-0_4-3 popd rm -rf $TMP]]> - If there any merge conflicts, use the command suggested by - CVS to help the merge. Explaining how to fix merge conflicts is - beyond the scope of this document; consult the CVS documentation - for more information on how to use CVS. -
- + If there are any merge conflicts, use the command + suggested by CVS to help the merge. Explaining how to fix merge + conflicts is beyond the scope of this document; consult the CVS + documentation for more information on how to use CVS. + + +
More information : the FAQ wiki page + + Please refer to, and feel free to contribute, +the FAQ page on the Princeton's wiki .
- + Configuration variables (for <emphasis>myplc</emphasis>) Listed below is the set of standard configuration variables @@ -827,10 +980,25 @@ rm -rf $TMP]]> templates that should be placed in /etc/planetlab/configs/. - &Variables; + This information is available online within + plc-config-tty, e.g.: + +Advanced usage of plc-config-tty + # plc-config-tty +Enter command (u for usual changes, w to save, ? for help) V plc_dns +========== Category = PLC_DNS +### Enable DNS +# Enable the internal DNS server. The server does not provide reverse +# resolution and is not a production quality or scalable DNS solution. +# Use the internal DNS server only for small deployments or for testing. +PLC_DNS_ENABLED +]]> + + List of the myplc configuration variables: + &Variables; - + Development configuration variables (for <emphasis>myplc-devel</emphasis>) &DevelVariables;