From: Thierry Parmentelat Date: Fri, 11 Aug 2006 18:32:52 +0000 (+0000) Subject: re-ordered for more user-friendly/straightforward presentation X-Git-Tag: planetlab-4_0-rc1~108 X-Git-Url: http://git.onelab.eu/?a=commitdiff_plain;h=9ffca9a0a663ca70335bcba5756f2561c213a49b;p=myplc.git re-ordered for more user-friendly/straightforward presentation - 2 main sections, myplc and myplc-devel - section myplc describes the case where all runs OK and gives implementation details (startup sequence & files installed) later on --- diff --git a/doc/myplc.pdf b/doc/myplc.pdf index 05f7154..05df6a7 100644 Binary files a/doc/myplc.pdf and b/doc/myplc.pdf differ diff --git a/doc/myplc.php b/doc/myplc.php index 06f803f..b9f7614 100644 --- a/doc/myplc.php +++ b/doc/myplc.php @@ -13,7 +13,7 @@

-MyPLC User's Guide

+MyPLC User's Guide

Mark Huang

@@ -45,39 +45,39 @@

Table of Contents

-
1. Overview
-
1.1. Purpose of the myplc-devel +
1. Overview
+
1.1. Purpose of the myplc-devel package
2. Requirements
3. Installating and using MyPLC
-
3.1. Installing MyPLC.
+
3.1. Installing MyPLC.
3.2. QuickStart
3.3. Changing the configuration
-
3.4. Installing nodes
-
3.5. Administering nodes
-
3.6. Creating a slice
+
3.4. Installing nodes
+
3.5. Administering nodes
+
3.6. Creating a slice
3.7. Understanding the startup sequence
3.8. Files and directories involved in myplc
4. Rebuilding and customizing MyPLC
-
4.1. Installation
+
4.1. Installation
4.2. Files and directories involved in myplc-devl
-
4.3. Fedora Core 4 mirror requirement
+
4.3. Fedora Core 4 mirror requirement
4.4. Building MyPLC
4.5. Updating CVS
A. Configuration variables (for myplc)
B. Development configuration variables (for myplc-devel)
-
Bibliography
+
Bibliography

-1. Overview

+1. Overview

MyPLC is a complete PlanetLab Central (PLC) portable installation contained within a chroot jail. The default installation consists of a web server, an @@ -100,7 +100,7 @@

-1.1.  Purpose of the myplc-devel +1.1.  Purpose of the myplc-devel package

The myplc package comes with all required node software, rebuilt from the public PlanetLab CVS @@ -167,7 +167,7 @@ practically any Linux 2.6 based distribution.

-3.1. Installing MyPLC.

+3.1. Installing MyPLC.

  • If your distribution supports RPM:

    @@ -194,11 +194,11 @@ the service command to invoke System V init scripts. As the examples suggest, the service must be started as root:

    -

    Example 1. Starting MyPLC:

    +

    Example 1. Starting MyPLC:

    # service plc start
    -

    Example 2. Stopping MyPLC:

    +

    Example 2. Stopping MyPLC:

    # service plc stop

    In Section 3.7, “Understanding the startup sequence”, we provide greater @@ -210,11 +210,11 @@ chkconfig command on a Red Hat or Fedora host system:

    -

    Example 3. Disabling automatic startup of MyPLC.

    +

    Example 3. Disabling automatic startup of MyPLC.

    # chkconfig plc off
    -

    Example 4. Re-enabling automatic startup of MyPLC.

    +

    Example 4. Re-enabling automatic startup of MyPLC.

    # chkconfig plc on
@@ -269,7 +269,7 @@

-3.4. Installing nodes

+3.4. Installing nodes

Install your first node by clicking Add Node under the Nodes tab. Fill in all the appropriate details, then click @@ -293,12 +293,12 @@

-3.5. Administering nodes

+3.5. Administering nodes

You may administer nodes as root by using the SSH key stored in /etc/planetlab/root_ssh_key.rsa.

-

Example 5. Accessing nodes via SSH. Replace +

Example 5. Accessing nodes via SSH. Replace node with the hostname of the node.

ssh -i /etc/planetlab/root_ssh_key.rsa root@node
@@ -321,7 +321,7 @@

-3.6. Creating a slice

+3.6. Creating a slice

Create a slice by clicking Create Slice under the Slices tab. Fill in all the appropriate details, then click Create. Add @@ -336,7 +336,7 @@ to determine if it needs to create or delete any slices. You may accelerate this process manually if desired.

-

Example 6. Forcing slice creation on a node.

+

Example 6. Forcing slice creation on a node.

# Update slices.xml immediately
 service plc start crond
 
@@ -352,7 +352,7 @@ vserver pl_conf exec service pl_conf restart
any failures. If no failures occur, you should see output similar to the following:

-

Example 7. A successful MyPLC startup.

