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="id2795259"></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="#id2864719">1. Overview</a></span></dt>
  49 <dd><dl><dt><span class="section"><a href="#id2842268">1.1.  Purpose of the <span class="emphasis"><em> myplc-devel
  50     </em></span> package </a></span></dt></dl></dd>
  51 <dt><span class="section"><a href="#Requirements">2.  Requirements </a></span></dt>
  52 <dt><span class="section"><a href="#Installation">3. Installating and using MyPLC</a></span></dt>
  53 <dd><dl>
  54 <dt><span class="section"><a href="#id2841677">3.1. Installing MyPLC.</a></span></dt>
  55 <dt><span class="section"><a href="#QuickStart">3.2.  QuickStart </a></span></dt>
  56 <dt><span class="section"><a href="#ChangingTheConfiguration">3.3. Changing the configuration</a></span></dt>
  57 <dt><span class="section"><a href="#id2842715">3.4. Installing nodes</a></span></dt>
  58 <dt><span class="section"><a href="#id2842797">3.5. Administering nodes</a></span></dt>
  59 <dt><span class="section"><a href="#id2842898">3.6. Creating a slice</a></span></dt>
  60 <dt><span class="section"><a href="#StartupSequence">3.7. Understanding the startup sequence</a></span></dt>
  61 <dt><span class="section"><a href="#FilesInvolvedRuntime">3.8.  Files and directories
  62     involved in <span class="emphasis"><em>myplc</em></span></a></span></dt>
  63 </dl></dd>
  64 <dt><span class="section"><a href="#DevelopmentEnvironment">4. Rebuilding and customizing MyPLC</a></span></dt>
  65 <dd><dl>
  66 <dt><span class="section"><a href="#id2894620">4.1. Installation</a></span></dt>
  67 <dt><span class="section"><a href="#FilesInvolvedDevel">4.2.  Files and directories
  68     involved in <span class="emphasis"><em>myplc-devl</em></span></a></span></dt>
  69 <dt><span class="section"><a href="#id2894876">4.3. Fedora Core 4 mirror requirement</a></span></dt>
  70 <dt><span class="section"><a href="#BuildingMyPLC">4.4. Building MyPLC</a></span></dt>
  71 <dt><span class="section"><a href="#UpdatingCVS">4.5. Updating CVS</a></span></dt>
  72 </dl></dd>
  73 <dt><span class="appendix"><a href="#VariablesRuntime">A. Configuration variables (for <span class="emphasis"><em>myplc</em></span>)</a></span></dt>
  74 <dt><span class="appendix"><a href="#VariablesDevel">B. Development configuration variables (for <span class="emphasis"><em>myplc-devel</em></span>)</a></span></dt>
  75 <dt><span class="bibliography"><a href="#id2898373">Bibliography</a></span></dt>
  76 </dl>
  77 </div>
  78 <div class="section" lang="en">
  79 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  80 <a name="id2864719"></a>1. Overview</h2></div></div></div>
  81 <p>MyPLC is a complete PlanetLab Central (PLC) portable
  82     installation contained within a <span><strong class="command">chroot</strong></span>
  83     jail. The default installation consists of a web server, an
  84     XML-RPC API server, a boot server, and a database server: the core
  85     components of PLC. The installation is customized through an
  86     easy-to-use graphical interface. All PLC services are started up
  87     and shut down through a single script installed on the host
  88     system. The usually complex process of installing and
  89     administering the PlanetLab backend is reduced by containing PLC
  90     services within a virtual filesystem. By packaging it in such a
  91     manner, MyPLC may also be run on any modern Linux distribution,
  92     and could conceivably even run in a PlanetLab slice.</p>
  93 <div class="figure">
  94 <a name="Architecture"></a><p class="title"><b>Figure 1. MyPLC architecture</b></p>
  95 <div class="mediaobject" align="center">
  96 <img src="architecture.png" align="middle" width="270" alt="MyPLC architecture"><div class="caption"><p>MyPLC should be viewed as a single application that
  97           provides multiple functions and can run on any host
  98           system.</p></div>
  99 </div>
 100 </div>
 101 <div class="section" lang="en">
 102 <div class="titlepage"><div><div><h3 class="title">
 103 <a name="id2842268"></a>1.1.  Purpose of the <span class="emphasis"><em> myplc-devel
 104     </em></span> package </h3></div></div></div>
 105 <p> The <span class="emphasis"><em>myplc</em></span> package comes with all
 106     required node software, rebuilt from the public PlanetLab CVS
 107     repository. If for any reason you need to implement your own
 108     customized version of this software, you can use the
 109     <span class="emphasis"><em>myplc-devel</em></span> package instead, for setting up
 110     your own development environment, including a local CVS
 111     repository; you can then freely manage your changes and rebuild
 112     your customized version of <span class="emphasis"><em>myplc</em></span>. We also
 113     provide good practices, that will then allow you to resync your local
 114     CVS repository with any further evolution on the mainstream public
 115     PlanetLab software. </p>
 116 </div>
 117 </div>
 118 <div class="section" lang="en">
 119 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 120 <a name="Requirements"></a>2.  Requirements </h2></div></div></div>
 121 <p> <span class="emphasis"><em>myplc</em></span> and
 122   <span class="emphasis"><em>myplc-devel</em></span> were designed as
 123   <span><strong class="command">chroot</strong></span> jails so as to reduce the requirements on
 124   your host operating system. So in theory, these distributions should
 125   work on virtually any Linux 2.6 based distribution, whether it
 126   supports rpm or not. </p>
 127 <p> However, things are never that simple and there indeed are
 128   some known limitations to this, so here are a couple notes as a
 129   recommended reading before you proceed with the installation.</p>
 130 <p> As of 9 August 2006 (i.e <span class="emphasis"><em>myplc-0.5</em></span>) :</p>
 131 <div class="itemizedlist"><ul type="disc">
 132 <li><p> The software is vastly based on <span class="emphasis"><em>Fedora
 133   Core 4</em></span>. Please note that the build server at Princeton
 134   runs <span class="emphasis"><em>Fedora Core 2</em></span>, togother with a upgraded
 135   version of yum.
 136   </p></li>
 137 <li>
 138 <p> myplc and myplc-devel are known to work on both
 139   <span class="emphasis"><em>Fedora Core 2</em></span> and <span class="emphasis"><em>Fedora Core
 140   4</em></span>. Please note however that, on fc4 at least, it is
 141   highly recommended to use the <span class="application">Security Level
 142   Configuration</span> utility and to <span class="emphasis"><em>switch off
 143   SElinux</em></span> on your box because : </p>
 144 <div class="itemizedlist"><ul type="circle">
 145 <li><p>
 146   myplc requires you to run SElinux as 'Permissive' at most
 147         </p></li>
 148 <li><p>
 149   myplc-devel requires you to turn SElinux Off.
 150         </p></li>
 151 </ul></div>
 152 </li>
 153 <li><p> In addition, as far as myplc is concerned, you
 154   need to check your firewall configuration since you need, of course,
 155   to open up the <span class="emphasis"><em>http</em></span> and
 156   <span class="emphasis"><em>https</em></span> ports, so as to accept connections from
 157   the managed nodes and from the users desktops. </p></li>
 158 </ul></div>
 159 </div>
 160 <div class="section" lang="en">
 161 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 162 <a name="Installation"></a>3. Installating and using MyPLC</h2></div></div></div>
 163 <p>Though internally composed of commodity software
 164     subpackages, MyPLC should be treated as a monolithic software
 165     application. MyPLC is distributed as single RPM package that has
 166     no external dependencies, allowing it to be installed on
 167     practically any Linux 2.6 based distribution.</p>
 168 <div class="section" lang="en">
 169 <div class="titlepage"><div><div><h3 class="title">
 170 <a name="id2841677"></a>3.1. Installing MyPLC.</h3></div></div></div>
 171 <div class="itemizedlist"><ul type="disc">
 172 <li>
 173 <p>If your distribution supports RPM:</p>
 174 <pre class="programlisting"># rpm -U http://build.planet-lab.org/build/myplc-0_4-rc1/RPMS/i386/myplc-0.4-1.planetlab.i386.rpm</pre>
 175 </li>
 176 <li>
 177 <p>If your distribution does not support RPM:</p>
 178 <pre class="programlisting"># cd /tmp
 179 # wget http://build.planet-lab.org/build/myplc-0_4-rc1/RPMS/i386/myplc-0.4-1.planetlab.i386.rpm
 180 # cd /
 181 # rpm2cpio /tmp/myplc-0.4-1.planetlab.i386.rpm | cpio -diu</pre>
 182 </li>
 183 </ul></div>
 184 <p> The <a href="#FilesInvolvedRuntime" title="3.8.  Files and directories
 185     involved in myplc">Section 3.8, “ Files and directories
 186     involved in <span class="emphasis"><em>myplc</em></span>”</a> below explains in
 187     details the installation strategy and the miscellaneous files and
 188     directories involved.</p>
 189 </div>
 190 <div class="section" lang="en">
 191 <div class="titlepage"><div><div><h3 class="title">
 192 <a name="QuickStart"></a>3.2.  QuickStart </h3></div></div></div>
 193 <p> On a Red Hat or Fedora host system, it is customary to use
 194     the <span><strong class="command">service</strong></span> command to invoke System V init
 195     scripts. As the examples suggest, the service must be started as root:</p>
 196 <div class="example">
 197 <a name="id2841851"></a><p class="title"><b>Example 1. Starting MyPLC:</b></p>
 198 <pre class="programlisting"># service plc start</pre>
 199 </div>
 200 <div class="example">
 201 <a name="id2841863"></a><p class="title"><b>Example 2. Stopping MyPLC:</b></p>
 202 <pre class="programlisting"># service plc stop</pre>
 203 </div>
 204 <p> In <a href="#StartupSequence" title="3.7. Understanding the startup sequence">Section 3.7, “Understanding the startup sequence”</a>, we provide greater
 205     details that might be helpful in the case where the service does
 206     not seem to take off correctly.</p>
 207 <p>Like all other registered System V init services, MyPLC is
 208     started and shut down automatically when your host system boots
 209     and powers off. You may disable automatic startup by invoking the
 210     <span><strong class="command">chkconfig</strong></span> command on a Red Hat or Fedora host
 211     system:</p>
 212 <div class="example">
 213 <a name="id2841901"></a><p class="title"><b>Example 3. Disabling automatic startup of MyPLC.</b></p>
 214 <pre class="programlisting"># chkconfig plc off</pre>
 215 </div>
 216 <div class="example">
 217 <a name="id2842528"></a><p class="title"><b>Example 4. Re-enabling automatic startup of MyPLC.</b></p>
 218 <pre class="programlisting"># chkconfig plc on</pre>
 219 </div>
 220 </div>
 221 <div class="section" lang="en">
 222 <div class="titlepage"><div><div><h3 class="title">
 223 <a name="ChangingTheConfiguration"></a>3.3. Changing the configuration</h3></div></div></div>
 224 <p>After verifying that MyPLC is working correctly, shut it
 225       down and begin changing some of the default variable
 226       values. Shut down MyPLC with <span><strong class="command">service plc stop</strong></span>
 227       (see <a href="#QuickStart" title="3.2.  QuickStart ">Section 3.2, “ QuickStart ”</a>). With a text
 228       editor, open the file
 229       <code class="filename">/etc/planetlab/plc_config.xml</code>. This file is
 230       a self-documenting configuration file written in XML. Variables
 231       are divided into categories. Variable identifiers must be
 232       alphanumeric, plus underscore. A variable is referred to
 233       canonically as the uppercase concatenation of its category
 234       identifier, an underscore, and its variable identifier. Thus, a
 235       variable with an <code class="literal">id</code> of
 236       <code class="literal">slice_prefix</code> in the <code class="literal">plc</code>
 237       category is referred to canonically as
 238       <code class="envar">PLC_SLICE_PREFIX</code>.</p>
 239 <p>The reason for this convention is that during MyPLC
 240       startup, <code class="filename">plc_config.xml</code> is translated into
 241       several different languages—shell, PHP, and
 242       Python—so that scripts written in each of these languages
 243       can refer to the same underlying configuration. Most MyPLC
 244       scripts are written in shell, so the convention for shell
 245       variables predominates.</p>
 246 <p>The variables that you should change immediately are:</p>
 247 <div class="itemizedlist"><ul type="disc">
 248 <li><p><code class="envar">PLC_NAME</code>: Change this to the
 249         name of your PLC installation.</p></li>
 250 <li><p><code class="envar">PLC_ROOT_PASSWORD</code>: Change this
 251         to a more secure password.</p></li>
 252 <li><p><code class="envar">PLC_MAIL_SUPPORT_ADDRESS</code>:
 253         Change this to the e-mail address at which you would like to
 254         receive support requests.</p></li>
 255 <li><p><code class="envar">PLC_DB_HOST</code>,
 256         <code class="envar">PLC_DB_IP</code>, <code class="envar">PLC_API_HOST</code>,
 257         <code class="envar">PLC_API_IP</code>, <code class="envar">PLC_WWW_HOST</code>,
 258         <code class="envar">PLC_WWW_IP</code>, <code class="envar">PLC_BOOT_HOST</code>,
 259         <code class="envar">PLC_BOOT_IP</code>: Change all of these to the
 260         preferred FQDN and external IP address of your host
 261         system.</p></li>
 262 </ul></div>
 263 <p>The full set of applicable variables is described in <a href="#VariablesDevel" title="B. Development configuration variables (for myplc-devel)">Appendix B, <i>Development configuration variables (for <span class="emphasis"><em>myplc-devel</em></span>)</i></a>. After changing these variables,
 264       save the file, then restart MyPLC with <span><strong class="command">service plc
 265       start</strong></span>. You should notice that the password of the
 266       default administrator account is no longer
 267       <code class="literal">root</code>, and that the default site name includes
 268       the name of your PLC installation instead of PlanetLab.</p>
 269 </div>
 270 <div class="section" lang="en">
 271 <div class="titlepage"><div><div><h3 class="title">
 272 <a name="id2842715"></a>3.4. Installing nodes</h3></div></div></div>
 273 <p>Install your first node by clicking <code class="literal">Add
 274       Node</code> under the <code class="literal">Nodes</code> tab. Fill in
 275       all the appropriate details, then click
 276       <code class="literal">Add</code>. Download the node's configuration file
 277       by clicking <code class="literal">Download configuration file</code> on
 278       the <span class="bold"><strong>Node Details</strong></span> page for the
 279       node. Save it to a floppy disk or USB key as detailed in [<a href="#TechsGuide" title="[TechsGuide]">1</a>].</p>
 280 <p>Follow the rest of the instructions in [<a href="#TechsGuide" title="[TechsGuide]">1</a>] for creating a Boot CD and installing
 281       the node, except download the Boot CD image from the
 282       <code class="filename">/download</code> directory of your PLC
 283       installation, not from PlanetLab Central. The images located
 284       here are customized for your installation. If you change the
 285       hostname of your boot server (<code class="envar">PLC_BOOT_HOST</code>), or
 286       if the SSL certificate of your boot server expires, MyPLC will
 287       regenerate it and rebuild the Boot CD with the new
 288       certificate. If this occurs, you must replace all Boot CDs
 289       created before the certificate was regenerated.</p>
 290 <p>The installation process for a node has significantly
 291       improved since PlanetLab 3.3. It should now take only a few
 292       seconds for a new node to become ready to create slices.</p>
 293 </div>
 294 <div class="section" lang="en">
 295 <div class="titlepage"><div><div><h3 class="title">
 296 <a name="id2842797"></a>3.5. Administering nodes</h3></div></div></div>
 297 <p>You may administer nodes as <code class="literal">root</code> by
 298       using the SSH key stored in
 299       <code class="filename">/etc/planetlab/root_ssh_key.rsa</code>.</p>
 300 <div class="example">
 301 <a name="id2842820"></a><p class="title"><b>Example 5. Accessing nodes via SSH. Replace
 302         <code class="literal">node</code> with the hostname of the node.</b></p>
 303 <pre class="programlisting">ssh -i /etc/planetlab/root_ssh_key.rsa root@node</pre>
 304 </div>
 305 <p>Besides the standard Linux log files located in
 306       <code class="filename">/var/log</code>, several other files can give you
 307       clues about any problems with active processes:</p>
 308 <div class="itemizedlist"><ul type="disc">
 309 <li><p><code class="filename">/var/log/pl_nm</code>: The log
 310         file for the Node Manager.</p></li>
 311 <li><p><code class="filename">/vservers/pl_conf/var/log/pl_conf</code>:
 312         The log file for the Slice Creation Service.</p></li>
 313 <li><p><code class="filename">/var/log/propd</code>: The log
 314         file for Proper, the service which allows certain slices to
 315         perform certain privileged operations in the root
 316         context.</p></li>
 317 <li><p><code class="filename">/vservers/pl_netflow/var/log/netflow.log</code>:
 318         The log file for PlanetFlow, the network traffic auditing
 319         service.</p></li>
 320 </ul></div>
 321 </div>
 322 <div class="section" lang="en">
 323 <div class="titlepage"><div><div><h3 class="title">
 324 <a name="id2842898"></a>3.6. Creating a slice</h3></div></div></div>
 325 <p>Create a slice by clicking <code class="literal">Create Slice</code>
 326       under the <code class="literal">Slices</code> tab. Fill in all the
 327       appropriate details, then click <code class="literal">Create</code>. Add
 328       nodes to the slice by clicking <code class="literal">Manage Nodes</code>
 329       on the <span class="bold"><strong>Slice Details</strong></span> page for
 330       the slice.</p>
 331 <p>A <span><strong class="command">cron</strong></span> job runs every five minutes and
 332       updates the file
 333       <code class="filename">/plc/data/var/www/html/xml/slices-0.5.xml</code>
 334       with information about current slice state. The Slice Creation
 335       Service running on every node polls this file every ten minutes
 336       to determine if it needs to create or delete any slices. You may
 337       accelerate this process manually if desired.</p>
 338 <div class="example">
 339 <a name="id2842960"></a><p class="title"><b>Example 6. Forcing slice creation on a node.</b></p>
 340 <pre class="programlisting"># Update slices.xml immediately
 341 service plc start crond
 342
 343 # Kick the Slice Creation Service on a particular node.
 344 ssh -i /etc/planetlab/root_ssh_key.rsa root@node \
 345 vserver pl_conf exec service pl_conf restart</pre>
 346 </div>
 347 </div>
 348 <div class="section" lang="en">
 349 <div class="titlepage"><div><div><h3 class="title">
 350 <a name="StartupSequence"></a>3.7. Understanding the startup sequence</h3></div></div></div>
 351 <p>During service startup described in <a href="#QuickStart" title="3.2.  QuickStart ">Section 3.2, “ QuickStart ”</a>, observe the output of this command for
 352     any failures. If no failures occur, you should see output similar
 353     to the following:</p>
 354 <div class="example">
 355 <a name="id2893858"></a><p class="title"><b>Example 7. A successful MyPLC startup.</b></p>
 356 <pre class="programlisting">Mounting PLC:                                              [  OK  ]
 357 PLC: Generating network files:                             [  OK  ]
 358 PLC: Starting system logger:                               [  OK  ]
 359 PLC: Starting database server:                             [  OK  ]
 360 PLC: Generating SSL certificates:                          [  OK  ]
 361 PLC: Configuring the API:                                  [  OK  ]
 362 PLC: Updating GPG keys:                                    [  OK  ]
 363 PLC: Generating SSH keys:                                  [  OK  ]
 364 PLC: Starting web server:                                  [  OK  ]
 365 PLC: Bootstrapping the database:                           [  OK  ]
 366 PLC: Starting DNS server:                                  [  OK  ]
 367 PLC: Starting crond:                                       [  OK  ]
 368 PLC: Rebuilding Boot CD:                                   [  OK  ]
 369 PLC: Rebuilding Boot Manager:                              [  OK  ]
 370 PLC: Signing node packages:                                [  OK  ]
 371 </pre>
 372 </div>
 373 <p>If <code class="filename">/plc/root</code> is mounted successfully, a
 374     complete log file of the startup process may be found at
 375     <code class="filename">/plc/root/var/log/boot.log</code>. Possible reasons
 376     for failure of each step include:</p>
 377 <div class="itemizedlist"><ul type="disc">
 378 <li><p><code class="literal">Mounting PLC</code>: If this step
 379       fails, first ensure that you started MyPLC as root. Check
 380       <code class="filename">/etc/sysconfig/plc</code> to ensure that
 381       <code class="envar">PLC_ROOT</code> and <code class="envar">PLC_DATA</code> refer to the
 382       right locations. You may also have too many existing loopback
 383       mounts, or your kernel may not support loopback mounting, bind
 384       mounting, or the ext3 filesystem. Try freeing at least one
 385       loopback device, or re-compiling your kernel to support loopback
 386       mounting, bind mounting, and the ext3 filesystem. If you see an
 387       error similar to <code class="literal">Permission denied while trying to open
 388       /plc/root.img</code>, then SELinux may be enabled. See <a href="#Requirements" title="2.  Requirements ">Section 2, “ Requirements ”</a> above for details.</p></li>
 389 <li><p><code class="literal">Starting database server</code>: If
 390       this step fails, check
 391       <code class="filename">/plc/root/var/log/pgsql</code> and
 392       <code class="filename">/plc/root/var/log/boot.log</code>. The most common
 393       reason for failure is that the default PostgreSQL port, TCP port
 394       5432, is already in use. Check that you are not running a
 395       PostgreSQL server on the host system.</p></li>
 396 <li><p><code class="literal">Starting web server</code>: If this
 397       step fails, check
 398       <code class="filename">/plc/root/var/log/httpd/error_log</code> and
 399       <code class="filename">/plc/root/var/log/boot.log</code> for obvious
 400       errors. The most common reason for failure is that the default
 401       web ports, TCP ports 80 and 443, are already in use. Check that
 402       you are not running a web server on the host
 403       system.</p></li>
 404 <li><p><code class="literal">Bootstrapping the database</code>:
 405       If this step fails, it is likely that the previous step
 406       (<code class="literal">Starting web server</code>) also failed. Another
 407       reason that it could fail is if <code class="envar">PLC_API_HOST</code> (see
 408       <a href="#ChangingTheConfiguration" title="3.3. Changing the configuration">Section 3.3, “Changing the configuration”</a>) does not resolve to
 409       the host on which the API server has been enabled. By default,
 410       all services, including the API server, are enabled and run on
 411       the same host, so check that <code class="envar">PLC_API_HOST</code> is
 412       either <code class="filename">localhost</code> or resolves to a local IP
 413       address.</p></li>
 414 <li><p><code class="literal">Starting crond</code>: If this step
 415       fails, it is likely that the previous steps (<code class="literal">Starting
 416       web server</code> and <code class="literal">Bootstrapping the
 417       database</code>) also failed. If not, check
 418       <code class="filename">/plc/root/var/log/boot.log</code> for obvious
 419       errors. This step starts the <span><strong class="command">cron</strong></span> service and
 420       generates the initial set of XML files that the Slice Creation
 421       Service uses to determine slice state.</p></li>
 422 </ul></div>
 423 <p>If no failures occur, then MyPLC should be active with a
 424     default configuration. Open a web browser on the host system and
 425     visit <code class="literal">http://localhost/</code>, which should bring you
 426     to the front page of your PLC installation. The password of the
 427     default administrator account
 428     <code class="literal">root@localhost.localdomain</code> (set by
 429     <code class="envar">PLC_ROOT_USER</code>) is <code class="literal">root</code> (set by
 430     <code class="envar">PLC_ROOT_PASSWORD</code>).</p>
 431 </div>
 432 <div class="section" lang="en">
 433 <div class="titlepage"><div><div><h3 class="title">
 434 <a name="FilesInvolvedRuntime"></a>3.8.  Files and directories
 435     involved in <span class="emphasis"><em>myplc</em></span></h3></div></div></div>
 436 <p>MyPLC installs the following files and directories:</p>
 437 <div class="orderedlist"><ol type="1">
 438 <li><p><code class="filename">/plc/root.img</code>: The main
 439       root filesystem of the MyPLC application. This file is an
 440       uncompressed ext3 filesystem that is loopback mounted on
 441       <code class="filename">/plc/root</code> when MyPLC starts. This
 442       filesystem, even when mounted, should be treated as an opaque
 443       binary that can and will be replaced in its entirety by any
 444       upgrade of MyPLC.</p></li>
 445 <li><p><code class="filename">/plc/root</code>: The mount point
 446       for <code class="filename">/plc/root.img</code>. Once the root filesystem
 447       is mounted, all MyPLC services run in a
 448       <span><strong class="command">chroot</strong></span> jail based in this
 449       directory.</p></li>
 450 <li>
 451 <p><code class="filename">/plc/data</code>: The directory where user
 452         data and generated files are stored. This directory is bind
 453         mounted onto <code class="filename">/plc/root/data</code> so that it is
 454         accessible as <code class="filename">/data</code> from within the
 455         <span><strong class="command">chroot</strong></span> jail. Files in this directory are
 456         marked with <span><strong class="command">%config(noreplace)</strong></span> in the
 457         RPM. That is, during an upgrade of MyPLC, if a file has not
 458         changed since the last installation or upgrade of MyPLC, it is
 459         subject to upgrade and replacement. If the file has changed,
 460         the new version of the file will be created with a
 461         <code class="filename">.rpmnew</code> extension. Symlinks within the
 462         MyPLC root filesystem ensure that the following directories
 463         (relative to <code class="filename">/plc/root</code>) are stored
 464         outside the MyPLC filesystem image:</p>
 465 <div class="itemizedlist"><ul type="disc">
 466 <li><p><code class="filename">/etc/planetlab</code>: This
 467           directory contains the configuration files, keys, and
 468           certificates that define your MyPLC
 469           installation.</p></li>
 470 <li><p><code class="filename">/var/lib/pgsql</code>: This
 471           directory contains PostgreSQL database
 472           files.</p></li>
 473 <li><p><code class="filename">/var/www/html/alpina-logs</code>: This
 474           directory contains node installation logs.</p></li>
 475 <li><p><code class="filename">/var/www/html/boot</code>: This
 476           directory contains the Boot Manager, customized for your MyPLC
 477           installation, and its data files.</p></li>
 478 <li><p><code class="filename">/var/www/html/download</code>: This
 479           directory contains Boot CD images, customized for your MyPLC
 480           installation.</p></li>
 481 <li><p><code class="filename">/var/www/html/install-rpms</code>: This
 482           directory is where you should install node package updates,
 483           if any. By default, nodes are installed from the tarball
 484           located at
 485           <code class="filename">/var/www/html/boot/PlanetLab-Bootstrap.tar.bz2</code>,
 486           which is pre-built from the latest PlanetLab Central
 487           sources, and installed as part of your MyPLC
 488           installation. However, nodes will attempt to install any
 489           newer RPMs located in
 490           <code class="filename">/var/www/html/install-rpms/planetlab</code>,
 491           after initial installation and periodically thereafter. You
 492           must run <span><strong class="command">yum-arch</strong></span> and
 493           <span><strong class="command">createrepo</strong></span> to update the
 494           <span><strong class="command">yum</strong></span> caches in this directory after
 495           installing a new RPM. PlanetLab Central cannot support any
 496           changes to this directory.</p></li>
 497 <li><p><code class="filename">/var/www/html/xml</code>: This
 498           directory contains various XML files that the Slice Creation
 499           Service uses to determine the state of slices. These XML
 500           files are refreshed periodically by <span><strong class="command">cron</strong></span>
 501           jobs running in the MyPLC root.</p></li>
 502 </ul></div>
 503 </li>
 504 <li><p><a name="MyplcInitScripts"></a><code class="filename">/etc/init.d/plc</code>: This file
 505         is a System V init script installed on your host filesystem,
 506         that allows you to start up and shut down MyPLC with a single
 507         command, as described in <a href="#QuickStart" title="3.2.  QuickStart ">Section 3.2, “ QuickStart ”</a>.</p></li>
 508 <li><p><code class="filename">/etc/sysconfig/plc</code>: This
 509       file is a shell script fragment that defines the variables
 510       <code class="envar">PLC_ROOT</code> and <code class="envar">PLC_DATA</code>. By default,
 511       the values of these variables are <code class="filename">/plc/root</code>
 512       and <code class="filename">/plc/data</code>, respectively. If you wish,
 513       you may move your MyPLC installation to another location on your
 514       host filesystem and edit the values of these variables
 515       appropriately, but you will break the RPM upgrade
 516       process. PlanetLab Central cannot support any changes to this
 517       file.</p></li>
 518 <li><p><code class="filename">/etc/planetlab</code>: This
 519       symlink to <code class="filename">/plc/data/etc/planetlab</code> is
 520       installed on the host system for convenience.</p></li>
 521 </ol></div>
 522 </div>
 523 </div>
 524 <div class="section" lang="en">
 525 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 526 <a name="DevelopmentEnvironment"></a>4. Rebuilding and customizing MyPLC</h2></div></div></div>
 527 <p>The MyPLC package, though distributed as an RPM, is not a
 528     traditional package that can be easily rebuilt from SRPM. The
 529     requisite build environment is quite extensive and numerous
 530     assumptions are made throughout the PlanetLab source code base,
 531     that the build environment is based on Fedora Core 4 and that
 532     access to a complete Fedora Core 4 mirror is available.</p>
 533 <p>For this reason, it is recommended that you only rebuild
 534     MyPLC (or any of its components) from within the MyPLC development
 535     environment. The MyPLC development environment is similar to MyPLC
 536     itself in that it is a portable filesystem contained within a
 537     <span><strong class="command">chroot</strong></span> jail. The filesystem contains all the
 538     necessary tools required to rebuild MyPLC, as well as a snapshot
 539     of the PlanetLab source code base in the form of a local CVS
 540     repository.</p>
 541 <div class="section" lang="en">
 542 <div class="titlepage"><div><div><h3 class="title">
 543 <a name="id2894620"></a>4.1. Installation</h3></div></div></div>
 544 <p>Install the MyPLC development environment similarly to how
 545       you would install MyPLC. You may install both packages on the same
 546       host system if you wish. As with MyPLC, the MyPLC development
 547       environment should be treated as a monolithic software
 548       application, and any files present in the
 549       <span><strong class="command">chroot</strong></span> jail should not be modified directly, as
 550       they are subject to upgrade.</p>
 551 <div class="itemizedlist"><ul type="disc">
 552 <li>
 553 <p>If your distribution supports RPM:</p>
 554 <pre class="programlisting"># rpm -U http://build.planet-lab.org/build/myplc-0_4-rc2/RPMS/i386/myplc-devel-0.4-2.planetlab.i386.rpm</pre>
 555 </li>
 556 <li>
 557 <p>If your distribution does not support RPM:</p>
 558 <pre class="programlisting"># cd /tmp
 559 # wget http://build.planet-lab.org/build/myplc-0_4-rc2/RPMS/i386/myplc-devel-0.4-2.planetlab.i386.rpm
 560 # cd /
 561 # rpm2cpio /tmp/myplc-devel-0.4-2.planetlab.i386.rpm | cpio -diu</pre>
 562 </li>
 563 </ul></div>
 564 </div>
 565 <div class="section" lang="en">
 566 <div class="titlepage"><div><div><h3 class="title">
 567 <a name="FilesInvolvedDevel"></a>4.2.  Files and directories
 568     involved in <span class="emphasis"><em>myplc-devl</em></span></h3></div></div></div>
 569 <p>The MyPLC development environment installs the following
 570       files and directories:</p>
 571 <div class="itemizedlist"><ul type="disc">
 572 <li><p><code class="filename">/plc/devel/root.img</code>: The
 573         main root filesystem of the MyPLC development environment. This
 574         file is an uncompressed ext3 filesystem that is loopback mounted
 575         on <code class="filename">/plc/devel/root</code> when the MyPLC
 576         development environment is initialized. This filesystem, even
 577         when mounted, should be treated as an opaque binary that can and
 578         will be replaced in its entirety by any upgrade of the MyPLC
 579         development environment.</p></li>
 580 <li><p><code class="filename">/plc/devel/root</code>: The mount
 581         point for
 582         <code class="filename">/plc/devel/root.img</code>.</p></li>
 583 <li>
 584 <p><code class="filename">/plc/devel/data</code>: The directory
 585           where user data and generated files are stored. This directory
 586           is bind mounted onto <code class="filename">/plc/devel/root/data</code>
 587           so that it is accessible as <code class="filename">/data</code> from
 588           within the <span><strong class="command">chroot</strong></span> jail. Files in this
 589           directory are marked with
 590           <span><strong class="command">%config(noreplace)</strong></span> in the RPM. Symlinks
 591           ensure that the following directories (relative to
 592           <code class="filename">/plc/devel/root</code>) are stored outside the
 593           root filesystem image:</p>
 594 <div class="itemizedlist"><ul type="circle">
 595 <li><p><code class="filename">/etc/planetlab</code>: This
 596             directory contains the configuration files that define your
 597             MyPLC development environment.</p></li>
 598 <li><p><code class="filename">/cvs</code>: A
 599             snapshot of the PlanetLab source code is stored as a CVS
 600             repository in this directory. Files in this directory will
 601             <span class="bold"><strong>not</strong></span> be updated by an upgrade of
 602             <code class="filename">myplc-devel</code>. See <a href="#UpdatingCVS" title="4.5. Updating CVS">Section 4.5, “Updating CVS”</a> for more information about updating
 603             PlanetLab source code.</p></li>
 604 <li><p><code class="filename">/build</code>:
 605             Builds are stored in this directory. This directory is bind
 606             mounted onto <code class="filename">/plc/devel/root/build</code> so that
 607             it is accessible as <code class="filename">/build</code> from within the
 608             <span><strong class="command">chroot</strong></span> jail. The build scripts in this
 609             directory are themselves source controlled; see <a href="#BuildingMyPLC" title="4.4. Building MyPLC">Section 4.4, “Building MyPLC”</a> for more information about executing
 610             builds.</p></li>
 611 </ul></div>
 612 </li>
 613 <li><p><code class="filename">/etc/init.d/plc-devel</code>: This file is
 614           a System V init script installed on your host filesystem, that
 615           allows you to start up and shut down the MyPLC development
 616           environment with a single command.</p></li>
 617 </ul></div>
 618 </div>
 619 <div class="section" lang="en">
 620 <div class="titlepage"><div><div><h3 class="title">
 621 <a name="id2894876"></a>4.3. Fedora Core 4 mirror requirement</h3></div></div></div>
 622 <p>The MyPLC development environment requires access to a
 623       complete Fedora Core 4 i386 RPM repository, because several
 624       different filesystems based upon Fedora Core 4 are constructed
 625       during the process of building MyPLC. You may configure the
 626       location of this repository via the
 627       <code class="envar">PLC_DEVEL_FEDORA_URL</code> variable in
 628       <code class="filename">/plc/devel/data/etc/planetlab/plc_config.xml</code>. The
 629       value of the variable should be a URL that points to the top
 630       level of a Fedora mirror that provides the
 631       <code class="filename">base</code>, <code class="filename">updates</code>, and
 632       <code class="filename">extras</code> repositories, e.g.,</p>
 633 <div class="itemizedlist"><ul type="disc">
 634 <li><p><code class="filename">file:///data/fedora</code></p></li>
 635 <li><p><code class="filename">http://coblitz.planet-lab.org/pub/fedora</code></p></li>
 636 <li><p><code class="filename">ftp://mirror.cs.princeton.edu/pub/mirrors/fedora</code></p></li>
 637 <li><p><code class="filename">ftp://mirror.stanford.edu/pub/mirrors/fedora</code></p></li>
 638 <li><p><code class="filename">http://rpmfind.net/linux/fedora</code></p></li>
 639 </ul></div>
 640 <p>As implied by the list, the repository may be located on
 641       the local filesystem, or it may be located on a remote FTP or
 642       HTTP server. URLs beginning with <code class="filename">file://</code>
 643       should exist at the specified location relative to the root of
 644       the <span><strong class="command">chroot</strong></span> jail. For optimum performance and
 645       reproducibility, specify
 646       <code class="envar">PLC_DEVEL_FEDORA_URL=file:///data/fedora</code> and
 647       download all Fedora Core 4 RPMS into
 648       <code class="filename">/plc/devel/data/fedora</code> on the host system
 649       after installing <code class="filename">myplc-devel</code>. Use a tool
 650       such as <span><strong class="command">wget</strong></span> or <span><strong class="command">rsync</strong></span> to
 651       download the RPMS from a public mirror:</p>
 652 <div class="example">
 653 <a name="id2895018"></a><p class="title"><b>Example 8. Setting up a local Fedora Core 4 repository.</b></p>
 654 <pre class="programlisting"># mkdir -p /plc/devel/data/fedora
 655 # cd /plc/devel/data/fedora
 656
 657 # for repo in core/4/i386/os core/updates/4/i386 extras/4/i386 ; do
 658 &gt;     wget -m -nH --cut-dirs=3 http://coblitz.planet-lab.org/pub/fedora/linux/$repo
 659 &gt; done</pre>
 660 </div>
 661 <p>Change the repository URI and <span><strong class="command">--cut-dirs</strong></span>
 662       level as needed to produce a hierarchy that resembles:</p>
 663 <pre class="programlisting">/plc/devel/data/fedora/core/4/i386/os
 664 /plc/devel/data/fedora/core/updates/4/i386
 665 /plc/devel/data/fedora/extras/4/i386</pre>
 666 <p>A list of additional Fedora Core 4 mirrors is available at
 667       <a href="http://fedora.redhat.com/Download/mirrors.html" target="_top">http://fedora.redhat.com/Download/mirrors.html</a>.</p>
 668 </div>
 669 <div class="section" lang="en">
 670 <div class="titlepage"><div><div><h3 class="title">
 671 <a name="BuildingMyPLC"></a>4.4. Building MyPLC</h3></div></div></div>
 672 <p>All PlanetLab source code modules are built and installed
 673       as RPMS. A set of build scripts, checked into the
 674       <code class="filename">build/</code> directory of the PlanetLab CVS
 675       repository, eases the task of rebuilding PlanetLab source
 676       code.</p>
 677 <p> Before you try building MyPLC, you might check the
 678       configuration, in a file named
 679       <span class="emphasis"><em>plc_config.xml</em></span> that relies on a very
 680       similar model as MyPLC, located in
 681       <span class="emphasis"><em>/etc/planetlab</em></span> within the chroot jail, or
 682       in <span class="emphasis"><em>/plc/devel/data/etc/planetlab</em></span> from the
 683       root context. The set of applicable variables is described in
 684       <a href="#VariablesDevel" title="B. Development configuration variables (for myplc-devel)">Appendix B, <i>Development configuration variables (for <span class="emphasis"><em>myplc-devel</em></span>)</i></a>. </p>
 685 <p>To build MyPLC, or any PlanetLab source code module, from
 686       within the MyPLC development environment, execute the following
 687       commands as root:</p>
 688 <div class="example">
 689 <a name="id2895119"></a><p class="title"><b>Example 9. Building MyPLC.</b></p>
 690 <pre class="programlisting"># Initialize MyPLC development environment
 691 service plc-devel start
 692
 693 # Enter development environment
 694 chroot /plc/devel/root su -
 695
 696 # Check out build scripts into a directory named after the current
 697 # date. This is simply a convention, it need not be followed
 698 # exactly. See build/build.sh for an example of a build script that
 699 # names build directories after CVS tags.
 700 DATE=$(date +%Y.%m.%d)
 701 cd /build
 702 cvs -d /cvs checkout -d $DATE build
 703
 704 # Build everything
 705 make -C $DATE</pre>
 706 </div>
 707 <p>If the build succeeds, a set of binary RPMS will be
 708       installed under
 709       <code class="filename">/plc/devel/data/build/$DATE/RPMS/</code> that you
 710       may copy to the
 711       <code class="filename">/var/www/html/install-rpms/planetlab</code>
 712       directory of your MyPLC installation (see <a href="#Installation" title="3. Installating and using MyPLC">Section 3, “Installating and using MyPLC”</a>).</p>
 713 </div>
 714 <div class="section" lang="en">
 715 <div class="titlepage"><div><div><h3 class="title">
 716 <a name="UpdatingCVS"></a>4.5. Updating CVS</h3></div></div></div>
 717 <p>A complete snapshot of the PlanetLab source code is included
 718       with the MyPLC development environment as a CVS repository in
 719       <code class="filename">/plc/devel/data/cvs</code>. This CVS repository may
 720       be accessed like any other CVS repository. It may be accessed
 721       using an interface such as <a href="http://www.freebsd.org/projects/cvsweb.html" target="_top">CVSweb</a>,
 722       and file permissions may be altered to allow for fine-grained
 723       access control. Although the files are included with the
 724       <code class="filename">myplc-devel</code> RPM, they are <span class="bold"><strong>not</strong></span> subject to upgrade once installed. New
 725       versions of the <code class="filename">myplc-devel</code> RPM will install
 726       updated snapshot repositories in
 727       <code class="filename">/plc/devel/data/cvs-%{version}-%{release}</code>,
 728       where <code class="literal">%{version}-%{release}</code> is replaced with
 729       the version number of the RPM.</p>
 730 <p>Because the CVS repository is not automatically upgraded,
 731       if you wish to keep your local repository synchronized with the
 732       public PlanetLab repository, it is highly recommended that you
 733       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
 734       branches</a> to track changes. Vendor branches ease the task
 735       of merging upstream changes with your local modifications. To
 736       import a new snapshot into your local repository (for example,
 737       if you have just upgraded from
 738       <code class="filename">myplc-devel-0.4-2</code> to
 739       <code class="filename">myplc-devel-0.4-3</code> and you notice the new
 740       repository in <code class="filename">/plc/devel/data/cvs-0.4-3</code>),
 741       execute the following commands as root from within the MyPLC
 742       development environment:</p>
 743 <div class="example">
 744 <a name="id2895270"></a><p class="title"><b>Example 10. Updating /data/cvs from /data/cvs-0.4-3.</b></p>
 745 <p><span class="bold"><strong>Warning</strong></span>: This may cause
 746         severe, irreversible changes to be made to your local
 747         repository. Always tag your local repository before
 748         importing.</p>
 749 <pre class="programlisting"># Initialize MyPLC development environment
 750 service plc-devel start
 751
 752 # Enter development environment
 753 chroot /plc/devel/root su -
 754
 755 # Tag current state
 756 cvs -d /cvs rtag before-myplc-0_4-3-merge
 757
 758 # Export snapshot
 759 TMP=$(mktemp -d /data/export.XXXXXX)
 760 pushd $TMP
 761 cvs -d /data/cvs-0.4-3 export -r HEAD .
 762 cvs -d /cvs import -m "PlanetLab sources from myplc-0.4-3" -ko -I ! . planetlab myplc-0_4-3
 763 popd
 764 rm -rf $TMP</pre>
 765 </div>
 766 <p>If there any merge conflicts, use the command suggested by
 767       CVS to help the merge. Explaining how to fix merge conflicts is
 768       beyond the scope of this document; consult the CVS documentation
 769       for more information on how to use CVS.</p>
 770 </div>
 771 </div>
 772 <div class="appendix" lang="en">
 773 <h2 class="title" style="clear: both">
 774 <a name="VariablesRuntime"></a>A. Configuration variables (for <span class="emphasis"><em>myplc</em></span>)</h2>
 775 <p>Listed below is the set of standard configuration variables
 776     and their default values, defined in the template
 777     <code class="filename">/etc/planetlab/default_config.xml</code>. Additional
 778     variables and their defaults may be defined in site-specific XML
 779     templates that should be placed in
 780     <code class="filename">/etc/planetlab/configs/</code>.</p>
 781 <div class="variablelist"><dl>
 782 <dt><span class="term">PLC_NAME</span></dt>
 783 <dd>
 784 <p>
 785                   Type: string</p>
 786 <p>
 787                   Default: PlanetLab Test</p>
 788 <p>The name of this PLC installation. It is used in
 789           the name of the default system site (e.g., PlanetLab Central)
 790           and in the names of various administrative entities (e.g.,
 791           PlanetLab Support).</p>
 792 </dd>
 793 <dt><span class="term">PLC_SLICE_PREFIX</span></dt>
 794 <dd>
 795 <p>
 796                   Type: string</p>
 797 <p>
 798                   Default: pl</p>
 799 <p>The abbreviated name of this PLC
 800           installation. It is used as the prefix for system slices
 801           (e.g., pl_conf). Warning: Currently, this variable should
 802           not be changed.</p>
 803 </dd>
 804 <dt><span class="term">PLC_ROOT_USER</span></dt>
 805 <dd>
 806 <p>
 807                   Type: email</p>
 808 <p>
 809                   Default: root@localhost.localdomain</p>
 810 <p>The name of the initial administrative
 811           account. We recommend that this account be used only to create
 812           additional accounts associated with real
 813           administrators, then disabled.</p>
 814 </dd>
 815 <dt><span class="term">PLC_ROOT_PASSWORD</span></dt>
 816 <dd>
 817 <p>
 818                   Type: password</p>
 819 <p>
 820                   Default: root</p>
 821 <p>The password of the initial administrative
 822           account. Also the password of the root account on the Boot
 823           CD.</p>
 824 </dd>
 825 <dt><span class="term">PLC_ROOT_SSH_KEY_PUB</span></dt>
 826 <dd>
 827 <p>
 828                   Type: file</p>
 829 <p>
 830                   Default: /etc/planetlab/root_ssh_key.pub</p>
 831 <p>The SSH public key used to access the root
 832           account on your nodes.</p>
 833 </dd>
 834 <dt><span class="term">PLC_ROOT_SSH_KEY</span></dt>
 835 <dd>
 836 <p>
 837                   Type: file</p>
 838 <p>
 839                   Default: /etc/planetlab/root_ssh_key.rsa</p>
 840 <p>The SSH private key used to access the root
 841           account on your nodes.</p>
 842 </dd>
 843 <dt><span class="term">PLC_DEBUG_SSH_KEY_PUB</span></dt>
 844 <dd>
 845 <p>
 846                   Type: file</p>
 847 <p>
 848                   Default: /etc/planetlab/debug_ssh_key.pub</p>
 849 <p>The SSH public key used to access the root
 850           account on your nodes when they are in Debug mode.</p>
 851 </dd>
 852 <dt><span class="term">PLC_DEBUG_SSH_KEY</span></dt>
 853 <dd>
 854 <p>
 855                   Type: file</p>
 856 <p>
 857                   Default: /etc/planetlab/debug_ssh_key.rsa</p>
 858 <p>The SSH private key used to access the root
 859           account on your nodes when they are in Debug mode.</p>
 860 </dd>
 861 <dt><span class="term">PLC_ROOT_GPG_KEY_PUB</span></dt>
 862 <dd>
 863 <p>
 864                   Type: file</p>
 865 <p>
 866                   Default: /etc/planetlab/pubring.gpg</p>
 867 <p>The GPG public keyring used to sign the Boot
 868           Manager and all node packages.</p>
 869 </dd>
 870 <dt><span class="term">PLC_ROOT_GPG_KEY</span></dt>
 871 <dd>
 872 <p>
 873                   Type: file</p>
 874 <p>
 875                   Default: /etc/planetlab/secring.gpg</p>
 876 <p>The SSH private key used to access the root
 877           account on your nodes.</p>
 878 </dd>
 879 <dt><span class="term">PLC_MA_SA_NAMESPACE</span></dt>
 880 <dd>
 881 <p>
 882                   Type: ip</p>
 883 <p>
 884                   Default: test</p>
 885 <p>The namespace of your MA/SA. This should be a
 886           globally unique value assigned by PlanetLab
 887           Central.</p>
 888 </dd>
 889 <dt><span class="term">PLC_MA_SA_SSL_KEY</span></dt>
 890 <dd>
 891 <p>
 892                   Type: file</p>
 893 <p>
 894                   Default: /etc/planetlab/ma_sa_ssl.key</p>
 895 <p>The SSL private key used for signing documents
 896           with the signature of your MA/SA. If non-existent, one will
 897           be generated.</p>
 898 </dd>
 899 <dt><span class="term">PLC_MA_SA_SSL_CRT</span></dt>
 900 <dd>
 901 <p>
 902                   Type: file</p>
 903 <p>
 904                   Default: /etc/planetlab/ma_sa_ssl.crt</p>
 905 <p>The corresponding SSL public certificate. By
 906           default, this certificate is self-signed. You may replace
 907           the certificate later with one signed by the PLC root
 908           CA.</p>
 909 </dd>
 910 <dt><span class="term">PLC_MA_SA_CA_SSL_CRT</span></dt>
 911 <dd>
 912 <p>
 913                   Type: file</p>
 914 <p>
 915                   Default: /etc/planetlab/ma_sa_ca_ssl.crt</p>
 916 <p>If applicable, the certificate of the PLC root
 917           CA. If your MA/SA certificate is self-signed, then this file
 918           is the same as your MA/SA certificate.</p>
 919 </dd>
 920 <dt><span class="term">PLC_MA_SA_CA_SSL_KEY_PUB</span></dt>
 921 <dd>
 922 <p>
 923                   Type: file</p>
 924 <p>
 925                   Default: /etc/planetlab/ma_sa_ca_ssl.pub</p>
 926 <p>If applicable, the public key of the PLC root
 927           CA. If your MA/SA certificate is self-signed, then this file
 928           is the same as your MA/SA public key.</p>
 929 </dd>
 930 <dt><span class="term">PLC_MA_SA_API_CRT</span></dt>
 931 <dd>
 932 <p>
 933                   Type: file</p>
 934 <p>
 935                   Default: /etc/planetlab/ma_sa_api.xml</p>
 936 <p>The API Certificate is your MA/SA public key
 937           embedded in a digitally signed XML document. By default,
 938           this document is self-signed. You may replace this
 939           certificate later with one signed by the PLC root
 940           CA.</p>
 941 </dd>
 942 <dt><span class="term">PLC_NET_DNS1</span></dt>
 943 <dd>
 944 <p>
 945                   Type: ip</p>
 946 <p>
 947                   Default: 127.0.0.1</p>
 948 <p>Primary DNS server address.</p>
 949 </dd>
 950 <dt><span class="term">PLC_NET_DNS2</span></dt>
 951 <dd>
 952 <p>
 953                   Type: ip</p>
 954 <p>
 955                   Default: </p>
 956 <p>Secondary DNS server address.</p>
 957 </dd>
 958 <dt><span class="term">PLC_DNS_ENABLED</span></dt>
 959 <dd>
 960 <p>
 961                   Type: boolean</p>
 962 <p>
 963                   Default: true</p>
 964 <p>Enable the internal DNS server. The server does
 965           not provide reverse resolution and is not a production
 966           quality or scalable DNS solution. Use the internal DNS
 967           server only for small deployments or for
 968           testing.</p>
 969 </dd>
 970 <dt><span class="term">PLC_MAIL_ENABLED</span></dt>
 971 <dd>
 972 <p>
 973                   Type: boolean</p>
 974 <p>
 975                   Default: false</p>
 976 <p>Set to false to suppress all e-mail notifications
 977           and warnings.</p>
 978 </dd>
 979 <dt><span class="term">PLC_MAIL_SUPPORT_ADDRESS</span></dt>
 980 <dd>
 981 <p>
 982                   Type: email</p>
 983 <p>
 984                   Default: root+support@localhost.localdomain</p>
 985 <p>This address is used for support
 986           requests. Support requests may include traffic complaints,
 987           security incident reporting, web site malfunctions, and
 988           general requests for information. We recommend that the
 989           address be aliased to a ticketing system such as Request
 990           Tracker.</p>
 991 </dd>
 992 <dt><span class="term">PLC_MAIL_BOOT_ADDRESS</span></dt>
 993 <dd>
 994 <p>
 995                   Type: email</p>
 996 <p>
 997                   Default: root+install-msgs@localhost.localdomain</p>
 998 <p>The API will notify this address when a problem
 999           occurs during node installation or boot.</p>
