From: Mark Huang Date: Tue, 18 Jul 2006 22:41:45 +0000 (+0000) Subject: add section about myplc-devel X-Git-Tag: planetlab-4_0-rc1~131 X-Git-Url: http://git.onelab.eu/?a=commitdiff_plain;h=01b95a6e7b46f916c40d5925df53e117d30567be;p=myplc.git add section about myplc-devel --- diff --git a/doc/.cvsignore b/doc/.cvsignore new file mode 100644 index 0000000..cdb1378 --- /dev/null +++ b/doc/.cvsignore @@ -0,0 +1 @@ +*.xml.valid diff --git a/doc/Makefile b/doc/Makefile index 14a62ed..8caff1d 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -4,18 +4,18 @@ # Mark Huang # Copyright (C) 2006 The Trustees of Princeton University # -# $Id: Makefile,v 1.3 2006/04/24 22:14:56 mlhuang Exp $ +# $Id: Makefile,v 1.4 2006/04/28 20:16:04 mlhuang Exp $ # vpath GenDoc.xsl ../../plc_www/doc -vpath plc_config.xml .. +vpath %_config.xml .. all: myplc.pdf myplc.php # Dependencies -.myplc.xml.valid: architecture.eps architecture.png variables.xml +.myplc.xml.valid: architecture.eps architecture.png plc_variables.xml plc_devel_variables.xml -variables.xml: variables.xsl plc_config.xml +%_variables.xml: variables.xsl %_config.xml xsltproc $(XSLFLAGS) --output $@ $^ # Validate the XML diff --git a/doc/myplc.pdf b/doc/myplc.pdf index d9f9814..f8a636c 100644 Binary files a/doc/myplc.pdf and b/doc/myplc.pdf differ diff --git a/doc/myplc.php b/doc/myplc.php index 720182a..fbc314c 100644 --- a/doc/myplc.php +++ b/doc/myplc.php @@ -41,22 +41,30 @@

Table of Contents

-
1. Overview
-
2. Installation
-
3. Quickstart
+
1. Overview
+
2. Installation
+
3. Quickstart
3.1. Changing the configuration
-
3.2. Installing nodes
-
3.3. Administering nodes
-
3.4. Creating a slice
+
3.2. Installing nodes
+
3.3. Administering nodes
+
3.4. Creating a slice
-
A. Configuration variables
-
Bibliography
+
4. Rebuilding and customizing MyPLC
+
+
4.1. Installation
+
4.2. Fedora Core 4 mirror requirement
+
4.3. Building MyPLC
+
4.4. Updating CVS
+
+
A. Configuration variables
+
B. Development environment configuration variables
+
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 @@ -80,28 +88,30 @@

-2. Installation

+2. Installation

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:

-

Example 1. Installing MyPLC.

+

Example 1. Installing MyPLC.

# If your distribution supports RPM
-rpm -U myplc-0.3-1.planetlab.i386.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 myplc-0.3-1.planetlab.i386.rpm | cpio -diu
+rpm2cpio /tmp/myplc-0.4-1.planetlab.i386.rpm | cpio -diu

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. The - filesystem, even when mounted, should be treated an opaque + /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 @@ -112,13 +122,14 @@ rpm2cpio myplc-0.3-1.planetlab.i386.rpm | cpio -diu

  • /plc/data: The directory where user data and generated files are stored. This directory is bind - mounted into the chroot jail on - /data. 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 chanegd, the new - version of the file will be created with a + 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 @@ -183,7 +194,7 @@ service plc stop the chkconfig command on a Red Hat or Fedora host system:

    -

    Example 3. Disabling automatic startup of MyPLC.

    +

    Example 3. Disabling automatic startup of MyPLC.

    # Disable automatic startup
 chkconfig plc off
 
@@ -208,13 +219,13 @@ chkconfig plc on

    -3. Quickstart

    +3. Quickstart

Once installed, start MyPLC (see Example 2, “Starting and stopping MyPLC.”). 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:

-

Example 4. A successful MyPLC startup.

+

Example 4. A successful MyPLC startup.

Mounting PLC:                                              [  OK  ]
 PLC: Generating network files:                             [  OK  ]
 PLC: Starting system logger:                               [  OK  ]
@@ -245,10 +256,12 @@ PLC: Signing node packages:                                [  OK  ]
       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. SELinux may
-      also be enabled. If you install MyPLC on Fedora Core 4 or 5, use
-      the Security Level Configuration
-      utility to configure SELinux to be
+      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. If you
+      installed MyPLC on Fedora Core 4 or 5, use the
+      Security Level Configuration utility
+      to configure SELinux to be
       Permissive.

 
  • Starting database server: If
       this step fails, check