+

Example 7. A successful MyPLC startup.

Mounting PLC:                                              [  OK  ]
 PLC: Generating network files:                             [  OK  ]
 PLC: Starting system logger:                               [  OK  ]
@@ -540,7 +540,7 @@ PLC: Signing node packages:                                [  OK  ]
     repository.

 

 

-4.1. Installation

+4.1. Installation

Install the MyPLC development environment similarly to how you would install MyPLC. You may install both packages on the same host system if you wish. As with MyPLC, the MyPLC development @@ -618,7 +618,7 @@ PLC: Signing node packages: [ OK ]

-4.3. Fedora Core 4 mirror requirement

+4.3. Fedora Core 4 mirror requirement

The MyPLC development environment requires access to a complete Fedora Core 4 i386 RPM repository, because several different filesystems based upon Fedora Core 4 are constructed @@ -650,7 +650,7 @@ PLC: Signing node packages: [ OK ] such as wget or rsync to download the RPMS from a public mirror:

-

Example 8. Setting up a local Fedora Core 4 repository.

+

Example 8. Setting up a local Fedora Core 4 repository.

# mkdir -p /plc/devel/data/fedora
 # cd /plc/devel/data/fedora
 
@@ -686,7 +686,7 @@ PLC: Signing node packages:                                [  OK  ]
       within the MyPLC development environment, execute the following
       commands as root:

 

-
Example 9. Building MyPLC.

+
Example 9. Building MyPLC.

 
# Initialize MyPLC development environment
 service plc-devel start
 
@@ -741,7 +741,7 @@ make -C $DATE

       execute the following commands as root from within the MyPLC
       development environment:

 

-
Example 10. Updating /data/cvs from /data/cvs-0.4-3.

+
Example 10. Updating /data/cvs from /data/cvs-0.4-3.

 
Warning: This may cause
 	severe, irreversible changes to be made to your local
 	repository. Always tag your local repository before
@@ -1422,1443 +1422,10 @@ rm -rf $TMP

-Bibliography

+Bibliography

[1] Mark Huang. PlanetLab Technical Contact's Guide.

-dummy 1.11 for cathing up with the xml numbering -
-
-
-

-MyPLC User's Guide

-

Mark Huang

-
Revision History
- - - - - - - - - - - - - -
Revision History
Revision 1.0April 7, 2006MLH

Initial draft.

Revision 1.1July 19, 2006MLH

Add development environment.

-
-

Abstract

-

This document describes the design, installation, and - administration of MyPLC, a complete PlanetLab Central (PLC) - portable installation contained within a - chroot jail. This document assumes advanced - knowledge of the PlanetLab architecture and Linux system - administration.

-
-
-
- -
-

Table of Contents

-
-
1. Overview
-
1.1. Purpose of the myplc-devel - package
-
2. Requirements
-
3. Installating and using MyPLC
-
-
3.1. Installing MyPLC.
-
3.2. QuickStart
-
3.3. Changing the configuration
-
3.4. Installing nodes
-
3.5. Administering nodes
-
3.6. Creating a slice
-
3.7. Understanding the startup sequence
-
3.8. Files and directories - involved in myplc
-
-
4. Rebuilding and customizing MyPLC
-
-
4.1. Installation
-
4.2. Files and directories - involved in myplc-devl
-
4.3. Fedora Core 4 mirror requirement
-
4.4. Building MyPLC
-
4.5. Updating CVS
-
-
A. Configuration variables (for myplc)
-
B. Development configuration variables (for myplc-devel)
-
Bibliography
-
-
-
-

-1. Overview

-

MyPLC is a complete PlanetLab Central (PLC) portable - installation contained within a chroot - jail. 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. The usually complex process of installing and - administering the PlanetLab backend is reduced by containing PLC - services within a virtual filesystem. By packaging it in such a - manner, MyPLC may also be run on any modern Linux distribution, - and could conceivably even run in a PlanetLab slice.

-
-

Figure 1. MyPLC architecture

-
-MyPLC architecture

MyPLC should be viewed as a single application that - provides multiple functions and can run on any host - system.

-
-
-
-

-1.1.  Purpose of the myplc-devel - package

-

The myplc package comes with all - required node software, rebuilt from the public PlanetLab CVS - repository. If for any reason you need to implement your own - customized version of this software, you can use the - myplc-devel package instead, for setting up - your own development environment, including a local CVS - repository; you can then freely manage your changes and rebuild - your customized version of myplc. We also - provide good practices, that will then allow you to resync your local - CVS repository with any further evolution on the mainstream public - PlanetLab software.

-
-
-
-

-2.  Requirements

-

myplc and - myplc-devel were designed as - chroot jails so as to reduce the requirements on - your host operating system. So in theory, these distributions should - work on virtually any Linux 2.6 based distribution, whether it - supports rpm or not.

