<?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>
<revhistory>
<revision>
<revnumber>1.0</revnumber>
-
<date>April 7, 2006</date>
-
<authorinitials>MLH</authorinitials>
-
+ <revdescription><para>Initial draft.</para></revdescription>
+ </revision>
+ <revision>
+ <revnumber>1.1</revnumber>
+ <date>July 19, 2006</date>
+ <authorinitials>MLH</authorinitials>
+ <revdescription><para>Add development environment.</para></revdescription>
+ </revision>
+ <revision>
+ <revnumber>1.2</revnumber>
+ <date>August 18, 2006</date>
+ <authorinitials>TPT</authorinitials>
<revdescription>
- <para>Initial draft.</para>
- </revdescription>
+ <para>Review section on configuration and introduce <command>plc-config-tty</command>.</para>
+ <para>Present implementation details last.</para>
+ </revdescription>
</revision>
</revhistory>
</articleinfo>
</caption>
</mediaobject>
</figure>
+
+ <section> <title> Purpose of the <emphasis> myplc-devel
+ </emphasis> package </title>
+ <para> The <emphasis>myplc</emphasis> package comes with all
+ required node software, rebuilt from the public PlanetLab CVS
+ repository. If for any reason you need to implement your own
+ customized version of this software, you can use the
+ <emphasis>myplc-devel</emphasis> package instead, for setting up
+ your own development environment, including a local CVS
+ repository; you can then freely manage your changes and rebuild
+ your customized version of <emphasis>myplc</emphasis>. We also
+ provide good practices, that will then allow you to resync your local
+ CVS repository with any further evolution on the mainstream public
+ PlanetLab software. </para> </section>
+
+ </section>
+
+
+ <section id="Requirements"> <title> Requirements </title>
+
+ <para> <emphasis>myplc</emphasis> and
+ <emphasis>myplc-devel</emphasis> were designed as
+ <command>chroot</command> jails so as to reduce the requirements on
+ your host operating system. So in theory, these distributions should
+ work on virtually any Linux 2.6 based distribution, whether it
+ supports rpm or not. </para>
+
+ <para> However, things are never that simple and there indeed are
+ some known limitations to this, so here are a couple notes as a
+ recommended reading before you proceed with the installation.</para>
+
+ <para> As of 17 August 2006 (i.e <emphasis>myplc-0.5-2</emphasis>) :</para>
+
+ <itemizedlist>
+ <listitem><para> The software is vastly based on <emphasis>Fedora
+ Core 4</emphasis>. Please note that the build server at Princeton
+ runs <emphasis>Fedora Core 2</emphasis>, togother with a upgraded
+ version of yum.
+ </para></listitem>
+
+ <listitem><para> myplc and myplc-devel are known to work on both
+ <emphasis>Fedora Core 2</emphasis> and <emphasis>Fedora Core
+ 4</emphasis>. Please note however that, on fc4 at least, it is
+ highly recommended to use the <application>Security Level
+ Configuration</application> utility and to <emphasis>switch off
+ SElinux</emphasis> on your box because : </para>
+
+ <itemizedlist>
+ <listitem><para>
+ myplc requires you to run SElinux as 'Permissive' at most
+ </para></listitem>
+ <listitem><para>
+ myplc-devel requires you to turn SElinux Off.
+ </para></listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem> <para> In addition, as far as myplc is concerned, you
+ need to check your firewall configuration since you need, of course,
+ to open up the <emphasis>http</emphasis> and
+ <emphasis>https</emphasis> ports, so as to accept connections from
+ the managed nodes and from the users desktops. </para> </listitem>
+
+ </itemizedlist>
</section>
- <section>
- <title>Installation</title>
+ <section id="Installation">
+ <title>Installating and using MyPLC</title>
<para>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:</para>
+ practically any Linux 2.6 based distribution.</para>
- <example>
+ <section>
<title>Installing MyPLC.</title>
- <programlisting><![CDATA[# If your distribution supports RPM
-rpm -U myplc-0.3-1.planetlab.i386.rpm
-
-# If your distribution does not support RPM
-cd /
-rpm2cpio myplc-0.3-1.planetlab.i386.rpm | cpio -diu]]></programlisting>
- </example>
-
- <para>MyPLC installs the following files and directories:</para>
-
- <itemizedlist>
-
- <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
- binary that can and will be replaced in its entirety by any
- upgrade of MyPLC.</para></listitem>
-
- <listitem><para><filename>/plc/root</filename>: The mount point
- for <filename>/plc/root.img</filename>. Once the root filesystem
- is mounted, all MyPLC services run in a
- <command>chroot</command> jail based in this
- directory.</para></listitem>
-
- <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
- <filename>.rpmnew</filename> extension. Symlinks within the
- MyPLC root filesystem ensure that the following directories
- (relative to <filename>/plc/root</filename>) are stored
- outside the MyPLC filesystem image:</para>
-
- <itemizedlist>
- <listitem><para><filename>/etc/planetlab</filename>: This
- directory contains the configuration files, keys, and
- certificates that define your MyPLC
- installation.</para></listitem>
-
- <listitem><para><filename>/var/lib/pgsql</filename>: This
- directory contains PostgreSQL database
- files.</para></listitem>
-
- <listitem><para><filename>/var/www/html/alpina-logs</filename>: This
- directory contains node installation logs.</para></listitem>
-
- <listitem><para><filename>/var/www/html/boot</filename>: This
- directory contains the Boot Manager, customized for your MyPLC
- installation, and its data files.</para></listitem>
-
- <listitem><para><filename>/var/www/html/download</filename>: This
- directory contains Boot CD images, customized for your MyPLC
- installation.</para></listitem>
-
- <listitem><para><filename>/var/www/html/install-rpms</filename>: This
- directory is where you should install node package updates,
- if any. By default, nodes are installed from the tarball
- located at
- <filename>/var/www/html/boot/PlanetLab-Bootstrap.tar.bz2</filename>,
- which is pre-built from the latest PlanetLab Central
- sources, and installed as part of your MyPLC
- installation. However, nodes will attempt to install any
- newer RPMs located in
- <filename>/var/www/html/install-rpms/planetlab</filename>,
- after initial installation and periodically thereafter. You
- must run <command>yum-arch</command> and
- <command>createrepo</command> to update the
- <command>yum</command> caches in this directory after
- installing a new RPM. PlanetLab Central cannot support any
- changes to this file.</para></listitem>
-
- <listitem><para><filename>/var/www/html/xml</filename>: This
- directory contains various XML files that the Slice Creation
- Service uses to determine the state of slices. These XML
- files are refreshed periodically by <command>cron</command>
- jobs running in the MyPLC root.</para></listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para><filename>/etc/init.d/plc</filename>: This file
- is a System V init script installed on your host filesystem,
- that allows you to start up and shut down MyPLC with a single
- command. On a Red Hat or Fedora host system, it is customary to
- use the <command>service</command> command to invoke System V
- init scripts:</para>
-
- <example id="StartingAndStoppingMyPLC">
- <title>Starting and stopping MyPLC.</title>
-
- <programlisting><![CDATA[# Starting MyPLC
-service plc start
-
-# Stopping MyPLC
-service plc stop]]></programlisting>
- </example>
-
- <para>Like all other registered System V init services, MyPLC is
- started and shut down automatically when your host system boots
- and powers off. You may disable automatic startup by invoking
- the <command>chkconfig</command> command on a Red Hat or Fedora
- host system:</para>
-
- <example>
- <title>Disabling automatic startup of MyPLC.</title>
-
- <programlisting><![CDATA[# Disable automatic startup
-chkconfig plc off
-
-# Enable automatic startup
-chkconfig plc on]]></programlisting>
- </example>
- </listitem>
-
- <listitem><para><filename>/etc/sysconfig/plc</filename>: This
- file is a shell script fragment that defines the variables
- <envar>PLC_ROOT</envar> and <envar>PLC_DATA</envar>. By default,
- the values of these variables are <filename>/plc/root</filename>
- and <filename>/plc/data</filename>, respectively. If you wish,
- you may move your MyPLC installation to another location on your
- host filesystem and edit the values of these variables
- appropriately, but you will break the RPM upgrade
- process. PlanetLab Central cannot support any changes to this
- file.</para></listitem>
-
- <listitem><para><filename>/etc/planetlab</filename>: This
- symlink to <filename>/plc/data/etc/planetlab</filename> is
- installed on the host system for convenience.</para></listitem>
+ <itemizedlist>
+ <listitem> <para>If your distribution supports RPM:</para>
+ <programlisting><![CDATA[# rpm -U http://build.planet-lab.org/build/myplc-0_4-rc1/RPMS/i386/myplc-0.4-1.planetlab.i386.rpm]]></programlisting></listitem>
+
+ <listitem> <para>If your distribution does not support RPM:</para>
+<programlisting><![CDATA[# cd /tmp
+# wget http://build.planet-lab.org/build/myplc-0_4-rc1/RPMS/i386/myplc-0.4-1.planetlab.i386.rpm
+# cd /
+# rpm2cpio /tmp/myplc-0.4-1.planetlab.i386.rpm | cpio -diu]]></programlisting></listitem>
</itemizedlist>
- </section>
- <section>
- <title>Quickstart</title>
+ <para> The <xref linkend="FilesInvolvedRuntime" /> below explains in
+ details the installation strategy and the miscellaneous files and
+ directories involved.</para>
+
+ </section>
- <para>Once installed, start MyPLC (see <xref
- linkend="StartingAndStoppingMyPLC" />). 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:</para>
+ <section id="QuickStart"> <title> QuickStart </title>
- <example>
- <title>A successful MyPLC startup.</title>
+ <para> On a Red Hat or Fedora host system, it is customary to use
+ the <command>service</command> command to invoke System V init
+ scripts. As the examples suggest, the service must be started as root:</para>
- <programlisting><![CDATA[Mounting PLC: [ OK ]
-PLC: Generating network files: [ OK ]
-PLC: Starting system logger: [ OK ]
-PLC: Starting database server: [ OK ]
-PLC: Generating SSL certificates: [ OK ]
-PLC: Generating SSH keys: [ OK ]
-PLC: Starting web server: [ OK ]
-PLC: Bootstrapping the database: [ OK ]
-PLC: Starting crond: [ OK ]
-PLC: Rebuilding Boot CD: [ OK ]
-PLC: Rebuilding Boot Manager: [ OK ]
-]]></programlisting>
+ <example><title>Starting MyPLC:</title>
+ <programlisting><![CDATA[# service plc start]]></programlisting>
+ </example>
+ <example><title>Stopping MyPLC:</title>
+ <programlisting><![CDATA[# service plc stop]]></programlisting>
</example>
- <para>If <filename>/plc/root</filename> is mounted successfully, a
- complete log file of the startup process may be found at
- <filename>/plc/root/var/log/boot.log</filename>. Possible reasons
- for failure of each step include:</para>
-
- <itemizedlist>
- <listitem><para><literal>Mounting PLC</literal>: If this step
- fails, first ensure that you started MyPLC as root. Check
- <filename>/etc/sysconfig/plc</filename> to ensure that
- <envar>PLC_ROOT</envar> and <envar>PLC_DATA</envar> refer to the
- right locations. You may also have too many existing loopback
- mounts, or your kernel may not support loopback mounting, bind
- mounting, or the ext3 filesystem. Try freeing at least one
- loopback device, or re-compiling your kernel to support loopback
- mounting, bind mounting, and the ext3
- filesystem.</para></listitem>
-
- <listitem><para><literal>Starting database server</literal>: If
- this step fails, check
- <filename>/plc/root/var/log/pgsql</filename> and
- <filename>/plc/root/var/log/boot.log</filename>. The most common
- reason for failure is that the default PostgreSQL port, TCP port
- 5432, is already in use. Check that you are not running a
- PostgreSQL server on the host system.</para></listitem>
-
- <listitem><para><literal>Starting web server</literal>: If this
- step fails, check
- <filename>/plc/root/var/log/httpd/error_log</filename> and
- <filename>/plc/root/var/log/boot.log</filename> for obvious
- errors. The most common reason for failure is that the default
- web ports, TCP ports 80 and 443, are already in use. Check that
- you are not running a web server on the host
- system.</para></listitem>
+ <para> In <xref linkend="StartupSequence" />, we provide greater
+ details that might be helpful in the case where the service does
+ not seem to take off correctly.</para>
- <listitem><para><literal>Bootstrapping the database</literal>:
- If this step fails, it is likely that the previous step
- (<literal>Starting web server</literal>) also failed. Another
- reason that it could fail is if <envar>PLC_API_HOST</envar> (see
- <xref linkend="ChangingTheConfiguration" />) does not resolve to
- the host on which the API server has been enabled. By default,
- all services, including the API server, are enabled and run on
- the same host, so check that <envar>PLC_API_HOST</envar> is
- either <filename>localhost</filename> or resolves to a local IP
- address.</para></listitem>
+ <para>Like all other registered System V init services, MyPLC is
+ started and shut down automatically when your host system boots
+ and powers off. You may disable automatic startup by invoking the
+ <command>chkconfig</command> command on a Red Hat or Fedora host
+ system:</para>
- <listitem><para><literal>Starting crond</literal>: If this step
- fails, it is likely that the previous steps (<literal>Starting
- web server</literal> and <literal>Bootstrapping the
- database</literal>) also failed. If not, check
- <filename>/plc/root/var/log/boot.log</filename> for obvious
- errors. This step starts the <command>cron</command> service and
- generates the initial set of XML files that the Slice Creation
- Service uses to determine slice state.</para></listitem>
- </itemizedlist>
+ <example> <title>Disabling automatic startup of MyPLC.</title>
+ <programlisting><![CDATA[# chkconfig plc off]]></programlisting></example>
+ <example> <title>Re-enabling automatic startup of MyPLC.</title>
+ <programlisting><![CDATA[# chkconfig plc on]]></programlisting></example>
- <para> Please also note that SELinux, when enabled, has been
- reported to prevent the system from operating smoothly. These
- reports were based on attempts made on FC4 and FC5. If you run any
- of those linux distributions, you should use the 'Security Level
- Configuration' utility and make sure SELinux is not configured as
- 'Enforcing', but as 'Permissive' at most. </para>
-
- <para>If no failures occur, then MyPLC should be active with a
- default configuration. Open a web browser on the host system and
- visit <literal>http://localhost/</literal>, which should bring you
- to the front page of your PLC installation. The password of the
- default administrator account
- <literal>root@localhost.localdomain</literal> (set by
- <envar>PLC_ROOT_USER</envar>) is <literal>root</literal> (set by
- <envar>PLC_ROOT_PASSWORD</envar>).</para>
+ </section>
- <section id="ChangingTheConfiguration">
+ <section id="Configuration">
<title>Changing the configuration</title>
<para>After verifying that MyPLC is working correctly, shut it
down and begin changing some of the default variable
values. Shut down MyPLC with <command>service plc stop</command>
- (see <xref linkend="StartingAndStoppingMyPLC" />). With a text
- editor, open the file
- <filename>/etc/planetlab/plc_config.xml</filename>. This file is
- a self-documenting configuration file written in XML. Variables
- are divided into categories. Variable identifiers must be
- alphanumeric, plus underscore. A variable is referred to
- canonically as the uppercase concatenation of its category
- identifier, an underscore, and its variable identifier. Thus, a
- variable with an <literal>id</literal> of
+ (see <xref linkend="QuickStart" />). </para>
+
+ <para> The preferred option for changing the configuration is to
+ use the <command>plc-config-tty</command> tool. This tool comes
+ with the root image, so you need to have it mounted first. The
+ full set of applicable variables is described in <xref
+ linkend="VariablesDevel" />, but using the <command>u</command>
+ guides you to the most useful ones. Note that if you
+ plan on federating with other PLCs, <emphasis> it is strongly
+ recommended that you change the <command> PLC_NAME
+ </command> and <command> PLC_SLICE_PREFIX </command>
+ settings. </emphasis>
+ Here is sample session:
+ </para>
+
+ <example><title>Using plc-config-tty for configuration:</title>
+ <programlisting><![CDATA[# service plc mount
+Mounting PLC: [ OK ]
+# chroot /plc/root su -
+<plc> # plc-config-tty
+Config file /etc/planetlab/configs/site.xml located under a non-existing directory
+Want to create /etc/planetlab/configs [y]/n ? y
+Created directory /etc/planetlab/configs
+Enter command (u for usual changes, w to save, ? for help) u
+== PLC_NAME : [PlanetLab Test] OneLab
+== PLC_SLICE_PREFIX : [pl] thone
+== PLC_ROOT_USER : [root@localhost.localdomain] root@onelab-plc.inria.fr
+== PLC_ROOT_PASSWORD : [root] plain-passwd
+== PLC_MAIL_ENABLED : [false] true
+== PLC_MAIL_SUPPORT_ADDRESS : [root+support@localhost.localdomain] support@one-lab.org
+== PLC_BOOT_HOST : [localhost.localdomain] onelab-plc.inria.fr
+== PLC_NET_DNS1 : [127.0.0.1] 138.96.250.248
+== PLC_NET_DNS2 : [None] 138.96.250.249
+Enter command (u for usual changes, w to save, ? for help) w
+Wrote /etc/planetlab/configs/site.xml
+Merged
+ /etc/planetlab/default_config.xml
+and /etc/planetlab/configs/site.xml
+into /etc/planetlab/plc_config.xml
+You might want to type 'r' (restart plc) or 'q' (quit)
+Enter command (u for usual changes, w to save, ? for help) r
+==================== Stopping plc
+...
+==================== Starting plc
+...
+Enter command (u for usual changes, w to save, ? for help) q
+<plc> # exit
+#
+]]></programlisting>
+ </example>
+
+ <para>If you used this method for configuring, you can skip to
+ the <xref linkend="LoginRealUser" />. As an alternative to using
+ <command>plc-config-tty</command>, you may also use a text
+ editor, but this requires some understanding on how the
+ configuration files are used within myplc. The
+ <emphasis>default</emphasis> configuration is stored in a file
+ named <filename>/etc/planetlab/default_config.xml</filename>,
+ that is designed to remain intact. You may store your local
+ changes in any file located in the <filename>configs/</filename>
+ sub-directory, that are loaded on top of the defaults. Finally
+ the file <filename>/etc/planetlab/plc_config.xml</filename> is
+ loaded, and the resulting configuration is stored in the latter
+ file, that is used as a reference.</para>
+
+ <para> Using a separate file for storing local changes only, as
+ <command>plc-config-tty</command> does, is not a workable option
+ with a text editor because it would involve tedious xml
+ re-assembling. So your local changes should go in
+ <filename>/etc/planetlab/plc_config.xml</filename>. Be warned
+ however that any change you might do this way could be lost if
+ you use <command>plc-config-tty</command> later on. </para>
+
+ <para>This file is a self-documenting configuration file written
+ in XML. Variables are divided into categories. Variable
+ identifiers must be alphanumeric, plus underscore. A variable is
+ referred to canonically as the uppercase concatenation of its
+ category identifier, an underscore, and its variable
+ identifier. Thus, a variable with an <literal>id</literal> of
<literal>slice_prefix</literal> in the <literal>plc</literal>
category is referred to canonically as
<envar>PLC_SLICE_PREFIX</envar>.</para>
<listitem><para><envar>PLC_ROOT_PASSWORD</envar>: Change this
to a more secure password.</para></listitem>
- <listitem><para><envar>PLC_NET_DNS1</envar>,
- <envar>PLC_NET_DNS2</envar>: Change these to the IP addresses
- of your primary and secondary DNS servers. Check
- <filename>/etc/resolv.conf</filename> on your host
- filesystem.</para></listitem>
-
<listitem><para><envar>PLC_MAIL_SUPPORT_ADDRESS</envar>:
Change this to the e-mail address at which you would like to
receive support requests.</para></listitem>
<listitem><para><envar>PLC_DB_HOST</envar>,
- <envar>PLC_API_HOST</envar>, <envar>PLC_WWW_HOST</envar>,
- <envar>PLC_BOOT_HOST</envar>: Change all of these to the
- preferred FQDN of your host system.</para></listitem>
+ <envar>PLC_DB_IP</envar>, <envar>PLC_API_HOST</envar>,
+ <envar>PLC_API_IP</envar>, <envar>PLC_WWW_HOST</envar>,
+ <envar>PLC_WWW_IP</envar>, <envar>PLC_BOOT_HOST</envar>,
+ <envar>PLC_BOOT_IP</envar>: Change all of these to the
+ preferred FQDN and external IP address of your host
+ system.</para></listitem>
</itemizedlist>
- <para>After changing these variables, save the file, then
- restart MyPLC with <command>service plc start</command>. You
- should notice that the password of the default administrator
- account is no longer <literal>root</literal>, and that the
- default site name includes the name of your PLC installation
- instead of PlanetLab.</para>
- </section>
+ <para> After changing these variables,
+ save the file, then restart MyPLC with <command>service plc
+ start</command>. You should notice that the password of the
+ default administrator account is no longer
+ <literal>root</literal>, and that the default site name includes
+ the name of your PLC installation instead of PlanetLab. As a
+ side effect of these changes, the ISO images for the boot CDs
+ now have new names, so that you can freely remove the ones names
+ after 'PlanetLab Test', which is the default value of
+ <envar>PLC_NAME</envar> </para>
+ </section>
+
+ <section id="LoginRealUser"> <title> Login as a real user </title>
+
+ <para>Now that myplc is up and running, you can connect to the
+ web site that by default runs on port 80. You can either
+ directly use the default administrator user that you configured
+ in <envar>PLC_ROOT_USER</envar> and
+ <envar>PLC_ROOT_PASSWORD</envar>, or create a real user through
+ the 'Joining' tab. Do not forget to select both PI and tech
+ roles, and to select the only site created at this stage.
+ Login as the administrator to enable this user, then login as
+ the real user.</para>
+ </section>
<section>
<title>Installing nodes</title>
vserver pl_conf exec service pl_conf restart]]></programlisting>
</example>
</section>
+
+ <section id="StartupSequence">
+ <title>Understanding the startup sequence</title>
+
+ <para>During service startup described in <xref
+ linkend="QuickStart" />, observe the output of this command for
+ any failures. If no failures occur, you should see output similar
+ to the following:</para>
+
+ <example>
+ <title>A successful MyPLC startup.</title>
+
+ <programlisting><![CDATA[Mounting PLC: [ OK ]
+PLC: Generating network files: [ OK ]
+PLC: Starting system logger: [ OK ]
+PLC: Starting database server: [ OK ]
+PLC: Generating SSL certificates: [ OK ]
+PLC: Configuring the API: [ OK ]
+PLC: Updating GPG keys: [ OK ]
+PLC: Generating SSH keys: [ OK ]
+PLC: Starting web server: [ OK ]
+PLC: Bootstrapping the database: [ OK ]
+PLC: Starting DNS server: [ OK ]
+PLC: Starting crond: [ OK ]
+PLC: Rebuilding Boot CD: [ OK ]
+PLC: Rebuilding Boot Manager: [ OK ]
+PLC: Signing node packages: [ OK ]
+]]></programlisting>
+ </example>
+
+ <para>If <filename>/plc/root</filename> is mounted successfully, a
+ complete log file of the startup process may be found at
+ <filename>/plc/root/var/log/boot.log</filename>. Possible reasons
+ for failure of each step include:</para>
+
+ <itemizedlist>
+ <listitem><para><literal>Mounting PLC</literal>: If this step
+ fails, first ensure that you started MyPLC as root. Check
+ <filename>/etc/sysconfig/plc</filename> to ensure that
+ <envar>PLC_ROOT</envar> and <envar>PLC_DATA</envar> refer to the
+ right locations. You may also have too many existing loopback
+ mounts, or your kernel may not support loopback mounting, bind
+ mounting, or the ext3 filesystem. Try freeing at least one
+ loopback device, or re-compiling your kernel to support loopback
+ mounting, bind mounting, and the ext3 filesystem. If you see an
+ error similar to <literal>Permission denied while trying to open
+ /plc/root.img</literal>, then SELinux may be enabled. See <xref
+ linkend="Requirements" /> above for details.</para></listitem>
+
+ <listitem><para><literal>Starting database server</literal>: If
+ this step fails, check
+ <filename>/plc/root/var/log/pgsql</filename> and
+ <filename>/plc/root/var/log/boot.log</filename>. The most common
+ reason for failure is that the default PostgreSQL port, TCP port
+ 5432, is already in use. Check that you are not running a
+ PostgreSQL server on the host system.</para></listitem>
+
+ <listitem><para><literal>Starting web server</literal>: If this
+ step fails, check
+ <filename>/plc/root/var/log/httpd/error_log</filename> and
+ <filename>/plc/root/var/log/boot.log</filename> for obvious
+ errors. The most common reason for failure is that the default
+ web ports, TCP ports 80 and 443, are already in use. Check that
+ you are not running a web server on the host
+ system.</para></listitem>
+
+ <listitem><para><literal>Bootstrapping the database</literal>:
+ If this step fails, it is likely that the previous step
+ (<literal>Starting web server</literal>) also failed. Another
+ reason that it could fail is if <envar>PLC_API_HOST</envar> (see
+ <xref linkend="Configuration" />) does not resolve to
+ the host on which the API server has been enabled. By default,
+ all services, including the API server, are enabled and run on
+ the same host, so check that <envar>PLC_API_HOST</envar> is
+ either <filename>localhost</filename> or resolves to a local IP
+ address. Also check that <envar>PLC_ROOT_USER</envar> looks like
+ an e-mail address.</para></listitem>
+
+ <listitem><para><literal>Starting crond</literal>: If this step
+ fails, it is likely that the previous steps (<literal>Starting
+ web server</literal> and <literal>Bootstrapping the
+ database</literal>) also failed. If not, check
+ <filename>/plc/root/var/log/boot.log</filename> for obvious
+ errors. This step starts the <command>cron</command> service and
+ generates the initial set of XML files that the Slice Creation
+ Service uses to determine slice state.</para></listitem>
+ </itemizedlist>
+
+ <para>If no failures occur, then MyPLC should be active with a
+ default configuration. Open a web browser on the host system and
+ visit <literal>http://localhost/</literal>, which should bring you
+ to the front page of your PLC installation. The password of the
+ default administrator account
+ <literal>root@localhost.localdomain</literal> (set by
+ <envar>PLC_ROOT_USER</envar>) is <literal>root</literal> (set by
+ <envar>PLC_ROOT_PASSWORD</envar>).</para>
+ </section>
+
+ <section id="FilesInvolvedRuntime"> <title> Files and directories
+ involved in <emphasis>myplc</emphasis></title>
+ <para>MyPLC installs the following files and directories:</para>
+
+ <orderedlist>
+
+ <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. 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>
+
+ <listitem><para><filename>/plc/root</filename>: The mount point
+ for <filename>/plc/root.img</filename>. Once the root filesystem
+ is mounted, all MyPLC services run in a
+ <command>chroot</command> jail based in this
+ directory.</para></listitem>
+
+ <listitem>
+ <para><filename>/plc/data</filename>: The directory where user
+ data and generated files are stored. This directory is bind
+ 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
+ outside the MyPLC filesystem image:</para>
+
+ <itemizedlist>
+ <listitem><para><filename>/etc/planetlab</filename>: This
+ directory contains the configuration files, keys, and
+ certificates that define your MyPLC
+ installation.</para></listitem>
+
+ <listitem><para><filename>/var/lib/pgsql</filename>: This
+ directory contains PostgreSQL database
+ files.</para></listitem>
+
+ <listitem><para><filename>/var/www/html/alpina-logs</filename>: This
+ directory contains node installation logs.</para></listitem>
+
+ <listitem><para><filename>/var/www/html/boot</filename>: This
+ directory contains the Boot Manager, customized for your MyPLC
+ installation, and its data files.</para></listitem>
+
+ <listitem><para><filename>/var/www/html/download</filename>: This
+ directory contains Boot CD images, customized for your MyPLC
+ installation.</para></listitem>
+
+ <listitem><para><filename>/var/www/html/install-rpms</filename>: This
+ directory is where you should install node package updates,
+ if any. By default, nodes are installed from the tarball
+ located at
+ <filename>/var/www/html/boot/PlanetLab-Bootstrap.tar.bz2</filename>,
+ which is pre-built from the latest PlanetLab Central
+ sources, and installed as part of your MyPLC
+ installation. However, nodes will attempt to install any
+ newer RPMs located in
+ <filename>/var/www/html/install-rpms/planetlab</filename>,
+ after initial installation and periodically thereafter. You
+ must run <command>yum-arch</command> and
+ <command>createrepo</command> to update the
+ <command>yum</command> caches in this directory after
+ installing a new RPM. PlanetLab Central cannot support any
+ changes to this directory.</para></listitem>
+
+ <listitem><para><filename>/var/www/html/xml</filename>: This
+ directory contains various XML files that the Slice Creation
+ Service uses to determine the state of slices. These XML
+ files are refreshed periodically by <command>cron</command>
+ jobs running in the MyPLC root.</para></listitem>
+
+ <listitem><para><filename>/root</filename>: this is the
+ location of the root-user's homedir, and for your
+ convenience is stored under <filename>/data</filename> so
+ that your local customizations survive across
+ updates - this feature is inherited from the
+ <command>myplc-devel</command> package, where it is probably
+ more useful. </para></listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ <listitem id="MyplcInitScripts">
+ <para><filename>/etc/init.d/plc</filename>: This file
+ is a System V init script installed on your host filesystem,
+ that allows you to start up and shut down MyPLC with a single
+ command, as described in <xref linkend="QuickStart" />.</para>
+ </listitem>
+
+ <listitem><para><filename>/etc/sysconfig/plc</filename>: This
+ file is a shell script fragment that defines the variables
+ <envar>PLC_ROOT</envar> and <envar>PLC_DATA</envar>. By default,
+ the values of these variables are <filename>/plc/root</filename>
+ and <filename>/plc/data</filename>, respectively. If you wish,
+ you may move your MyPLC installation to another location on your
+ host filesystem and edit the values of these variables
+ appropriately, but you will break the RPM upgrade
+ process. PlanetLab Central cannot support any changes to this
+ file.</para></listitem>
+
+ <listitem><para><filename>/etc/planetlab</filename>: This
+ symlink to <filename>/plc/data/etc/planetlab</filename> is
+ installed on the host system for convenience.</para></listitem>
+ </orderedlist>
+ </section>
</section>
- <appendix>
- <title>Configuration variables</title>
+ <section id="DevelopmentEnvironment">
+ <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>
+
+ <itemizedlist>
+ <listitem> <para>If your distribution supports RPM:</para>
+ <programlisting><![CDATA[# rpm -U http://build.planet-lab.org/build/myplc-0_4-rc2/RPMS/i386/myplc-devel-0.4-2.planetlab.i386.rpm]]></programlisting></listitem>
+
+ <listitem> <para>If your distribution does not support RPM:</para>
+<programlisting><![CDATA[# 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></listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Configuration</title>
+
+ <para> The default configuration should work as-is on most
+ sites. Configuring the development package can be achieved in a
+ similar way as for <emphasis>myplc</emphasis>, as described in
+ <xref linkend="Configuration"
+ />. <command>plc-config-tty</command> supports a
+ <emphasis>-d</emphasis> option for supporting the
+ <emphasis>myplc-devel</emphasis> case, that can be useful in a
+ context where it would not guess it by itself. Refer to <xref
+ linkend="VariablesDevel" /> for a list of variables.</para>
+ </section>
+
+ <section id="FilesInvolvedDevel"> <title> Files and directories
+ involved in <emphasis>myplc-devl</emphasis></title>
+
+ <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>
+
+ <listitem><para><filename>/root</filename>: this is the
+ location of the root-user's homedir, and for your
+ convenience is stored under <filename>/data</filename> so
+ that your local customizations survive across
+ updates. </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> Before you try building MyPLC, you might check the
+ configuration, in a file named
+ <emphasis>plc_config.xml</emphasis> that relies on a very
+ similar model as MyPLC, located in
+ <emphasis>/etc/planetlab</emphasis> within the chroot jail, or
+ in <emphasis>/plc/devel/data/etc/planetlab</emphasis> from the
+ root context. The set of applicable variables is described in
+ <xref linkend="VariablesDevel" />. </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 vendor branches to track changes, as
+ described <ulink
+ url="http://ximbiot.com/cvs/wiki/index.php?title=CVS--Concurrent_Versions_System_v1.12.12.1:_Tracking_third-party_sources">here</ulink>
+ and <ulink
+ url="http://cvsbook.red-bean.com/cvsbook.html#Tracking%20Third-Party%20Sources%20(Vendor%20Branches)">here</ulink>.
+ 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 "Merging myplc-0.4-3" -ko -I ! . planetlab myplc-0_4-3
+popd
+rm -rf $TMP]]></programlisting>
+ </example>
+
+ <para>If there are any merge conflicts, use the command
+ suggested by CVS to help the merge. Explaining how to fix merge
+ conflicts is beyond the scope of this document; consult the CVS
+ documentation for more information on how to use CVS.</para>
+ </section> </section>
+
+<section><title> More information : the FAQ wiki page</title>
+
+<para> Please refer to, and feel free to contribute, <ulink
+url="https://wiki.planet-lab.org/twiki/bin/view/Planetlab/MyplcFAQ">
+the FAQ page on the Princeton's wiki </ulink>.</para></section>
+
+ <appendix id="VariablesRuntime">
+ <title>Configuration variables (for <emphasis>myplc</emphasis>)</title>
<para>Listed below is the set of standard configuration variables
and their default values, defined in the template
templates that should be placed in
<filename>/etc/planetlab/configs/</filename>.</para>
- &Variables;
+ <para>This information is available online within
+ <command>plc-config-tty</command>, e.g.:</para>
+
+<example><title>Advanced usage of plc-config-tty</title>
+<programlisting><![CDATA[<plc> # plc-config-tty
+Enter command (u for usual changes, w to save, ? for help) V plc_dns
+========== Category = PLC_DNS
+### Enable DNS
+# Enable the internal DNS server. The server does not provide reverse
+# resolution and is not a production quality or scalable DNS solution.
+# Use the internal DNS server only for small deployments or for testing.
+PLC_DNS_ENABLED
+]]></programlisting></example>
+
+ <para> List of the <command>myplc</command> configuration variables:</para>
+ &Variables;
+ </appendix>
+
+ <appendix id="VariablesDevel">
+ <title>Development configuration variables (for <emphasis>myplc-devel</emphasis>)</title>
+
+ &DevelVariables;
</appendix>
<bibliography>
git://git.onelab.eu / myplc.git / blobdiff