doc/myplc.php

   1 <?php
   2
   3   // DO NOT EDIT. This file was automatically generated from
   4   // DocBook XML. See plc_www/doc/README.
   5
   6   $_title= "MyPLC User's Guide";
   7
   8   require_once('session.php');
   9   require_once('header.php');
  10   require_once('nav.php');
  11
  12   ?><div class="article" lang="en">
  13 <div class="titlepage">
  14 <div>
  15 <div><h1 class="title">
  16 <a name="id224920"></a>MyPLC User's Guide</h1></div>
  17 <div><div class="author"><h3 class="author"><span class="firstname">Mark Huang</span></h3></div></div>
  18 <div><div class="revhistory"><table border="1" width="100%" summary="Revision history">
  19 <tr><th align="left" valign="top" colspan="3"><b>Revision History</b></th></tr>
  20 <tr>
  21 <td align="left">Revision 1.0</td>
  22 <td align="left">April 7, 2006</td>
  23 <td align="left">MLH</td>
  24 </tr>
  25 <tr><td align="left" colspan="3">
  26           <p>Initial draft.</p>
  27         </td></tr>
  28 </table></div></div>
  29 <div><div class="abstract">
  30 <p class="title"><b>Abstract</b></p>
  31 <p>This document describes the design, installation, and
  32       administration of MyPLC, a complete PlanetLab Central (PLC)
  33       portable installation contained within a
  34       <span><strong class="command">chroot</strong></span> jail. This document assumes advanced
  35       knowledge of the PlanetLab architecture and Linux system
  36       administration.</p>
  37 </div></div>
  38 </div>
  39 <hr>
  40 </div>
  41 <div class="toc">
  42 <p><b>Table of Contents</b></p>
  43 <dl>
  44 <dt><span class="section"><a href="#id225358">1. Overview</a></span></dt>
  45 <dt><span class="section"><a href="#id225202">2. Installation</a></span></dt>
  46 <dt><span class="section"><a href="#id267666">3. Quickstart</a></span></dt>
  47 <dd><dl>
  48 <dt><span class="section"><a href="#ChangingTheConfiguration">3.1. Changing the configuration</a></span></dt>
  49 <dt><span class="section"><a href="#id268166">3.2. Installing nodes</a></span></dt>
  50 <dt><span class="section"><a href="#id268240">3.3. Administering nodes</a></span></dt>
  51 <dt><span class="section"><a href="#id268334">3.4. Creating a slice</a></span></dt>
  52 </dl></dd>
  53 <dt><span class="appendix"><a href="#id268409">A. Configuration variables</a></span></dt>
  54 <dt><span class="bibliography"><a href="#id270747">Bibliography</a></span></dt>
  55 </dl>
  56 </div>
  57 <div class="section" lang="en">
  58 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  59 <a name="id225358"></a>1. Overview</h2></div></div></div>
  60 <p>MyPLC is a complete PlanetLab Central (PLC) portable
  61     installation contained within a <span><strong class="command">chroot</strong></span>
  62     jail. The default installation consists of a web server, an
  63     XML-RPC API server, a boot server, and a database server: the core
  64     components of PLC. The installation is customized through an
  65     easy-to-use graphical interface. All PLC services are started up
  66     and shut down through a single script installed on the host
  67     system. The usually complex process of installing and
  68     administering the PlanetLab backend is reduced by containing PLC
  69     services within a virtual filesystem. By packaging it in such a
  70     manner, MyPLC may also be run on any modern Linux distribution,
  71     and could conceivably even run in a PlanetLab slice.</p>
  72 <div class="figure">
  73 <a name="Architecture"></a><p class="title"><b>Figure 1. MyPLC architecture</b></p>
  74 <div class="mediaobject" align="center">
  75 <img src="architecture.png" align="middle" width="270" alt="MyPLC architecture"><div class="caption"><p>MyPLC should be viewed as a single application that
  76           provides multiple functions and can run on any host
  77           system.</p></div>
  78 </div>
  79 </div>
  80 </div>
  81 <div class="section" lang="en">
  82 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  83 <a name="id225202"></a>2. Installation</h2></div></div></div>
  84 <p>Though internally composed of commodity software
  85     subpackages, MyPLC should be treated as a monolithic software
  86     application. MyPLC is distributed as single RPM package that has
  87     no external dependencies, allowing it to be installed on
  88     practically any Linux 2.6 based distribution:</p>
  89 <div class="example">
  90 <a name="id225260"></a><p class="title"><b>Example 1. Installing MyPLC.</b></p>
  91 <pre class="programlisting"># If your distribution supports RPM
  92 rpm -U myplc-0.3-1.planetlab.i386.rpm
  93
  94 # If your distribution does not support RPM
  95 cd /
  96 rpm2cpio myplc-0.3-1.planetlab.i386.rpm | cpio -diu</pre>
  97 </div>
  98 <p>MyPLC installs the following files and directories:</p>
  99 <div class="itemizedlist"><ul type="disc">
 100 <li><p><code class="filename">/plc/root.img</code>: The main
 101       root filesystem of the MyPLC application. This file is an
 102       uncompressed ext3 filesystem that is loopback mounted on
 103       <code class="filename">/plc/root</code> when MyPLC starts. The
 104       filesystem, even when mounted, should be treated an opaque
 105       binary that can and will be replaced in its entirety by any
 106       upgrade of MyPLC.</p></li>
 107 <li><p><code class="filename">/plc/root</code>: The mount point
 108       for <code class="filename">/plc/root.img</code>. Once the root filesystem
 109       is mounted, all MyPLC services run in a
 110       <span><strong class="command">chroot</strong></span> jail based in this
 111       directory.</p></li>
 112 <li>
 113 <p><code class="filename">/plc/data</code>: The directory where user
 114         data and generated files are stored. This directory is bind
 115         mounted into the <span><strong class="command">chroot</strong></span> jail on
 116         <code class="filename">/data</code>. Files in this directory are marked
 117         with <span><strong class="command">%config(noreplace)</strong></span> in the RPM. That
 118         is, during an upgrade of MyPLC, if a file has not changed
 119         since the last installation or upgrade of MyPLC, it is subject
 120         to upgrade and replacement. If the file has chanegd, the new
 121         version of the file will be created with a
 122         <code class="filename">.rpmnew</code> extension. Symlinks within the
 123         MyPLC root filesystem ensure that the following directories
 124         (relative to <code class="filename">/plc/root</code>) are stored
 125         outside the MyPLC filesystem image:</p>
 126 <div class="itemizedlist"><ul type="circle">
 127 <li><p><code class="filename">/etc/planetlab</code>: This
 128           directory contains the configuration files, keys, and
 129           certificates that define your MyPLC
 130           installation.</p></li>
 131 <li><p><code class="filename">/var/lib/pgsql</code>: This
 132           directory contains PostgreSQL database
 133           files.</p></li>
 134 <li><p><code class="filename">/var/www/html/alpina-logs</code>: This
 135           directory contains node installation logs.</p></li>
 136 <li><p><code class="filename">/var/www/html/boot</code>: This
 137           directory contains the Boot Manager, customized for your MyPLC
 138           installation, and its data files.</p></li>
 139 <li><p><code class="filename">/var/www/html/download</code>: This
 140           directory contains Boot CD images, customized for your MyPLC
 141           installation.</p></li>
 142 <li><p><code class="filename">/var/www/html/install-rpms</code>: This
 143           directory is where you should install node package updates,
 144           if any. By default, nodes are installed from the tarball
 145           located at
 146           <code class="filename">/var/www/html/boot/PlanetLab-Bootstrap.tar.bz2</code>,
 147           which is pre-built from the latest PlanetLab Central
 148           sources, and installed as part of your MyPLC
 149           installation. However, nodes will attempt to install any
 150           newer RPMs located in
 151           <code class="filename">/var/www/html/install-rpms/planetlab</code>,
 152           after initial installation and periodically thereafter. You
 153           must run <span><strong class="command">yum-arch</strong></span> and
 154           <span><strong class="command">createrepo</strong></span> to update the
 155           <span><strong class="command">yum</strong></span> caches in this directory after
 156           installing a new RPM. PlanetLab Central cannot support any
 157           changes to this directory.</p></li>
 158 <li><p><code class="filename">/var/www/html/xml</code>: This
 159           directory contains various XML files that the Slice Creation
 160           Service uses to determine the state of slices. These XML
 161           files are refreshed periodically by <span><strong class="command">cron</strong></span>
 162           jobs running in the MyPLC root.</p></li>
 163 </ul></div>
 164 </li>
 165 <li>
 166 <p><code class="filename">/etc/init.d/plc</code>: This file
 167         is a System V init script installed on your host filesystem,
 168         that allows you to start up and shut down MyPLC with a single
 169         command. On a Red Hat or Fedora host system, it is customary to
 170         use the <span><strong class="command">service</strong></span> command to invoke System V
 171         init scripts:</p>
 172 <div class="example">
 173 <a name="StartingAndStoppingMyPLC"></a><p class="title"><b>Example 2. Starting and stopping MyPLC.</b></p>
 174 <pre class="programlisting"># Starting MyPLC
 175 service plc start
 176
 177 # Stopping MyPLC
 178 service plc stop</pre>
 179 </div>
 180 <p>Like all other registered System V init services, MyPLC is
 181         started and shut down automatically when your host system boots
 182         and powers off. You may disable automatic startup by invoking
 183         the <span><strong class="command">chkconfig</strong></span> command on a Red Hat or Fedora
 184         host system:</p>
 185 <div class="example">
 186 <a name="id243542"></a><p class="title"><b>Example 3. Disabling automatic startup of MyPLC.</b></p>
 187 <pre class="programlisting"># Disable automatic startup
 188 chkconfig plc off
 189
 190 # Enable automatic startup
 191 chkconfig plc on</pre>
 192 </div>
 193 </li>
 194 <li><p><code class="filename">/etc/sysconfig/plc</code>: This
 195       file is a shell script fragment that defines the variables
 196       <code class="envar">PLC_ROOT</code> and <code class="envar">PLC_DATA</code>. By default,
 197       the values of these variables are <code class="filename">/plc/root</code>
 198       and <code class="filename">/plc/data</code>, respectively. If you wish,
 199       you may move your MyPLC installation to another location on your
 200       host filesystem and edit the values of these variables
 201       appropriately, but you will break the RPM upgrade
 202       process. PlanetLab Central cannot support any changes to this
 203       file.</p></li>
 204 <li><p><code class="filename">/etc/planetlab</code>: This
 205       symlink to <code class="filename">/plc/data/etc/planetlab</code> is
 206       installed on the host system for convenience.</p></li>
 207 </ul></div>
 208 </div>
 209 <div class="section" lang="en">
 210 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 211 <a name="id267666"></a>3. Quickstart</h2></div></div></div>
 212 <p>Once installed, start MyPLC (see <a href="#StartingAndStoppingMyPLC" title="Example 2. Starting and stopping MyPLC.">Example 2, “Starting and stopping MyPLC.”</a>). MyPLC must be started as
 213     root. Observe the output of this command for any failures. If no
 214     failures occur, you should see output similar to the
 215     following:</p>
 216 <div class="example">
 217 <a name="id267787"></a><p class="title"><b>Example 4. A successful MyPLC startup.</b></p>
 218 <pre class="programlisting">Mounting PLC:                                              [  OK  ]
 219 PLC: Generating network files:                             [  OK  ]
 220 PLC: Starting system logger:                               [  OK  ]
 221 PLC: Starting database server:                             [  OK  ]
 222 PLC: Generating SSL certificates:                          [  OK  ]
 223 PLC: Generating SSH keys:                                  [  OK  ]
 224 PLC: Starting web server:                                  [  OK  ]
 225 PLC: Bootstrapping the database:                           [  OK  ]
 226 PLC: Starting DNS server:                                  [  OK  ]
 227 PLC: Starting crond:                                       [  OK  ]
 228 PLC: Rebuilding Boot CD:                                   [  OK  ]
 229 PLC: Rebuilding Boot Manager:                              [  OK  ]
 230 PLC: Signing node packages:                                [  OK  ]
 231 </pre>
 232 </div>
 233 <p>If <code class="filename">/plc/root</code> is mounted successfully, a
 234     complete log file of the startup process may be found at
 235     <code class="filename">/plc/root/var/log/boot.log</code>. Possible reasons
 236     for failure of each step include:</p>
 237 <div class="itemizedlist"><ul type="disc">
 238 <li><p><code class="literal">Mounting PLC</code>: If this step
 239       fails, first ensure that you started MyPLC as root. Check
 240       <code class="filename">/etc/sysconfig/plc</code> to ensure that
 241       <code class="envar">PLC_ROOT</code> and <code class="envar">PLC_DATA</code> refer to the
 242       right locations. You may also have too many existing loopback
 243       mounts, or your kernel may not support loopback mounting, bind
 244       mounting, or the ext3 filesystem. Try freeing at least one
 245       loopback device, or re-compiling your kernel to support loopback
 246       mounting, bind mounting, and the ext3 filesystem. SELinux may
 247       also be enabled. If you install MyPLC on Fedora Core 4 or 5, use
 248       the <span class="application">Security Level Configuration</span>
 249       utility to configure SELinux to be
 250       <code class="literal">Permissive</code>.</p></li>
 251 <li><p><code class="literal">Starting database server</code>: If
 252       this step fails, check
 253       <code class="filename">/plc/root/var/log/pgsql</code> and
 254       <code class="filename">/plc/root/var/log/boot.log</code>. The most common
 255       reason for failure is that the default PostgreSQL port, TCP port
 256       5432, is already in use. Check that you are not running a
 257       PostgreSQL server on the host system.</p></li>
 258 <li><p><code class="literal">Starting web server</code>: If this
 259       step fails, check
 260       <code class="filename">/plc/root/var/log/httpd/error_log</code> and
 261       <code class="filename">/plc/root/var/log/boot.log</code> for obvious
 262       errors. The most common reason for failure is that the default
 263       web ports, TCP ports 80 and 443, are already in use. Check that
 264       you are not running a web server on the host
 265       system.</p></li>
 266 <li><p><code class="literal">Bootstrapping the database</code>:
 267       If this step fails, it is likely that the previous step
 268       (<code class="literal">Starting web server</code>) also failed. Another
 269       reason that it could fail is if <code class="envar">PLC_API_HOST</code> (see
 270       <a href="#ChangingTheConfiguration" title="3.1. Changing the configuration">Section 3.1, “Changing the configuration”</a>) does not resolve to
 271       the host on which the API server has been enabled. By default,
 272       all services, including the API server, are enabled and run on
 273       the same host, so check that <code class="envar">PLC_API_HOST</code> is
 274       either <code class="filename">localhost</code> or resolves to a local IP
 275       address.</p></li>
 276 <li><p><code class="literal">Starting crond</code>: If this step
 277       fails, it is likely that the previous steps (<code class="literal">Starting
 278       web server</code> and <code class="literal">Bootstrapping the
 279       database</code>) also failed. If not, check
 280       <code class="filename">/plc/root/var/log/boot.log</code> for obvious
 281       errors. This step starts the <span><strong class="command">cron</strong></span> service and
 282       generates the initial set of XML files that the Slice Creation
 283       Service uses to determine slice state.</p></li>
 284 </ul></div>
 285 <p>If no failures occur, then MyPLC should be active with a
 286     default configuration. Open a web browser on the host system and
 287     visit <code class="literal">http://localhost/</code>, which should bring you
 288     to the front page of your PLC installation. The password of the
 289     default administrator account
 290     <code class="literal">root@localhost.localdomain</code> (set by
 291     <code class="envar">PLC_ROOT_USER</code>) is <code class="literal">root</code> (set by
 292     <code class="envar">PLC_ROOT_PASSWORD</code>).</p>
 293 <div class="section" lang="en">
 294 <div class="titlepage"><div><div><h3 class="title">
 295 <a name="ChangingTheConfiguration"></a>3.1. Changing the configuration</h3></div></div></div>
 296 <p>After verifying that MyPLC is working correctly, shut it
 297       down and begin changing some of the default variable
 298       values. Shut down MyPLC with <span><strong class="command">service plc stop</strong></span>
 299       (see <a href="#StartingAndStoppingMyPLC" title="Example 2. Starting and stopping MyPLC.">Example 2, “Starting and stopping MyPLC.”</a>). With a text
 300       editor, open the file
 301       <code class="filename">/etc/planetlab/plc_config.xml</code>. This file is
 302       a self-documenting configuration file written in XML. Variables
 303       are divided into categories. Variable identifiers must be
 304       alphanumeric, plus underscore. A variable is referred to
 305       canonically as the uppercase concatenation of its category
 306       identifier, an underscore, and its variable identifier. Thus, a
 307       variable with an <code class="literal">id</code> of
 308       <code class="literal">slice_prefix</code> in the <code class="literal">plc</code>
 309       category is referred to canonically as
 310       <code class="envar">PLC_SLICE_PREFIX</code>.</p>
 311 <p>The reason for this convention is that during MyPLC
 312       startup, <code class="filename">plc_config.xml</code> is translated into
 313       several different languages—shell, PHP, and
 314       Python—so that scripts written in each of these languages
 315       can refer to the same underlying configuration. Most MyPLC
 316       scripts are written in shell, so the convention for shell
 317       variables predominates.</p>
 318 <p>The variables that you should change immediately are:</p>
 319 <div class="itemizedlist"><ul type="disc">
 320 <li><p><code class="envar">PLC_NAME</code>: Change this to the
 321         name of your PLC installation.</p></li>
 322 <li><p><code class="envar">PLC_ROOT_PASSWORD</code>: Change this
 323         to a more secure password.</p></li>
 324 <li><p><code class="envar">PLC_MAIL_SUPPORT_ADDRESS</code>:
 325         Change this to the e-mail address at which you would like to
 326         receive support requests.</p></li>
 327 <li><p><code class="envar">PLC_DB_HOST</code>,
 328         <code class="envar">PLC_DB_IP</code>, <code class="envar">PLC_API_HOST</code>,
 329         <code class="envar">PLC_API_IP</code>, <code class="envar">PLC_WWW_HOST</code>,
 330         <code class="envar">PLC_WWW_IP</code>, <code class="envar">PLC_BOOT_HOST</code>,
 331         <code class="envar">PLC_BOOT_IP</code>: Change all of these to the
 332         preferred FQDN and external IP address of your host
 333         system.</p></li>
 334 </ul></div>
 335 <p>After changing these variables, save the file, then
 336       restart MyPLC with <span><strong class="command">service plc start</strong></span>. You
 337       should notice that the password of the default administrator
 338       account is no longer <code class="literal">root</code>, and that the
 339       default site name includes the name of your PLC installation
 340       instead of PlanetLab.</p>
 341 </div>
 342 <div class="section" lang="en">
 343 <div class="titlepage"><div><div><h3 class="title">
 344 <a name="id268166"></a>3.2. Installing nodes</h3></div></div></div>
 345 <p>Install your first node by clicking <code class="literal">Add
 346       Node</code> under the <code class="literal">Nodes</code> tab. Fill in
 347       all the appropriate details, then click
 348       <code class="literal">Add</code>. Download the node's configuration file
 349       by clicking <code class="literal">Download configuration file</code> on
 350       the <span class="bold"><strong>Node Details</strong></span> page for the
 351       node. Save it to a floppy disk or USB key as detailed in [<a href="#TechsGuide" title="[TechsGuide]">1</a>].</p>
 352 <p>Follow the rest of the instructions in [<a href="#TechsGuide" title="[TechsGuide]">1</a>] for creating a Boot CD and installing
 353       the node, except download the Boot CD image from the
 354       <code class="filename">/download</code> directory of your PLC
 355       installation, not from PlanetLab Central. The images located
 356       here are customized for your installation. If you change the
 357       hostname of your boot server (<code class="envar">PLC_BOOT_HOST</code>), or
 358       if the SSL certificate of your boot server expires, MyPLC will
 359       regenerate it and rebuild the Boot CD with the new
 360       certificate. If this occurs, you must replace all Boot CDs
 361       created before the certificate was regenerated.</p>
 362 <p>The installation process for a node has significantly
 363       improved since PlanetLab 3.3. It should now take only a few
 364       seconds for a new node to become ready to create slices.</p>
 365 </div>
 366 <div class="section" lang="en">
 367 <div class="titlepage"><div><div><h3 class="title">
 368 <a name="id268240"></a>3.3. Administering nodes</h3></div></div></div>
 369 <p>You may administer nodes as <code class="literal">root</code> by
 370       using the SSH key stored in
 371       <code class="filename">/etc/planetlab/root_ssh_key.rsa</code>.</p>
 372 <div class="example">
 373 <a name="id268262"></a><p class="title"><b>Example 5. Accessing nodes via SSH. Replace
 374         <code class="literal">node</code> with the hostname of the node.</b></p>
 375 <pre class="programlisting">ssh -i /etc/planetlab/root_ssh_key.rsa root@node</pre>
 376 </div>
 377 <p>Besides the standard Linux log files located in
 378       <code class="filename">/var/log</code>, several other files can give you
 379       clues about any problems with active processes:</p>
 380 <div class="itemizedlist"><ul type="disc">
 381 <li><p><code class="filename">/var/log/pl_nm</code>: The log
 382         file for the Node Manager.</p></li>
 383 <li><p><code class="filename">/vservers/pl_conf/var/log/pl_conf</code>:
 384         The log file for the Slice Creation Service.</p></li>
 385 <li><p><code class="filename">/var/log/propd</code>: The log
 386         file for Proper, the service which allows certain slices to
 387         perform certain privileged operations in the root
 388         context.</p></li>
 389 <li><p><code class="filename">/vservers/pl_netflow/var/log/netflow.log</code>:
 390         The log file for PlanetFlow, the network traffic auditing
 391         service.</p></li>
 392 </ul></div>
 393 </div>
 394 <div class="section" lang="en">
 395 <div class="titlepage"><div><div><h3 class="title">
 396 <a name="id268334"></a>3.4. Creating a slice</h3></div></div></div>
 397 <p>Create a slice by clicking <code class="literal">Create Slice</code>
 398       under the <code class="literal">Slices</code> tab. Fill in all the
 399       appropriate details, then click <code class="literal">Create</code>. Add
 400       nodes to the slice by clicking <code class="literal">Manage Nodes</code>
 401       on the <span class="bold"><strong>Slice Details</strong></span> page for
 402       the slice.</p>
 403 <p>A <span><strong class="command">cron</strong></span> job runs every five minutes and
 404       updates the file
 405       <code class="filename">/plc/data/var/www/html/xml/slices-0.5.xml</code>
 406       with information about current slice state. The Slice Creation
 407       Service running on every node polls this file every ten minutes
 408       to determine if it needs to create or delete any slices. You may
 409       accelerate this process manually if desired.</p>
 410 <div class="example">
 411 <a name="id268392"></a><p class="title"><b>Example 6. Forcing slice creation on a node.</b></p>
 412 <pre class="programlisting"># Update slices.xml immediately
 413 service plc start crond
 414
 415 # Kick the Slice Creation Service on a particular node.
 416 ssh -i /etc/planetlab/root_ssh_key.rsa root@node \
 417 vserver pl_conf exec service pl_conf restart</pre>
 418 </div>
 419 </div>
 420 </div>
 421 <div class="appendix" lang="en">
 422 <h2 class="title" style="clear: both">
 423 <a name="id268409"></a>A. Configuration variables</h2>
 424 <p>Listed below is the set of standard configuration variables
 425     and their default values, defined in the template
 426     <code class="filename">/etc/planetlab/default_config.xml</code>. Additional
 427     variables and their defaults may be defined in site-specific XML
 428     templates that should be placed in
 429     <code class="filename">/etc/planetlab/configs/</code>.</p>
 430 <div class="variablelist"><dl>
 431 <dt><span class="term">PLC_NAME</span></dt>
 432 <dd>
 433 <p>
 434                   Type: string</p>
 435 <p>
 436                   Default: PlanetLab Test</p>
 437 <p>The name of this PLC installation. It is used in
 438           the name of the default system site (e.g., PlanetLab Central)
 439           and in the names of various administrative entities (e.g.,
 440           PlanetLab Support).</p>
 441 </dd>
 442 <dt><span class="term">PLC_SLICE_PREFIX</span></dt>
 443 <dd>
 444 <p>
 445                   Type: string</p>
 446 <p>
 447                   Default: pl</p>
 448 <p>The abbreviated name of this PLC
 449           installation. It is used as the prefix for system slices
 450           (e.g., pl_conf). Warning: Currently, this variable should
 451           not be changed.</p>
 452 </dd>
 453 <dt><span class="term">PLC_ROOT_USER</span></dt>
 454 <dd>
 455 <p>
 456                   Type: email</p>
 457 <p>
 458                   Default: root@localhost.localdomain</p>
 459 <p>The name of the initial administrative
 460           account. We recommend that this account be used only to create
 461           additional accounts associated with real
 462           administrators, then disabled.</p>
 463 </dd>
 464 <dt><span class="term">PLC_ROOT_PASSWORD</span></dt>
 465 <dd>
 466 <p>
 467                   Type: password</p>
 468 <p>
 469                   Default: root</p>
 470 <p>The password of the initial administrative
 471           account. Also the password of the root account on the Boot
 472           CD.</p>
 473 </dd>
 474 <dt><span class="term">PLC_ROOT_SSH_KEY_PUB</span></dt>
 475 <dd>
 476 <p>
 477                   Type: file</p>
 478 <p>
 479                   Default: /etc/planetlab/root_ssh_key.pub</p>
 480 <p>The SSH public key used to access the root
 481           account on your nodes.</p>
 482 </dd>
 483 <dt><span class="term">PLC_ROOT_SSH_KEY</span></dt>
 484 <dd>
 485 <p>
 486                   Type: file</p>
 487 <p>
 488                   Default: /etc/planetlab/root_ssh_key.rsa</p>
 489 <p>The SSH private key used to access the root
 490           account on your nodes.</p>
 491 </dd>
 492 <dt><span class="term">PLC_DEBUG_SSH_KEY_PUB</span></dt>
 493 <dd>
 494 <p>
 495                   Type: file</p>
 496 <p>
 497                   Default: /etc/planetlab/debug_ssh_key.pub</p>
 498 <p>The SSH public key used to access the root
 499           account on your nodes when they are in Debug mode.</p>
 500 </dd>
 501 <dt><span class="term">PLC_DEBUG_SSH_KEY</span></dt>
 502 <dd>
 503 <p>
 504                   Type: file</p>
 505 <p>
 506                   Default: /etc/planetlab/debug_ssh_key.rsa</p>
 507 <p>The SSH private key used to access the root
 508           account on your nodes when they are in Debug mode.</p>
 509 </dd>
 510 <dt><span class="term">PLC_ROOT_GPG_KEY_PUB</span></dt>
 511 <dd>
 512 <p>
 513                   Type: file</p>
 514 <p>
 515                   Default: /etc/planetlab/pubring.gpg</p>
 516 <p>The GPG public keyring used to sign the Boot
 517           Manager and all node packages.</p>
 518 </dd>
 519 <dt><span class="term">PLC_ROOT_GPG_KEY</span></dt>
 520 <dd>
 521 <p>
 522                   Type: file</p>
 523 <p>
 524                   Default: /etc/planetlab/secring.gpg</p>
 525 <p>The SSH private key used to access the root
 526           account on your nodes.</p>
 527 </dd>
 528 <dt><span class="term">PLC_NET_DNS1</span></dt>
 529 <dd>
 530 <p>
 531                   Type: ip</p>
 532 <p>
 533                   Default: 127.0.0.1</p>
 534 <p>Primary DNS server address.</p>
 535 </dd>
 536 <dt><span class="term">PLC_NET_DNS2</span></dt>
 537 <dd>
 538 <p>
 539                   Type: ip</p>
 540 <p>
 541                   Default: </p>
 542 <p>Secondary DNS server address.</p>
 543 </dd>
 544 <dt><span class="term">PLC_DNS_ENABLED</span></dt>
 545 <dd>
 546 <p>
 547                   Type: boolean</p>
 548 <p>
 549                   Default: true</p>
 550 <p>Enable the internal DNS server. The server does
 551           not provide reverse resolution and is not a production
 552           quality or scalable DNS solution. Use the internal DNS
 553           server only for small deployments or for
 554           testing.</p>
 555 </dd>
 556 <dt><span class="term">PLC_MAIL_ENABLED</span></dt>
 557 <dd>
 558 <p>
 559                   Type: boolean</p>
 560 <p>
 561                   Default: false</p>
 562 <p>Set to false to suppress all e-mail notifications
 563           and warnings.</p>
 564 </dd>
 565 <dt><span class="term">PLC_MAIL_SUPPORT_ADDRESS</span></dt>
 566 <dd>
 567 <p>
 568                   Type: email</p>
 569 <p>
 570                   Default: root+support@localhost.localdomain</p>
 571 <p>This address is used for support
 572           requests. Support requests may include traffic complaints,
 573           security incident reporting, web site malfunctions, and
 574           general requests for information. We recommend that the
 575           address be aliased to a ticketing system such as Request
 576           Tracker.</p>
 577 </dd>
 578 <dt><span class="term">PLC_MAIL_BOOT_ADDRESS</span></dt>
 579 <dd>
 580 <p>
 581                   Type: email</p>
 582 <p>
 583                   Default: root+install-msgs@localhost.localdomain</p>
 584 <p>The API will notify this address when a problem
 585           occurs during node installation or boot.</p>
 586 </dd>
 587 <dt><span class="term">PLC_MAIL_SLICE_ADDRESS</span></dt>
 588 <dd>
 589 <p>
 590                   Type: email</p>
 591 <p>
 592                   Default: root+SLICE@localhost.localdomain</p>
 593 <p>This address template is used for sending
 594           e-mail notifications to slices. SLICE will be replaced with
 595           the name of the slice.</p>
 596 </dd>
 597 <dt><span class="term">PLC_DB_ENABLED</span></dt>
 598 <dd>
 599 <p>
 600                   Type: boolean</p>
 601 <p>
 602                   Default: true</p>
 603 <p>Enable the database server on this
 604           machine.</p>
 605 </dd>
 606 <dt><span class="term">PLC_DB_TYPE</span></dt>
 607 <dd>
 608 <p>
 609                   Type: string</p>
 610 <p>
 611                   Default: postgresql</p>
 612 <p>The type of database server. Currently, only
 613           postgresql is supported.</p>
 614 </dd>
 615 <dt><span class="term">PLC_DB_HOST</span></dt>
 616 <dd>
 617 <p>
 618                   Type: hostname</p>
 619 <p>
 620                   Default: localhost.localdomain</p>
 621 <p>The fully qualified hostname of the database
 622           server.</p>
 623 </dd>
 624 <dt><span class="term">PLC_DB_IP</span></dt>
 625 <dd>
 626 <p>
 627                   Type: ip</p>
 628 <p>
 629                   Default: 127.0.0.1</p>
 630 <p>The IP address of the database server, if not
 631           resolvable by the configured DNS servers.</p>
 632 </dd>
 633 <dt><span class="term">PLC_DB_PORT</span></dt>
 634 <dd>
 635 <p>
 636                   Type: int</p>
 637 <p>
 638                   Default: 5432</p>
 639 <p>The TCP port number through which the database
 640           server should be accessed.</p>
 641 </dd>
 642 <dt><span class="term">PLC_DB_NAME</span></dt>
 643 <dd>
 644 <p>
 645                   Type: string</p>
 646 <p>
 647                   Default: planetlab3</p>
 648 <p>The name of the database to access.</p>
 649 </dd>
 650 <dt><span class="term">PLC_DB_USER</span></dt>
 651 <dd>
 652 <p>
 653                   Type: string</p>
 654 <p>
 655                   Default: pgsqluser</p>
 656 <p>The username to use when accessing the
 657           database.</p>
 658 </dd>
 659 <dt><span class="term">PLC_DB_PASSWORD</span></dt>
 660 <dd>
 661 <p>
 662                   Type: password</p>
 663 <p>
 664                   Default: </p>
 665 <p>The password to use when accessing the
 666           database. If left blank, one will be
 667           generated.</p>
 668 </dd>
 669 <dt><span class="term">PLC_API_ENABLED</span></dt>
 670 <dd>
 671 <p>
 672                   Type: boolean</p>
 673 <p>
 674                   Default: true</p>
 675 <p>Enable the API server on this
 676           machine.</p>
 677 </dd>
 678 <dt><span class="term">PLC_API_DEBUG</span></dt>
 679 <dd>
 680 <p>
 681                   Type: boolean</p>
 682 <p>
 683                   Default: false</p>
 684 <p>Enable verbose API debugging. Do not enable on
 685           a production system!</p>
 686 </dd>
 687 <dt><span class="term">PLC_API_HOST</span></dt>
 688 <dd>
 689 <p>
 690                   Type: hostname</p>
 691 <p>
 692                   Default: localhost.localdomain</p>
 693 <p>The fully qualified hostname of the API
 694           server.</p>
 695 </dd>
 696 <dt><span class="term">PLC_API_IP</span></dt>
 697 <dd>
 698 <p>
 699                   Type: ip</p>
 700 <p>
 701                   Default: 127.0.0.1</p>
 702 <p>The IP address of the API server, if not
 703           resolvable by the configured DNS servers.</p>
 704 </dd>
 705 <dt><span class="term">PLC_API_PORT</span></dt>
 706 <dd>
 707 <p>
 708                   Type: int</p>
 709 <p>
 710                   Default: 80</p>
 711 <p>The TCP port number through which the API
 712           should be accessed. Warning: SSL (port 443) access is not
 713           fully supported by the website code yet. We recommend that
 714           port 80 be used for now and that the API server either run
 715           on the same machine as the web server, or that they both be
 716           on a secure wired network.</p>
 717 </dd>
 718 <dt><span class="term">PLC_API_PATH</span></dt>
 719 <dd>
 720 <p>
 721                   Type: string</p>
 722 <p>
 723                   Default: /PLCAPI/</p>
 724 <p>The base path of the API URL.</p>
 725 </dd>
 726 <dt><span class="term">PLC_API_MAINTENANCE_USER</span></dt>
 727 <dd>
 728 <p>
 729                   Type: string</p>
 730 <p>
 731                   Default: maint@localhost.localdomain</p>
 732 <p>The username of the maintenance account. This
 733           account is used by local scripts that perform automated
 734           tasks, and cannot be used for normal logins.</p>
 735 </dd>
 736 <dt><span class="term">PLC_API_MAINTENANCE_PASSWORD</span></dt>
 737 <dd>
 738 <p>
 739                   Type: password</p>
 740 <p>
 741                   Default: </p>
 742 <p>The password of the maintenance account. If
 743           left blank, one will be generated. We recommend that the
 744           password be changed periodically.</p>
 745 </dd>
 746 <dt><span class="term">PLC_API_MAINTENANCE_SOURCES</span></dt>
 747 <dd>
 748 <p>
 749                   Type: hostname</p>
 750 <p>
 751                   Default: </p>
 752 <p>A space-separated list of IP addresses allowed
 753           to access the API through the maintenance account. The value
 754           of this variable is set automatically to allow only the API,
 755           web, and boot servers, and should not be
 756           changed.</p>
 757 </dd>
 758 <dt><span class="term">PLC_API_SSL_CRT</span></dt>
 759 <dd>
 760 <p>
 761                   Type: file</p>
 762 <p>
 763                   Default: /etc/planetlab/api_ssl.crt</p>
 764 <p>The signed SSL certificate to use for HTTPS
 765           access. If not specified or non-existent, a self-signed
 766           certificate will be generated.</p>
 767 </dd>
 768 <dt><span class="term">PLC_API_SSL_KEY</span></dt>
 769 <dd>
 770 <p>
 771                   Type: file</p>
 772 <p>
 773                   Default: /etc/planetlab/api_ssl.key</p>
 774 <p>The corresponding SSL private key used for
 775           signing the certificate, and for signing slice tickets. If
 776           not specified or non-existent, one will be
 777           generated.</p>
 778 </dd>
 779 <dt><span class="term">PLC_API_SSL_KEY_PUB</span></dt>
 780 <dd>
 781 <p>
 782                   Type: file</p>
 783 <p>
 784                   Default: /etc/planetlab/api_ssl.pub</p>
 785 <p>The corresponding SSL public key. If not
 786           specified or non-existent, one will be
 787           generated.</p>
 788 </dd>
 789 <dt><span class="term">PLC_WWW_ENABLED</span></dt>
 790 <dd>
 791 <p>
 792                   Type: boolean</p>
 793 <p>
 794                   Default: true</p>
 795 <p>Enable the web server on this
 796           machine.</p>
 797 </dd>
 798 <dt><span class="term">PLC_WWW_DEBUG</span></dt>
 799 <dd>
 800 <p>
 801                   Type: boolean</p>
 802 <p>
 803                   Default: false</p>
 804 <p>Enable debugging output on web pages. Do not
 805           enable on a production system!</p>
 806 </dd>
 807 <dt><span class="term">PLC_WWW_HOST</span></dt>
 808 <dd>
 809 <p>
 810                   Type: hostname</p>
 811 <p>
 812                   Default: localhost.localdomain</p>
 813 <p>The fully qualified hostname of the web
 814           server.</p>
 815 </dd>
 816 <dt><span class="term">PLC_WWW_IP</span></dt>
 817 <dd>
 818 <p>
 819                   Type: ip</p>
 820 <p>
 821                   Default: 127.0.0.1</p>
 822 <p>The IP address of the web server, if not
 823           resolvable by the configured DNS servers.</p>
 824 </dd>
 825 <dt><span class="term">PLC_WWW_PORT</span></dt>
 826 <dd>
 827 <p>
 828                   Type: int</p>
 829 <p>
 830                   Default: 80</p>
 831 <p>The TCP port number through which the
 832           unprotected portions of the web site should be
 833           accessed.</p>
 834 </dd>
 835 <dt><span class="term">PLC_WWW_SSL_PORT</span></dt>
 836 <dd>
 837 <p>
 838                   Type: int</p>
 839 <p>
 840                   Default: 443</p>
 841 <p>The TCP port number through which the protected
 842           portions of the web site should be accessed.</p>
 843 </dd>
 844 <dt><span class="term">PLC_WWW_SSL_CRT</span></dt>
 845 <dd>
 846 <p>
 847                   Type: file</p>
 848 <p>
 849                   Default: /etc/planetlab/www_ssl.crt</p>
 850 <p>The signed SSL certificate to use for HTTPS
 851           access. If not specified or non-existent, a self-signed
 852           certificate will be generated.</p>
 853 </dd>
 854 <dt><span class="term">PLC_WWW_SSL_KEY</span></dt>
 855 <dd>
 856 <p>
 857                   Type: file</p>
 858 <p>
 859                   Default: /etc/planetlab/www_ssl.key</p>
 860 <p>The corresponding SSL private key. If not
 861           specified or non-existent, one will be
 862           generated.</p>
 863 </dd>
 864 <dt><span class="term">PLC_BOOT_ENABLED</span></dt>
 865 <dd>
 866 <p>
 867                   Type: boolean</p>
 868 <p>
 869                   Default: true</p>
 870 <p>Enable the boot server on this
 871           machine.</p>
 872 </dd>
 873 <dt><span class="term">PLC_BOOT_HOST</span></dt>
 874 <dd>
 875 <p>
 876                   Type: hostname</p>
 877 <p>
 878                   Default: localhost.localdomain</p>
 879 <p>The fully qualified hostname of the boot
 880           server.</p>
 881 </dd>
 882 <dt><span class="term">PLC_BOOT_IP</span></dt>
 883 <dd>
 884 <p>
 885                   Type: ip</p>
 886 <p>
 887                   Default: 127.0.0.1</p>
 888 <p>The IP address of the boot server, if not
 889           resolvable by the configured DNS servers.</p>
 890 </dd>
 891 <dt><span class="term">PLC_BOOT_PORT</span></dt>
 892 <dd>
 893 <p>
 894                   Type: int</p>
 895 <p>
 896                   Default: 80</p>
 897 <p>The TCP port number through which the
 898           unprotected portions of the boot server should be
 899           accessed.</p>
 900 </dd>
 901 <dt><span class="term">PLC_BOOT_SSL_PORT</span></dt>
 902 <dd>
 903 <p>
 904                   Type: int</p>
 905 <p>
 906                   Default: 443</p>
 907 <p>The TCP port number through which the protected
 908           portions of the boot server should be
 909           accessed.</p>
 910 </dd>
 911 <dt><span class="term">PLC_BOOT_SSL_CRT</span></dt>
 912 <dd>
 913 <p>
 914                   Type: binary</p>
 915 <p>
 916                   Default: /etc/planetlab/boot_ssl.crt</p>
 917 <p>The signed SSL certificate to use for HTTPS
 918           access. If not specified, or non-existent a self-signed
 919           certificate will be generated.</p>
 920 </dd>
 921 <dt><span class="term">PLC_BOOT_SSL_KEY</span></dt>
 922 <dd>
 923 <p>
 924                   Type: binary</p>
 925 <p>
 926                   Default: /etc/planetlab/boot_ssl.key</p>
 927 <p>The corresponding SSL private key. If not
 928           specified or non-existent, one will be
 929           generated.</p>
 930 </dd>
 931 </dl></div>
 932 </div>
 933 <div class="bibliography">
 934 <div class="titlepage"><div><div><h2 class="title">
 935 <a name="id270747"></a>Bibliography</h2></div></div></div>
 936 <div class="biblioentry">
 937 <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
 938       Technical Contact's Guide</a></i>. </span></p>
 939 </div>
 940 </div>
 941 </div><?php require('footer.php'); ?>