-

However, things are never that simple and there indeed are - some known limitations to this, so here are a couple notes as a - recommended reading before you proceed with the installation.

-

As of 9 August 2006 (i.e myplc-0.5) :

-
    -

  • The software is vastly based on Fedora - Core 4. Please note that the build server at Princeton - runs Fedora Core 2, togother with a upgraded - version of yum. -

    • -
  • -

    myplc and myplc-devel are known to work on both - Fedora Core 2 and Fedora Core - 4. Please note however that, on fc4 at least, it is - highly recommended to use the Security Level - Configuration utility and to switch off - SElinux on your box because :

    -
      -

    • - myplc requires you to run SElinux as 'Permissive' at most -

      • -

    • - myplc-devel requires you to turn SElinux Off. -

      • -
    -
    • -

  • In addition, as far as myplc is concerned, you - 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.

    • -
-
-
-

-3. 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.

-
-

-3.1. Installing MyPLC.

-
    -
  • -

    If your distribution supports RPM:

    -
    # rpm -U http://build.planet-lab.org/build/myplc-0_4-rc1/RPMS/i386/myplc-0.4-1.planetlab.i386.rpm
    -
    • -
  • -

    If your distribution does not support RPM:

    -
    # cd /tmp
-# wget http://build.planet-lab.org/build/myplc-0_4-rc1/RPMS/i386/myplc-0.4-1.planetlab.i386.rpm
-# cd /
-# rpm2cpio /tmp/myplc-0.4-1.planetlab.i386.rpm | cpio -diu
    -
    • -
-

The Section 3.8, “ Files and directories - involved in myplc” below explains in - details the installation strategy and the miscellaneous files and - directories involved.

-
-
-

-3.2.  QuickStart

-

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:

-
-

Example 1. Starting MyPLC:

-
# service plc start
-
-
-

Example 2. Stopping MyPLC:

-
# service plc stop
-
-

In Section 3.7, “Understanding the startup sequence”, 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:

-
-

Example 3. Disabling automatic startup of MyPLC.

-
# chkconfig plc off
-
-
-

Example 4. Re-enabling automatic startup of MyPLC.

-
# chkconfig plc on
-
-
-
-

-3.3. 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 Section 3.2, “ QuickStart ”). 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 - 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.

-

The variables that you should change immediately are:

-
    -

  • PLC_NAME: Change this to the - name of your PLC installation.

    • -

  • 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_DB_IP, PLC_API_HOST, - PLC_API_IP, PLC_WWW_HOST, - PLC_WWW_IP, PLC_BOOT_HOST, - PLC_BOOT_IP: Change all of these to the - preferred FQDN and external IP address of your host - system.

    • -
-

The full set of applicable variables is described in Appendix B, Development configuration variables (for myplc-devel). 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.

-
-
-

-3.4. Installing nodes

-

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 configuration file - by clicking Download configuration file on - the Node Details page for the - node. Save it to a floppy disk or USB key as detailed in [1].

-

Follow the rest of the instructions in [1] for creating a Boot CD and installing - the node, except download the Boot CD image from the - /download directory of your PLC - installation, not from PlanetLab Central. The images located - here are customized for your installation. If you change the - hostname of your boot server (PLC_BOOT_HOST), or - if the SSL certificate of your boot server expires, MyPLC will - regenerate it and rebuild the Boot CD with the new - certificate. If this occurs, you must replace all Boot CDs - created before the certificate was regenerated.

-

The installation process for a node has significantly - improved since PlanetLab 3.3. It should now take only a few - seconds for a new node to become ready to create slices.

-
-
-

-3.5. Administering nodes

-

You may administer nodes as root by - using the SSH key stored in - /etc/planetlab/root_ssh_key.rsa.

-
-

Example 5. Accessing nodes via SSH. Replace - node with the hostname of the node.

-
ssh -i /etc/planetlab/root_ssh_key.rsa root@node
-
-

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/pl_nm: The log - file for the Node Manager.

    • -

  • /vservers/pl_conf/var/log/pl_conf: - The log file for the Slice Creation Service.

    • -

  • /var/log/propd: The log - file for Proper, the service which allows certain slices to - perform certain privileged operations in the root - context.

    • -

  • /vservers/pl_netflow/var/log/netflow.log: - The log file for PlanetFlow, the network traffic auditing - service.

    • -
-
-
-

-3.6. Creating a slice

-

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.

-

A cron job runs every five minutes and - updates the file - /plc/data/var/www/html/xml/slices-0.5.xml - with information about current slice state. The Slice Creation - Service running on every node polls this file every ten minutes - to determine if it needs to create or delete any slices. You may - accelerate this process manually if desired.

-
-

Example 6. Forcing slice creation on a node.

