doc/myplc.php

   1 <?php
   2
   3   // DO NOT EDIT. This file was automatically generated from
   4   // DocBook XML. See plc_www/doc/README.
   5
   6   $_title= "MyPLC User's Guide";
   7
   8   require_once('session.php');
   9   require_once('header.php');
  10   require_once('nav.php');
  11
  12   ?><div class="article" lang="en">
  13 <div class="titlepage">
  14 <div>
  15 <div><h1 class="title">
  16 <a name="id224920"></a>MyPLC User's Guide</h1></div>
  17 <div><div class="author"><h3 class="author"><span class="firstname">Mark Huang</span></h3></div></div>
  18 <div><div class="revhistory"><table border="1" width="100%" summary="Revision history">
  19 <tr><th align="left" valign="top" colspan="3"><b>Revision History</b></th></tr>
  20 <tr>
  21 <td align="left">Revision 1.0</td>
  22 <td align="left">April 7, 2006</td>
  23 <td align="left">MLH</td>
  24 </tr>
  25 <tr><td align="left" colspan="3"><p>Initial draft.</p></td></tr>
  26 <tr>
  27 <td align="left">Revision 1.1</td>
  28 <td align="left">July 19, 2006</td>
  29 <td align="left">MLH</td>
  30 </tr>
  31 <tr><td align="left" colspan="3"><p>Add development environment.</p></td></tr>
  32 </table></div></div>
  33 <div><div class="abstract">
  34 <p class="title"><b>Abstract</b></p>
  35 <p>This document describes the design, installation, and
  36       administration of MyPLC, a complete PlanetLab Central (PLC)
  37       portable installation contained within a
  38       <span><strong class="command">chroot</strong></span> jail. This document assumes advanced
  39       knowledge of the PlanetLab architecture and Linux system
  40       administration.</p>
  41 </div></div>
  42 </div>
  43 <hr>
  44 </div>
  45 <div class="toc">
  46 <p><b>Table of Contents</b></p>
  47 <dl>
  48 <dt><span class="section"><a href="#id225375">1. Overview</a></span></dt>
  49 <dt><span class="section"><a href="#Installation">2. Installation</a></span></dt>
  50 <dt><span class="section"><a href="#id267694">3. Quickstart</a></span></dt>
  51 <dd><dl>
  52 <dt><span class="section"><a href="#ChangingTheConfiguration">3.1. Changing the configuration</a></span></dt>
  53 <dt><span class="section"><a href="#id268201">3.2. Installing nodes</a></span></dt>
  54 <dt><span class="section"><a href="#id268275">3.3. Administering nodes</a></span></dt>
  55 <dt><span class="section"><a href="#id268369">3.4. Creating a slice</a></span></dt>
  56 </dl></dd>
  57 <dt><span class="section"><a href="#id268444">4. Rebuilding and customizing MyPLC</a></span></dt>
  58 <dd><dl>
  59 <dt><span class="section"><a href="#id268469">4.1. Installation</a></span></dt>
  60 <dt><span class="section"><a href="#id268676">4.2. Fedora Core 4 mirror requirement</a></span></dt>
  61 <dt><span class="section"><a href="#BuildingMyPLC">4.3. Building MyPLC</a></span></dt>
  62 <dt><span class="section"><a href="#UpdatingCVS">4.4. Updating CVS</a></span></dt>
  63 </dl></dd>
  64 <dt><span class="appendix"><a href="#id269037">A. Configuration variables</a></span></dt>
  65 <dt><span class="appendix"><a href="#id271742">B. Development environment configuration variables</a></span></dt>
  66 <dt><span class="bibliography"><a href="#id271824">Bibliography</a></span></dt>
  67 </dl>
  68 </div>
  69 <div class="section" lang="en">
  70 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  71 <a name="id225375"></a>1. Overview</h2></div></div></div>
  72 <p>MyPLC is a complete PlanetLab Central (PLC) portable
  73     installation contained within a <span><strong class="command">chroot</strong></span>
  74     jail. The default installation consists of a web server, an
  75     XML-RPC API server, a boot server, and a database server: the core
  76     components of PLC. The installation is customized through an
  77     easy-to-use graphical interface. All PLC services are started up
  78     and shut down through a single script installed on the host
  79     system. The usually complex process of installing and
  80     administering the PlanetLab backend is reduced by containing PLC
  81     services within a virtual filesystem. By packaging it in such a
  82     manner, MyPLC may also be run on any modern Linux distribution,
  83     and could conceivably even run in a PlanetLab slice.</p>
  84 <div class="figure">
  85 <a name="Architecture"></a><p class="title"><b>Figure 1. MyPLC architecture</b></p>
  86 <div class="mediaobject" align="center">
  87 <img src="architecture.png" align="middle" width="270" alt="MyPLC architecture"><div class="caption"><p>MyPLC should be viewed as a single application that
  88           provides multiple functions and can run on any host
  89           system.</p></div>
  90 </div>
  91 </div>
  92 </div>
  93 <div class="section" lang="en">
  94 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  95 <a name="Installation"></a>2. Installation</h2></div></div></div>
  96 <p>Though internally composed of commodity software
  97     subpackages, MyPLC should be treated as a monolithic software
  98     application. MyPLC is distributed as single RPM package that has
  99     no external dependencies, allowing it to be installed on
 100     practically any Linux 2.6 based distribution:</p>
 101 <div class="example">
 102 <a name="id225278"></a><p class="title"><b>Example 1. Installing MyPLC.</b></p>
 103 <pre class="programlisting"># If your distribution supports RPM
 104 rpm -U http://build.planet-lab.org/build/myplc-0_4-rc1/RPMS/i386/myplc-0.4-1.planetlab.i386.rpm
 105
 106 # If your distribution does not support RPM
 107 cd /tmp
 108 wget http://build.planet-lab.org/build/myplc-0_4-rc1/RPMS/i386/myplc-0.4-1.planetlab.i386.rpm
 109 cd /
 110 rpm2cpio /tmp/myplc-0.4-1.planetlab.i386.rpm | cpio -diu</pre>
 111 </div>
 112 <p>MyPLC installs the following files and directories:</p>
 113 <div class="itemizedlist"><ul type="disc">
 114 <li><p><code class="filename">/plc/root.img</code>: The main
 115       root filesystem of the MyPLC application. This file is an
 116       uncompressed ext3 filesystem that is loopback mounted on
 117       <code class="filename">/plc/root</code> when MyPLC starts. This
 118       filesystem, even when mounted, should be treated as an opaque
 119       binary that can and will be replaced in its entirety by any
 120       upgrade of MyPLC.</p></li>
 121 <li><p><code class="filename">/plc/root</code>: The mount point
 122       for <code class="filename">/plc/root.img</code>. Once the root filesystem
 123       is mounted, all MyPLC services run in a
 124       <span><strong class="command">chroot</strong></span> jail based in this
 125       directory.</p></li>
 126 <li>
 127 <p><code class="filename">/plc/data</code>: The directory where user
 128         data and generated files are stored. This directory is bind
 129         mounted onto <code class="filename">/plc/root/data</code> so that it is
 130         accessible as <code class="filename">/data</code> from within the
 131         <span><strong class="command">chroot</strong></span> jail. Files in this directory are
 132         marked with <span><strong class="command">%config(noreplace)</strong></span> in the
 133         RPM. That is, during an upgrade of MyPLC, if a file has not
 134         changed since the last installation or upgrade of MyPLC, it is
 135         subject to upgrade and replacement. If the file has changed,
 136         the new version of the file will be created with a
 137         <code class="filename">.rpmnew</code> extension. Symlinks within the
 138         MyPLC root filesystem ensure that the following directories
 139         (relative to <code class="filename">/plc/root</code>) are stored
 140         outside the MyPLC filesystem image:</p>
 141 <div class="itemizedlist"><ul type="circle">
 142 <li><p><code class="filename">/etc/planetlab</code>: This
 143           directory contains the configuration files, keys, and
 144           certificates that define your MyPLC
 145           installation.</p></li>
 146 <li><p><code class="filename">/var/lib/pgsql</code>: This
 147           directory contains PostgreSQL database
 148           files.</p></li>
 149 <li><p><code class="filename">/var/www/html/alpina-logs</code>: This
 150           directory contains node installation logs.</p></li>
 151 <li><p><code class="filename">/var/www/html/boot</code>: This
 152           directory contains the Boot Manager, customized for your MyPLC
 153           installation, and its data files.</p></li>
 154 <li><p><code class="filename">/var/www/html/download</code>: This
 155           directory contains Boot CD images, customized for your MyPLC
 156           installation.</p></li>
 157 <li><p><code class="filename">/var/www/html/install-rpms</code>: This
 158           directory is where you should install node package updates,
 159           if any. By default, nodes are installed from the tarball
 160           located at
 161           <code class="filename">/var/www/html/boot/PlanetLab-Bootstrap.tar.bz2</code>,
 162           which is pre-built from the latest PlanetLab Central
 163           sources, and installed as part of your MyPLC
 164           installation. However, nodes will attempt to install any
 165           newer RPMs located in
 166           <code class="filename">/var/www/html/install-rpms/planetlab</code>,
 167           after initial installation and periodically thereafter. You
 168           must run <span><strong class="command">yum-arch</strong></span> and
 169           <span><strong class="command">createrepo</strong></span> to update the
 170           <span><strong class="command">yum</strong></span> caches in this directory after
 171           installing a new RPM. PlanetLab Central cannot support any
 172           changes to this directory.</p></li>
 173 <li><p><code class="filename">/var/www/html/xml</code>: This
 174           directory contains various XML files that the Slice Creation
 175           Service uses to determine the state of slices. These XML
 176           files are refreshed periodically by <span><strong class="command">cron</strong></span>
 177           jobs running in the MyPLC root.</p></li>
 178 </ul></div>
 179 </li>
 180 <li>
 181 <p><code class="filename">/etc/init.d/plc</code>: This file
 182         is a System V init script installed on your host filesystem,
 183         that allows you to start up and shut down MyPLC with a single
 184         command. On a Red Hat or Fedora host system, it is customary to
 185         use the <span><strong class="command">service</strong></span> command to invoke System V
 186         init scripts:</p>
 187 <div class="example">
 188 <a name="StartingAndStoppingMyPLC"></a><p class="title"><b>Example 2. Starting and stopping MyPLC.</b></p>
 189 <pre class="programlisting"># Starting MyPLC
 190 service plc start
 191
 192 # Stopping MyPLC
 193 service plc stop</pre>
 194 </div>
 195 <p>Like all other registered System V init services, MyPLC is
 196         started and shut down automatically when your host system boots
 197         and powers off. You may disable automatic startup by invoking
 198         the <span><strong class="command">chkconfig</strong></span> command on a Red Hat or Fedora
 199         host system:</p>
 200 <div class="example">
 201 <a name="id243568"></a><p class="title"><b>Example 3. Disabling automatic startup of MyPLC.</b></p>
 202 <pre class="programlisting"># Disable automatic startup
 203 chkconfig plc off
 204
 205 # Enable automatic startup
 206 chkconfig plc on</pre>
 207 </div>
 208 </li>
 209 <li><p><code class="filename">/etc/sysconfig/plc</code>: This
 210       file is a shell script fragment that defines the variables
 211       <code class="envar">PLC_ROOT</code> and <code class="envar">PLC_DATA</code>. By default,
 212       the values of these variables are <code class="filename">/plc/root</code>
 213       and <code class="filename">/plc/data</code>, respectively. If you wish,
 214       you may move your MyPLC installation to another location on your
 215       host filesystem and edit the values of these variables
 216       appropriately, but you will break the RPM upgrade
 217       process. PlanetLab Central cannot support any changes to this
 218       file.</p></li>
 219 <li><p><code class="filename">/etc/planetlab</code>: This
 220       symlink to <code class="filename">/plc/data/etc/planetlab</code> is
 221       installed on the host system for convenience.</p></li>
 222 </ul></div>
 223 </div>
 224 <div class="section" lang="en">
 225 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 226 <a name="id267694"></a>3. Quickstart</h2></div></div></div>
 227 <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
 228     root. Observe the output of this command for any failures. If no
 229     failures occur, you should see output similar to the
 230     following:</p>
 231 <div class="example">
 232 <a name="id267814"></a><p class="title"><b>Example 4. A successful MyPLC startup.</b></p>
 233 <pre class="programlisting">Mounting PLC:                                              [  OK  ]
 234 PLC: Generating network files:                             [  OK  ]
 235 PLC: Starting system logger:                               [  OK  ]
 236 PLC: Starting database server:                             [  OK  ]
 237 PLC: Generating SSL certificates:                          [  OK  ]
 238 PLC: Configuring the API:                                  [  OK  ]
 239 PLC: Updating GPG keys:                                    [  OK  ]
 240 PLC: Generating SSH keys:                                  [  OK  ]
 241 PLC: Starting web server:                                  [  OK  ]
 242 PLC: Bootstrapping the database:                           [  OK  ]
 243 PLC: Starting DNS server:                                  [  OK  ]
 244 PLC: Starting crond:                                       [  OK  ]
 245 PLC: Rebuilding Boot CD:                                   [  OK  ]
 246 PLC: Rebuilding Boot Manager:                              [  OK  ]
 247 PLC: Signing node packages:                                [  OK  ]
 248 </pre>
 249 </div>
 250 <p>If <code class="filename">/plc/root</code> is mounted successfully, a
 251     complete log file of the startup process may be found at
 252     <code class="filename">/plc/root/var/log/boot.log</code>. Possible reasons
 253     for failure of each step include:</p>
 254 <div class="itemizedlist"><ul type="disc">
 255 <li><p><code class="literal">Mounting PLC</code>: If this step
 256       fails, first ensure that you started MyPLC as root. Check
 257       <code class="filename">/etc/sysconfig/plc</code> to ensure that
 258       <code class="envar">PLC_ROOT</code> and <code class="envar">PLC_DATA</code> refer to the
 259       right locations. You may also have too many existing loopback
 260       mounts, or your kernel may not support loopback mounting, bind
 261       mounting, or the ext3 filesystem. Try freeing at least one
 262       loopback device, or re-compiling your kernel to support loopback
 263       mounting, bind mounting, and the ext3 filesystem. If you see an
 264       error similar to <code class="literal">Permission denied while trying to open
 265       /plc/root.img</code>, then SELinux may be enabled. If you
 266       installed MyPLC on Fedora Core 4 or 5, use the
 267       <span class="application">Security Level Configuration</span> utility
 268       to configure SELinux to be
 269       <code class="literal">Permissive</code>.</p></li>
 270 <li><p><code class="literal">Starting database server</code>: If
 271       this step fails, check
 272       <code class="filename">/plc/root/var/log/pgsql</code> and
 273       <code class="filename">/plc/root/var/log/boot.log</code>. The most common
 274       reason for failure is that the default PostgreSQL port, TCP port
 275       5432, is already in use. Check that you are not running a
 276       PostgreSQL server on the host system.</p></li>
 277 <li><p><code class="literal">Starting web server</code>: If this
 278       step fails, check
 279       <code class="filename">/plc/root/var/log/httpd/error_log</code> and
 280       <code class="filename">/plc/root/var/log/boot.log</code> for obvious
 281       errors. The most common reason for failure is that the default
 282       web ports, TCP ports 80 and 443, are already in use. Check that
 283       you are not running a web server on the host
 284       system.</p></li>
 285 <li><p><code class="literal">Bootstrapping the database</code>:
 286       If this step fails, it is likely that the previous step
 287       (<code class="literal">Starting web server</code>) also failed. Another
 288       reason that it could fail is if <code class="envar">PLC_API_HOST</code> (see
 289       <a href="#ChangingTheConfiguration" title="3.1. Changing the configuration">Section 3.1, “Changing the configuration”</a>) does not resolve to
 290       the host on which the API server has been enabled. By default,
 291       all services, including the API server, are enabled and run on
 292       the same host, so check that <code class="envar">PLC_API_HOST</code> is
 293       either <code class="filename">localhost</code> or resolves to a local IP
 294       address.</p></li>
 295 <li><p><code class="literal">Starting crond</code>: If this step
 296       fails, it is likely that the previous steps (<code class="literal">Starting
 297       web server</code> and <code class="literal">Bootstrapping the
 298       database</code>) also failed. If not, check
 299       <code class="filename">/plc/root/var/log/boot.log</code> for obvious
 300       errors. This step starts the <span><strong class="command">cron</strong></span> service and
 301       generates the initial set of XML files that the Slice Creation
 302       Service uses to determine slice state.</p></li>
 303 </ul></div>
 304 <p>If no failures occur, then MyPLC should be active with a
 305     default configuration. Open a web browser on the host system and
 306     visit <code class="literal">http://localhost/</code>, which should bring you
 307     to the front page of your PLC installation. The password of the
 308     default administrator account
 309     <code class="literal">root@localhost.localdomain</code> (set by
 310     <code class="envar">PLC_ROOT_USER</code>) is <code class="literal">root</code> (set by
 311     <code class="envar">PLC_ROOT_PASSWORD</code>).</p>
 312 <div class="section" lang="en">
 313 <div class="titlepage"><div><div><h3 class="title">
 314 <a name="ChangingTheConfiguration"></a>3.1. Changing the configuration</h3></div></div></div>
 315 <p>After verifying that MyPLC is working correctly, shut it
 316       down and begin changing some of the default variable
 317       values. Shut down MyPLC with <span><strong class="command">service plc stop</strong></span>
 318       (see <a href="#StartingAndStoppingMyPLC" title="Example 2. Starting and stopping MyPLC.">Example 2, “Starting and stopping MyPLC.”</a>). With a text
 319       editor, open the file
 320       <code class="filename">/etc/planetlab/plc_config.xml</code>. This file is
 321       a self-documenting configuration file written in XML. Variables
 322       are divided into categories. Variable identifiers must be
 323       alphanumeric, plus underscore. A variable is referred to
 324       canonically as the uppercase concatenation of its category
 325       identifier, an underscore, and its variable identifier. Thus, a
 326       variable with an <code class="literal">id</code> of
 327       <code class="literal">slice_prefix</code> in the <code class="literal">plc</code>
 328       category is referred to canonically as
 329       <code class="envar">PLC_SLICE_PREFIX</code>.</p>
 330 <p>The reason for this convention is that during MyPLC
 331       startup, <code class="filename">plc_config.xml</code> is translated into
 332       several different languages—shell, PHP, and
 333       Python—so that scripts written in each of these languages
 334       can refer to the same underlying configuration. Most MyPLC
 335       scripts are written in shell, so the convention for shell
 336       variables predominates.</p>
 337 <p>The variables that you should change immediately are:</p>
 338 <div class="itemizedlist"><ul type="disc">
 339 <li><p><code class="envar">PLC_NAME</code>: Change this to the
 340         name of your PLC installation.</p></li>
 341 <li><p><code class="envar">PLC_ROOT_PASSWORD</code>: Change this
 342         to a more secure password.</p></li>
 343 <li><p><code class="envar">PLC_MAIL_SUPPORT_ADDRESS</code>:
 344         Change this to the e-mail address at which you would like to
 345         receive support requests.</p></li>
 346 <li><p><code class="envar">PLC_DB_HOST</code>,
 347         <code class="envar">PLC_DB_IP</code>, <code class="envar">PLC_API_HOST</code>,
 348         <code class="envar">PLC_API_IP</code>, <code class="envar">PLC_WWW_HOST</code>,
 349         <code class="envar">PLC_WWW_IP</code>, <code class="envar">PLC_BOOT_HOST</code>,
 350         <code class="envar">PLC_BOOT_IP</code>: Change all of these to the
 351         preferred FQDN and external IP address of your host
 352         system.</p></li>
 353 </ul></div>
 354 <p>After changing these variables, save the file, then
 355       restart MyPLC with <span><strong class="command">service plc start</strong></span>. You
 356       should notice that the password of the default administrator
 357       account is no longer <code class="literal">root</code>, and that the
 358       default site name includes the name of your PLC installation
 359       instead of PlanetLab.</p>
 360 </div>
 361 <div class="section" lang="en">
 362 <div class="titlepage"><div><div><h3 class="title">
 363 <a name="id268201"></a>3.2. Installing nodes</h3></div></div></div>
 364 <p>Install your first node by clicking <code class="literal">Add
 365       Node</code> under the <code class="literal">Nodes</code> tab. Fill in
 366       all the appropriate details, then click
 367       <code class="literal">Add</code>. Download the node's configuration file
 368       by clicking <code class="literal">Download configuration file</code> on
 369       the <span class="bold"><strong>Node Details</strong></span> page for the
 370       node. Save it to a floppy disk or USB key as detailed in [<a href="#TechsGuide" title="[TechsGuide]">1</a>].</p>
 371 <p>Follow the rest of the instructions in [<a href="#TechsGuide" title="[TechsGuide]">1</a>] for creating a Boot CD and installing
 372       the node, except download the Boot CD image from the
 373       <code class="filename">/download</code> directory of your PLC
 374       installation, not from PlanetLab Central. The images located
 375       here are customized for your installation. If you change the
 376       hostname of your boot server (<code class="envar">PLC_BOOT_HOST</code>), or
 377       if the SSL certificate of your boot server expires, MyPLC will
 378       regenerate it and rebuild the Boot CD with the new
 379       certificate. If this occurs, you must replace all Boot CDs
 380       created before the certificate was regenerated.</p>
 381 <p>The installation process for a node has significantly
 382       improved since PlanetLab 3.3. It should now take only a few
 383       seconds for a new node to become ready to create slices.</p>
 384 </div>
 385 <div class="section" lang="en">
 386 <div class="titlepage"><div><div><h3 class="title">
 387 <a name="id268275"></a>3.3. Administering nodes</h3></div></div></div>
 388 <p>You may administer nodes as <code class="literal">root</code> by
 389       using the SSH key stored in
 390       <code class="filename">/etc/planetlab/root_ssh_key.rsa</code>.</p>
 391 <div class="example">
 392 <a name="id268297"></a><p class="title"><b>Example 5. Accessing nodes via SSH. Replace
 393         <code class="literal">node</code> with the hostname of the node.</b></p>
 394 <pre class="programlisting">ssh -i /etc/planetlab/root_ssh_key.rsa root@node</pre>
 395 </div>
 396 <p>Besides the standard Linux log files located in
 397       <code class="filename">/var/log</code>, several other files can give you
 398       clues about any problems with active processes:</p>
 399 <div class="itemizedlist"><ul type="disc">
 400 <li><p><code class="filename">/var/log/pl_nm</code>: The log
 401         file for the Node Manager.</p></li>
 402 <li><p><code class="filename">/vservers/pl_conf/var/log/pl_conf</code>:
 403         The log file for the Slice Creation Service.</p></li>
 404 <li><p><code class="filename">/var/log/propd</code>: The log
 405         file for Proper, the service which allows certain slices to
 406         perform certain privileged operations in the root
 407         context.</p></li>
 408 <li><p><code class="filename">/vservers/pl_netflow/var/log/netflow.log</code>:
 409         The log file for PlanetFlow, the network traffic auditing
 410         service.</p></li>
 411 </ul></div>
 412 </div>
 413 <div class="section" lang="en">
 414 <div class="titlepage"><div><div><h3 class="title">
 415 <a name="id268369"></a>3.4. Creating a slice</h3></div></div></div>
 416 <p>Create a slice by clicking <code class="literal">Create Slice</code>
 417       under the <code class="literal">Slices</code> tab. Fill in all the
 418       appropriate details, then click <code class="literal">Create</code>. Add
 419       nodes to the slice by clicking <code class="literal">Manage Nodes</code>
 420       on the <span class="bold"><strong>Slice Details</strong></span> page for
 421       the slice.</p>
 422 <p>A <span><strong class="command">cron</strong></span> job runs every five minutes and
 423       updates the file
 424       <code class="filename">/plc/data/var/www/html/xml/slices-0.5.xml</code>
 425       with information about current slice state. The Slice Creation
 426       Service running on every node polls this file every ten minutes
 427       to determine if it needs to create or delete any slices. You may
 428       accelerate this process manually if desired.</p>
 429 <div class="example">
 430 <a name="id268427"></a><p class="title"><b>Example 6. Forcing slice creation on a node.</b></p>
 431 <pre class="programlisting"># Update slices.xml immediately
 432 service plc start crond
 433
 434 # Kick the Slice Creation Service on a particular node.
 435 ssh -i /etc/planetlab/root_ssh_key.rsa root@node \
 436 vserver pl_conf exec service pl_conf restart</pre>
 437 </div>
 438 </div>
 439 </div>
 440 <div class="section" lang="en">
 441 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 442 <a name="id268444"></a>4. Rebuilding and customizing MyPLC</h2></div></div></div>
 443 <p>The MyPLC package, though distributed as an RPM, is not a
 444     traditional package that can be easily rebuilt from SRPM. The
 445     requisite build environment is quite extensive and numerous
 446     assumptions are made throughout the PlanetLab source code base,
 447     that the build environment is based on Fedora Core 4 and that
 448     access to a complete Fedora Core 4 mirror is available.</p>
 449 <p>For this reason, it is recommended that you only rebuild
 450     MyPLC (or any of its components) from within the MyPLC development
 451     environment. The MyPLC development environment is similar to MyPLC
 452     itself in that it is a portable filesystem contained within a
 453     <span><strong class="command">chroot</strong></span> jail. The filesystem contains all the
 454     necessary tools required to rebuild MyPLC, as well as a snapshot
 455     of the PlanetLab source code base in the form of a local CVS
 456     repository.</p>
 457 <div class="section" lang="en">
 458 <div class="titlepage"><div><div><h3 class="title">
 459 <a name="id268469"></a>4.1. Installation</h3></div></div></div>
 460 <p>Install the MyPLC development environment similarly to how
 461       you would install MyPLC. You may install both packages on the same
 462       host system if you wish. As with MyPLC, the MyPLC development
 463       environment should be treated as a monolithic software
 464       application, and any files present in the
 465       <span><strong class="command">chroot</strong></span> jail should not be modified directly, as
 466       they are subject to upgrade.</p>
 467 <div class="example">
 468 <a name="id268487"></a><p class="title"><b>Example 7. Installing the MyPLC development environment.</b></p>
 469 <pre class="programlisting"># If your distribution supports RPM
 470 rpm -U http://build.planet-lab.org/build/myplc-0_4-rc2/RPMS/i386/myplc-devel-0.4-2.planetlab.i386.rpm
 471
 472 # If your distribution does not support RPM
 473 cd /tmp
 474 wget http://build.planet-lab.org/build/myplc-0_4-rc2/RPMS/i386/myplc-devel-0.4-2.planetlab.i386.rpm
 475 cd /
 476 rpm2cpio /tmp/myplc-devel-0.4-2.planetlab.i386.rpm | cpio -diu</pre>
 477 </div>
 478 <p>The MyPLC development environment installs the following
 479       files and directories:</p>
 480 <div class="itemizedlist"><ul type="disc">
 481 <li><p><code class="filename">/plc/devel/root.img</code>: The
 482         main root filesystem of the MyPLC development environment. This
 483         file is an uncompressed ext3 filesystem that is loopback mounted
 484         on <code class="filename">/plc/devel/root</code> when the MyPLC
 485         development environment is initialized. This filesystem, even
 486         when mounted, should be treated as an opaque binary that can and
 487         will be replaced in its entirety by any upgrade of the MyPLC
 488         development environment.</p></li>
 489 <li><p><code class="filename">/plc/devel/root</code>: The mount
 490         point for
 491         <code class="filename">/plc/devel/root.img</code>.</p></li>
 492 <li>
 493 <p><code class="filename">/plc/devel/data</code>: The directory
 494           where user data and generated files are stored. This directory
 495           is bind mounted onto <code class="filename">/plc/devel/root/data</code>
 496           so that it is accessible as <code class="filename">/data</code> from
 497           within the <span><strong class="command">chroot</strong></span> jail. Files in this
 498           directory are marked with
 499           <span><strong class="command">%config(noreplace)</strong></span> in the RPM. Symlinks
 500           ensure that the following directories (relative to
 501           <code class="filename">/plc/devel/root</code>) are stored outside the
 502           root filesystem image:</p>
 503 <div class="itemizedlist"><ul type="circle">
 504 <li><p><code class="filename">/etc/planetlab</code>: This
 505             directory contains the configuration files that define your
 506             MyPLC development environment.</p></li>
 507 <li><p><code class="filename">/cvs</code>: A
 508             snapshot of the PlanetLab source code is stored as a CVS
 509             repository in this directory. Files in this directory will
 510             <span class="bold"><strong>not</strong></span> be updated by an upgrade of
 511             <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
 512             PlanetLab source code.</p></li>
 513 <li><p><code class="filename">/build</code>:
 514             Builds are stored in this directory. This directory is bind
 515             mounted onto <code class="filename">/plc/devel/root/build</code> so that
 516             it is accessible as <code class="filename">/build</code> from within the
 517             <span><strong class="command">chroot</strong></span> jail. The build scripts in this
 518             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
 519             builds.</p></li>
 520 </ul></div>
 521 </li>
 522 <li><p><code class="filename">/etc/init.d/plc-devel</code>: This file is
 523           a System V init script installed on your host filesystem, that
 524           allows you to start up and shut down the MyPLC development
 525           environment with a single command.</p></li>
 526 </ul></div>
 527 </div>
 528 <div class="section" lang="en">
 529 <div class="titlepage"><div><div><h3 class="title">
 530 <a name="id268676"></a>4.2. Fedora Core 4 mirror requirement</h3></div></div></div>
 531 <p>The MyPLC development environment requires access to a
 532       complete Fedora Core 4 i386 RPM repository, because several
 533       different filesystems based upon Fedora Core 4 are constructed
 534       during the process of building MyPLC. You may configure the
 535       location of this repository via the
 536       <code class="envar">PLC_DEVEL_FEDORA_URL</code> variable in
 537       <code class="filename">/plc/devel/data/etc/planetlab/plc_config.xml</code>. The
 538       value of the variable should be a URL that points to the top
 539       level of a Fedora mirror that provides the
 540       <code class="filename">base</code>, <code class="filename">updates</code>, and
 541       <code class="filename">extras</code> repositories, e.g.,</p>
 542 <div class="itemizedlist"><ul type="disc">
 543 <li><p><code class="filename">file:///data/fedora</code></p></li>
 544 <li><p><code class="filename">http://coblitz.planet-lab.org/pub/fedora</code></p></li>
 545 <li><p><code class="filename">ftp://mirror.cs.princeton.edu/pub/mirrors/fedora</code></p></li>
 546 <li><p><code class="filename">ftp://mirror.stanford.edu/pub/mirrors/fedora</code></p></li>
 547 <li><p><code class="filename">http://rpmfind.net/linux/fedora</code></p></li>
 548 </ul></div>
 549 <p>As implied by the list, the repository may be located on
 550       the local filesystem, or it may be located on a remote FTP or
 551       HTTP server. URLs beginning with <code class="filename">file://</code>
 552       should exist at the specified location relative to the root of
 553       the <span><strong class="command">chroot</strong></span> jail. For optimum performance and
 554       reproducibility, specify
 555       <code class="envar">PLC_DEVEL_FEDORA_URL=file:///data/fedora</code> and
 556       download all Fedora Core 4 RPMS into
 557       <code class="filename">/plc/devel/data/fedora</code> on the host system
 558       after installing <code class="filename">myplc-devel</code>. Use a tool
 559       such as <span><strong class="command">wget</strong></span> or <span><strong class="command">rsync</strong></span> to
 560       download the RPMS from a public mirror:</p>
 561 <div class="example">
 562 <a name="id268807"></a><p class="title"><b>Example 8. Setting up a local Fedora Core 4 repository.</b></p>
 563 <pre class="programlisting">mkdir -p /plc/devel/data/fedora
 564 cd /plc/devel/data/fedora
 565
 566 for repo in core/4/i386/os core/updates/4/i386 extras/4/i386 ; do
 567     wget -m -nH --cut-dirs=3 http://coblitz.planet-lab.org/pub/fedora/linux/$repo
 568 done</pre>
 569 </div>
 570 <p>Change the repository URI and <span><strong class="command">--cut-dirs</strong></span>
 571       level as needed to produce a hierarchy that resembles:</p>
 572 <pre class="programlisting">/plc/devel/data/fedora/core/4/i386/os
 573 /plc/devel/data/fedora/core/updates/4/i386
 574 /plc/devel/data/fedora/extras/4/i386</pre>
 575 <p>A list of additional Fedora Core 4 mirrors is available at
 576       <a href="http://fedora.redhat.com/Download/mirrors.html" target="_top">http://fedora.redhat.com/Download/mirrors.html</a>.</p>
 577 </div>
 578 <div class="section" lang="en">
 579 <div class="titlepage"><div><div><h3 class="title">
 580 <a name="BuildingMyPLC"></a>4.3. Building MyPLC</h3></div></div></div>
 581 <p>All PlanetLab source code modules are built and installed
 582       as RPMS. A set of build scripts, checked into the
 583       <code class="filename">build/</code> directory of the PlanetLab CVS
 584       repository, eases the task of rebuilding PlanetLab source
 585       code.</p>
 586 <p>To build MyPLC, or any PlanetLab source code module, from
 587       within the MyPLC development environment, execute the following
 588       commands as root:</p>
 589 <div class="example">
 590 <a name="id268873"></a><p class="title"><b>Example 9. Building MyPLC.</b></p>
 591 <pre class="programlisting"># Initialize MyPLC development environment
 592 service plc-devel start
 593
 594 # Enter development environment
 595 chroot /plc/devel/root su -
 596
 597 # Check out build scripts into a directory named after the current
 598 # date. This is simply a convention, it need not be followed
 599 # exactly. See build/build.sh for an example of a build script that
 600 # names build directories after CVS tags.
 601 DATE=$(date +%Y.%m.%d)
 602 cd /build
 603 cvs -d /cvs checkout -d $DATE build
 604
 605 # Build everything
 606 make -C $DATE</pre>
 607 </div>
 608 <p>If the build succeeds, a set of binary RPMS will be
 609       installed under
 610       <code class="filename">/plc/devel/data/build/$DATE/RPMS/</code> that you
 611       may copy to the
 612       <code class="filename">/var/www/html/install-rpms/planetlab</code>
 613       directory of your MyPLC installation (see <a href="#Installation" title="2. Installation">Section 2, “Installation”</a>).</p>
 614 </div>
 615 <div class="section" lang="en">
 616 <div class="titlepage"><div><div><h3 class="title">
 617 <a name="UpdatingCVS"></a>4.4. Updating CVS</h3></div></div></div>
 618 <p>A complete snapshot of the PlanetLab source code is included
 619       with the MyPLC development environment as a CVS repository in
 620       <code class="filename">/plc/devel/data/cvs</code>. This CVS repository may
 621       be accessed like any other CVS repository. It may be accessed
 622       using an interface such as <a href="http://www.freebsd.org/projects/cvsweb.html" target="_top">CVSweb</a>,
 623       and file permissions may be altered to allow for fine-grained
 624       access control. Although the files are included with the
 625       <code class="filename">myplc-devel</code> RPM, they are <span class="bold"><strong>not</strong></span> subject to upgrade once installed. New
 626       versions of the <code class="filename">myplc-devel</code> RPM will install
 627       updated snapshot repositories in
 628       <code class="filename">/plc/devel/data/cvs-%{version}-%{release}</code>,
 629       where <code class="literal">%{version}-%{release}</code> is replaced with
 630       the version number of the RPM.</p>
 631 <p>Because the CVS repository is not automatically upgraded,
 632       if you wish to keep your local repository synchronized with the
 633       public PlanetLab repository, it is highly recommended that you
 634       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
 635       branches</a> to track changes. Vendor branches ease the task
 636       of merging upstream changes with your local modifications. To
 637       import a new snapshot into your local repository (for example,
 638       if you have just upgraded from
 639       <code class="filename">myplc-devel-0.4-2</code> to
 640       <code class="filename">myplc-devel-0.4-3</code> and you notice the new
 641       repository in <code class="filename">/plc/devel/data/cvs-0.4-3</code>),
 642       execute the following commands as root from within the MyPLC
 643       development environment:</p>
 644 <div class="example">
 645 <a name="id269004"></a><p class="title"><b>Example 10. Updating /data/cvs from /data/cvs-0.4-3.</b></p>
 646 <p><span class="bold"><strong>Warning</strong></span>: This may cause
 647         severe, irreversible changes to be made to your local
 648         repository. Always tag your local repository before
 649         importing.</p>
 650 <pre class="programlisting"># Initialize MyPLC development environment
 651 service plc-devel start
 652
 653 # Enter development environment
 654 chroot /plc/devel/root su -
 655
 656 # Tag current state
 657 cvs -d /cvs rtag before-myplc-0_4-3-merge
 658
 659 # Export snapshot
 660 TMP=$(mktemp -d /data/export.XXXXXX)
 661 pushd $TMP
 662 cvs -d /data/cvs-0.4-3 export -r HEAD .
 663 cvs -d /cvs import -m "PlanetLab sources from myplc-0.4-3" -ko -I ! . planetlab myplc-0_4-3
 664 popd
 665 rm -rf $TMP</pre>
 666 </div>
 667 <p>If there any merge conflicts, use the command suggested by
 668       CVS to help the merge. Explaining how to fix merge conflicts is
 669       beyond the scope of this document; consult the CVS documentation
 670       for more information on how to use CVS.</p>
 671 </div>
 672 </div>
 673 <div class="appendix" lang="en">
 674 <h2 class="title" style="clear: both">
 675 <a name="id269037"></a>A. Configuration variables</h2>
 676 <p>Listed below is the set of standard configuration variables
 677     and their default values, defined in the template
 678     <code class="filename">/etc/planetlab/default_config.xml</code>. Additional
 679     variables and their defaults may be defined in site-specific XML
 680     templates that should be placed in
 681     <code class="filename">/etc/planetlab/configs/</code>.</p>
 682 <div class="variablelist"><dl>
 683 <dt><span class="term">PLC_NAME</span></dt>
 684 <dd>
 685 <p>
 686                   Type: string</p>
 687 <p>
 688                   Default: PlanetLab Test</p>
 689 <p>The name of this PLC installation. It is used in
 690           the name of the default system site (e.g., PlanetLab Central)
 691           and in the names of various administrative entities (e.g.,
 692           PlanetLab Support).</p>
 693 </dd>
 694 <dt><span class="term">PLC_SLICE_PREFIX</span></dt>
 695 <dd>
 696 <p>
 697                   Type: string</p>
 698 <p>
 699                   Default: pl</p>
 700 <p>The abbreviated name of this PLC
 701           installation. It is used as the prefix for system slices
 702           (e.g., pl_conf). Warning: Currently, this variable should
 703           not be changed.</p>
 704 </dd>
 705 <dt><span class="term">PLC_ROOT_USER</span></dt>
 706 <dd>
 707 <p>
 708                   Type: email</p>
 709 <p>
 710                   Default: root@localhost.localdomain</p>
 711 <p>The name of the initial administrative
 712           account. We recommend that this account be used only to create
 713           additional accounts associated with real
 714           administrators, then disabled.</p>
 715 </dd>
 716 <dt><span class="term">PLC_ROOT_PASSWORD</span></dt>
 717 <dd>
 718 <p>
 719                   Type: password</p>
 720 <p>
 721                   Default: root</p>
 722 <p>The password of the initial administrative
 723           account. Also the password of the root account on the Boot
 724           CD.</p>
 725 </dd>
 726 <dt><span class="term">PLC_ROOT_SSH_KEY_PUB</span></dt>
 727 <dd>
 728 <p>
 729                   Type: file</p>
 730 <p>
 731                   Default: /etc/planetlab/root_ssh_key.pub</p>
 732 <p>The SSH public key used to access the root
 733           account on your nodes.</p>
 734 </dd>
 735 <dt><span class="term">PLC_ROOT_SSH_KEY</span></dt>
 736 <dd>
 737 <p>
 738                   Type: file</p>
 739 <p>
 740                   Default: /etc/planetlab/root_ssh_key.rsa</p>
 741 <p>The SSH private key used to access the root
 742           account on your nodes.</p>
 743 </dd>
 744 <dt><span class="term">PLC_DEBUG_SSH_KEY_PUB</span></dt>
 745 <dd>
 746 <p>
 747                   Type: file</p>
 748 <p>
 749                   Default: /etc/planetlab/debug_ssh_key.pub</p>
 750 <p>The SSH public key used to access the root
 751           account on your nodes when they are in Debug mode.</p>
 752 </dd>
 753 <dt><span class="term">PLC_DEBUG_SSH_KEY</span></dt>
 754 <dd>
 755 <p>
 756                   Type: file</p>
 757 <p>
 758                   Default: /etc/planetlab/debug_ssh_key.rsa</p>
 759 <p>The SSH private key used to access the root
 760           account on your nodes when they are in Debug mode.</p>
 761 </dd>
 762 <dt><span class="term">PLC_ROOT_GPG_KEY_PUB</span></dt>
 763 <dd>
 764 <p>
 765                   Type: file</p>
 766 <p>
 767                   Default: /etc/planetlab/pubring.gpg</p>
 768 <p>The GPG public keyring used to sign the Boot
 769           Manager and all node packages.</p>
 770 </dd>
 771 <dt><span class="term">PLC_ROOT_GPG_KEY</span></dt>
 772 <dd>
 773 <p>
 774                   Type: file</p>
 775 <p>
 776                   Default: /etc/planetlab/secring.gpg</p>
 777 <p>The SSH private key used to access the root
 778           account on your nodes.</p>
 779 </dd>
 780 <dt><span class="term">PLC_MA_SA_NAMESPACE</span></dt>
 781 <dd>
 782 <p>
 783                   Type: ip</p>
 784 <p>
 785                   Default: test</p>
 786 <p>The namespace of your MA/SA. This should be a
 787           globally unique value assigned by PlanetLab
 788           Central.</p>
 789 </dd>
 790 <dt><span class="term">PLC_MA_SA_SSL_KEY</span></dt>
 791 <dd>
 792 <p>
 793                   Type: file</p>
 794 <p>
 795                   Default: /etc/planetlab/ma_sa_ssl.key</p>
 796 <p>The SSL private key used for signing documents
 797           with the signature of your MA/SA. If non-existent, one will
 798           be generated.</p>
 799 </dd>
 800 <dt><span class="term">PLC_MA_SA_SSL_CRT</span></dt>
 801 <dd>
 802 <p>
 803                   Type: file</p>
 804 <p>
 805                   Default: /etc/planetlab/ma_sa_ssl.crt</p>
 806 <p>The corresponding SSL public certificate. By
 807           default, this certificate is self-signed. You may replace
 808           the certificate later with one signed by the PLC root
 809           CA.</p>
 810 </dd>
 811 <dt><span class="term">PLC_MA_SA_CA_SSL_CRT</span></dt>
 812 <dd>
 813 <p>
 814                   Type: file</p>
 815 <p>
 816                   Default: /etc/planetlab/ma_sa_ca_ssl.crt</p>
 817 <p>If applicable, the certificate of the PLC root
 818           CA. If your MA/SA certificate is self-signed, then this file
 819           is the same as your MA/SA certificate.</p>
 820 </dd>
 821 <dt><span class="term">PLC_MA_SA_CA_SSL_KEY_PUB</span></dt>
 822 <dd>
 823 <p>
 824                   Type: file</p>
 825 <p>
 826                   Default: /etc/planetlab/ma_sa_ca_ssl.pub</p>
 827 <p>If applicable, the public key of the PLC root
 828           CA. If your MA/SA certificate is self-signed, then this file
 829           is the same as your MA/SA public key.</p>
 830 </dd>
 831 <dt><span class="term">PLC_MA_SA_API_CRT</span></dt>
 832 <dd>
 833 <p>
 834                   Type: file</p>
 835 <p>
 836                   Default: /etc/planetlab/ma_sa_api.xml</p>
 837 <p>The API Certificate is your MA/SA public key
 838           embedded in a digitally signed XML document. By default,
 839           this document is self-signed. You may replace this
 840           certificate later with one signed by the PLC root
 841           CA.</p>
 842 </dd>
 843 <dt><span class="term">PLC_NET_DNS1</span></dt>
 844 <dd>
 845 <p>
 846                   Type: ip</p>
 847 <p>
 848                   Default: 127.0.0.1</p>
 849 <p>Primary DNS server address.</p>
 850 </dd>
 851 <dt><span class="term">PLC_NET_DNS2</span></dt>
 852 <dd>
 853 <p>
 854                   Type: ip</p>
 855 <p>
 856                   Default: </p>
 857 <p>Secondary DNS server address.</p>
 858 </dd>
 859 <dt><span class="term">PLC_DNS_ENABLED</span></dt>
 860 <dd>
 861 <p>
 862                   Type: boolean</p>
 863 <p>
 864                   Default: true</p>
 865 <p>Enable the internal DNS server. The server does
 866           not provide reverse resolution and is not a production
 867           quality or scalable DNS solution. Use the internal DNS
 868           server only for small deployments or for
 869           testing.</p>
 870 </dd>
 871 <dt><span class="term">PLC_MAIL_ENABLED</span></dt>
 872 <dd>
 873 <p>
 874                   Type: boolean</p>
 875 <p>
 876                   Default: false</p>
 877 <p>Set to false to suppress all e-mail notifications
 878           and warnings.</p>
 879 </dd>
 880 <dt><span class="term">PLC_MAIL_SUPPORT_ADDRESS</span></dt>
 881 <dd>
 882 <p>
 883                   Type: email</p>
 884 <p>
 885                   Default: root+support@localhost.localdomain</p>
 886 <p>This address is used for support
 887           requests. Support requests may include traffic complaints,
 888           security incident reporting, web site malfunctions, and
 889           general requests for information. We recommend that the
 890           address be aliased to a ticketing system such as Request
 891           Tracker.</p>
 892 </dd>
 893 <dt><span class="term">PLC_MAIL_BOOT_ADDRESS</span></dt>
 894 <dd>
 895 <p>
 896                   Type: email</p>
 897 <p>
 898                   Default: root+install-msgs@localhost.localdomain</p>
 899 <p>The API will notify this address when a problem
 900           occurs during node installation or boot.</p>
 901 </dd>
 902 <dt><span class="term">PLC_MAIL_SLICE_ADDRESS</span></dt>
 903 <dd>
 904 <p>
 905                   Type: email</p>
 906 <p>
 907                   Default: root+SLICE@localhost.localdomain</p>
 908 <p>This address template is used for sending
 909           e-mail notifications to slices. SLICE will be replaced with
 910           the name of the slice.</p>
 911 </dd>
 912 <dt><span class="term">PLC_DB_ENABLED</span></dt>
 913 <dd>
 914 <p>
 915                   Type: boolean</p>
 916 <p>
 917                   Default: true</p>
 918 <p>Enable the database server on this
 919           machine.</p>
 920 </dd>
 921 <dt><span class="term">PLC_DB_TYPE</span></dt>
 922 <dd>
 923 <p>
 924                   Type: string</p>
 925 <p>
 926                   Default: postgresql</p>
 927 <p>The type of database server. Currently, only
 928           postgresql is supported.</p>
 929 </dd>
 930 <dt><span class="term">PLC_DB_HOST</span></dt>
 931 <dd>
 932 <p>
 933                   Type: hostname</p>
 934 <p>
 935                   Default: localhost.localdomain</p>
 936 <p>The fully qualified hostname of the database
 937           server.</p>
 938 </dd>
 939 <dt><span class="term">PLC_DB_IP</span></dt>
 940 <dd>
 941 <p>
 942                   Type: ip</p>
 943 <p>
 944                   Default: 127.0.0.1</p>
 945 <p>The IP address of the database server, if not
 946           resolvable by the configured DNS servers.</p>
 947 </dd>
 948 <dt><span class="term">PLC_DB_PORT</span></dt>
 949 <dd>
 950 <p>
 951                   Type: int</p>
 952 <p>
 953                   Default: 5432</p>
 954 <p>The TCP port number through which the database
 955           server should be accessed.</p>
 956 </dd>
 957 <dt><span class="term">PLC_DB_NAME</span></dt>
 958 <dd>
 959 <p>
 960                   Type: string</p>
 961 <p>
 962                   Default: planetlab3</p>
 963 <p>The name of the database to access.</p>
 964 </dd>
 965 <dt><span class="term">PLC_DB_USER</span></dt>
 966 <dd>
 967 <p>
 968                   Type: string</p>
 969 <p>
 970                   Default: pgsqluser</p>
 971 <p>The username to use when accessing the
 972           database.</p>
 973 </dd>
 974 <dt><span class="term">PLC_DB_PASSWORD</span></dt>
 975 <dd>
 976 <p>
 977                   Type: password</p>
 978 <p>
 979                   Default: </p>
 980 <p>The password to use when accessing the
 981           database. If left blank, one will be
 982           generated.</p>
 983 </dd>
 984 <dt><span class="term">PLC_API_ENABLED</span></dt>
 985 <dd>
 986 <p>
 987                   Type: boolean</p>
 988 <p>
 989                   Default: true</p>
 990 <p>Enable the API server on this
 991           machine.</p>
 992 </dd>
 993 <dt><span class="term">PLC_API_DEBUG</span></dt>
 994 <dd>
 995 <p>
 996                   Type: boolean</p>
 997 <p>
 998                   Default: false</p>
 999 <p>Enable verbose API debugging. Do not enable on