1000 </dd>
1001 <dt><span class="term">PLC_MAIL_SLICE_ADDRESS</span></dt>
1002 <dd>
1003 <p>
1004                   Type: email</p>
1005 <p>
1006                   Default: root+SLICE@localhost.localdomain</p>
1007 <p>This address template is used for sending
1008           e-mail notifications to slices. SLICE will be replaced with
1009           the name of the slice.</p>
1010 </dd>
1011 <dt><span class="term">PLC_DB_ENABLED</span></dt>
1012 <dd>
1013 <p>
1014                   Type: boolean</p>
1015 <p>
1016                   Default: true</p>
1017 <p>Enable the database server on this
1018           machine.</p>
1019 </dd>
1020 <dt><span class="term">PLC_DB_TYPE</span></dt>
1021 <dd>
1022 <p>
1023                   Type: string</p>
1024 <p>
1025                   Default: postgresql</p>
1026 <p>The type of database server. Currently, only
1027           postgresql is supported.</p>
1028 </dd>
1029 <dt><span class="term">PLC_DB_HOST</span></dt>
1030 <dd>
1031 <p>
1032                   Type: hostname</p>
1033 <p>
1034                   Default: localhost.localdomain</p>
1035 <p>The fully qualified hostname of the database
1036           server.</p>
1037 </dd>
1038 <dt><span class="term">PLC_DB_IP</span></dt>
1039 <dd>
1040 <p>
1041                   Type: ip</p>
1042 <p>
1043                   Default: 127.0.0.1</p>
1044 <p>The IP address of the database server, if not
1045           resolvable by the configured DNS servers.</p>
1046 </dd>
1047 <dt><span class="term">PLC_DB_PORT</span></dt>
1048 <dd>
1049 <p>
1050                   Type: int</p>
1051 <p>
1052                   Default: 5432</p>
1053 <p>The TCP port number through which the database
1054           server should be accessed.</p>
1055 </dd>
1056 <dt><span class="term">PLC_DB_NAME</span></dt>
1057 <dd>
1058 <p>
1059                   Type: string</p>
1060 <p>
1061                   Default: planetlab3</p>
1062 <p>The name of the database to access.</p>
1063 </dd>
1064 <dt><span class="term">PLC_DB_USER</span></dt>
1065 <dd>
1066 <p>
1067                   Type: string</p>
1068 <p>
1069                   Default: pgsqluser</p>
1070 <p>The username to use when accessing the
1071           database.</p>
1072 </dd>
1073 <dt><span class="term">PLC_DB_PASSWORD</span></dt>
1074 <dd>
1075 <p>
1076                   Type: password</p>
1077 <p>
1078                   Default: </p>
1079 <p>The password to use when accessing the
1080           database. If left blank, one will be
1081           generated.</p>
1082 </dd>
1083 <dt><span class="term">PLC_API_ENABLED</span></dt>
1084 <dd>
1085 <p>
1086                   Type: boolean</p>
1087 <p>
1088                   Default: true</p>
1089 <p>Enable the API server on this
1090           machine.</p>
1091 </dd>
1092 <dt><span class="term">PLC_API_DEBUG</span></dt>
1093 <dd>
1094 <p>
1095                   Type: boolean</p>
1096 <p>
1097                   Default: false</p>
1098 <p>Enable verbose API debugging. Do not enable on
1099           a production system!</p>
1100 </dd>
1101 <dt><span class="term">PLC_API_HOST</span></dt>
1102 <dd>
1103 <p>
1104                   Type: hostname</p>
1105 <p>
1106                   Default: localhost.localdomain</p>
1107 <p>The fully qualified hostname of the API
1108           server.</p>
1109 </dd>
1110 <dt><span class="term">PLC_API_IP</span></dt>
1111 <dd>
1112 <p>
1113                   Type: ip</p>
1114 <p>
1115                   Default: 127.0.0.1</p>
1116 <p>The IP address of the API server, if not
1117           resolvable by the configured DNS servers.</p>
1118 </dd>
1119 <dt><span class="term">PLC_API_PORT</span></dt>
1120 <dd>
1121 <p>
1122                   Type: int</p>
1123 <p>
1124                   Default: 80</p>
1125 <p>The TCP port number through which the API
1126           should be accessed. Warning: SSL (port 443) access is not
1127           fully supported by the website code yet. We recommend that
1128           port 80 be used for now and that the API server either run
1129           on the same machine as the web server, or that they both be
1130           on a secure wired network.</p>
1131 </dd>
1132 <dt><span class="term">PLC_API_PATH</span></dt>
1133 <dd>
1134 <p>
1135                   Type: string</p>
1136 <p>
1137                   Default: /PLCAPI/</p>
1138 <p>The base path of the API URL.</p>
1139 </dd>
1140 <dt><span class="term">PLC_API_MAINTENANCE_USER</span></dt>
1141 <dd>
1142 <p>
1143                   Type: string</p>
1144 <p>
1145                   Default: maint@localhost.localdomain</p>
1146 <p>The username of the maintenance account. This
1147           account is used by local scripts that perform automated
1148           tasks, and cannot be used for normal logins.</p>
1149 </dd>
1150 <dt><span class="term">PLC_API_MAINTENANCE_PASSWORD</span></dt>
1151 <dd>
1152 <p>
1153                   Type: password</p>
1154 <p>
1155                   Default: </p>
1156 <p>The password of the maintenance account. If
1157           left blank, one will be generated. We recommend that the
1158           password be changed periodically.</p>
1159 </dd>
1160 <dt><span class="term">PLC_API_MAINTENANCE_SOURCES</span></dt>
1161 <dd>
1162 <p>
1163                   Type: hostname</p>
1164 <p>
1165                   Default: </p>
1166 <p>A space-separated list of IP addresses allowed
1167           to access the API through the maintenance account. The value
1168           of this variable is set automatically to allow only the API,
1169           web, and boot servers, and should not be
1170           changed.</p>
1171 </dd>
1172 <dt><span class="term">PLC_API_SSL_KEY</span></dt>
1173 <dd>
1174 <p>
1175                   Type: file</p>
1176 <p>
1177                   Default: /etc/planetlab/api_ssl.key</p>
1178 <p>The SSL private key to use for encrypting HTTPS
1179           traffic. If non-existent, one will be
1180           generated.</p>
1181 </dd>
1182 <dt><span class="term">PLC_API_SSL_CRT</span></dt>
1183 <dd>
1184 <p>
1185                   Type: file</p>
1186 <p>
1187                   Default: /etc/planetlab/api_ssl.crt</p>
1188 <p>The corresponding SSL public certificate. By
1189           default, this certificate is self-signed. You may replace
1190           the certificate later with one signed by a root
1191           CA.</p>
1192 </dd>
1193 <dt><span class="term">PLC_API_CA_SSL_CRT</span></dt>
1194 <dd>
1195 <p>
1196                   Type: file</p>
1197 <p>
1198                   Default: /etc/planetlab/api_ca_ssl.crt</p>
1199 <p>The certificate of the root CA, if any, that
1200           signed your server certificate. If your server certificate is
1201           self-signed, then this file is the same as your server
1202           certificate.</p>
1203 </dd>
1204 <dt><span class="term">PLC_WWW_ENABLED</span></dt>
1205 <dd>
1206 <p>
1207                   Type: boolean</p>
1208 <p>
1209                   Default: true</p>
1210 <p>Enable the web server on this
1211           machine.</p>
1212 </dd>
1213 <dt><span class="term">PLC_WWW_DEBUG</span></dt>
1214 <dd>
1215 <p>
1216                   Type: boolean</p>
1217 <p>
1218                   Default: false</p>
1219 <p>Enable debugging output on web pages. Do not
1220           enable on a production system!</p>
1221 </dd>
1222 <dt><span class="term">PLC_WWW_HOST</span></dt>
1223 <dd>
1224 <p>
1225                   Type: hostname</p>
1226 <p>
1227                   Default: localhost.localdomain</p>
1228 <p>The fully qualified hostname of the web
1229           server.</p>
1230 </dd>
1231 <dt><span class="term">PLC_WWW_IP</span></dt>
1232 <dd>
1233 <p>
1234                   Type: ip</p>
1235 <p>
1236                   Default: 127.0.0.1</p>
1237 <p>The IP address of the web server, if not
1238           resolvable by the configured DNS servers.</p>
1239 </dd>
1240 <dt><span class="term">PLC_WWW_PORT</span></dt>
1241 <dd>
1242 <p>
1243                   Type: int</p>
1244 <p>
1245                   Default: 80</p>
1246 <p>The TCP port number through which the
1247           unprotected portions of the web site should be
1248           accessed.</p>
1249 </dd>
1250 <dt><span class="term">PLC_WWW_SSL_PORT</span></dt>
1251 <dd>
1252 <p>
1253                   Type: int</p>
1254 <p>
1255                   Default: 443</p>
1256 <p>The TCP port number through which the protected
1257           portions of the web site should be accessed.</p>
1258 </dd>
1259 <dt><span class="term">PLC_WWW_SSL_KEY</span></dt>
1260 <dd>
1261 <p>
1262                   Type: file</p>
1263 <p>
1264                   Default: /etc/planetlab/www_ssl.key</p>
1265 <p>The SSL private key to use for encrypting HTTPS
1266           traffic. If non-existent, one will be
1267           generated.</p>
1268 </dd>
1269 <dt><span class="term">PLC_WWW_SSL_CRT</span></dt>
1270 <dd>
1271 <p>
1272                   Type: file</p>
1273 <p>
1274                   Default: /etc/planetlab/www_ssl.crt</p>
1275 <p>The corresponding SSL public certificate for
1276           the HTTP server. By default, this certificate is
1277           self-signed. You may replace the certificate later with one
1278           signed by a root CA.</p>
1279 </dd>
1280 <dt><span class="term">PLC_WWW_CA_SSL_CRT</span></dt>
1281 <dd>
1282 <p>
1283                   Type: file</p>
1284 <p>
1285                   Default: /etc/planetlab/www_ca_ssl.crt</p>
1286 <p>The certificate of the root CA, if any, that
1287           signed your server certificate. If your server certificate is
1288           self-signed, then this file is the same as your server
1289           certificate.</p>
1290 </dd>
1291 <dt><span class="term">PLC_BOOT_ENABLED</span></dt>
1292 <dd>
1293 <p>
1294                   Type: boolean</p>
1295 <p>
1296                   Default: true</p>
1297 <p>Enable the boot server on this
1298           machine.</p>
1299 </dd>
1300 <dt><span class="term">PLC_BOOT_HOST</span></dt>
1301 <dd>
1302 <p>
1303                   Type: hostname</p>
1304 <p>
1305                   Default: localhost.localdomain</p>
1306 <p>The fully qualified hostname of the boot
1307           server.</p>
1308 </dd>
1309 <dt><span class="term">PLC_BOOT_IP</span></dt>
1310 <dd>
1311 <p>
1312                   Type: ip</p>
1313 <p>
1314                   Default: 127.0.0.1</p>
1315 <p>The IP address of the boot server, if not
1316           resolvable by the configured DNS servers.</p>
1317 </dd>
1318 <dt><span class="term">PLC_BOOT_PORT</span></dt>
1319 <dd>
1320 <p>
1321                   Type: int</p>
1322 <p>
1323                   Default: 80</p>
1324 <p>The TCP port number through which the
1325           unprotected portions of the boot server should be
1326           accessed.</p>
1327 </dd>
1328 <dt><span class="term">PLC_BOOT_SSL_PORT</span></dt>
1329 <dd>
1330 <p>
1331                   Type: int</p>
1332 <p>
1333                   Default: 443</p>
1334 <p>The TCP port number through which the protected
1335           portions of the boot server should be
1336           accessed.</p>
1337 </dd>
1338 <dt><span class="term">PLC_BOOT_SSL_KEY</span></dt>
1339 <dd>
1340 <p>
1341                   Type: file</p>
1342 <p>
1343                   Default: /etc/planetlab/boot_ssl.key</p>
1344 <p>The SSL private key to use for encrypting HTTPS
1345           traffic.</p>
1346 </dd>
1347 <dt><span class="term">PLC_BOOT_SSL_CRT</span></dt>
1348 <dd>
1349 <p>
1350                   Type: file</p>
1351 <p>
1352                   Default: /etc/planetlab/boot_ssl.crt</p>
1353 <p>The corresponding SSL public certificate for
1354           the HTTP server. By default, this certificate is
1355           self-signed. You may replace the certificate later with one
1356           signed by a root CA.</p>
1357 </dd>
1358 <dt><span class="term">PLC_BOOT_CA_SSL_CRT</span></dt>
1359 <dd>
1360 <p>
1361                   Type: file</p>
1362 <p>
1363                   Default: /etc/planetlab/boot_ca_ssl.crt</p>
1364 <p>The certificate of the root CA, if any, that
1365           signed your server certificate. If your server certificate is
1366           self-signed, then this file is the same as your server
1367           certificate.</p>
1368 </dd>
1369 </dl></div>
1370 </div>
1371 <div class="appendix" lang="en">
1372 <h2 class="title" style="clear: both">
1373 <a name="VariablesDevel"></a>B. Development configuration variables (for <span class="emphasis"><em>myplc-devel</em></span>)</h2>
1374 <div class="variablelist"><dl>
1375 <dt><span class="term">PLC_DEVEL_FEDORA_RELEASE</span></dt>
1376 <dd>
1377 <p>
1378                   Type: string</p>
1379 <p>
1380                   Default: 4</p>
1381 <p>Version number of Fedora Core upon which to
1382           base the build environment. Warning: Currently, only Fedora
1383           Core 4 is supported.</p>
1384 </dd>
1385 <dt><span class="term">PLC_DEVEL_FEDORA_ARCH</span></dt>
1386 <dd>
1387 <p>
1388                   Type: string</p>
1389 <p>
1390                   Default: i386</p>
1391 <p>Base architecture of the build
1392           environment. Warning: Currently, only i386 is
1393           supported.</p>
1394 </dd>
1395 <dt><span class="term">PLC_DEVEL_FEDORA_URL</span></dt>
1396 <dd>
1397 <p>
1398                   Type: string</p>
1399 <p>
1400                   Default: file:///usr/share/mirrors/fedora</p>
1401 <p>Fedora Core mirror from which to install
1402           filesystems.</p>
1403 </dd>
1404 <dt><span class="term">PLC_DEVEL_CVSROOT</span></dt>
1405 <dd>
1406 <p>
1407                   Type: string</p>
1408 <p>
1409                   Default: /cvs</p>
1410 <p>CVSROOT to use when checking out code.</p>
1411 </dd>
1412 <dt><span class="term">PLC_DEVEL_BOOTSTRAP</span></dt>
1413 <dd>
1414 <p>
1415                   Type: boolean</p>
1416 <p>
1417                   Default: false</p>
1418 <p>Controls whether MyPLC should be built inside
1419           of its own development environment.</p>
1420 </dd>
1421 </dl></div>
1422 </div>
1423 <div class="bibliography">
1424 <div class="titlepage"><div><div><h2 class="title">
1425 <a name="id2898373"></a>Bibliography</h2></div></div></div>
1426 <div class="biblioentry">
1427 <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
1428       Technical Contact's Guide</a></i>. </span></p>
1429 </div>
1430 </div>
1431 </div><?php require('footer.php'); ?>
1432 dummy 1.11 for cathing up with the xml numbering
1433 <?php
1434
1435   // DO NOT EDIT. This file was automatically generated from
1436   // DocBook XML. See plc_www/doc/README.
1437
1438   $_title= "MyPLC User's Guide";
1439
1440   require_once('session.php');
1441   require_once('header.php');
1442   require_once('nav.php');
1443
1444   ?><div class="article" lang="en">
1445 <div class="titlepage">
1446 <div>
1447 <div><h1 class="title">
1448 <a name="id2795259"></a>MyPLC User's Guide</h1></div>
1449 <div><div class="author"><h3 class="author"><span class="firstname">Mark Huang</span></h3></div></div>
1450 <div><div class="revhistory"><table border="1" width="100%" summary="Revision history">
1451 <tr><th align="left" valign="top" colspan="3"><b>Revision History</b></th></tr>
1452 <tr>
1453 <td align="left">Revision 1.0</td>
1454 <td align="left">April 7, 2006</td>
1455 <td align="left">MLH</td>
1456 </tr>
1457 <tr><td align="left" colspan="3"><p>Initial draft.</p></td></tr>
1458 <tr>
1459 <td align="left">Revision 1.1</td>
1460 <td align="left">July 19, 2006</td>
1461 <td align="left">MLH</td>
1462 </tr>
1463 <tr><td align="left" colspan="3"><p>Add development environment.</p></td></tr>
1464 </table></div></div>
1465 <div><div class="abstract">
1466 <p class="title"><b>Abstract</b></p>
1467 <p>This document describes the design, installation, and
1468       administration of MyPLC, a complete PlanetLab Central (PLC)
1469       portable installation contained within a
1470       <span><strong class="command">chroot</strong></span> jail. This document assumes advanced
1471       knowledge of the PlanetLab architecture and Linux system
1472       administration.</p>
1473 </div></div>
1474 </div>
1475 <hr>
1476 </div>
1477 <div class="toc">
1478 <p><b>Table of Contents</b></p>
1479 <dl>
1480 <dt><span class="section"><a href="#id2864719">1. Overview</a></span></dt>
1481 <dd><dl><dt><span class="section"><a href="#id2842268">1.1.  Purpose of the <span class="emphasis"><em> myplc-devel
1482     </em></span> package </a></span></dt></dl></dd>
1483 <dt><span class="section"><a href="#Requirements">2.  Requirements </a></span></dt>
1484 <dt><span class="section"><a href="#Installation">3. Installating and using MyPLC</a></span></dt>
1485 <dd><dl>
1486 <dt><span class="section"><a href="#id2841677">3.1. Installing MyPLC.</a></span></dt>
1487 <dt><span class="section"><a href="#QuickStart">3.2.  QuickStart </a></span></dt>
1488 <dt><span class="section"><a href="#ChangingTheConfiguration">3.3. Changing the configuration</a></span></dt>
1489 <dt><span class="section"><a href="#id2842715">3.4. Installing nodes</a></span></dt>
1490 <dt><span class="section"><a href="#id2842797">3.5. Administering nodes</a></span></dt>
1491 <dt><span class="section"><a href="#id2842898">3.6. Creating a slice</a></span></dt>
1492 <dt><span class="section"><a href="#StartupSequence">3.7. Understanding the startup sequence</a></span></dt>
1493 <dt><span class="section"><a href="#FilesInvolvedRuntime">3.8.  Files and directories
1494     involved in <span class="emphasis"><em>myplc</em></span></a></span></dt>
1495 </dl></dd>
1496 <dt><span class="section"><a href="#DevelopmentEnvironment">4. Rebuilding and customizing MyPLC</a></span></dt>
1497 <dd><dl>
1498 <dt><span class="section"><a href="#id2894620">4.1. Installation</a></span></dt>
1499 <dt><span class="section"><a href="#FilesInvolvedDevel">4.2.  Files and directories
1500     involved in <span class="emphasis"><em>myplc-devl</em></span></a></span></dt>
1501 <dt><span class="section"><a href="#id2894876">4.3. Fedora Core 4 mirror requirement</a></span></dt>
1502 <dt><span class="section"><a href="#BuildingMyPLC">4.4. Building MyPLC</a></span></dt>
1503 <dt><span class="section"><a href="#UpdatingCVS">4.5. Updating CVS</a></span></dt>
1504 </dl></dd>
1505 <dt><span class="appendix"><a href="#VariablesRuntime">A. Configuration variables (for <span class="emphasis"><em>myplc</em></span>)</a></span></dt>
1506 <dt><span class="appendix"><a href="#VariablesDevel">B. Development configuration variables (for <span class="emphasis"><em>myplc-devel</em></span>)</a></span></dt>
1507 <dt><span class="bibliography"><a href="#id2898373">Bibliography</a></span></dt>
1508 </dl>
1509 </div>
1510 <div class="section" lang="en">
1511 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1512 <a name="id2864719"></a>1. Overview</h2></div></div></div>
1513 <p>MyPLC is a complete PlanetLab Central (PLC) portable
1514     installation contained within a <span><strong class="command">chroot</strong></span>
1515     jail. The default installation consists of a web server, an
1516     XML-RPC API server, a boot server, and a database server: the core
1517     components of PLC. The installation is customized through an
1518     easy-to-use graphical interface. All PLC services are started up
1519     and shut down through a single script installed on the host
1520     system. The usually complex process of installing and
1521     administering the PlanetLab backend is reduced by containing PLC
1522     services within a virtual filesystem. By packaging it in such a
1523     manner, MyPLC may also be run on any modern Linux distribution,
1524     and could conceivably even run in a PlanetLab slice.</p>
1525 <div class="figure">
1526 <a name="Architecture"></a><p class="title"><b>Figure 1. MyPLC architecture</b></p>
1527 <div class="mediaobject" align="center">
1528 <img src="architecture.png" align="middle" width="270" alt="MyPLC architecture"><div class="caption"><p>MyPLC should be viewed as a single application that
1529           provides multiple functions and can run on any host
1530           system.</p></div>
1531 </div>
1532 </div>
1533 <div class="section" lang="en">
1534 <div class="titlepage"><div><div><h3 class="title">
1535 <a name="id2842268"></a>1.1.  Purpose of the <span class="emphasis"><em> myplc-devel
1536     </em></span> package </h3></div></div></div>
1537 <p> The <span class="emphasis"><em>myplc</em></span> package comes with all
1538     required node software, rebuilt from the public PlanetLab CVS
1539     repository. If for any reason you need to implement your own
1540     customized version of this software, you can use the
1541     <span class="emphasis"><em>myplc-devel</em></span> package instead, for setting up
1542     your own development environment, including a local CVS
1543     repository; you can then freely manage your changes and rebuild
1544     your customized version of <span class="emphasis"><em>myplc</em></span>. We also
1545     provide good practices, that will then allow you to resync your local
1546     CVS repository with any further evolution on the mainstream public
1547     PlanetLab software. </p>
1548 </div>
1549 </div>
1550 <div class="section" lang="en">
1551 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1552 <a name="Requirements"></a>2.  Requirements </h2></div></div></div>
1553 <p> <span class="emphasis"><em>myplc</em></span> and
1554   <span class="emphasis"><em>myplc-devel</em></span> were designed as
1555   <span><strong class="command">chroot</strong></span> jails so as to reduce the requirements on
1556   your host operating system. So in theory, these distributions should
1557   work on virtually any Linux 2.6 based distribution, whether it
1558   supports rpm or not. </p>
1559 <p> However, things are never that simple and there indeed are
1560   some known limitations to this, so here are a couple notes as a
1561   recommended reading before you proceed with the installation.</p>
1562 <p> As of 9 August 2006 (i.e <span class="emphasis"><em>myplc-0.5</em></span>) :</p>
1563 <div class="itemizedlist"><ul type="disc">
1564 <li><p> The software is vastly based on <span class="emphasis"><em>Fedora
1565   Core 4</em></span>. Please note that the build server at Princeton
1566   runs <span class="emphasis"><em>Fedora Core 2</em></span>, togother with a upgraded
1567   version of yum.
1568   </p></li>
1569 <li>
1570 <p> myplc and myplc-devel are known to work on both
1571   <span class="emphasis"><em>Fedora Core 2</em></span> and <span class="emphasis"><em>Fedora Core
1572   4</em></span>. Please note however that, on fc4 at least, it is
1573   highly recommended to use the <span class="application">Security Level
1574   Configuration</span> utility and to <span class="emphasis"><em>switch off
1575   SElinux</em></span> on your box because : </p>
1576 <div class="itemizedlist"><ul type="circle">
1577 <li><p>
1578   myplc requires you to run SElinux as 'Permissive' at most
1579         </p></li>
1580 <li><p>
1581   myplc-devel requires you to turn SElinux Off.
1582         </p></li>
1583 </ul></div>
1584 </li>
1585 <li><p> In addition, as far as myplc is concerned, you
1586   need to check your firewall configuration since you need, of course,
1587   to open up the <span class="emphasis"><em>http</em></span> and
1588   <span class="emphasis"><em>https</em></span> ports, so as to accept connections from
1589   the managed nodes and from the users desktops. </p></li>
1590 </ul></div>
1591 </div>
1592 <div class="section" lang="en">
1593 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1594 <a name="Installation"></a>3. Installating and using MyPLC</h2></div></div></div>
1595 <p>Though internally composed of commodity software
1596     subpackages, MyPLC should be treated as a monolithic software
1597     application. MyPLC is distributed as single RPM package that has
1598     no external dependencies, allowing it to be installed on
1599     practically any Linux 2.6 based distribution.</p>
1600 <div class="section" lang="en">
1601 <div class="titlepage"><div><div><h3 class="title">
1602 <a name="id2841677"></a>3.1. Installing MyPLC.</h3></div></div></div>
1603 <div class="itemizedlist"><ul type="disc">
1604 <li>
1605 <p>If your distribution supports RPM:</p>
1606 <pre class="programlisting"># rpm -U http://build.planet-lab.org/build/myplc-0_4-rc1/RPMS/i386/myplc-0.4-1.planetlab.i386.rpm</pre>
1607 </li>
1608 <li>
1609 <p>If your distribution does not support RPM:</p>
1610 <pre class="programlisting"># cd /tmp
1611 # wget http://build.planet-lab.org/build/myplc-0_4-rc1/RPMS/i386/myplc-0.4-1.planetlab.i386.rpm
1612 # cd /
1613 # rpm2cpio /tmp/myplc-0.4-1.planetlab.i386.rpm | cpio -diu</pre>
1614 </li>
1615 </ul></div>
1616 <p> The <a href="#FilesInvolvedRuntime" title="3.8.  Files and directories
1617     involved in myplc">Section 3.8, “ Files and directories
1618     involved in <span class="emphasis"><em>myplc</em></span>”</a> below explains in
1619     details the installation strategy and the miscellaneous files and
1620     directories involved.</p>
1621 </div>
1622 <div class="section" lang="en">
1623 <div class="titlepage"><div><div><h3 class="title">
1624 <a name="QuickStart"></a>3.2.  QuickStart </h3></div></div></div>
1625 <p> On a Red Hat or Fedora host system, it is customary to use
1626     the <span><strong class="command">service</strong></span> command to invoke System V init
1627     scripts. As the examples suggest, the service must be started as root:</p>
1628 <div class="example">
1629 <a name="id2841851"></a><p class="title"><b>Example 1. Starting MyPLC:</b></p>
1630 <pre class="programlisting"># service plc start</pre>
1631 </div>
1632 <div class="example">
1633 <a name="id2841863"></a><p class="title"><b>Example 2. Stopping MyPLC:</b></p>
1634 <pre class="programlisting"># service plc stop</pre>
1635 </div>
1636 <p> In <a href="#StartupSequence" title="3.7. Understanding the startup sequence">Section 3.7, “Understanding the startup sequence”</a>, we provide greater
1637     details that might be helpful in the case where the service does
1638     not seem to take off correctly.</p>
1639 <p>Like all other registered System V init services, MyPLC is
1640     started and shut down automatically when your host system boots
1641     and powers off. You may disable automatic startup by invoking the
1642     <span><strong class="command">chkconfig</strong></span> command on a Red Hat or Fedora host
1643     system:</p>
1644 <div class="example">
1645 <a name="id2841901"></a><p class="title"><b>Example 3. Disabling automatic startup of MyPLC.</b></p>
1646 <pre class="programlisting"># chkconfig plc off</pre>
1647 </div>
1648 <div class="example">
1649 <a name="id2842528"></a><p class="title"><b>Example 4. Re-enabling automatic startup of MyPLC.</b></p>
1650 <pre class="programlisting"># chkconfig plc on</pre>
1651 </div>
1652 </div>
1653 <div class="section" lang="en">
1654 <div class="titlepage"><div><div><h3 class="title">
1655 <a name="ChangingTheConfiguration"></a>3.3. Changing the configuration</h3></div></div></div>
1656 <p>After verifying that MyPLC is working correctly, shut it
1657       down and begin changing some of the default variable
1658       values. Shut down MyPLC with <span><strong class="command">service plc stop</strong></span>
1659       (see <a href="#QuickStart" title="3.2.  QuickStart ">Section 3.2, “ QuickStart ”</a>). With a text
1660       editor, open the file
1661       <code class="filename">/etc/planetlab/plc_config.xml</code>. This file is
1662       a self-documenting configuration file written in XML. Variables
1663       are divided into categories. Variable identifiers must be
1664       alphanumeric, plus underscore. A variable is referred to
1665       canonically as the uppercase concatenation of its category
1666       identifier, an underscore, and its variable identifier. Thus, a
1667       variable with an <code class="literal">id</code> of
1668       <code class="literal">slice_prefix</code> in the <code class="literal">plc</code>
1669       category is referred to canonically as
1670       <code class="envar">PLC_SLICE_PREFIX</code>.</p>
1671 <p>The reason for this convention is that during MyPLC
1672       startup, <code class="filename">plc_config.xml</code> is translated into
1673       several different languages—shell, PHP, and
1674       Python—so that scripts written in each of these languages
1675       can refer to the same underlying configuration. Most MyPLC
1676       scripts are written in shell, so the convention for shell
1677       variables predominates.</p>
1678 <p>The variables that you should change immediately are:</p>
1679 <div class="itemizedlist"><ul type="disc">
1680 <li><p><code class="envar">PLC_NAME</code>: Change this to the
1681         name of your PLC installation.</p></li>
1682 <li><p><code class="envar">PLC_ROOT_PASSWORD</code>: Change this
1683         to a more secure password.</p></li>
1684 <li><p><code class="envar">PLC_MAIL_SUPPORT_ADDRESS</code>:
1685         Change this to the e-mail address at which you would like to
1686         receive support requests.</p></li>
1687 <li><p><code class="envar">PLC_DB_HOST</code>,
1688         <code class="envar">PLC_DB_IP</code>, <code class="envar">PLC_API_HOST</code>,
1689         <code class="envar">PLC_API_IP</code>, <code class="envar">PLC_WWW_HOST</code>,
1690         <code class="envar">PLC_WWW_IP</code>, <code class="envar">PLC_BOOT_HOST</code>,
1691         <code class="envar">PLC_BOOT_IP</code>: Change all of these to the
1692         preferred FQDN and external IP address of your host
1693         system.</p></li>
1694 </ul></div>
1695 <p>The full set of applicable variables is described in <a href="#VariablesDevel" title="B. Development configuration variables (for myplc-devel)">Appendix B, <i>Development configuration variables (for <span class="emphasis"><em>myplc-devel</em></span>)</i></a>. After changing these variables,
1696       save the file, then restart MyPLC with <span><strong class="command">service plc
1697       start</strong></span>. You should notice that the password of the
1698       default administrator account is no longer
1699       <code class="literal">root</code>, and that the default site name includes
1700       the name of your PLC installation instead of PlanetLab.</p>
1701 </div>
1702 <div class="section" lang="en">
1703 <div class="titlepage"><div><div><h3 class="title">
1704 <a name="id2842715"></a>3.4. Installing nodes</h3></div></div></div>
1705 <p>Install your first node by clicking <code class="literal">Add
1706       Node</code> under the <code class="literal">Nodes</code> tab. Fill in
1707       all the appropriate details, then click
1708       <code class="literal">Add</code>. Download the node's configuration file
1709       by clicking <code class="literal">Download configuration file</code> on
1710       the <span class="bold"><strong>Node Details</strong></span> page for the
1711       node. Save it to a floppy disk or USB key as detailed in [<a href="#TechsGuide" title="[TechsGuide]">1</a>].</p>
1712 <p>Follow the rest of the instructions in [<a href="#TechsGuide" title="[TechsGuide]">1</a>] for creating a Boot CD and installing
1713       the node, except download the Boot CD image from the
1714       <code class="filename">/download</code> directory of your PLC
1715       installation, not from PlanetLab Central. The images located
1716       here are customized for your installation. If you change the
1717       hostname of your boot server (<code class="envar">PLC_BOOT_HOST</code>), or
1718       if the SSL certificate of your boot server expires, MyPLC will
1719       regenerate it and rebuild the Boot CD with the new
1720       certificate. If this occurs, you must replace all Boot CDs
1721       created before the certificate was regenerated.</p>
1722 <p>The installation process for a node has significantly
1723       improved since PlanetLab 3.3. It should now take only a few
1724       seconds for a new node to become ready to create slices.</p>
1725 </div>
1726 <div class="section" lang="en">
1727 <div class="titlepage"><div><div><h3 class="title">
1728 <a name="id2842797"></a>3.5. Administering nodes</h3></div></div></div>
1729 <p>You may administer nodes as <code class="literal">root</code> by
1730       using the SSH key stored in
1731       <code class="filename">/etc/planetlab/root_ssh_key.rsa</code>.</p>
1732 <div class="example">
1733 <a name="id2842820"></a><p class="title"><b>Example 5. Accessing nodes via SSH. Replace
1734         <code class="literal">node</code> with the hostname of the node.</b></p>
1735 <pre class="programlisting">ssh -i /etc/planetlab/root_ssh_key.rsa root@node</pre>
1736 </div>
1737 <p>Besides the standard Linux log files located in
1738       <code class="filename">/var/log</code>, several other files can give you
1739       clues about any problems with active processes:</p>
1740 <div class="itemizedlist"><ul type="disc">
1741 <li><p><code class="filename">/var/log/pl_nm</code>: The log
1742         file for the Node Manager.</p></li>
1743 <li><p><code class="filename">/vservers/pl_conf/var/log/pl_conf</code>:
1744         The log file for the Slice Creation Service.</p></li>
1745 <li><p><code class="filename">/var/log/propd</code>: The log
1746         file for Proper, the service which allows certain slices to
1747         perform certain privileged operations in the root
1748         context.</p></li>
1749 <li><p><code class="filename">/vservers/pl_netflow/var/log/netflow.log</code>:
1750         The log file for PlanetFlow, the network traffic auditing
1751         service.</p></li>
1752 </ul></div>
1753 </div>
1754 <div class="section" lang="en">
1755 <div class="titlepage"><div><div><h3 class="title">
1756 <a name="id2842898"></a>3.6. Creating a slice</h3></div></div></div>
1757 <p>Create a slice by clicking <code class="literal">Create Slice</code>
1758       under the <code class="literal">Slices</code> tab. Fill in all the
1759       appropriate details, then click <code class="literal">Create</code>. Add
1760       nodes to the slice by clicking <code class="literal">Manage Nodes</code>
1761       on the <span class="bold"><strong>Slice Details</strong></span> page for
1762       the slice.</p>
1763 <p>A <span><strong class="command">cron</strong></span> job runs every five minutes and
1764       updates the file
1765       <code class="filename">/plc/data/var/www/html/xml/slices-0.5.xml</code>
1766       with information about current slice state. The Slice Creation
1767       Service running on every node polls this file every ten minutes
1768       to determine if it needs to create or delete any slices. You may
1769       accelerate this process manually if desired.</p>
1770 <div class="example">
1771 <a name="id2842960"></a><p class="title"><b>Example 6. Forcing slice creation on a node.</b></p>
1772 <pre class="programlisting"># Update slices.xml immediately
1773 service plc start crond
1774
1775 # Kick the Slice Creation Service on a particular node.
1776 ssh -i /etc/planetlab/root_ssh_key.rsa root@node \
1777 vserver pl_conf exec service pl_conf restart</pre>
1778 </div>
1779 </div>
1780 <div class="section" lang="en">
1781 <div class="titlepage"><div><div><h3 class="title">
1782 <a name="StartupSequence"></a>3.7. Understanding the startup sequence</h3></div></div></div>
1783 <p>During service startup described in <a href="#QuickStart" title="3.2.  QuickStart ">Section 3.2, “ QuickStart ”</a>, observe the output of this command for
1784     any failures. If no failures occur, you should see output similar
1785     to the following:</p>
1786 <div class="example">
1787 <a name="id2893858"></a><p class="title"><b>Example 7. A successful MyPLC startup.</b></p>
1788 <pre class="programlisting">Mounting PLC:                                              [  OK  ]
1789 PLC: Generating network files:                             [  OK  ]
1790 PLC: Starting system logger:                               [  OK  ]
1791 PLC: Starting database server:                             [  OK  ]
1792 PLC: Generating SSL certificates:                          [  OK  ]
1793 PLC: Configuring the API:                                  [  OK  ]
1794 PLC: Updating GPG keys:                                    [  OK  ]
1795 PLC: Generating SSH keys:                                  [  OK  ]
1796 PLC: Starting web server:                                  [  OK  ]
1797 PLC: Bootstrapping the database:                           [  OK  ]
1798 PLC: Starting DNS server:                                  [  OK  ]
1799 PLC: Starting crond:                                       [  OK  ]
1800 PLC: Rebuilding Boot CD:                                   [  OK  ]
1801 PLC: Rebuilding Boot Manager:                              [  OK  ]
1802 PLC: Signing node packages:                                [  OK  ]
1803 </pre>
1804 </div>
1805 <p>If <code class="filename">/plc/root</code> is mounted successfully, a
1806     complete log file of the startup process may be found at
1807     <code class="filename">/plc/root/var/log/boot.log</code>. Possible reasons
1808     for failure of each step include:</p>
1809 <div class="itemizedlist"><ul type="disc">
1810 <li><p><code class="literal">Mounting PLC</code>: If this step
1811       fails, first ensure that you started MyPLC as root. Check
1812       <code class="filename">/etc/sysconfig/plc</code> to ensure that
1813       <code class="envar">PLC_ROOT</code> and <code class="envar">PLC_DATA</code> refer to the
1814       right locations. You may also have too many existing loopback
1815       mounts, or your kernel may not support loopback mounting, bind
1816       mounting, or the ext3 filesystem. Try freeing at least one
1817       loopback device, or re-compiling your kernel to support loopback
1818       mounting, bind mounting, and the ext3 filesystem. If you see an
1819       error similar to <code class="literal">Permission denied while trying to open
1820       /plc/root.img</code>, then SELinux may be enabled. See <a href="#Requirements" title="2.  Requirements ">Section 2, “ Requirements ”</a> above for details.</p></li>
1821 <li><p><code class="literal">Starting database server</code>: If
1822       this step fails, check
1823       <code class="filename">/plc/root/var/log/pgsql</code> and
1824       <code class="filename">/plc/root/var/log/boot.log</code>. The most common
1825       reason for failure is that the default PostgreSQL port, TCP port
1826       5432, is already in use. Check that you are not running a
1827       PostgreSQL server on the host system.</p></li>
1828 <li><p><code class="literal">Starting web server</code>: If this
1829       step fails, check
1830       <code class="filename">/plc/root/var/log/httpd/error_log</code> and
1831       <code class="filename">/plc/root/var/log/boot.log</code> for obvious
1832       errors. The most common reason for failure is that the default
1833       web ports, TCP ports 80 and 443, are already in use. Check that
1834       you are not running a web server on the host
1835       system.</p></li>
1836 <li><p><code class="literal">Bootstrapping the database</code>:
1837       If this step fails, it is likely that the previous step
1838       (<code class="literal">Starting web server</code>) also failed. Another
1839       reason that it could fail is if <code class="envar">PLC_API_HOST</code> (see
1840       <a href="#ChangingTheConfiguration" title="3.3. Changing the configuration">Section 3.3, “Changing the configuration”</a>) does not resolve to
1841       the host on which the API server has been enabled. By default,
1842       all services, including the API server, are enabled and run on
1843       the same host, so check that <code class="envar">PLC_API_HOST</code> is
1844       either <code class="filename">localhost</code> or resolves to a local IP
1845       address.</p></li>
1846 <li><p><code class="literal">Starting crond</code>: If this step
1847       fails, it is likely that the previous steps (<code class="literal">Starting
1848       web server</code> and <code class="literal">Bootstrapping the
1849       database</code>) also failed. If not, check
1850       <code class="filename">/plc/root/var/log/boot.log</code> for obvious
1851       errors. This step starts the <span><strong class="command">cron</strong></span> service and
1852       generates the initial set of XML files that the Slice Creation
1853       Service uses to determine slice state.</p></li>
1854 </ul></div>
1855 <p>If no failures occur, then MyPLC should be active with a
1856     default configuration. Open a web browser on the host system and
1857     visit <code class="literal">http://localhost/</code>, which should bring you
1858     to the front page of your PLC installation. The password of the
1859     default administrator account
1860     <code class="literal">root@localhost.localdomain</code> (set by
1861     <code class="envar">PLC_ROOT_USER</code>) is <code class="literal">root</code> (set by
1862     <code class="envar">PLC_ROOT_PASSWORD</code>).</p>
1863 </div>
1864 <div class="section" lang="en">
1865 <div class="titlepage"><div><div><h3 class="title">
1866 <a name="FilesInvolvedRuntime"></a>3.8.  Files and directories
1867     involved in <span class="emphasis"><em>myplc</em></span></h3></div></div></div>
1868 <p>MyPLC installs the following files and directories:</p>
1869 <div class="orderedlist"><ol type="1">
1870 <li><p><code class="filename">/plc/root.img</code>: The main
1871       root filesystem of the MyPLC application. This file is an
1872       uncompressed ext3 filesystem that is loopback mounted on
1873       <code class="filename">/plc/root</code> when MyPLC starts. This
1874       filesystem, even when mounted, should be treated as an opaque
1875       binary that can and will be replaced in its entirety by any
1876       upgrade of MyPLC.</p></li>
1877 <li><p><code class="filename">/plc/root</code>: The mount point
1878       for <code class="filename">/plc/root.img</code>. Once the root filesystem
1879       is mounted, all MyPLC services run in a
1880       <span><strong class="command">chroot</strong></span> jail based in this
1881       directory.</p></li>
1882 <li>
1883 <p><code class="filename">/plc/data</code>: The directory where user
1884         data and generated files are stored. This directory is bind
1885         mounted onto <code class="filename">/plc/root/data</code> so that it is
1886         accessible as <code class="filename">/data</code> from within the
1887         <span><strong class="command">chroot</strong></span> jail. Files in this directory are
1888         marked with <span><strong class="command">%config(noreplace)</strong></span> in the
1889         RPM. That is, during an upgrade of MyPLC, if a file has not
1890         changed since the last installation or upgrade of MyPLC, it is
1891         subject to upgrade and replacement. If the file has changed,
1892         the new version of the file will be created with a
1893         <code class="filename">.rpmnew</code> extension. Symlinks within the
1894         MyPLC root filesystem ensure that the following directories
1895         (relative to <code class="filename">/plc/root</code>) are stored
1896         outside the MyPLC filesystem image:</p>
1897 <div class="itemizedlist"><ul type="disc">
1898 <li><p><code class="filename">/etc/planetlab</code>: This
1899           directory contains the configuration files, keys, and
1900           certificates that define your MyPLC
1901           installation.</p></li>
1902 <li><p><code class="filename">/var/lib/pgsql</code>: This
1903           directory contains PostgreSQL database
1904           files.</p></li>
1905 <li><p><code class="filename">/var/www/html/alpina-logs</code>: This
1906           directory contains node installation logs.</p></li>
1907 <li><p><code class="filename">/var/www/html/boot</code>: This
1908           directory contains the Boot Manager, customized for your MyPLC
1909           installation, and its data files.</p></li>
1910 <li><p><code class="filename">/var/www/html/download</code>: This
1911           directory contains Boot CD images, customized for your MyPLC
1912           installation.</p></li>
1913 <li><p><code class="filename">/var/www/html/install-rpms</code>: This
1914           directory is where you should install node package updates,
1915           if any. By default, nodes are installed from the tarball
1916           located at
1917           <code class="filename">/var/www/html/boot/PlanetLab-Bootstrap.tar.bz2</code>,
1918           which is pre-built from the latest PlanetLab Central
1919           sources, and installed as part of your MyPLC
1920           installation. However, nodes will attempt to install any
1921           newer RPMs located in
1922           <code class="filename">/var/www/html/install-rpms/planetlab</code>,
1923           after initial installation and periodically thereafter. You
1924           must run <span><strong class="command">yum-arch</strong></span> and
1925           <span><strong class="command">createrepo</strong></span> to update the
1926           <span><strong class="command">yum</strong></span> caches in this directory after
1927           installing a new RPM. PlanetLab Central cannot support any
1928           changes to this directory.</p></li>
1929 <li><p><code class="filename">/var/www/html/xml</code>: This
1930           directory contains various XML files that the Slice Creation
1931           Service uses to determine the state of slices. These XML
1932           files are refreshed periodically by <span><strong class="command">cron</strong></span>
1933           jobs running in the MyPLC root.</p></li>
1934 </ul></div>
1935 </li>
1936 <li><p><a name="MyplcInitScripts"></a><code class="filename">/etc/init.d/plc</code>: This file
1937         is a System V init script installed on your host filesystem,
1938         that allows you to start up and shut down MyPLC with a single
1939         command, as described in <a href="#QuickStart" title="3.2.  QuickStart ">Section 3.2, “ QuickStart ”</a>.</p></li>
1940 <li><p><code class="filename">/etc/sysconfig/plc</code>: This
1941       file is a shell script fragment that defines the variables
1942       <code class="envar">PLC_ROOT</code> and <code class="envar">PLC_DATA</code>. By default,
1943       the values of these variables are <code class="filename">/plc/root</code>
1944       and <code class="filename">/plc/data</code>, respectively. If you wish,
1945       you may move your MyPLC installation to another location on your
1946       host filesystem and edit the values of these variables
1947       appropriately, but you will break the RPM upgrade
1948       process. PlanetLab Central cannot support any changes to this
1949       file.</p></li>
1950 <li><p><code class="filename">/etc/planetlab</code>: This
1951       symlink to <code class="filename">/plc/data/etc/planetlab</code> is
1952       installed on the host system for convenience.</p></li>
1953 </ol></div>
1954 </div>
1955 </div>
1956 <div class="section" lang="en">
1957 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1958 <a name="DevelopmentEnvironment"></a>4. Rebuilding and customizing MyPLC</h2></div></div></div>
1959 <p>The MyPLC package, though distributed as an RPM, is not a
1960     traditional package that can be easily rebuilt from SRPM. The
1961     requisite build environment is quite extensive and numerous
1962     assumptions are made throughout the PlanetLab source code base,
1963     that the build environment is based on Fedora Core 4 and that
1964     access to a complete Fedora Core 4 mirror is available.</p>
1965 <p>For this reason, it is recommended that you only rebuild
1966     MyPLC (or any of its components) from within the MyPLC development
1967     environment. The MyPLC development environment is similar to MyPLC
1968     itself in that it is a portable filesystem contained within a
1969     <span><strong class="command">chroot</strong></span> jail. The filesystem contains all the
1970     necessary tools required to rebuild MyPLC, as well as a snapshot
1971     of the PlanetLab source code base in the form of a local CVS
1972     repository.</p>
1973 <div class="section" lang="en">
1974 <div class="titlepage"><div><div><h3 class="title">
1975 <a name="id2894620"></a>4.1. Installation</h3></div></div></div>
1976 <p>Install the MyPLC development environment similarly to how
1977       you would install MyPLC. You may install both packages on the same
1978       host system if you wish. As with MyPLC, the MyPLC development
1979       environment should be treated as a monolithic software
1980       application, and any files present in the
1981       <span><strong class="command">chroot</strong></span> jail should not be modified directly, as
1982       they are subject to upgrade.</p>
1983 <div class="itemizedlist"><ul type="disc">
1984 <li>
1985 <p>If your distribution supports RPM:</p>
1986 <pre class="programlisting"># rpm -U http://build.planet-lab.org/build/myplc-0_4-rc2/RPMS/i386/myplc-devel-0.4-2.planetlab.i386.rpm</pre>
1987 </li>
1988 <li>
1989 <p>If your distribution does not support RPM:</p>
1990 <pre class="programlisting"># cd /tmp
1991 # wget http://build.planet-lab.org/build/myplc-0_4-rc2/RPMS/i386/myplc-devel-0.4-2.planetlab.i386.rpm
1992 # cd /
1993 # rpm2cpio /tmp/myplc-devel-0.4-2.planetlab.i386.rpm | cpio -diu</pre>
1994 </li>
1995 </ul></div>
1996 </div>
1997 <div class="section" lang="en">
1998 <div class="titlepage"><div><div><h3 class="title">
1999 <a name="FilesInvolvedDevel"></a>4.2.  Files and directories
2000     involved in <span class="emphasis"><em>myplc-devl</em></span></h3></div></div></div>
2001 <p>The MyPLC development environment installs the following
2002       files and directories:</p>
2003 <div class="itemizedlist"><ul type="disc">
2004 <li><p><code class="filename">/plc/devel/root.img</code>: The
2005         main root filesystem of the MyPLC development environment. This
2006         file is an uncompressed ext3 filesystem that is loopback mounted
2007         on <code class="filename">/plc/devel/root</code> when the MyPLC
2008         development environment is initialized. This filesystem, even
2009         when mounted, should be treated as an opaque binary that can and
2010         will be replaced in its entirety by any upgrade of the MyPLC
2011         development environment.</p></li>
2012 <li><p><code class="filename">/plc/devel/root</code>: The mount
2013         point for
2014         <code class="filename">/plc/devel/root.img</code>.</p></li>
2015 <li>
2016 <p><code class="filename">/plc/devel/data</code>: The directory
2017           where user data and generated files are stored. This directory
2018           is bind mounted onto <code class="filename">/plc/devel/root/data</code>
2019           so that it is accessible as <code class="filename">/data</code> from
2020           within the <span><strong class="command">chroot</strong></span> jail. Files in this
2021           directory are marked with
2022           <span><strong class="command">%config(noreplace)</strong></span> in the RPM. Symlinks
2023           ensure that the following directories (relative to
2024           <code class="filename">/plc/devel/root</code>) are stored outside the
2025           root filesystem image:</p>
2026 <div class="itemizedlist"><ul type="circle">
2027 <li><p><code class="filename">/etc/planetlab</code>: This
2028             directory contains the configuration files that define your
2029             MyPLC development environment.</p></li>
2030 <li><p><code class="filename">/cvs</code>: A
2031             snapshot of the PlanetLab source code is stored as a CVS
2032             repository in this directory. Files in this directory will
2033             <span class="bold"><strong>not</strong></span> be updated by an upgrade of
2034             <code class="filename">myplc-devel</code>. See <a href="#UpdatingCVS" title="4.5. Updating CVS">Section 4.5, “Updating CVS”</a> for more information about updating
2035             PlanetLab source code.</p></li>
2036 <li><p><code class="filename">/build</code>:
2037             Builds are stored in this directory. This directory is bind
2038             mounted onto <code class="filename">/plc/devel/root/build</code> so that
2039             it is accessible as <code class="filename">/build</code> from within the
2040             <span><strong class="command">chroot</strong></span> jail. The build scripts in this
2041             directory are themselves source controlled; see <a href="#BuildingMyPLC" title="4.4. Building MyPLC">Section 4.4, “Building MyPLC”</a> for more information about executing
2042             builds.</p></li>
2043 </ul></div>
2044 </li>
2045 <li><p><code class="filename">/etc/init.d/plc-devel</code>: This file is
2046           a System V init script installed on your host filesystem, that
2047           allows you to start up and shut down the MyPLC development
2048           environment with a single command.</p></li>
2049 </ul></div>
2050 </div>
2051 <div class="section" lang="en">
2052 <div class="titlepage"><div><div><h3 class="title">
2053 <a name="id2894876"></a>4.3. Fedora Core 4 mirror requirement</h3></div></div></div>
2054 <p>The MyPLC development environment requires access to a
2055       complete Fedora Core 4 i386 RPM repository, because several
2056       different filesystems based upon Fedora Core 4 are constructed
2057       during the process of building MyPLC. You may configure the
2058       location of this repository via the
2059       <code class="envar">PLC_DEVEL_FEDORA_URL</code> variable in
2060       <code class="filename">/plc/devel/data/etc/planetlab/plc_config.xml</code>. The
2061       value of the variable should be a URL that points to the top
2062       level of a Fedora mirror that provides the
2063       <code class="filename">base</code>, <code class="filename">updates</code>, and
2064       <code class="filename">extras</code> repositories, e.g.,</p>
2065 <div class="itemizedlist"><ul type="disc">
2066 <li><p><code class="filename">file:///data/fedora</code></p></li>
2067 <li><p><code class="filename">http://coblitz.planet-lab.org/pub/fedora</code></p></li>
2068 <li><p><code class="filename">ftp://mirror.cs.princeton.edu/pub/mirrors/fedora</code></p></li>
2069 <li><p><code class="filename">ftp://mirror.stanford.edu/pub/mirrors/fedora</code></p></li>
2070 <li><p><code class="filename">http://rpmfind.net/linux/fedora</code></p></li>
2071 </ul></div>
2072 <p>As implied by the list, the repository may be located on
2073       the local filesystem, or it may be located on a remote FTP or
2074       HTTP server. URLs beginning with <code class="filename">file://</code>
2075       should exist at the specified location relative to the root of
2076       the <span><strong class="command">chroot</strong></span> jail. For optimum performance and
2077       reproducibility, specify
2078       <code class="envar">PLC_DEVEL_FEDORA_URL=file:///data/fedora</code> and
2079       download all Fedora Core 4 RPMS into
2080       <code class="filename">/plc/devel/data/fedora</code> on the host system
2081       after installing <code class="filename">myplc-devel</code>. Use a tool
2082       such as <span><strong class="command">wget</strong></span> or <span><strong class="command">rsync</strong></span> to
2083       download the RPMS from a public mirror:</p>
2084 <div class="example">
2085 <a name="id2895018"></a><p class="title"><b>Example 8. Setting up a local Fedora Core 4 repository.</b></p>
2086 <pre class="programlisting"># mkdir -p /plc/devel/data/fedora
2087 # cd /plc/devel/data/fedora
2088
2089 # for repo in core/4/i386/os core/updates/4/i386 extras/4/i386 ; do
2090 &gt;     wget -m -nH --cut-dirs=3 http://coblitz.planet-lab.org/pub/fedora/linux/$repo
2091 &gt; done</pre>
2092 </div>
2093 <p>Change the repository URI and <span><strong class="command">--cut-dirs</strong></span>
2094       level as needed to produce a hierarchy that resembles:</p>
2095 <pre class="programlisting">/plc/devel/data/fedora/core/4/i386/os
2096 /plc/devel/data/fedora/core/updates/4/i386
2097 /plc/devel/data/fedora/extras/4/i386</pre>
2098 <p>A list of additional Fedora Core 4 mirrors is available at
2099       <a href="http://fedora.redhat.com/Download/mirrors.html" target="_top">http://fedora.redhat.com/Download/mirrors.html</a>.</p>
2100 </div>
2101 <div class="section" lang="en">
2102 <div class="titlepage"><div><div><h3 class="title">
2103 <a name="BuildingMyPLC"></a>4.4. Building MyPLC</h3></div></div></div>
2104 <p>All PlanetLab source code modules are built and installed
2105       as RPMS. A set of build scripts, checked into the
2106       <code class="filename">build/</code> directory of the PlanetLab CVS
2107       repository, eases the task of rebuilding PlanetLab source
2108       code.</p>
2109 <p> Before you try building MyPLC, you might check the
2110       configuration, in a file named
2111       <span class="emphasis"><em>plc_config.xml</em></span> that relies on a very
2112       similar model as MyPLC, located in
2113       <span class="emphasis"><em>/etc/planetlab</em></span> within the chroot jail, or
2114       in <span class="emphasis"><em>/plc/devel/data/etc/planetlab</em></span> from the
2115       root context. The set of applicable variables is described in
2116       <a href="#VariablesDevel" title="B. Development configuration variables (for myplc-devel)">Appendix B, <i>Development configuration variables (for <span class="emphasis"><em>myplc-devel</em></span>)</i></a>. </p>
2117 <p>To build MyPLC, or any PlanetLab source code module, from
2118       within the MyPLC development environment, execute the following
2119       commands as root:</p>
2120 <div class="example">
2121 <a name="id2895119"></a><p class="title"><b>Example 9. Building MyPLC.</b></p>
2122 <pre class="programlisting"># Initialize MyPLC development environment
2123 service plc-devel start
2124
2125 # Enter development environment
2126 chroot /plc/devel/root su -
2127
2128 # Check out build scripts into a directory named after the current
2129 # date. This is simply a convention, it need not be followed
2130 # exactly. See build/build.sh for an example of a build script that
2131 # names build directories after CVS tags.
2132 DATE=$(date +%Y.%m.%d)
2133 cd /build
2134 cvs -d /cvs checkout -d $DATE build
2135
2136 # Build everything
2137 make -C $DATE</pre>
2138 </div>
2139 <p>If the build succeeds, a set of binary RPMS will be
2140       installed under
2141       <code class="filename">/plc/devel/data/build/$DATE/RPMS/</code> that you
2142       may copy to the
2143       <code class="filename">/var/www/html/install-rpms/planetlab</code>
2144       directory of your MyPLC installation (see <a href="#Installation" title="3. Installating and using MyPLC">Section 3, “Installating and using MyPLC”</a>).</p>
2145 </div>
2146 <div class="section" lang="en">
2147 <div class="titlepage"><div><div><h3 class="title">
2148 <a name="UpdatingCVS"></a>4.5. Updating CVS</h3></div></div></div>
2149 <p>A complete snapshot of the PlanetLab source code is included
2150       with the MyPLC development environment as a CVS repository in
2151       <code class="filename">/plc/devel/data/cvs</code>. This CVS repository may
2152       be accessed like any other CVS repository. It may be accessed
2153       using an interface such as <a href="http://www.freebsd.org/projects/cvsweb.html" target="_top">CVSweb</a>,
2154       and file permissions may be altered to allow for fine-grained
2155       access control. Although the files are included with the
2156       <code class="filename">myplc-devel</code> RPM, they are <span class="bold"><strong>not</strong></span> subject to upgrade once installed. New
2157       versions of the <code class="filename">myplc-devel</code> RPM will install
2158       updated snapshot repositories in
2159       <code class="filename">/plc/devel/data/cvs-%{version}-%{release}</code>,
2160       where <code class="literal">%{version}-%{release}</code> is replaced with
2161       the version number of the RPM.</p>
2162 <p>Because the CVS repository is not automatically upgraded,
2163       if you wish to keep your local repository synchronized with the
2164       public PlanetLab repository, it is highly recommended that you
2165       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
2166       branches</a> to track changes. Vendor branches ease the task
2167       of merging upstream changes with your local modifications. To
2168       import a new snapshot into your local repository (for example,
2169       if you have just upgraded from
2170       <code class="filename">myplc-devel-0.4-2</code> to
2171       <code class="filename">myplc-devel-0.4-3</code> and you notice the new
2172       repository in <code class="filename">/plc/devel/data/cvs-0.4-3</code>),
2173       execute the following commands as root from within the MyPLC
2174       development environment:</p>
2175 <div class="example">
2176 <a name="id2895270"></a><p class="title"><b>Example 10. Updating /data/cvs from /data/cvs-0.4-3.</b></p>
2177 <p><span class="bold"><strong>Warning</strong></span>: This may cause
2178         severe, irreversible changes to be made to your local
2179         repository. Always tag your local repository before
2180         importing.</p>
2181 <pre class="programlisting"># Initialize MyPLC development environment
2182 service plc-devel start
2183
2184 # Enter development environment
2185 chroot /plc/devel/root su -
2186
2187 # Tag current state
2188 cvs -d /cvs rtag before-myplc-0_4-3-merge
2189
2190 # Export snapshot
2191 TMP=$(mktemp -d /data/export.XXXXXX)
2192 pushd $TMP
2193 cvs -d /data/cvs-0.4-3 export -r HEAD .
2194 cvs -d /cvs import -m "PlanetLab sources from myplc-0.4-3" -ko -I ! . planetlab myplc-0_4-3
2195 popd
2196 rm -rf $TMP</pre>
2197 </div>
2198 <p>If there any merge conflicts, use the command suggested by
2199       CVS to help the merge. Explaining how to fix merge conflicts is
2200       beyond the scope of this document; consult the CVS documentation
2201       for more information on how to use CVS.</p>
2202 </div>
2203 </div>
2204 <div class="appendix" lang="en">
2205 <h2 class="title" style="clear: both">
2206 <a name="VariablesRuntime"></a>A. Configuration variables (for <span class="emphasis"><em>myplc</em></span>)</h2>
2207 <p>Listed below is the set of standard configuration variables
2208     and their default values, defined in the template
2209     <code class="filename">/etc/planetlab/default_config.xml</code>. Additional
2210     variables and their defaults may be defined in site-specific XML
2211     templates that should be placed in
2212     <code class="filename">/etc/planetlab/configs/</code>.</p>
2213 <div class="variablelist"><dl>
2214 <dt><span class="term">PLC_NAME</span></dt>
2215 <dd>
2216 <p>
2217                   Type: string</p>
2218 <p>
2219                   Default: PlanetLab Test</p>
2220 <p>The name of this PLC installation. It is used in
2221           the name of the default system site (e.g., PlanetLab Central)
2222           and in the names of various administrative entities (e.g.,
2223           PlanetLab Support).</p>
2224 </dd>
2225 <dt><span class="term">PLC_SLICE_PREFIX</span></dt>
2226 <dd>
2227 <p>
2228                   Type: string</p>
2229 <p>
2230                   Default: pl</p>
2231 <p>The abbreviated name of this PLC
2232           installation. It is used as the prefix for system slices
2233           (e.g., pl_conf). Warning: Currently, this variable should
2234           not be changed.</p>
2235 </dd>
2236 <dt><span class="term">PLC_ROOT_USER</span></dt>
2237 <dd>
2238 <p>
2239                   Type: email</p>
2240 <p>
2241                   Default: root@localhost.localdomain</p>
2242 <p>The name of the initial administrative
2243           account. We recommend that this account be used only to create
2244           additional accounts associated with real
2245           administrators, then disabled.</p>
2246 </dd>
2247 <dt><span class="term">PLC_ROOT_PASSWORD</span></dt>
2248 <dd>
2249 <p>
2250                   Type: password</p>
2251 <p>
2252                   Default: root</p>
2253 <p>The password of the initial administrative
2254           account. Also the password of the root account on the Boot
2255           CD.</p>
2256 </dd>
2257 <dt><span class="term">PLC_ROOT_SSH_KEY_PUB</span></dt>
2258 <dd>
2259 <p>
2260                   Type: file</p>
2261 <p>
2262                   Default: /etc/planetlab/root_ssh_key.pub</p>
2263 <p>The SSH public key used to access the root
2264           account on your nodes.</p>
2265 </dd>
2266 <dt><span class="term">PLC_ROOT_SSH_KEY</span></dt>
2267 <dd>
2268 <p>
2269                   Type: file</p>
2270 <p>
2271                   Default: /etc/planetlab/root_ssh_key.rsa</p>
2272 <p>The SSH private key used to access the root
2273           account on your nodes.</p>
2274 </dd>
2275 <dt><span class="term">PLC_DEBUG_SSH_KEY_PUB</span></dt>
2276 <dd>
2277 <p>
2278                   Type: file</p>
2279 <p>
2280                   Default: /etc/planetlab/debug_ssh_key.pub</p>
2281 <p>The SSH public key used to access the root
2282           account on your nodes when they are in Debug mode.</p>
2283 </dd>
2284 <dt><span class="term">PLC_DEBUG_SSH_KEY</span></dt>
2285 <dd>
2286 <p>
2287                   Type: file</p>
2288 <p>
2289                   Default: /etc/planetlab/debug_ssh_key.rsa</p>
2290 <p>The SSH private key used to access the root
2291           account on your nodes when they are in Debug mode.</p>
2292 </dd>
2293 <dt><span class="term">PLC_ROOT_GPG_KEY_PUB</span></dt>
2294 <dd>
2295 <p>
2296                   Type: file</p>
2297 <p>
2298                   Default: /etc/planetlab/pubring.gpg</p>
2299 <p>The GPG public keyring used to sign the Boot
2300           Manager and all node packages.</p>
2301 </dd>
2302 <dt><span class="term">PLC_ROOT_GPG_KEY</span></dt>
2303 <dd>
2304 <p>
2305                   Type: file</p>
2306 <p>
2307                   Default: /etc/planetlab/secring.gpg</p>
2308 <p>The SSH private key used to access the root
2309           account on your nodes.</p>
2310 </dd>
2311 <dt><span class="term">PLC_MA_SA_NAMESPACE</span></dt>
2312 <dd>
2313 <p>
2314                   Type: ip</p>
2315 <p>
2316                   Default: test</p>
2317 <p>The namespace of your MA/SA. This should be a
2318           globally unique value assigned by PlanetLab
2319           Central.</p>
2320 </dd>
2321 <dt><span class="term">PLC_MA_SA_SSL_KEY</span></dt>
2322 <dd>
2323 <p>
2324                   Type: file</p>
2325 <p>
2326                   Default: /etc/planetlab/ma_sa_ssl.key</p>
2327 <p>The SSL private key used for signing documents
2328           with the signature of your MA/SA. If non-existent, one will
2329           be generated.</p>
2330 </dd>
2331 <dt><span class="term">PLC_MA_SA_SSL_CRT</span></dt>
2332 <dd>
2333 <p>
2334                   Type: file</p>
2335 <p>
2336                   Default: /etc/planetlab/ma_sa_ssl.crt</p>
2337 <p>The corresponding SSL public certificate. By
2338           default, this certificate is self-signed. You may replace
2339           the certificate later with one signed by the PLC root
2340           CA.</p>
2341 </dd>
2342 <dt><span class="term">PLC_MA_SA_CA_SSL_CRT</span></dt>
2343 <dd>
2344 <p>
2345                   Type: file</p>
2346 <p>
2347                   Default: /etc/planetlab/ma_sa_ca_ssl.crt</p>
2348 <p>If applicable, the certificate of the PLC root
2349           CA. If your MA/SA certificate is self-signed, then this file
2350           is the same as your MA/SA certificate.</p>
2351 </dd>
2352 <dt><span class="term">PLC_MA_SA_CA_SSL_KEY_PUB</span></dt>
2353 <dd>
2354 <p>
2355                   Type: file</p>
2356 <p>
2357                   Default: /etc/planetlab/ma_sa_ca_ssl.pub</p>
2358 <p>If applicable, the public key of the PLC root
2359           CA. If your MA/SA certificate is self-signed, then this file
2360           is the same as your MA/SA public key.</p>
2361 </dd>
2362 <dt><span class="term">PLC_MA_SA_API_CRT</span></dt>
2363 <dd>
2364 <p>
2365                   Type: file</p>
2366 <p>
2367                   Default: /etc/planetlab/ma_sa_api.xml</p>
2368 <p>The API Certificate is your MA/SA public key
2369           embedded in a digitally signed XML document. By default,
2370           this document is self-signed. You may replace this
2371           certificate later with one signed by the PLC root
2372           CA.</p>
2373 </dd>
2374 <dt><span class="term">PLC_NET_DNS1</span></dt>
2375 <dd>
2376 <p>
2377                   Type: ip</p>
2378 <p>
2379                   Default: 127.0.0.1</p>
2380 <p>Primary DNS server address.</p>
2381 </dd>
2382 <dt><span class="term">PLC_NET_DNS2</span></dt>
2383 <dd>
2384 <p>
2385                   Type: ip</p>
2386 <p>
2387                   Default: </p>
2388 <p>Secondary DNS server address.</p>
2389 </dd>
2390 <dt><span class="term">PLC_DNS_ENABLED</span></dt>
2391 <dd>
2392 <p>
2393                   Type: boolean</p>
2394 <p>
2395                   Default: true</p>
2396 <p>Enable the internal DNS server. The server does
2397           not provide reverse resolution and is not a production
2398           quality or scalable DNS solution. Use the internal DNS
2399           server only for small deployments or for
2400           testing.</p>
2401 </dd>
2402 <dt><span class="term">PLC_MAIL_ENABLED</span></dt>
2403 <dd>
2404 <p>
2405                   Type: boolean</p>
2406 <p>
2407                   Default: false</p>
2408 <p>Set to false to suppress all e-mail notifications
2409           and warnings.</p>
2410 </dd>
2411 <dt><span class="term">PLC_MAIL_SUPPORT_ADDRESS</span></dt>
2412 <dd>
2413 <p>
2414                   Type: email</p>
2415 <p>
2416                   Default: root+support@localhost.localdomain</p>
2417 <p>This address is used for support
2418           requests. Support requests may include traffic complaints,
2419           security incident reporting, web site malfunctions, and
2420           general requests for information. We recommend that the
2421           address be aliased to a ticketing system such as Request
2422           Tracker.</p>
2423 </dd>
2424 <dt><span class="term">PLC_MAIL_BOOT_ADDRESS</span></dt>
2425 <dd>
2426 <p>
2427                   Type: email</p>
2428 <p>
2429                   Default: root+install-msgs@localhost.localdomain</p>
2430 <p>The API will notify this address when a problem
2431           occurs during node installation or boot.</p>
2432 </dd>
2433 <dt><span class="term">PLC_MAIL_SLICE_ADDRESS</span></dt>
2434 <dd>
2435 <p>
2436                   Type: email</p>
2437 <p>
2438                   Default: root+SLICE@localhost.localdomain</p>
2439 <p>This address template is used for sending
2440           e-mail notifications to slices. SLICE will be replaced with
2441           the name of the slice.</p>
2442 </dd>
2443 <dt><span class="term">PLC_DB_ENABLED</span></dt>
2444 <dd>
2445 <p>
2446                   Type: boolean</p>
2447 <p>
2448                   Default: true</p>
2449 <p>Enable the database server on this
2450           machine.</p>
2451 </dd>
2452 <dt><span class="term">PLC_DB_TYPE</span></dt>
2453 <dd>
2454 <p>
2455                   Type: string</p>
2456 <p>
2457                   Default: postgresql</p>
2458 <p>The type of database server. Currently, only
2459           postgresql is supported.</p>
2460 </dd>
2461 <dt><span class="term">PLC_DB_HOST</span></dt>
2462 <dd>
2463 <p>
2464                   Type: hostname</p>
2465 <p>
2466                   Default: localhost.localdomain</p>
2467 <p>The fully qualified hostname of the database
2468           server.</p>
2469 </dd>
2470 <dt><span class="term">PLC_DB_IP</span></dt>
2471 <dd>
2472 <p>
2473                   Type: ip</p>
2474 <p>
2475                   Default: 127.0.0.1</p>
2476 <p>The IP address of the database server, if not
2477           resolvable by the configured DNS servers.</p>
2478 </dd>
2479 <dt><span class="term">PLC_DB_PORT</span></dt>
2480 <dd>
2481 <p>
2482                   Type: int</p>
2483 <p>
2484                   Default: 5432</p>
2485 <p>The TCP port number through which the database
2486           server should be accessed.</p>
2487 </dd>
2488 <dt><span class="term">PLC_DB_NAME</span></dt>
2489 <dd>
2490 <p>
2491                   Type: string</p>
2492 <p>
2493                   Default: planetlab3</p>
2494 <p>The name of the database to access.</p>
2495 </dd>
2496 <dt><span class="term">PLC_DB_USER</span></dt>
2497 <dd>
2498 <p>
2499                   Type: string</p>
2500 <p>
2501                   Default: pgsqluser</p>
2502 <p>The username to use when accessing the
2503           database.</p>
2504 </dd>
2505 <dt><span class="term">PLC_DB_PASSWORD</span></dt>
2506 <dd>
2507 <p>
2508                   Type: password</p>
2509 <p>
2510                   Default: </p>
2511 <p>The password to use when accessing the
2512           database. If left blank, one will be
2513           generated.</p>
2514 </dd>
2515 <dt><span class="term">PLC_API_ENABLED</span></dt>
2516 <dd>
2517 <p>
2518                   Type: boolean</p>
2519 <p>
2520                   Default: true</p>
2521 <p>Enable the API server on this
2522           machine.</p>
2523 </dd>
2524 <dt><span class="term">PLC_API_DEBUG</span></dt>
2525 <dd>
2526 <p>
2527                   Type: boolean</p>
2528 <p>
2529                   Default: false</p>
2530 <p>Enable verbose API debugging. Do not enable on
2531           a production system!</p>
2532 </dd>
2533 <dt><span class="term">PLC_API_HOST</span></dt>
2534 <dd>
2535 <p>
2536                   Type: hostname</p>
2537 <p>
2538                   Default: localhost.localdomain</p>
2539 <p>The fully qualified hostname of the API
2540           server.</p>
2541 </dd>
2542 <dt><span class="term">PLC_API_IP</span></dt>
2543 <dd>
2544 <p>
2545                   Type: ip</p>
2546 <p>
2547                   Default: 127.0.0.1</p>
2548 <p>The IP address of the API server, if not
2549           resolvable by the configured DNS servers.</p>
2550 </dd>
2551 <dt><span class="term">PLC_API_PORT</span></dt>
2552 <dd>
2553 <p>
2554                   Type: int</p>
2555 <p>
2556                   Default: 80</p>
2557 <p>The TCP port number through which the API
2558           should be accessed. Warning: SSL (port 443) access is not
2559           fully supported by the website code yet. We recommend that
2560           port 80 be used for now and that the API server either run
2561           on the same machine as the web server, or that they both be
2562           on a secure wired network.</p>
2563 </dd>
2564 <dt><span class="term">PLC_API_PATH</span></dt>
2565 <dd>
2566 <p>
2567                   Type: string</p>
2568 <p>
2569                   Default: /PLCAPI/</p>
2570 <p>The base path of the API URL.</p>
2571 </dd>
2572 <dt><span class="term">PLC_API_MAINTENANCE_USER</span></dt>
2573 <dd>
2574 <p>
2575                   Type: string</p>
2576 <p>
2577                   Default: maint@localhost.localdomain</p>
2578 <p>The username of the maintenance account. This
2579           account is used by local scripts that perform automated
2580           tasks, and cannot be used for normal logins.</p>
2581 </dd>
2582 <dt><span class="term">PLC_API_MAINTENANCE_PASSWORD</span></dt>
2583 <dd>
2584 <p>
2585                   Type: password</p>
2586 <p>
2587                   Default: </p>
2588 <p>The password of the maintenance account. If
2589           left blank, one will be generated. We recommend that the
2590           password be changed periodically.</p>
2591 </dd>
2592 <dt><span class="term">PLC_API_MAINTENANCE_SOURCES</span></dt>
2593 <dd>
2594 <p>
2595                   Type: hostname</p>
2596 <p>
2597                   Default: </p>
2598 <p>A space-separated list of IP addresses allowed
2599           to access the API through the maintenance account. The value
2600           of this variable is set automatically to allow only the API,
2601           web, and boot servers, and should not be
2602           changed.</p>
2603 </dd>
2604 <dt><span class="term">PLC_API_SSL_KEY</span></dt>
2605 <dd>
2606 <p>
2607                   Type: file</p>
2608 <p>
2609                   Default: /etc/planetlab/api_ssl.key</p>
2610 <p>The SSL private key to use for encrypting HTTPS
2611           traffic. If non-existent, one will be
2612           generated.</p>
2613 </dd>
2614 <dt><span class="term">PLC_API_SSL_CRT</span></dt>
2615 <dd>
2616 <p>
2617                   Type: file</p>
2618 <p>
2619                   Default: /etc/planetlab/api_ssl.crt</p>
2620 <p>The corresponding SSL public certificate. By
2621           default, this certificate is self-signed. You may replace
2622           the certificate later with one signed by a root
2623           CA.</p>
2624 </dd>
2625 <dt><span class="term">PLC_API_CA_SSL_CRT</span></dt>
2626 <dd>
2627 <p>
2628                   Type: file</p>
2629 <p>
2630                   Default: /etc/planetlab/api_ca_ssl.crt</p>
2631 <p>The certificate of the root CA, if any, that
2632           signed your server certificate. If your server certificate is
2633           self-signed, then this file is the same as your server
2634           certificate.</p>
2635 </dd>
2636 <dt><span class="term">PLC_WWW_ENABLED</span></dt>
2637 <dd>
2638 <p>
2639                   Type: boolean</p>
2640 <p>
2641                   Default: true</p>
2642 <p>Enable the web server on this
2643           machine.</p>
2644 </dd>
2645 <dt><span class="term">PLC_WWW_DEBUG</span></dt>
2646 <dd>
2647 <p>
2648                   Type: boolean</p>
2649 <p>
2650                   Default: false</p>
2651 <p>Enable debugging output on web pages. Do not
2652           enable on a production system!</p>
2653 </dd>
2654 <dt><span class="term">PLC_WWW_HOST</span></dt>
2655 <dd>
2656 <p>
2657                   Type: hostname</p>
2658 <p>
2659                   Default: localhost.localdomain</p>
2660 <p>The fully qualified hostname of the web
2661           server.</p>
2662 </dd>
2663 <dt><span class="term">PLC_WWW_IP</span></dt>
2664 <dd>
2665 <p>
2666                   Type: ip</p>
2667 <p>
2668                   Default: 127.0.0.1</p>
2669 <p>The IP address of the web server, if not
2670           resolvable by the configured DNS servers.</p>
2671 </dd>
2672 <dt><span class="term">PLC_WWW_PORT</span></dt>
2673 <dd>
2674 <p>
2675                   Type: int</p>
2676 <p>
2677                   Default: 80</p>
2678 <p>The TCP port number through which the
2679           unprotected portions of the web site should be
2680           accessed.</p>
2681 </dd>
2682 <dt><span class="term">PLC_WWW_SSL_PORT</span></dt>
2683 <dd>
2684 <p>
2685                   Type: int</p>
2686 <p>
2687                   Default: 443</p>
2688 <p>The TCP port number through which the protected
2689           portions of the web site should be accessed.</p>
2690 </dd>
2691 <dt><span class="term">PLC_WWW_SSL_KEY</span></dt>
2692 <dd>
2693 <p>
2694                   Type: file</p>
2695 <p>
2696                   Default: /etc/planetlab/www_ssl.key</p>
2697 <p>The SSL private key to use for encrypting HTTPS
2698           traffic. If non-existent, one will be
2699           generated.</p>
2700 </dd>
2701 <dt><span class="term">PLC_WWW_SSL_CRT</span></dt>
2702 <dd>
2703 <p>
2704                   Type: file</p>
2705 <p>
2706                   Default: /etc/planetlab/www_ssl.crt</p>
2707 <p>The corresponding SSL public certificate for
2708           the HTTP server. By default, this certificate is
2709           self-signed. You may replace the certificate later with one
2710           signed by a root CA.</p>
2711 </dd>
2712 <dt><span class="term">PLC_WWW_CA_SSL_CRT</span></dt>
2713 <dd>
2714 <p>
2715                   Type: file</p>
2716 <p>
2717                   Default: /etc/planetlab/www_ca_ssl.crt</p>
2718 <p>The certificate of the root CA, if any, that
2719           signed your server certificate. If your server certificate is
2720           self-signed, then this file is the same as your server
2721           certificate.</p>
2722 </dd>
2723 <dt><span class="term">PLC_BOOT_ENABLED</span></dt>
2724 <dd>
2725 <p>
2726                   Type: boolean</p>
2727 <p>
2728                   Default: true</p>
2729 <p>Enable the boot server on this
2730           machine.</p>
2731 </dd>
2732 <dt><span class="term">PLC_BOOT_HOST</span></dt>
2733 <dd>
2734 <p>
2735                   Type: hostname</p>
2736 <p>
2737                   Default: localhost.localdomain</p>
2738 <p>The fully qualified hostname of the boot
2739           server.</p>
2740 </dd>
2741 <dt><span class="term">PLC_BOOT_IP</span></dt>
2742 <dd>
2743 <p>
2744                   Type: ip</p>
2745 <p>
2746                   Default: 127.0.0.1</p>
2747 <p>The IP address of the boot server, if not
2748           resolvable by the configured DNS servers.</p>
2749 </dd>
2750 <dt><span class="term">PLC_BOOT_PORT</span></dt>
2751 <dd>
2752 <p>
2753                   Type: int</p>
2754 <p>
2755                   Default: 80</p>
2756 <p>The TCP port number through which the
2757           unprotected portions of the boot server should be
2758           accessed.</p>
2759 </dd>
2760 <dt><span class="term">PLC_BOOT_SSL_PORT</span></dt>
2761 <dd>
2762 <p>
2763                   Type: int</p>
2764 <p>
2765                   Default: 443</p>
2766 <p>The TCP port number through which the protected
2767           portions of the boot server should be
2768           accessed.</p>
2769 </dd>
2770 <dt><span class="term">PLC_BOOT_SSL_KEY</span></dt>
2771 <dd>
2772 <p>
2773                   Type: file</p>
2774 <p>
2775                   Default: /etc/planetlab/boot_ssl.key</p>
2776 <p>The SSL private key to use for encrypting HTTPS
2777           traffic.</p>
2778 </dd>
2779 <dt><span class="term">PLC_BOOT_SSL_CRT</span></dt>
2780 <dd>
2781 <p>
2782                   Type: file</p>
2783 <p>
2784                   Default: /etc/planetlab/boot_ssl.crt</p>
2785 <p>The corresponding SSL public certificate for
2786           the HTTP server. By default, this certificate is
2787           self-signed. You may replace the certificate later with one
2788           signed by a root CA.</p>
2789 </dd>
2790 <dt><span class="term">PLC_BOOT_CA_SSL_CRT</span></dt>
2791 <dd>
2792 <p>
2793                   Type: file</p>
2794 <p>
2795                   Default: /etc/planetlab/boot_ca_ssl.crt</p>
2796 <p>The certificate of the root CA, if any, that
2797           signed your server certificate. If your server certificate is
2798           self-signed, then this file is the same as your server
2799           certificate.</p>
2800 </dd>
2801 </dl></div>
2802 </div>
2803 <div class="appendix" lang="en">
2804 <h2 class="title" style="clear: both">
2805 <a name="VariablesDevel"></a>B. Development configuration variables (for <span class="emphasis"><em>myplc-devel</em></span>)</h2>
2806 <div class="variablelist"><dl>
2807 <dt><span class="term">PLC_DEVEL_FEDORA_RELEASE</span></dt>
2808 <dd>
2809 <p>
2810                   Type: string</p>
2811 <p>
2812                   Default: 4</p>
2813 <p>Version number of Fedora Core upon which to
2814           base the build environment. Warning: Currently, only Fedora
2815           Core 4 is supported.</p>
2816 </dd>
2817 <dt><span class="term">PLC_DEVEL_FEDORA_ARCH</span></dt>
2818 <dd>
2819 <p>
2820                   Type: string</p>
2821 <p>
2822                   Default: i386</p>
2823 <p>Base architecture of the build
2824           environment. Warning: Currently, only i386 is
2825           supported.</p>
2826 </dd>
2827 <dt><span class="term">PLC_DEVEL_FEDORA_URL</span></dt>
2828 <dd>
2829 <p>
2830                   Type: string</p>
2831 <p>
2832                   Default: file:///usr/share/mirrors/fedora</p>
2833 <p>Fedora Core mirror from which to install
2834           filesystems.</p>
2835 </dd>
2836 <dt><span class="term">PLC_DEVEL_CVSROOT</span></dt>
2837 <dd>
2838 <p>
2839                   Type: string</p>
2840 <p>
2841                   Default: /cvs</p>
2842 <p>CVSROOT to use when checking out code.</p>
2843 </dd>
2844 <dt><span class="term">PLC_DEVEL_BOOTSTRAP</span></dt>
2845 <dd>
2846 <p>
2847                   Type: boolean</p>
2848 <p>
2849                   Default: false</p>
2850 <p>Controls whether MyPLC should be built inside
2851           of its own development environment.</p>
2852 </dd>
2853 </dl></div>
2854 </div>
2855 <div class="bibliography">
2856 <div class="titlepage"><div><div><h2 class="title">
2857 <a name="id2898373"></a>Bibliography</h2></div></div></div>
2858 <div class="biblioentry">
2859 <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
2860       Technical Contact's Guide</a></i>. </span></p>
2861 </div>
2862 </div>
2863 </div><?php require('footer.php'); ?>
2864 dummy 1.12 for cathing up with the xml numbering