-
# Update slices.xml immediately
-service plc start crond
-
-# Kick the Slice Creation Service on a particular node.
-ssh -i /etc/planetlab/root_ssh_key.rsa root@node \
-vserver pl_conf exec service pl_conf restart
-
-
-
-

-3.7. Understanding the startup sequence

-

During service startup described in Section 3.2, “ QuickStart ”, observe the output of this command for - any failures. If no failures occur, you should see output similar - to the following:

-
-

Example 7. A successful MyPLC startup.

-
Mounting PLC:                                              [  OK  ]
-PLC: Generating network files:                             [  OK  ]
-PLC: Starting system logger:                               [  OK  ]
-PLC: Starting database server:                             [  OK  ]
-PLC: Generating SSL certificates:                          [  OK  ]
-PLC: Configuring the API:                                  [  OK  ]
-PLC: Updating GPG keys:                                    [  OK  ]
-PLC: Generating SSH keys:                                  [  OK  ]
-PLC: Starting web server:                                  [  OK  ]
-PLC: Bootstrapping the database:                           [  OK  ]
-PLC: Starting DNS server:                                  [  OK  ]
-PLC: Starting crond:                                       [  OK  ]
-PLC: Rebuilding Boot CD:                                   [  OK  ]
-PLC: Rebuilding Boot Manager:                              [  OK  ]
-PLC: Signing node packages:                                [  OK  ]
-
-
-

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 Section 2, “ Requirements ” 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 - Section 3.3, “Changing the configuration”) 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.

    • -

  • 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).

-
-
-

-3.8.  Files and directories - involved in myplc

-

MyPLC installs the following files and directories:

-
    -

  1. /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.

    2. -

  2. /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.

    3. -
  3. -

    /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.

      • -
    -
    4. -

  4. /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 Section 3.2, “ QuickStart ”.

    5. -

  5. /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.

    6. -

  6. /etc/planetlab: This - symlink to /plc/data/etc/planetlab is - installed on the host system for convenience.

    7. -
-
-
-
-

-4. Rebuilding and customizing MyPLC

-

The MyPLC package, though distributed as an RPM, is not a - traditional package that can be easily rebuilt from SRPM. The - requisite build environment is quite extensive and numerous - assumptions are made throughout the PlanetLab source code base, - that the build environment is based on Fedora Core 4 and that - access to a complete Fedora Core 4 mirror is available.

-

For this reason, it is recommended that you only rebuild - MyPLC (or any of its components) from within the MyPLC development - environment. The MyPLC development environment is similar to MyPLC - itself in that it is a portable filesystem contained within a - chroot jail. The filesystem contains all the - necessary tools required to rebuild MyPLC, as well as a snapshot - of the PlanetLab source code base in the form of a local CVS - repository.

-
-

-4.1. Installation

-

Install the MyPLC development environment similarly to how - you would install MyPLC. You may install both packages on the same - host system if you wish. As with MyPLC, the MyPLC development - environment should be treated as a monolithic software - application, and any files present in the - chroot jail should not be modified directly, as - they are subject to upgrade.

-
    -
  • -

    If your distribution supports RPM:

    -
    # rpm -U http://build.planet-lab.org/build/myplc-0_4-rc2/RPMS/i386/myplc-devel-0.4-2.planetlab.i386.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
    -
    • -
-
-
-

-4.2.  Files and directories - involved in myplc-devl

-

The MyPLC development environment installs the following - files and directories:

-
    -

  • /plc/devel/root.img: The - main root filesystem of the MyPLC development environment. This - file is an uncompressed ext3 filesystem that is loopback mounted - on /plc/devel/root when the MyPLC - development environment is initialized. 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 the MyPLC - development environment.

    • -

  • /plc/devel/root: The mount - point for - /plc/devel/root.img.

    • -
  • -

    /plc/devel/data: The directory - where user data and generated files are stored. This directory - is bind mounted onto /plc/devel/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. Symlinks - ensure that the following directories (relative to - /plc/devel/root) are stored outside the - root filesystem image:

    -
      -

    • /etc/planetlab: This - directory contains the configuration files that define your - MyPLC development environment.

      • -

    • /cvs: A - snapshot of the PlanetLab source code is stored as a CVS - repository in this directory. Files in this directory will - not be updated by an upgrade of - myplc-devel. See Section 4.5, “Updating CVS” for more information about updating - PlanetLab source code.

      • -

    • /build: - Builds are stored in this directory. This directory is bind - mounted onto /plc/devel/root/build so that - it is accessible as /build from within the - chroot jail. The build scripts in this - directory are themselves source controlled; see Section 4.4, “Building MyPLC” for more information about executing - builds.

      • -
    -
    • -

  • /etc/init.d/plc-devel: This file is - a System V init script installed on your host filesystem, that - allows you to start up and shut down the MyPLC development - environment with a single command.

    • -
-
-
-