@@ -343,7 +356,7 @@ PLC: Signing node packages:                                [  OK  ]

    • -3.2. Installing nodes

    +3.2. Installing nodes

    Install your first node by clicking Add Node under the Nodes tab. Fill in all the appropriate details, then click @@ -367,12 +380,12 @@ PLC: Signing node packages: [ OK ]

    -3.3. Administering nodes

    +3.3. 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
    @@ -395,7 +408,7 @@ PLC: Signing node packages: [ OK ]

    -3.4. Creating a slice

    +3.4. Creating a slice

    Create a slice by clicking Create Slice under the Slices tab. Fill in all the appropriate details, then click Create. Add @@ -410,7 +423,7 @@ PLC: Signing node packages: [ OK ] 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
 
@@ -420,9 +433,242 @@ vserver pl_conf exec service pl_conf restart
    +
    +

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

    +
    +

    Example 7. Installing the MyPLC development environment.

    +
    # 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
    +
    +

    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.4, “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.3, “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.2. 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.3. 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.

    +

    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 2, “Installation”).

    +
    +
    +

    +4.4. 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

    +A. Configuration variables

    Listed below is the set of standard configuration variables and their default values, defined in the template /etc/planetlab/default_config.xml. Additional @@ -527,33 +773,6 @@ vserver pl_conf exec service pl_conf restart

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

    -
    PLC_ROOT_CA_SSL_KEY
    -
    -

    - Type: file

    -

    - Default: /etc/planetlab/root_ca_ssl.key

    -

    The SSL private key used for signing all other - generated certificates. If non-existent, one will be - generated.

    -
    -
    PLC_ROOT_CA_SSL_KEY_PUB
    -
    -

    - Type: file

    -

    - Default: /etc/planetlab/root_ca_ssl.pub

    -

    The corresponding SSL public key.

    -
    -
    PLC_ROOT_CA_SSL_CRT
    -
    -

    - Type: file

    -

    - Default: /etc/planetlab/root_ca_ssl.crt

    -

    The corresponding SSL public - certificate.

    -
    PLC_MA_SA_NAMESPACE

    @@ -574,22 +793,36 @@ vserver pl_conf exec service pl_conf restart with the signature of your MA/SA. If non-existent, one will be generated.

    -
    PLC_MA_SA_SSL_KEY_PUB
    +
    PLC_MA_SA_SSL_CRT

    Type: file

    - Default: /etc/planetlab/ma_sa_ssl.pub

    -

    The corresponding SSL public key.

    + 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_SSL_CRT
    +
    PLC_MA_SA_CA_SSL_CRT

    Type: file

    - Default: /etc/planetlab/ma_sa_ssl.crt

    -

    The corresponding SSL public certificate, - signed by the root CA.

    + 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
    @@ -597,11 +830,11 @@ vserver pl_conf exec service pl_conf restart Type: file

    Default: /etc/planetlab/ma_sa_api.xml

    -

    The API Certificate for your MA/SA is the SSL - public key for your MA/SA embedded in an XML document and - signed by the root CA SSL private key. The API Certificate - can be used by any PlanetLab node managed by any MA, to - verify that your MA/SA public key is valid.

    +

    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
    @@ -849,8 +1082,21 @@ vserver pl_conf exec service pl_conf restart Type: file

    Default: /etc/planetlab/api_ssl.crt

    -

    The corresponding SSL public certificate, - signed by the root CA.

    +

    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
    @@ -923,8 +1169,21 @@ vserver pl_conf exec service pl_conf restart Type: file

    Default: /etc/planetlab/www_ssl.crt

    -

    The corresponding SSL public certificate, - signed by the root CA.

    +

    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
    @@ -980,8 +1239,7 @@ vserver pl_conf exec service pl_conf restart

    Default: /etc/planetlab/boot_ssl.key

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

    + traffic.

    PLC_BOOT_SSL_CRT
    @@ -989,14 +1247,79 @@ vserver pl_conf exec service pl_conf restart Type: file

    Default: /etc/planetlab/boot_ssl.crt

    -

    The corresponding SSL public certificate, - signed by the root CA.

    +

    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 environment configuration variables

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

    +Bibliography

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

    diff --git a/doc/myplc.xml b/doc/myplc.xml index 98e8bc2..e727b7a 100644 --- a/doc/myplc.xml +++ b/doc/myplc.xml @@ -1,7 +1,8 @@ + + ]>
    @@ -76,7 +77,7 @@ -
    +
    Installation Though internally composed of commodity software @@ -88,12 +89,14 @@ Installing MyPLC. - +rpm2cpio /tmp/myplc-0.4-1.planetlab.i386.rpm | cpio -diu]]> MyPLC installs the following files and directories: @@ -103,8 +106,8 @@ rpm2cpio myplc-0.3-1.planetlab.i386.rpm | cpio -diu]]> /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. The - filesystem, even when mounted, should be treated an opaque + /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. @@ -117,13 +120,14 @@ rpm2cpio myplc-0.3-1.planetlab.i386.rpm | cpio -diu]]> /plc/data: The directory where user data and generated files are stored. This directory is bind - mounted into the chroot jail on - /data. 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 chanegd, the new - version of the file will be created with a + 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 @@ -271,10 +275,12 @@ PLC: Signing node packages: [ OK ] 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. SELinux may - also be enabled. If you install MyPLC on Fedora Core 4 or 5, use - the Security Level Configuration - utility to configure SELinux to be + 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. If you + installed MyPLC on Fedora Core 4 or 5, use the + Security Level Configuration utility + to configure SELinux to be Permissive. Starting database server: If @@ -476,6 +482,279 @@ vserver pl_conf exec service pl_conf restart]]>
    +
    + 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. + +
    + 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. + + + Installing the MyPLC development environment. + + + + + 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 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 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. + + +
    + +
    + 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: + + + Setting up a local Fedora Core 4 repository. + + + + + Change the repository URI and --cut-dirs + level as needed to produce a hierarchy that resembles: + + + + A list of additional Fedora Core 4 mirrors is available at + http://fedora.redhat.com/Download/mirrors.html. +
    + +
    + 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. + + To build MyPLC, or any PlanetLab source code module, from + within the MyPLC development environment, execute the following + commands as root: + + + Building MyPLC. + + + + + 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 ). +
    + +
    + 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: + + + 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. + + + + + 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. +
    +
    + Configuration variables @@ -489,6 +768,12 @@ vserver pl_conf exec service pl_conf restart]]> &Variables; + + Development environment configuration variables + + &DevelVariables; + + Bibliography diff --git a/doc/plc_devel_variables.xml b/doc/plc_devel_variables.xml new file mode 100644 index 0000000..263aa3c --- /dev/null +++ b/doc/plc_devel_variables.xml @@ -0,0 +1,58 @@ + + + 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. + + + diff --git a/doc/variables.xml b/doc/plc_variables.xml similarity index 86% rename from doc/variables.xml rename to doc/plc_variables.xml index 87a58e2..e0d7806 100644 --- a/doc/variables.xml +++ b/doc/plc_variables.xml @@ -116,39 +116,6 @@ account on your nodes. - - PLC_ROOT_CA_SSL_KEY - - - Type: file - - Default: /etc/planetlab/root_ca_ssl.key - The SSL private key used for signing all other - generated certificates. If non-existent, one will be - generated. - - - - PLC_ROOT_CA_SSL_KEY_PUB - - - Type: file - - Default: /etc/planetlab/root_ca_ssl.pub - The corresponding SSL public key. - - - - PLC_ROOT_CA_SSL_CRT - - - Type: file - - Default: /etc/planetlab/root_ca_ssl.crt - The corresponding SSL public - certificate. - - PLC_MA_SA_NAMESPACE @@ -174,24 +141,40 @@ - PLC_MA_SA_SSL_KEY_PUB + PLC_MA_SA_SSL_CRT Type: file - Default: /etc/planetlab/ma_sa_ssl.pub - The corresponding SSL public key. + 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_SSL_CRT + PLC_MA_SA_CA_SSL_CRT Type: file - Default: /etc/planetlab/ma_sa_ssl.crt - The corresponding SSL public certificate, - signed by the root CA. + 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. @@ -201,11 +184,11 @@ Type: file Default: /etc/planetlab/ma_sa_api.xml - The API Certificate for your MA/SA is the SSL - public key for your MA/SA embedded in an XML document and - signed by the root CA SSL private key. The API Certificate - can be used by any PlanetLab node managed by any MA, to - verify that your MA/SA public key is valid. + 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. @@ -505,8 +488,23 @@ Type: file Default: /etc/planetlab/api_ssl.crt - The corresponding SSL public certificate, - signed by the root CA. + 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. @@ -595,8 +593,23 @@ Type: file Default: /etc/planetlab/www_ssl.crt - The corresponding SSL public certificate, - signed by the root CA. + 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. @@ -664,8 +677,7 @@ Default: /etc/planetlab/boot_ssl.key The SSL private key to use for encrypting HTTPS - traffic. If non-existent, one will be - generated. + traffic. @@ -675,8 +687,23 @@ Type: file Default: /etc/planetlab/boot_ssl.crt - The corresponding SSL public certificate, - signed by the root CA. + 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.