From: Mark Huang <mlhuang@cs.princeton.edu>
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 <mlhuang@cs.princeton.edu>
# 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 @@
<div class="toc">
<p><b>Table of Contents</b></p>
<dl>
-<dt><span class="section"><a href="#id225357">1. Overview</a></span></dt>
-<dt><span class="section"><a href="#id225202">2. Installation</a></span></dt>
-<dt><span class="section"><a href="#id267666">3. Quickstart</a></span></dt>
+<dt><span class="section"><a href="#id225359">1. Overview</a></span></dt>
+<dt><span class="section"><a href="#Installation">2. Installation</a></span></dt>
+<dt><span class="section"><a href="#id267678">3. Quickstart</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="#ChangingTheConfiguration">3.1. Changing the configuration</a></span></dt>
-<dt><span class="section"><a href="#id268167">3.2. Installing nodes</a></span></dt>
-<dt><span class="section"><a href="#id268241">3.3. Administering nodes</a></span></dt>
-<dt><span class="section"><a href="#id268335">3.4. Creating a slice</a></span></dt>
+<dt><span class="section"><a href="#id268186">3.2. Installing nodes</a></span></dt>
+<dt><span class="section"><a href="#id268260">3.3. Administering nodes</a></span></dt>
+<dt><span class="section"><a href="#id268354">3.4. Creating a slice</a></span></dt>
</dl></dd>
-<dt><span class="appendix"><a href="#id268410">A. Configuration variables</a></span></dt>
-<dt><span class="bibliography"><a href="#id271055">Bibliography</a></span></dt>
+<dt><span class="section"><a href="#id268428">4. Rebuilding and customizing MyPLC</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="#id268453">4.1. Installation</a></span></dt>
+<dt><span class="section"><a href="#id268661">4.2. Fedora Core 4 mirror requirement</a></span></dt>
+<dt><span class="section"><a href="#BuildingMyPLC">4.3. Building MyPLC</a></span></dt>
+<dt><span class="section"><a href="#UpdatingCVS">4.4. Updating CVS</a></span></dt>
+</dl></dd>
+<dt><span class="appendix"><a href="#id269022">A. Configuration variables</a></span></dt>
+<dt><span class="appendix"><a href="#id271727">B. Development environment configuration variables</a></span></dt>
+<dt><span class="bibliography"><a href="#id271809">Bibliography</a></span></dt>
</dl>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="id225357"></a>1. Overview</h2></div></div></div>
+<a name="id225359"></a>1. Overview</h2></div></div></div>
<p>MyPLC is a complete PlanetLab Central (PLC) portable
installation contained within a <span><strong class="command">chroot</strong></span>
jail. The default installation consists of a web server, an
@@ -80,28 +88,30 @@
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="id225202"></a>2. Installation</h2></div></div></div>
+<a name="Installation"></a>2. Installation</h2></div></div></div>
<p>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:</p>
<div class="example">
-<a name="id225260"></a><p class="title"><b>Example 1. Installing MyPLC.</b></p>
+<a name="id225262"></a><p class="title"><b>Example 1. Installing MyPLC.</b></p>
<pre class="programlisting"># 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</pre>
+rpm2cpio /tmp/myplc-0.4-1.planetlab.i386.rpm | cpio -diu</pre>
</div>
<p>MyPLC installs the following files and directories:</p>
<div class="itemizedlist"><ul type="disc">
<li><p><code class="filename">/plc/root.img</code>: The main
root filesystem of the MyPLC application. This file is an
uncompressed ext3 filesystem that is loopback mounted on
- <code class="filename">/plc/root</code> when MyPLC starts. The
- filesystem, even when mounted, should be treated an opaque
+ <code class="filename">/plc/root</code> 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.</p></li>
<li><p><code class="filename">/plc/root</code>: The mount point
@@ -112,13 +122,14 @@ rpm2cpio myplc-0.3-1.planetlab.i386.rpm | cpio -diu</pre>
<li>
<p><code class="filename">/plc/data</code>: The directory where user
data and generated files are stored. This directory is bind
- mounted into the <span><strong class="command">chroot</strong></span> jail on
- <code class="filename">/data</code>. Files in this directory are marked
- with <span><strong class="command">%config(noreplace)</strong></span> 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 <code class="filename">/plc/root/data</code> so that it is
+ accessible as <code class="filename">/data</code> from within the
+ <span><strong class="command">chroot</strong></span> jail. Files in this directory are
+ marked with <span><strong class="command">%config(noreplace)</strong></span> 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
<code class="filename">.rpmnew</code> extension. Symlinks within the
MyPLC root filesystem ensure that the following directories
(relative to <code class="filename">/plc/root</code>) are stored
@@ -183,7 +194,7 @@ service plc stop</pre>
the <span><strong class="command">chkconfig</strong></span> command on a Red Hat or Fedora
host system:</p>
<div class="example">
-<a name="id243542"></a><p class="title"><b>Example 3. Disabling automatic startup of MyPLC.</b></p>
+<a name="id243553"></a><p class="title"><b>Example 3. Disabling automatic startup of MyPLC.</b></p>
<pre class="programlisting"># Disable automatic startup
chkconfig plc off
@@ -208,13 +219,13 @@ chkconfig plc on</pre>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="id267666"></a>3. Quickstart</h2></div></div></div>
+<a name="id267678"></a>3. Quickstart</h2></div></div></div>
<p>Once installed, start MyPLC (see <a href="#StartingAndStoppingMyPLC" title="Example 2. Starting and stopping MyPLC.">Example 2, âStarting and stopping MyPLC.â</a>). 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:</p>
<div class="example">
-<a name="id267786"></a><p class="title"><b>Example 4. A successful MyPLC startup.</b></p>
+<a name="id267798"></a><p class="title"><b>Example 4. A successful MyPLC startup.</b></p>
<pre class="programlisting">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 <span class="application">Security Level Configuration</span>
- utility to configure SELinux to be
+ mounting, bind mounting, and the ext3 filesystem. If you see an
+ error similar to <code class="literal">Permission denied while trying to open
+ /plc/root.img</code>, then SELinux may be enabled. If you
+ installed MyPLC on Fedora Core 4 or 5, use the
+ <span class="application">Security Level Configuration</span> utility
+ to configure SELinux to be
<code class="literal">Permissive</code>.</p></li>
<li><p><code class="literal">Starting database server</code>: If
this step fails, check
@@ -343,7 +356,7 @@ PLC: Signing node packages: [ OK ]
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
-<a name="id268167"></a>3.2. Installing nodes</h3></div></div></div>
+<a name="id268186"></a>3.2. Installing nodes</h3></div></div></div>
<p>Install your first node by clicking <code class="literal">Add
Node</code> under the <code class="literal">Nodes</code> tab. Fill in
all the appropriate details, then click
@@ -367,12 +380,12 @@ PLC: Signing node packages: [ OK ]
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
-<a name="id268241"></a>3.3. Administering nodes</h3></div></div></div>
+<a name="id268260"></a>3.3. Administering nodes</h3></div></div></div>
<p>You may administer nodes as <code class="literal">root</code> by
using the SSH key stored in
<code class="filename">/etc/planetlab/root_ssh_key.rsa</code>.</p>
<div class="example">
-<a name="id268263"></a><p class="title"><b>Example 5. Accessing nodes via SSH. Replace
+<a name="id268281"></a><p class="title"><b>Example 5. Accessing nodes via SSH. Replace
<code class="literal">node</code> with the hostname of the node.</b></p>
<pre class="programlisting">ssh -i /etc/planetlab/root_ssh_key.rsa root@node</pre>
</div>
@@ -395,7 +408,7 @@ PLC: Signing node packages: [ OK ]
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
-<a name="id268335"></a>3.4. Creating a slice</h3></div></div></div>
+<a name="id268354"></a>3.4. Creating a slice</h3></div></div></div>
<p>Create a slice by clicking <code class="literal">Create Slice</code>
under the <code class="literal">Slices</code> tab. Fill in all the
appropriate details, then click <code class="literal">Create</code>. 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.</p>
<div class="example">
-<a name="id268393"></a><p class="title"><b>Example 6. Forcing slice creation on a node.</b></p>
+<a name="id268412"></a><p class="title"><b>Example 6. Forcing slice creation on a node.</b></p>
<pre class="programlisting"># Update slices.xml immediately
service plc start crond
@@ -420,9 +433,242 @@ vserver pl_conf exec service pl_conf restart</pre>
</div>
</div>
</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="id268428"></a>4. Rebuilding and customizing MyPLC</h2></div></div></div>
+<p>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.</p>
+<p>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
+ <span><strong class="command">chroot</strong></span> 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.</p>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id268453"></a>4.1. Installation</h3></div></div></div>
+<p>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
+ <span><strong class="command">chroot</strong></span> jail should not be modified directly, as
+ they are subject to upgrade.</p>
+<div class="example">
+<a name="id268472"></a><p class="title"><b>Example 7. Installing the MyPLC development environment.</b></p>
+<pre class="programlisting"># 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</pre>
+</div>
+<p>The MyPLC development environment installs the following
+ files and directories:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p><code class="filename">/plc/devel/root.img</code>: The
+ main root filesystem of the MyPLC development environment. This
+ file is an uncompressed ext3 filesystem that is loopback mounted
+ on <code class="filename">/plc/devel/root</code> 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.</p></li>
+<li><p><code class="filename">/plc/devel/root</code>: The mount
+ point for
+ <code class="filename">/plc/devel/root.img</code>.</p></li>
+<li>
+<p><code class="filename">/plc/devel/data</code>: The directory
+ where user data and generated files are stored. This directory
+ is bind mounted onto <code class="filename">/plc/devel/root/data</code>
+ so that it is accessible as <code class="filename">/data</code> from
+ within the <span><strong class="command">chroot</strong></span> jail. Files in this
+ directory are marked with
+ <span><strong class="command">%config(noreplace)</strong></span> in the RPM. Symlinks
+ ensure that the following directories (relative to
+ <code class="filename">/plc/devel/root</code>) are stored outside the
+ root filesystem image:</p>
+<div class="itemizedlist"><ul type="circle">
+<li><p><code class="filename">/etc/planetlab</code>: This
+ directory contains the configuration files that define your
+ MyPLC development environment.</p></li>
+<li><p><code class="filename">/cvs</code>: A
+ snapshot of the PlanetLab source code is stored as a CVS
+ repository in this directory. Files in this directory will
+ <span class="bold"><strong>not</strong></span> be updated by an upgrade of
+ <code class="filename">myplc-devel</code>. See <a href="#UpdatingCVS" title="4.4. Updating CVS">Section 4.4, âUpdating CVSâ</a> for more information about updating
+ PlanetLab source code.</p></li>
+<li><p><code class="filename">/build</code>:
+ Builds are stored in this directory. This directory is bind
+ mounted onto <code class="filename">/plc/devel/root/build</code> so that
+ it is accessible as <code class="filename">/build</code> from within the
+ <span><strong class="command">chroot</strong></span> jail. The build scripts in this
+ directory are themselves source controlled; see <a href="#BuildingMyPLC" title="4.3. Building MyPLC">Section 4.3, âBuilding MyPLCâ</a> for more information about executing
+ builds.</p></li>
+</ul></div>
+</li>
+<li><p><code class="filename">/etc/init.d/plc-devel</code>: 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.</p></li>
+</ul></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id268661"></a>4.2. Fedora Core 4 mirror requirement</h3></div></div></div>
+<p>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
+ <code class="envar">PLC_DEVEL_FEDORA_URL</code> variable in
+ <code class="filename">/plc/devel/data/etc/planetlab/plc_config.xml</code>. The
+ value of the variable should be a URL that points to the top
+ level of a Fedora mirror that provides the
+ <code class="filename">base</code>, <code class="filename">updates</code>, and
+ <code class="filename">extras</code> repositories, e.g.,</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p><code class="filename">file:///data/fedora</code></p></li>
+<li><p><code class="filename">http://coblitz.planet-lab.org/pub/fedora</code></p></li>
+<li><p><code class="filename">ftp://mirror.cs.princeton.edu/pub/mirrors/fedora</code></p></li>
+<li><p><code class="filename">ftp://mirror.stanford.edu/pub/mirrors/fedora</code></p></li>
+<li><p><code class="filename">http://rpmfind.net/linux/fedora</code></p></li>
+</ul></div>
+<p>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 <code class="filename">file://</code>
+ should exist at the specified location relative to the root of
+ the <span><strong class="command">chroot</strong></span> jail. For optimum performance and
+ reproducibility, specify
+ <code class="envar">PLC_DEVEL_FEDORA_URL=file:///data/fedora</code> and
+ download all Fedora Core 4 RPMS into
+ <code class="filename">/plc/devel/data/fedora</code> on the host system
+ after installing <code class="filename">myplc-devel</code>. Use a tool
+ such as <span><strong class="command">wget</strong></span> or <span><strong class="command">rsync</strong></span> to
+ download the RPMS from a public mirror:</p>
+<div class="example">
+<a name="id268792"></a><p class="title"><b>Example 8. Setting up a local Fedora Core 4 repository.</b></p>
+<pre class="programlisting">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</pre>
+</div>
+<p>Change the repository URI and <span><strong class="command">--cut-dirs</strong></span>
+ level as needed to produce a hierarchy that resembles:</p>
+<pre class="programlisting">/plc/devel/data/fedora/core/4/i386/os
+/plc/devel/data/fedora/core/updates/4/i386
+/plc/devel/data/fedora/extras/4/i386</pre>
+<p>A list of additional Fedora Core 4 mirrors is available at
+ <a href="http://fedora.redhat.com/Download/mirrors.html" target="_top">http://fedora.redhat.com/Download/mirrors.html</a>.</p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="BuildingMyPLC"></a>4.3. Building MyPLC</h3></div></div></div>
+<p>All PlanetLab source code modules are built and installed
+ as RPMS. A set of build scripts, checked into the
+ <code class="filename">build/</code> directory of the PlanetLab CVS
+ repository, eases the task of rebuilding PlanetLab source
+ code.</p>
+<p>To build MyPLC, or any PlanetLab source code module, from
+ within the MyPLC development environment, execute the following
+ commands as root:</p>
+<div class="example">
+<a name="id268858"></a><p class="title"><b>Example 9. Building MyPLC.</b></p>
+<pre class="programlisting"># 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</pre>
+</div>
+<p>If the build succeeds, a set of binary RPMS will be
+ installed under
+ <code class="filename">/plc/devel/data/build/$DATE/RPMS/</code> that you
+ may copy to the
+ <code class="filename">/var/www/html/install-rpms/planetlab</code>
+ directory of your MyPLC installation (see <a href="#Installation" title="2. Installation">Section 2, âInstallationâ</a>).</p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="UpdatingCVS"></a>4.4. Updating CVS</h3></div></div></div>
+<p>A complete snapshot of the PlanetLab source code is included
+ with the MyPLC development environment as a CVS repository in
+ <code class="filename">/plc/devel/data/cvs</code>. This CVS repository may
+ be accessed like any other CVS repository. It may be accessed
+ using an interface such as <a href="http://www.freebsd.org/projects/cvsweb.html" target="_top">CVSweb</a>,
+ and file permissions may be altered to allow for fine-grained
+ access control. Although the files are included with the
+ <code class="filename">myplc-devel</code> RPM, they are <span class="bold"><strong>not</strong></span> subject to upgrade once installed. New
+ versions of the <code class="filename">myplc-devel</code> RPM will install
+ updated snapshot repositories in
+ <code class="filename">/plc/devel/data/cvs-%{version}-%{release}</code>,
+ where <code class="literal">%{version}-%{release}</code> is replaced with
+ the version number of the RPM.</p>
+<p>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 <a href="http://ximbiot.com/cvs/wiki/index.php?title=CVS--Concurrent_Versions_System_v1.12.12.1:_Tracking_third-party_sources" target="_top">vendor
+ branches</a> 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
+ <code class="filename">myplc-devel-0.4-2</code> to
+ <code class="filename">myplc-devel-0.4-3</code> and you notice the new
+ repository in <code class="filename">/plc/devel/data/cvs-0.4-3</code>),
+ execute the following commands as root from within the MyPLC
+ development environment:</p>
+<div class="example">
+<a name="id268989"></a><p class="title"><b>Example 10. Updating /data/cvs from /data/cvs-0.4-3.</b></p>
+<p><span class="bold"><strong>Warning</strong></span>: This may cause
+ severe, irreversible changes to be made to your local
+ repository. Always tag your local repository before
+ importing.</p>
+<pre class="programlisting"># 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</pre>
+</div>
+<p>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.</p>
+</div>
+</div>
<div class="appendix" lang="en">
<h2 class="title" style="clear: both">
-<a name="id268410"></a>A. Configuration variables</h2>
+<a name="id269022"></a>A. Configuration variables</h2>
<p>Listed below is the set of standard configuration variables
and their default values, defined in the template
<code class="filename">/etc/planetlab/default_config.xml</code>. Additional
@@ -527,33 +773,6 @@ vserver pl_conf exec service pl_conf restart</pre>
<p>The SSH private key used to access the root
account on your nodes.</p>
</dd>
-<dt><span class="term">PLC_ROOT_CA_SSL_KEY</span></dt>
-<dd>
-<p>
- Type: file</p>
-<p>
- Default: /etc/planetlab/root_ca_ssl.key</p>
-<p>The SSL private key used for signing all other
- generated certificates. If non-existent, one will be
- generated.</p>
-</dd>
-<dt><span class="term">PLC_ROOT_CA_SSL_KEY_PUB</span></dt>
-<dd>
-<p>
- Type: file</p>
-<p>
- Default: /etc/planetlab/root_ca_ssl.pub</p>
-<p>The corresponding SSL public key.</p>
-</dd>
-<dt><span class="term">PLC_ROOT_CA_SSL_CRT</span></dt>
-<dd>
-<p>
- Type: file</p>
-<p>
- Default: /etc/planetlab/root_ca_ssl.crt</p>
-<p>The corresponding SSL public
- certificate.</p>
-</dd>
<dt><span class="term">PLC_MA_SA_NAMESPACE</span></dt>
<dd>
<p>
@@ -574,22 +793,36 @@ vserver pl_conf exec service pl_conf restart</pre>
with the signature of your MA/SA. If non-existent, one will
be generated.</p>
</dd>
-<dt><span class="term">PLC_MA_SA_SSL_KEY_PUB</span></dt>
+<dt><span class="term">PLC_MA_SA_SSL_CRT</span></dt>
<dd>
<p>
Type: file</p>
<p>
- Default: /etc/planetlab/ma_sa_ssl.pub</p>
-<p>The corresponding SSL public key.</p>
+ Default: /etc/planetlab/ma_sa_ssl.crt</p>
+<p>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.</p>
</dd>
-<dt><span class="term">PLC_MA_SA_SSL_CRT</span></dt>
+<dt><span class="term">PLC_MA_SA_CA_SSL_CRT</span></dt>
<dd>
<p>
Type: file</p>
<p>
- Default: /etc/planetlab/ma_sa_ssl.crt</p>
-<p>The corresponding SSL public certificate,
- signed by the root CA.</p>
+ Default: /etc/planetlab/ma_sa_ca_ssl.crt</p>
+<p>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.</p>
+</dd>
+<dt><span class="term">PLC_MA_SA_CA_SSL_KEY_PUB</span></dt>
+<dd>
+<p>
+ Type: file</p>
+<p>
+ Default: /etc/planetlab/ma_sa_ca_ssl.pub</p>
+<p>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.</p>
</dd>
<dt><span class="term">PLC_MA_SA_API_CRT</span></dt>
<dd>
@@ -597,11 +830,11 @@ vserver pl_conf exec service pl_conf restart</pre>
Type: file</p>
<p>
Default: /etc/planetlab/ma_sa_api.xml</p>
-<p>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.</p>
+<p>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.</p>
</dd>
<dt><span class="term">PLC_NET_DNS1</span></dt>
<dd>
@@ -849,8 +1082,21 @@ vserver pl_conf exec service pl_conf restart</pre>
Type: file</p>
<p>
Default: /etc/planetlab/api_ssl.crt</p>
-<p>The corresponding SSL public certificate,
- signed by the root CA.</p>
+<p>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.</p>
+</dd>
+<dt><span class="term">PLC_API_CA_SSL_CRT</span></dt>
+<dd>
+<p>
+ Type: file</p>
+<p>
+ Default: /etc/planetlab/api_ca_ssl.crt</p>
+<p>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.</p>
</dd>
<dt><span class="term">PLC_WWW_ENABLED</span></dt>
<dd>
@@ -923,8 +1169,21 @@ vserver pl_conf exec service pl_conf restart</pre>
Type: file</p>
<p>
Default: /etc/planetlab/www_ssl.crt</p>
-<p>The corresponding SSL public certificate,
- signed by the root CA.</p>
+<p>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.</p>
+</dd>
+<dt><span class="term">PLC_WWW_CA_SSL_CRT</span></dt>
+<dd>
+<p>
+ Type: file</p>
+<p>
+ Default: /etc/planetlab/www_ca_ssl.crt</p>
+<p>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.</p>
</dd>
<dt><span class="term">PLC_BOOT_ENABLED</span></dt>
<dd>
@@ -980,8 +1239,7 @@ vserver pl_conf exec service pl_conf restart</pre>
<p>
Default: /etc/planetlab/boot_ssl.key</p>
<p>The SSL private key to use for encrypting HTTPS
- traffic. If non-existent, one will be
- generated.</p>
+ traffic.</p>
</dd>
<dt><span class="term">PLC_BOOT_SSL_CRT</span></dt>
<dd>
@@ -989,14 +1247,79 @@ vserver pl_conf exec service pl_conf restart</pre>
Type: file</p>
<p>
Default: /etc/planetlab/boot_ssl.crt</p>
-<p>The corresponding SSL public certificate,
- signed by the root CA.</p>
+<p>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.</p>
+</dd>
+<dt><span class="term">PLC_BOOT_CA_SSL_CRT</span></dt>
+<dd>
+<p>
+ Type: file</p>
+<p>
+ Default: /etc/planetlab/boot_ca_ssl.crt</p>
+<p>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.</p>
+</dd>
+</dl></div>
+</div>
+<div class="appendix" lang="en">
+<h2 class="title" style="clear: both">
+<a name="id271727"></a>B. Development environment configuration variables</h2>
+<div class="variablelist"><dl>
+<dt><span class="term">PLC_DEVEL_FEDORA_RELEASE</span></dt>
+<dd>
+<p>
+ Type: string</p>
+<p>
+ Default: 4</p>
+<p>Version number of Fedora Core upon which to
+ base the build environment. Warning: Currently, only Fedora
+ Core 4 is supported.</p>
+</dd>
+<dt><span class="term">PLC_DEVEL_FEDORA_ARCH</span></dt>
+<dd>
+<p>
+ Type: string</p>
+<p>
+ Default: i386</p>
+<p>Base architecture of the build
+ environment. Warning: Currently, only i386 is
+ supported.</p>
+</dd>
+<dt><span class="term">PLC_DEVEL_FEDORA_URL</span></dt>
+<dd>
+<p>
+ Type: string</p>
+<p>
+ Default: file:///usr/share/mirrors/fedora</p>
+<p>Fedora Core mirror from which to install
+ filesystems.</p>
+</dd>
+<dt><span class="term">PLC_DEVEL_CVSROOT</span></dt>
+<dd>
+<p>
+ Type: string</p>
+<p>
+ Default: /cvs</p>
+<p>CVSROOT to use when checking out code.</p>
+</dd>
+<dt><span class="term">PLC_DEVEL_BOOTSTRAP</span></dt>
+<dd>
+<p>
+ Type: boolean</p>
+<p>
+ Default: false</p>
+<p>Controls whether MyPLC should be built inside
+ of its own development environment.</p>
</dd>
</dl></div>
</div>
<div class="bibliography">
<div class="titlepage"><div><div><h2 class="title">
-<a name="id271055"></a>Bibliography</h2></div></div></div>
+<a name="id271809"></a>Bibliography</h2></div></div></div>
<div class="biblioentry">
<a name="TechsGuide"></a><p>[1] <span class="author"><span class="firstname">Mark</span> <span class="surname">Huang</span>. </span><span class="title"><i><a href="http://www.planet-lab.org/doc/TechsGuide.php" target="_top">PlanetLab
Technical Contact's Guide</a></i>. </span></p>
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 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
- <!ENTITY Variables SYSTEM "variables.xml">
+ <!ENTITY Variables SYSTEM "plc_variables.xml">
+ <!ENTITY DevelVariables SYSTEM "plc_devel_variables.xml">
]>
<article>
<articleinfo>
@@ -76,7 +77,7 @@
</figure>
</section>
- <section>
+ <section id="Installation">
<title>Installation</title>
<para>Though internally composed of commodity software
@@ -88,12 +89,14 @@
<example>
<title>Installing MyPLC.</title>
- <programlisting><![CDATA[# If your distribution supports RPM
-rpm -U myplc-0.3-1.planetlab.i386.rpm
+ <programlisting><![CDATA[# 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 myplc-0.3-1.planetlab.i386.rpm | cpio -diu]]></programlisting>
+rpm2cpio /tmp/myplc-0.4-1.planetlab.i386.rpm | cpio -diu]]></programlisting>
</example>
<para>MyPLC installs the following files and directories:</para>
@@ -103,8 +106,8 @@ rpm2cpio myplc-0.3-1.planetlab.i386.rpm | cpio -diu]]></programlisting>
<listitem><para><filename>/plc/root.img</filename>: The main
root filesystem of the MyPLC application. This file is an
uncompressed ext3 filesystem that is loopback mounted on
- <filename>/plc/root</filename> when MyPLC starts. The
- filesystem, even when mounted, should be treated an opaque
+ <filename>/plc/root</filename> 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.</para></listitem>
@@ -117,13 +120,14 @@ rpm2cpio myplc-0.3-1.planetlab.i386.rpm | cpio -diu]]></programlisting>
<listitem>
<para><filename>/plc/data</filename>: The directory where user
data and generated files are stored. This directory is bind
- mounted into the <command>chroot</command> jail on
- <filename>/data</filename>. Files in this directory are marked
- with <command>%config(noreplace)</command> 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 <filename>/plc/root/data</filename> so that it is
+ accessible as <filename>/data</filename> from within the
+ <command>chroot</command> jail. Files in this directory are
+ marked with <command>%config(noreplace)</command> 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
<filename>.rpmnew</filename> extension. Symlinks within the
MyPLC root filesystem ensure that the following directories
(relative to <filename>/plc/root</filename>) 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 <application>Security Level Configuration</application>
- utility to configure SELinux to be
+ mounting, bind mounting, and the ext3 filesystem. If you see an
+ error similar to <literal>Permission denied while trying to open
+ /plc/root.img</literal>, then SELinux may be enabled. If you
+ installed MyPLC on Fedora Core 4 or 5, use the
+ <application>Security Level Configuration</application> utility
+ to configure SELinux to be
<literal>Permissive</literal>.</para></listitem>
<listitem><para><literal>Starting database server</literal>: If
@@ -476,6 +482,279 @@ vserver pl_conf exec service pl_conf restart]]></programlisting>
</section>
</section>
+ <section>
+ <title>Rebuilding and customizing MyPLC</title>
+
+ <para>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.</para>
+
+ <para>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
+ <command>chroot</command> 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.</para>
+
+ <section>
+ <title>Installation</title>
+
+ <para>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
+ <command>chroot</command> jail should not be modified directly, as
+ they are subject to upgrade.</para>
+
+ <example>
+ <title>Installing the MyPLC development environment.</title>
+
+ <programlisting><![CDATA[# 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]]></programlisting>
+ </example>
+
+ <para>The MyPLC development environment installs the following
+ files and directories:</para>
+
+ <itemizedlist>
+ <listitem><para><filename>/plc/devel/root.img</filename>: The
+ main root filesystem of the MyPLC development environment. This
+ file is an uncompressed ext3 filesystem that is loopback mounted
+ on <filename>/plc/devel/root</filename> 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.</para></listitem>
+
+ <listitem><para><filename>/plc/devel/root</filename>: The mount
+ point for
+ <filename>/plc/devel/root.img</filename>.</para></listitem>
+
+ <listitem>
+ <para><filename>/plc/devel/data</filename>: The directory
+ where user data and generated files are stored. This directory
+ is bind mounted onto <filename>/plc/devel/root/data</filename>
+ so that it is accessible as <filename>/data</filename> from
+ within the <command>chroot</command> jail. Files in this
+ directory are marked with
+ <command>%config(noreplace)</command> in the RPM. Symlinks
+ ensure that the following directories (relative to
+ <filename>/plc/devel/root</filename>) are stored outside the
+ root filesystem image:</para>
+
+ <itemizedlist>
+ <listitem><para><filename>/etc/planetlab</filename>: This
+ directory contains the configuration files that define your
+ MyPLC development environment.</para></listitem>
+
+ <listitem><para><filename>/cvs</filename>: A
+ snapshot of the PlanetLab source code is stored as a CVS
+ repository in this directory. Files in this directory will
+ <emphasis role="bold">not</emphasis> be updated by an upgrade of
+ <filename>myplc-devel</filename>. See <xref
+ linkend="UpdatingCVS" /> for more information about updating
+ PlanetLab source code.</para></listitem>
+
+ <listitem><para><filename>/build</filename>:
+ Builds are stored in this directory. This directory is bind
+ mounted onto <filename>/plc/devel/root/build</filename> so that
+ it is accessible as <filename>/build</filename> from within the
+ <command>chroot</command> jail. The build scripts in this
+ directory are themselves source controlled; see <xref
+ linkend="BuildingMyPLC" /> for more information about executing
+ builds.</para></listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para><filename>/etc/init.d/plc-devel</filename>: 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.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Fedora Core 4 mirror requirement</title>
+
+ <para>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
+ <envar>PLC_DEVEL_FEDORA_URL</envar> variable in
+ <filename>/plc/devel/data/etc/planetlab/plc_config.xml</filename>. The
+ value of the variable should be a URL that points to the top
+ level of a Fedora mirror that provides the
+ <filename>base</filename>, <filename>updates</filename>, and
+ <filename>extras</filename> repositories, e.g.,</para>
+
+ <itemizedlist>
+ <listitem><para><filename>file:///data/fedora</filename></para></listitem>
+ <listitem><para><filename>http://coblitz.planet-lab.org/pub/fedora</filename></para></listitem>
+ <listitem><para><filename>ftp://mirror.cs.princeton.edu/pub/mirrors/fedora</filename></para></listitem>
+ <listitem><para><filename>ftp://mirror.stanford.edu/pub/mirrors/fedora</filename></para></listitem>
+ <listitem><para><filename>http://rpmfind.net/linux/fedora</filename></para></listitem>
+ </itemizedlist>
+
+ <para>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 <filename>file://</filename>
+ should exist at the specified location relative to the root of
+ the <command>chroot</command> jail. For optimum performance and
+ reproducibility, specify
+ <envar>PLC_DEVEL_FEDORA_URL=file:///data/fedora</envar> and
+ download all Fedora Core 4 RPMS into
+ <filename>/plc/devel/data/fedora</filename> on the host system
+ after installing <filename>myplc-devel</filename>. Use a tool
+ such as <command>wget</command> or <command>rsync</command> to
+ download the RPMS from a public mirror:</para>
+
+ <example>
+ <title>Setting up a local Fedora Core 4 repository.</title>
+
+ <programlisting><![CDATA[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]]></programlisting>
+ </example>
+
+ <para>Change the repository URI and <command>--cut-dirs</command>
+ level as needed to produce a hierarchy that resembles:</para>
+
+ <programlisting><![CDATA[/plc/devel/data/fedora/core/4/i386/os
+/plc/devel/data/fedora/core/updates/4/i386
+/plc/devel/data/fedora/extras/4/i386]]></programlisting>
+
+ <para>A list of additional Fedora Core 4 mirrors is available at
+ <ulink url="http://fedora.redhat.com/Download/mirrors.html">http://fedora.redhat.com/Download/mirrors.html</ulink>.</para>
+ </section>
+
+ <section id="BuildingMyPLC">
+ <title>Building MyPLC</title>
+
+ <para>All PlanetLab source code modules are built and installed
+ as RPMS. A set of build scripts, checked into the
+ <filename>build/</filename> directory of the PlanetLab CVS
+ repository, eases the task of rebuilding PlanetLab source
+ code.</para>
+
+ <para>To build MyPLC, or any PlanetLab source code module, from
+ within the MyPLC development environment, execute the following
+ commands as root:</para>
+
+ <example>
+ <title>Building MyPLC.</title>
+
+ <programlisting><![CDATA[# 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]]></programlisting>
+ </example>
+
+ <para>If the build succeeds, a set of binary RPMS will be
+ installed under
+ <filename>/plc/devel/data/build/$DATE/RPMS/</filename> that you
+ may copy to the
+ <filename>/var/www/html/install-rpms/planetlab</filename>
+ directory of your MyPLC installation (see <xref
+ linkend="Installation" />).</para>
+ </section>
+
+ <section id="UpdatingCVS">
+ <title>Updating CVS</title>
+
+ <para>A complete snapshot of the PlanetLab source code is included
+ with the MyPLC development environment as a CVS repository in
+ <filename>/plc/devel/data/cvs</filename>. This CVS repository may
+ be accessed like any other CVS repository. It may be accessed
+ using an interface such as <ulink
+ url="http://www.freebsd.org/projects/cvsweb.html">CVSweb</ulink>,
+ and file permissions may be altered to allow for fine-grained
+ access control. Although the files are included with the
+ <filename>myplc-devel</filename> RPM, they are <emphasis
+ role="bold">not</emphasis> subject to upgrade once installed. New
+ versions of the <filename>myplc-devel</filename> RPM will install
+ updated snapshot repositories in
+ <filename>/plc/devel/data/cvs-%{version}-%{release}</filename>,
+ where <literal>%{version}-%{release}</literal> is replaced with
+ the version number of the RPM.</para>
+
+ <para>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 <ulink
+ url="http://ximbiot.com/cvs/wiki/index.php?title=CVS--Concurrent_Versions_System_v1.12.12.1:_Tracking_third-party_sources">vendor
+ branches</ulink> 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
+ <filename>myplc-devel-0.4-2</filename> to
+ <filename>myplc-devel-0.4-3</filename> and you notice the new
+ repository in <filename>/plc/devel/data/cvs-0.4-3</filename>),
+ execute the following commands as root from within the MyPLC
+ development environment:</para>
+
+ <example>
+ <title>Updating /data/cvs from /data/cvs-0.4-3.</title>
+
+ <para><emphasis role="bold">Warning</emphasis>: This may cause
+ severe, irreversible changes to be made to your local
+ repository. Always tag your local repository before
+ importing.</para>
+
+ <programlisting><![CDATA[# 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]]></programlisting>
+ </example>
+
+ <para>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.</para>
+ </section>
+ </section>
+
<appendix>
<title>Configuration variables</title>
@@ -489,6 +768,12 @@ vserver pl_conf exec service pl_conf restart]]></programlisting>
&Variables;
</appendix>
+ <appendix>
+ <title>Development environment configuration variables</title>
+
+ &DevelVariables;
+ </appendix>
+
<bibliography>
<title>Bibliography</title>
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 @@
+<variablelist>
+ <varlistentry>
+ <term>PLC_DEVEL_FEDORA_RELEASE</term>
+ <listitem>
+ <para>
+ Type: string</para>
+ <para>
+ Default: 4</para>
+ <para>Version number of Fedora Core upon which to
+ base the build environment. Warning: Currently, only Fedora
+ Core 4 is supported.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_DEVEL_FEDORA_ARCH</term>
+ <listitem>
+ <para>
+ Type: string</para>
+ <para>
+ Default: i386</para>
+ <para>Base architecture of the build
+ environment. Warning: Currently, only i386 is
+ supported.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_DEVEL_FEDORA_URL</term>
+ <listitem>
+ <para>
+ Type: string</para>
+ <para>
+ Default: file:///usr/share/mirrors/fedora</para>
+ <para>Fedora Core mirror from which to install
+ filesystems.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_DEVEL_CVSROOT</term>
+ <listitem>
+ <para>
+ Type: string</para>
+ <para>
+ Default: /cvs</para>
+ <para>CVSROOT to use when checking out code.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_DEVEL_BOOTSTRAP</term>
+ <listitem>
+ <para>
+ Type: boolean</para>
+ <para>
+ Default: false</para>
+ <para>Controls whether MyPLC should be built inside
+ of its own development environment.</para>
+ </listitem>
+ </varlistentry>
+</variablelist>
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.</para>
</listitem>
</varlistentry>
- <varlistentry>
- <term>PLC_ROOT_CA_SSL_KEY</term>
- <listitem>
- <para>
- Type: file</para>
- <para>
- Default: /etc/planetlab/root_ca_ssl.key</para>
- <para>The SSL private key used for signing all other
- generated certificates. If non-existent, one will be
- generated.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>PLC_ROOT_CA_SSL_KEY_PUB</term>
- <listitem>
- <para>
- Type: file</para>
- <para>
- Default: /etc/planetlab/root_ca_ssl.pub</para>
- <para>The corresponding SSL public key.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>PLC_ROOT_CA_SSL_CRT</term>
- <listitem>
- <para>
- Type: file</para>
- <para>
- Default: /etc/planetlab/root_ca_ssl.crt</para>
- <para>The corresponding SSL public
- certificate.</para>
- </listitem>
- </varlistentry>
<varlistentry>
<term>PLC_MA_SA_NAMESPACE</term>
<listitem>
@@ -174,24 +141,40 @@
</listitem>
</varlistentry>
<varlistentry>
- <term>PLC_MA_SA_SSL_KEY_PUB</term>
+ <term>PLC_MA_SA_SSL_CRT</term>
<listitem>
<para>
Type: file</para>
<para>
- Default: /etc/planetlab/ma_sa_ssl.pub</para>
- <para>The corresponding SSL public key.</para>
+ Default: /etc/planetlab/ma_sa_ssl.crt</para>
+ <para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>PLC_MA_SA_SSL_CRT</term>
+ <term>PLC_MA_SA_CA_SSL_CRT</term>
<listitem>
<para>
Type: file</para>
<para>
- Default: /etc/planetlab/ma_sa_ssl.crt</para>
- <para>The corresponding SSL public certificate,
- signed by the root CA.</para>
+ Default: /etc/planetlab/ma_sa_ca_ssl.crt</para>
+ <para>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.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_MA_SA_CA_SSL_KEY_PUB</term>
+ <listitem>
+ <para>
+ Type: file</para>
+ <para>
+ Default: /etc/planetlab/ma_sa_ca_ssl.pub</para>
+ <para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -201,11 +184,11 @@
Type: file</para>
<para>
Default: /etc/planetlab/ma_sa_api.xml</para>
- <para>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.</para>
+ <para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -505,8 +488,23 @@
Type: file</para>
<para>
Default: /etc/planetlab/api_ssl.crt</para>
- <para>The corresponding SSL public certificate,
- signed by the root CA.</para>
+ <para>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.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_API_CA_SSL_CRT</term>
+ <listitem>
+ <para>
+ Type: file</para>
+ <para>
+ Default: /etc/planetlab/api_ca_ssl.crt</para>
+ <para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -595,8 +593,23 @@
Type: file</para>
<para>
Default: /etc/planetlab/www_ssl.crt</para>
- <para>The corresponding SSL public certificate,
- signed by the root CA.</para>
+ <para>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.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_WWW_CA_SSL_CRT</term>
+ <listitem>
+ <para>
+ Type: file</para>
+ <para>
+ Default: /etc/planetlab/www_ca_ssl.crt</para>
+ <para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -664,8 +677,7 @@
<para>
Default: /etc/planetlab/boot_ssl.key</para>
<para>The SSL private key to use for encrypting HTTPS
- traffic. If non-existent, one will be
- generated.</para>
+ traffic.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -675,8 +687,23 @@
Type: file</para>
<para>
Default: /etc/planetlab/boot_ssl.crt</para>
- <para>The corresponding SSL public certificate,
- signed by the root CA.</para>
+ <para>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.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_BOOT_CA_SSL_CRT</term>
+ <listitem>
+ <para>
+ Type: file</para>
+ <para>
+ Default: /etc/planetlab/boot_ca_ssl.crt</para>
+ <para>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.</para>
</listitem>
</varlistentry>
</variablelist>