-4.3. Fedora Core 4 mirror requirement

-

The MyPLC development environment requires access to a - complete Fedora Core 4 i386 RPM repository, because several - different filesystems based upon Fedora Core 4 are constructed - during the process of building MyPLC. You may configure the - location of this repository via the - PLC_DEVEL_FEDORA_URL variable in - /plc/devel/data/etc/planetlab/plc_config.xml. The - value of the variable should be a URL that points to the top - level of a Fedora mirror that provides the - base, updates, and - extras repositories, e.g.,

-
    -

  • file:///data/fedora

    • -

  • http://coblitz.planet-lab.org/pub/fedora

    • -

  • ftp://mirror.cs.princeton.edu/pub/mirrors/fedora

    • -

  • ftp://mirror.stanford.edu/pub/mirrors/fedora

    • -

  • http://rpmfind.net/linux/fedora

    • -
-

As implied by the list, the repository may be located on - the local filesystem, or it may be located on a remote FTP or - HTTP server. URLs beginning with file:// - should exist at the specified location relative to the root of - the chroot jail. For optimum performance and - reproducibility, specify - PLC_DEVEL_FEDORA_URL=file:///data/fedora and - download all Fedora Core 4 RPMS into - /plc/devel/data/fedora on the host system - after installing myplc-devel. Use a tool - such as wget or rsync to - download the RPMS from a public mirror:

-
-

Example 8. Setting up a local Fedora Core 4 repository.

-
# mkdir -p /plc/devel/data/fedora
-# cd /plc/devel/data/fedora
-
-# 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 - level as needed to produce a hierarchy that resembles:

-
/plc/devel/data/fedora/core/4/i386/os
-/plc/devel/data/fedora/core/updates/4/i386
-/plc/devel/data/fedora/extras/4/i386
-

A list of additional Fedora Core 4 mirrors is available at - http://fedora.redhat.com/Download/mirrors.html.

-
-
-

-4.4. Building MyPLC

-

All PlanetLab source code modules are built and installed - as RPMS. A set of build scripts, checked into the - build/ directory of the PlanetLab CVS - 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 - Appendix B, Development configuration variables (for myplc-devel).

-

To build MyPLC, or any PlanetLab source code module, from - within the MyPLC development environment, execute the following - commands as root:

-
-

Example 9. Building MyPLC.

-
# Initialize MyPLC development environment
-service plc-devel start
-
-# Enter development environment
-chroot /plc/devel/root su -
-
-# Check out build scripts into a directory named after the current
-# date. This is simply a convention, it need not be followed
-# exactly. See build/build.sh for an example of a build script that
-# names build directories after CVS tags.
-DATE=$(date +%Y.%m.%d)
-cd /build
-cvs -d /cvs checkout -d $DATE build
-
-# Build everything
-make -C $DATE
-
-

If the build succeeds, a set of binary RPMS will be - installed under - /plc/devel/data/build/$DATE/RPMS/ that you - may copy to the - /var/www/html/install-rpms/planetlab - directory of your MyPLC installation (see Section 3, “Installating and using MyPLC”).

-
-
-

-4.5. Updating CVS

-

A complete snapshot of the PlanetLab source code is included - with the MyPLC development environment as a CVS repository in - /plc/devel/data/cvs. This CVS repository may - be accessed like any other CVS repository. It may be accessed - using an interface such as CVSweb, - and file permissions may be altered to allow for fine-grained - access control. Although the files are included with the - myplc-devel RPM, they are not subject to upgrade once installed. New - versions of the myplc-devel RPM will install - updated snapshot repositories in - /plc/devel/data/cvs-%{version}-%{release}, - where %{version}-%{release} is replaced with - the version number of the RPM.

-

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 - 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), - execute the following commands as root from within the MyPLC - development environment:

-
-

Example 10. Updating /data/cvs from /data/cvs-0.4-3.

-

Warning: This may cause - severe, irreversible changes to be made to your local - repository. Always tag your local repository before - importing.

-
# Initialize MyPLC development environment
-service plc-devel start
-
-# Enter development environment
-chroot /plc/devel/root su -
-
-# Tag current state
-cvs -d /cvs rtag before-myplc-0_4-3-merge
-
-# Export snapshot
-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
-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.

-
-
-
-

-A. Configuration variables (for myplc)

-

Listed below is the set of standard configuration variables - and their default values, defined in the template - /etc/planetlab/default_config.xml. Additional - variables and their defaults may be defined in site-specific XML - templates that should be placed in - /etc/planetlab/configs/.

-
-
PLC_NAME
-
-

- Type: string

-

- Default: PlanetLab Test

-

The name of this PLC installation. It is used in - the name of the default system site (e.g., PlanetLab Central) - and in the names of various administrative entities (e.g., - PlanetLab Support).

-
-
PLC_SLICE_PREFIX
-
-