1000           a production system!</p>
1001 </dd>
1002 <dt><span class="term">PLC_API_HOST</span></dt>
1003 <dd>
1004 <p>
1005                   Type: hostname</p>
1006 <p>
1007                   Default: localhost.localdomain</p>
1008 <p>The fully qualified hostname of the API
1009           server.</p>
1010 </dd>
1011 <dt><span class="term">PLC_API_IP</span></dt>
1012 <dd>
1013 <p>
1014                   Type: ip</p>
1015 <p>
1016                   Default: 127.0.0.1</p>
1017 <p>The IP address of the API server, if not
1018           resolvable by the configured DNS servers.</p>
1019 </dd>
1020 <dt><span class="term">PLC_API_PORT</span></dt>
1021 <dd>
1022 <p>
1023                   Type: int</p>
1024 <p>
1025                   Default: 80</p>
1026 <p>The TCP port number through which the API
1027           should be accessed. Warning: SSL (port 443) access is not
1028           fully supported by the website code yet. We recommend that
1029           port 80 be used for now and that the API server either run
1030           on the same machine as the web server, or that they both be
1031           on a secure wired network.</p>
1032 </dd>
1033 <dt><span class="term">PLC_API_PATH</span></dt>
1034 <dd>
1035 <p>
1036                   Type: string</p>
1037 <p>
1038                   Default: /PLCAPI/</p>
1039 <p>The base path of the API URL.</p>
1040 </dd>
1041 <dt><span class="term">PLC_API_MAINTENANCE_USER</span></dt>
1042 <dd>
1043 <p>
1044                   Type: string</p>
1045 <p>
1046                   Default: maint@localhost.localdomain</p>
1047 <p>The username of the maintenance account. This
1048           account is used by local scripts that perform automated
1049           tasks, and cannot be used for normal logins.</p>
1050 </dd>
1051 <dt><span class="term">PLC_API_MAINTENANCE_PASSWORD</span></dt>
1052 <dd>
1053 <p>
1054                   Type: password</p>
1055 <p>
1056                   Default: </p>
1057 <p>The password of the maintenance account. If
1058           left blank, one will be generated. We recommend that the
1059           password be changed periodically.</p>
1060 </dd>
1061 <dt><span class="term">PLC_API_MAINTENANCE_SOURCES</span></dt>
1062 <dd>
1063 <p>
1064                   Type: hostname</p>
1065 <p>
1066                   Default: </p>
1067 <p>A space-separated list of IP addresses allowed
1068           to access the API through the maintenance account. The value
1069           of this variable is set automatically to allow only the API,
1070           web, and boot servers, and should not be
1071           changed.</p>
1072 </dd>
1073 <dt><span class="term">PLC_API_SSL_KEY</span></dt>
1074 <dd>
1075 <p>
1076                   Type: file</p>
1077 <p>
1078                   Default: /etc/planetlab/api_ssl.key</p>
1079 <p>The SSL private key to use for encrypting HTTPS
1080           traffic. If non-existent, one will be
1081           generated.</p>
1082 </dd>
1083 <dt><span class="term">PLC_API_SSL_CRT</span></dt>
1084 <dd>
1085 <p>
1086                   Type: file</p>
1087 <p>
1088                   Default: /etc/planetlab/api_ssl.crt</p>
1089 <p>The corresponding SSL public certificate. By
1090           default, this certificate is self-signed. You may replace
1091           the certificate later with one signed by a root
1092           CA.</p>
1093 </dd>
1094 <dt><span class="term">PLC_API_CA_SSL_CRT</span></dt>
1095 <dd>
1096 <p>
1097                   Type: file</p>
1098 <p>
1099                   Default: /etc/planetlab/api_ca_ssl.crt</p>
1100 <p>The certificate of the root CA, if any, that
1101           signed your server certificate. If your server certificate is
1102           self-signed, then this file is the same as your server
1103           certificate.</p>
1104 </dd>
1105 <dt><span class="term">PLC_WWW_ENABLED</span></dt>
1106 <dd>
1107 <p>
1108                   Type: boolean</p>
1109 <p>
1110                   Default: true</p>
1111 <p>Enable the web server on this
1112           machine.</p>
1113 </dd>
1114 <dt><span class="term">PLC_WWW_DEBUG</span></dt>
1115 <dd>
1116 <p>
1117                   Type: boolean</p>
1118 <p>
1119                   Default: false</p>
1120 <p>Enable debugging output on web pages. Do not
1121           enable on a production system!</p>
1122 </dd>
1123 <dt><span class="term">PLC_WWW_HOST</span></dt>
1124 <dd>
1125 <p>
1126                   Type: hostname</p>
1127 <p>
1128                   Default: localhost.localdomain</p>
1129 <p>The fully qualified hostname of the web
1130           server.</p>
1131 </dd>
1132 <dt><span class="term">PLC_WWW_IP</span></dt>
1133 <dd>
1134 <p>
1135                   Type: ip</p>
1136 <p>
1137                   Default: 127.0.0.1</p>
1138 <p>The IP address of the web server, if not
1139           resolvable by the configured DNS servers.</p>
1140 </dd>
1141 <dt><span class="term">PLC_WWW_PORT</span></dt>
1142 <dd>
1143 <p>
1144                   Type: int</p>
1145 <p>
1146                   Default: 80</p>
1147 <p>The TCP port number through which the
1148           unprotected portions of the web site should be
1149           accessed.</p>
1150 </dd>
1151 <dt><span class="term">PLC_WWW_SSL_PORT</span></dt>
1152 <dd>
1153 <p>
1154                   Type: int</p>
1155 <p>
1156                   Default: 443</p>
1157 <p>The TCP port number through which the protected
1158           portions of the web site should be accessed.</p>
1159 </dd>
1160 <dt><span class="term">PLC_WWW_SSL_KEY</span></dt>
1161 <dd>
1162 <p>
1163                   Type: file</p>
1164 <p>
1165                   Default: /etc/planetlab/www_ssl.key</p>
1166 <p>The SSL private key to use for encrypting HTTPS
1167           traffic. If non-existent, one will be
1168           generated.</p>
1169 </dd>
1170 <dt><span class="term">PLC_WWW_SSL_CRT</span></dt>
1171 <dd>
1172 <p>
1173                   Type: file</p>
1174 <p>
1175                   Default: /etc/planetlab/www_ssl.crt</p>
1176 <p>The corresponding SSL public certificate for
1177           the HTTP server. By default, this certificate is
1178           self-signed. You may replace the certificate later with one
1179           signed by a root CA.</p>
1180 </dd>
1181 <dt><span class="term">PLC_WWW_CA_SSL_CRT</span></dt>
1182 <dd>
1183 <p>
1184                   Type: file</p>
1185 <p>
1186                   Default: /etc/planetlab/www_ca_ssl.crt</p>
1187 <p>The certificate of the root CA, if any, that
1188           signed your server certificate. If your server certificate is
1189           self-signed, then this file is the same as your server
1190           certificate.</p>
1191 </dd>
1192 <dt><span class="term">PLC_BOOT_ENABLED</span></dt>
1193 <dd>
1194 <p>
1195                   Type: boolean</p>
1196 <p>
1197                   Default: true</p>
1198 <p>Enable the boot server on this
1199           machine.</p>
1200 </dd>
1201 <dt><span class="term">PLC_BOOT_HOST</span></dt>
1202 <dd>
1203 <p>
1204                   Type: hostname</p>
1205 <p>
1206                   Default: localhost.localdomain</p>
1207 <p>The fully qualified hostname of the boot
1208           server.</p>
1209 </dd>
1210 <dt><span class="term">PLC_BOOT_IP</span></dt>
1211 <dd>
1212 <p>
1213                   Type: ip</p>
1214 <p>
1215                   Default: 127.0.0.1</p>
1216 <p>The IP address of the boot server, if not
1217           resolvable by the configured DNS servers.</p>
1218 </dd>
1219 <dt><span class="term">PLC_BOOT_PORT</span></dt>
1220 <dd>
1221 <p>
1222                   Type: int</p>
1223 <p>
1224                   Default: 80</p>
1225 <p>The TCP port number through which the
1226           unprotected portions of the boot server should be
1227           accessed.</p>
1228 </dd>
1229 <dt><span class="term">PLC_BOOT_SSL_PORT</span></dt>
1230 <dd>
1231 <p>
1232                   Type: int</p>
1233 <p>
1234                   Default: 443</p>
1235 <p>The TCP port number through which the protected
1236           portions of the boot server should be
1237           accessed.</p>
1238 </dd>
1239 <dt><span class="term">PLC_BOOT_SSL_KEY</span></dt>
1240 <dd>
1241 <p>
1242                   Type: file</p>
1243 <p>
1244                   Default: /etc/planetlab/boot_ssl.key</p>
1245 <p>The SSL private key to use for encrypting HTTPS
1246           traffic.</p>
1247 </dd>
1248 <dt><span class="term">PLC_BOOT_SSL_CRT</span></dt>
1249 <dd>
1250 <p>
1251                   Type: file</p>
1252 <p>
1253                   Default: /etc/planetlab/boot_ssl.crt</p>
1254 <p>The corresponding SSL public certificate for
1255           the HTTP server. By default, this certificate is
1256           self-signed. You may replace the certificate later with one
1257           signed by a root CA.</p>
1258 </dd>
1259 <dt><span class="term">PLC_BOOT_CA_SSL_CRT</span></dt>
1260 <dd>
1261 <p>
1262                   Type: file</p>
1263 <p>
1264                   Default: /etc/planetlab/boot_ca_ssl.crt</p>
1265 <p>The certificate of the root CA, if any, that
1266           signed your server certificate. If your server certificate is
1267           self-signed, then this file is the same as your server
1268           certificate.</p>
1269 </dd>
1270 </dl></div>
1271 </div>
1272 <div class="appendix" lang="en">
1273 <h2 class="title" style="clear: both">
1274 <a name="id271742"></a>B. Development environment configuration variables</h2>
1275 <div class="variablelist"><dl>
1276 <dt><span class="term">PLC_DEVEL_FEDORA_RELEASE</span></dt>
1277 <dd>
1278 <p>
1279                   Type: string</p>
1280 <p>
1281                   Default: 4</p>
1282 <p>Version number of Fedora Core upon which to
1283           base the build environment. Warning: Currently, only Fedora
1284           Core 4 is supported.</p>
1285 </dd>
1286 <dt><span class="term">PLC_DEVEL_FEDORA_ARCH</span></dt>
1287 <dd>
1288 <p>
1289                   Type: string</p>
1290 <p>
1291                   Default: i386</p>
1292 <p>Base architecture of the build
1293           environment. Warning: Currently, only i386 is
1294           supported.</p>
1295 </dd>
1296 <dt><span class="term">PLC_DEVEL_FEDORA_URL</span></dt>
1297 <dd>
1298 <p>
1299                   Type: string</p>
1300 <p>
1301                   Default: file:///usr/share/mirrors/fedora</p>
1302 <p>Fedora Core mirror from which to install
1303           filesystems.</p>
1304 </dd>
1305 <dt><span class="term">PLC_DEVEL_CVSROOT</span></dt>
1306 <dd>
1307 <p>
1308                   Type: string</p>
1309 <p>
1310                   Default: /cvs</p>
1311 <p>CVSROOT to use when checking out code.</p>
1312 </dd>
1313 <dt><span class="term">PLC_DEVEL_BOOTSTRAP</span></dt>
1314 <dd>
1315 <p>
1316                   Type: boolean</p>
1317 <p>
1318                   Default: false</p>
1319 <p>Controls whether MyPLC should be built inside
1320           of its own development environment.</p>
1321 </dd>
1322 </dl></div>
1323 </div>
1324 <div class="bibliography">
1325 <div class="titlepage"><div><div><h2 class="title">
1326 <a name="id271824"></a>Bibliography</h2></div></div></div>
1327 <div class="biblioentry">
1328 <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
1329       Technical Contact's Guide</a></i>. </span></p>
1330 </div>
1331 </div>
1332 </div><?php require('footer.php'); ?>