- Type: string

-

- Default: pl

-

The abbreviated name of this PLC - installation. It is used as the prefix for system slices - (e.g., pl_conf). Warning: Currently, this variable should - not be changed.

-
-
PLC_ROOT_USER
-
-

- Type: email

-

- Default: root@localhost.localdomain

-

The name of the initial administrative - account. We recommend that this account be used only to create - additional accounts associated with real - administrators, then disabled.

-
-
PLC_ROOT_PASSWORD
-
-

- Type: password

-

- Default: root

-

The password of the initial administrative - account. Also the password of the root account on the Boot - CD.

-
-
PLC_ROOT_SSH_KEY_PUB
-
-

- Type: file

-

- Default: /etc/planetlab/root_ssh_key.pub

-

The SSH public key used to access the root - account on your nodes.

-
-
PLC_ROOT_SSH_KEY
-
-

- Type: file

-

- Default: /etc/planetlab/root_ssh_key.rsa

-

The SSH private key used to access the root - account on your nodes.

-
-
PLC_DEBUG_SSH_KEY_PUB
-
-

- Type: file

-

- Default: /etc/planetlab/debug_ssh_key.pub

-

The SSH public key used to access the root - account on your nodes when they are in Debug mode.

-
-
PLC_DEBUG_SSH_KEY
-
-

- Type: file

-

- Default: /etc/planetlab/debug_ssh_key.rsa

-

The SSH private key used to access the root - account on your nodes when they are in Debug mode.

-
-
PLC_ROOT_GPG_KEY_PUB
-
-

- Type: file

-

- Default: /etc/planetlab/pubring.gpg

-

The GPG public keyring used to sign the Boot - Manager and all node packages.

-
-
PLC_ROOT_GPG_KEY
-
-

- Type: file

-

- Default: /etc/planetlab/secring.gpg

-

The SSH private key used to access the root - account on your nodes.

-
-
PLC_MA_SA_NAMESPACE
-
-

- Type: ip

-

- Default: test

-

The namespace of your MA/SA. This should be a - globally unique value assigned by PlanetLab - Central.

-
-
PLC_MA_SA_SSL_KEY
-
-

- Type: file

-

- Default: /etc/planetlab/ma_sa_ssl.key

-

The SSL private key used for signing documents - with the signature of your MA/SA. If non-existent, one will - be generated.

-
-
PLC_MA_SA_SSL_CRT
-
-

- Type: file

-

- Default: /etc/planetlab/ma_sa_ssl.crt

-

The corresponding SSL public certificate. By - default, this certificate is self-signed. You may replace - the certificate later with one signed by the PLC root - CA.

-
-
PLC_MA_SA_CA_SSL_CRT
-
-

- Type: file

-

- Default: /etc/planetlab/ma_sa_ca_ssl.crt

-

If applicable, the certificate of the PLC root - CA. If your MA/SA certificate is self-signed, then this file - is the same as your MA/SA certificate.

-
-
PLC_MA_SA_CA_SSL_KEY_PUB
-
-

- Type: file

-

- Default: /etc/planetlab/ma_sa_ca_ssl.pub

-

If applicable, the public key of the PLC root - CA. If your MA/SA certificate is self-signed, then this file - is the same as your MA/SA public key.

-
-
PLC_MA_SA_API_CRT
-
-

- Type: file

-

- Default: /etc/planetlab/ma_sa_api.xml

-

The API Certificate is your MA/SA public key - embedded in a digitally signed XML document. By default, - this document is self-signed. You may replace this - certificate later with one signed by the PLC root - CA.

-
-
PLC_NET_DNS1
-
-

- Type: ip

-

- Default: 127.0.0.1

-

Primary DNS server address.

-
-
PLC_NET_DNS2
-
-

- Type: ip

-

- Default:

-

Secondary DNS server address.

-
-
PLC_DNS_ENABLED
-
-

- Type: boolean

-

- Default: true

-

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_MAIL_ENABLED
-
-

- Type: boolean

-

- Default: false

-

Set to false to suppress all e-mail notifications - and warnings.

-
-
PLC_MAIL_SUPPORT_ADDRESS
-
-

- Type: email

-

- Default: root+support@localhost.localdomain

-

This address is used for support - requests. Support requests may include traffic complaints, - security incident reporting, web site malfunctions, and - general requests for information. We recommend that the - address be aliased to a ticketing system such as Request - Tracker.

-
-
PLC_MAIL_BOOT_ADDRESS
-
-

- Type: email

-

- Default: root+install-msgs@localhost.localdomain

-

The API will notify this address when a problem - occurs during node installation or boot.

-
-
PLC_MAIL_SLICE_ADDRESS
-
-

- Type: email

-

- Default: root+SLICE@localhost.localdomain

-

This address template is used for sending - e-mail notifications to slices. SLICE will be replaced with - the name of the slice.

-
-
PLC_DB_ENABLED
-
-

- Type: boolean

-

- Default: true

-

Enable the database server on this - machine.

-
-
PLC_DB_TYPE
-
-

- Type: string

-

- Default: postgresql

-

The type of database server. Currently, only - postgresql is supported.

-
-
PLC_DB_HOST
-
-

- Type: hostname

-

- Default: localhost.localdomain

-

The fully qualified hostname of the database - server.

-
-
PLC_DB_IP
-
-

- Type: ip

-

- Default: 127.0.0.1

-

The IP address of the database server, if not - resolvable by the configured DNS servers.

-
-
PLC_DB_PORT
-
-

- Type: int

-

- Default: 5432

-

The TCP port number through which the database - server should be accessed.

-
-
PLC_DB_NAME
-
-

- Type: string

-

- Default: planetlab3

-

The name of the database to access.

-
-
PLC_DB_USER
-
-

- Type: string

-

- Default: pgsqluser

-

The username to use when accessing the - database.

-
-
PLC_DB_PASSWORD
-
-

- Type: password

-

- Default:

-

The password to use when accessing the - database. If left blank, one will be - generated.

-
-
PLC_API_ENABLED
-
-

- Type: boolean

-

- Default: true

-

Enable the API server on this - machine.

-
-
PLC_API_DEBUG
-
-

- Type: boolean

-

- Default: false

-

Enable verbose API debugging. Do not enable on - a production system!

-
-
PLC_API_HOST
-
-

- Type: hostname

-

- Default: localhost.localdomain

-

The fully qualified hostname of the API - server.

-
-
PLC_API_IP
-
-

- Type: ip

-

- Default: 127.0.0.1

-

The IP address of the API server, if not - resolvable by the configured DNS servers.

-
-
PLC_API_PORT
-
-

- Type: int

-

- Default: 80

-

The TCP port number through which the API - should be accessed. Warning: SSL (port 443) access is not - fully supported by the website code yet. We recommend that - port 80 be used for now and that the API server either run - on the same machine as the web server, or that they both be - on a secure wired network.

-
-
PLC_API_PATH
-
-

- Type: string

-

- Default: /PLCAPI/

-

The base path of the API URL.

-
-
PLC_API_MAINTENANCE_USER
-
-

- Type: string

-

- Default: maint@localhost.localdomain

-

The username of the maintenance account. This - account is used by local scripts that perform automated - tasks, and cannot be used for normal logins.

-
-
PLC_API_MAINTENANCE_PASSWORD
-
-

- Type: password

-

- Default:

-

The password of the maintenance account. If - left blank, one will be generated. We recommend that the - password be changed periodically.

-
-
PLC_API_MAINTENANCE_SOURCES
-
-

- Type: hostname

-

- Default:

-

A space-separated list of IP addresses allowed - to access the API through the maintenance account. The value - of this variable is set automatically to allow only the API, - web, and boot servers, and should not be - changed.

-
-
PLC_API_SSL_KEY
-
-

- Type: file

-

- Default: /etc/planetlab/api_ssl.key

-

The SSL private key to use for encrypting HTTPS - traffic. If non-existent, one will be - generated.

-
-
PLC_API_SSL_CRT
-
-

- Type: file

-

- Default: /etc/planetlab/api_ssl.crt

-

The corresponding SSL public certificate. By - default, this certificate is self-signed. You may replace - the certificate later with one signed by a root - CA.

-
-
PLC_API_CA_SSL_CRT
-
-

- Type: file

-

- Default: /etc/planetlab/api_ca_ssl.crt

-

The certificate of the root CA, if any, that - signed your server certificate. If your server certificate is - self-signed, then this file is the same as your server - certificate.

-
-
PLC_WWW_ENABLED
-
-

- Type: boolean

-

- Default: true

-

Enable the web server on this - machine.

-
-
PLC_WWW_DEBUG
-
-

- Type: boolean

-

- Default: false

-

Enable debugging output on web pages. Do not - enable on a production system!

-
-
PLC_WWW_HOST
-
-

- Type: hostname

-

- Default: localhost.localdomain

-

The fully qualified hostname of the web - server.

-
-
PLC_WWW_IP
-
-

- Type: ip

-

- Default: 127.0.0.1

-

The IP address of the web server, if not - resolvable by the configured DNS servers.

-
-
PLC_WWW_PORT
-
-

- Type: int

-

- Default: 80

-

The TCP port number through which the - unprotected portions of the web site should be - accessed.

-
-
PLC_WWW_SSL_PORT
-
-

- Type: int

-

- Default: 443

-

The TCP port number through which the protected - portions of the web site should be accessed.

-
-
PLC_WWW_SSL_KEY
-
-

- Type: file

-

- Default: /etc/planetlab/www_ssl.key

-

The SSL private key to use for encrypting HTTPS - traffic. If non-existent, one will be - generated.

-
-
PLC_WWW_SSL_CRT
-
-

- Type: file

-

- Default: /etc/planetlab/www_ssl.crt

-

The corresponding SSL public certificate for - the HTTP server. By default, this certificate is - self-signed. You may replace the certificate later with one - signed by a root CA.

-
-
PLC_WWW_CA_SSL_CRT
-
-

- Type: file

-

- Default: /etc/planetlab/www_ca_ssl.crt

-

The certificate of the root CA, if any, that - signed your server certificate. If your server certificate is - self-signed, then this file is the same as your server - certificate.

-
-
PLC_BOOT_ENABLED
-
-

- Type: boolean

-

- Default: true

-

Enable the boot server on this - machine.

-
-
PLC_BOOT_HOST
-
-

- Type: hostname

-

- Default: localhost.localdomain

-

The fully qualified hostname of the boot - server.

-
-
PLC_BOOT_IP
-
-

- Type: ip

-

- Default: 127.0.0.1

-

The IP address of the boot server, if not - resolvable by the configured DNS servers.

-
-
PLC_BOOT_PORT
-
-

- Type: int

-

- Default: 80

-

The TCP port number through which the - unprotected portions of the boot server should be - accessed.

-
-
PLC_BOOT_SSL_PORT
-
-

- Type: int

-

- Default: 443

-

The TCP port number through which the protected - portions of the boot server should be - accessed.

-
-
PLC_BOOT_SSL_KEY
-
-

- Type: file

-

- Default: /etc/planetlab/boot_ssl.key

-

The SSL private key to use for encrypting HTTPS - traffic.

-
-
PLC_BOOT_SSL_CRT
-
-

- Type: file

-

- Default: /etc/planetlab/boot_ssl.crt

-

The corresponding SSL public certificate for - the HTTP server. By default, this certificate is - self-signed. You may replace the certificate later with one - signed by a root CA.

-
-
PLC_BOOT_CA_SSL_CRT
-
-

- Type: file

-

- Default: /etc/planetlab/boot_ca_ssl.crt

-

The certificate of the root CA, if any, that - signed your server certificate. If your server certificate is - self-signed, then this file is the same as your server - certificate.

-
-
-
-
-

-B. Development configuration variables (for myplc-devel)

-
-
PLC_DEVEL_FEDORA_RELEASE
-
-

- Type: string

-

- Default: 4

-

Version number of Fedora Core upon which to - base the build environment. Warning: Currently, only Fedora - Core 4 is supported.

-
-
PLC_DEVEL_FEDORA_ARCH
-
-

- Type: string

-

- Default: i386

-

Base architecture of the build - environment. Warning: Currently, only i386 is - supported.

-
-
PLC_DEVEL_FEDORA_URL
-
-

- Type: string

-

- Default: file:///usr/share/mirrors/fedora

-

Fedora Core mirror from which to install - filesystems.

-
-
PLC_DEVEL_CVSROOT
-
-

- Type: string

-

- Default: /cvs

-

CVSROOT to use when checking out code.

-
-
PLC_DEVEL_BOOTSTRAP
-
-

- Type: boolean

-

- Default: false

-

Controls whether MyPLC should be built inside - of its own development environment.

-
-
-
-
-

-Bibliography

-
-

[1] Mark Huang. PlanetLab - Technical Contact's Guide.

-
-
- -dummy 1.12 for cathing up with the xml numbering diff --git a/doc/myplc.xml b/doc/myplc.xml index e1d8080..f5bc22f 100644 --- a/doc/myplc.xml +++ b/doc/myplc.xml @@ -107,7 +107,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 9 August 2006 (i.e myplc-0.5) : The software is vastly based on Fedora @@ -137,260 +137,69 @@ 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. - - 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. - + Disabling automatic startup of MyPLC. + + Re-enabling automatic startup of MyPLC. + - 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 @@ -398,7 +207,7 @@ PLC: Signing node packages: [ OK ] 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 + (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 @@ -440,13 +249,14 @@ 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. -
+ The full set of applicable variables is described in . 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. +
Installing nodes @@ -542,6 +352,208 @@ 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. + + 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. + + + + + /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 +586,20 @@ 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]]> - +
Files and directories + involved in <emphasis>myplc-devl</emphasis> The MyPLC development environment installs the following files and directories: @@ -688,12 +702,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 +730,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: @@ -817,7 +840,7 @@ rm -rf $TMP]]>
- + Configuration variables (for <emphasis>myplc</emphasis>) Listed below is the set of standard configuration variables @@ -830,7 +853,7 @@ rm -rf $TMP]]> &Variables; - + Development configuration variables (for <emphasis>myplc-devel</emphasis>) &DevelVariables;