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="#id268160">3.2. Installing nodes</a></span></dt>
  50 <dt><span class="section"><a href="#id268236">3.3. Administering nodes</a></span></dt>
  51 <dt><span class="section"><a href="#id268330">3.4. Creating a slice</a></span></dt>
  52 </dl></dd>
  53 <dt><span class="appendix"><a href="#id268404">A. Configuration variables</a></span></dt>
  54 <dt><span class="bibliography"><a href="#id270529">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 file.</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="id267786"></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 crond:                                       [  OK  ]
 227 PLC: Rebuilding Boot CD:                                   [  OK  ]
 228 PLC: Rebuilding Boot Manager:                              [  OK  ]
 229 </pre>
 230 </div>
 231 <p>If <code class="filename">/plc/root</code> is mounted successfully, a
 232     complete log file of the startup process may be found at
 233     <code class="filename">/plc/root/var/log/boot.log</code>. Possible reasons
 234     for failure of each step include:</p>
 235 <div class="itemizedlist"><ul type="disc">
 236 <li><p><code class="literal">Mounting PLC</code>: If this step
 237       fails, first ensure that you started MyPLC as root. Check
 238       <code class="filename">/etc/sysconfig/plc</code> to ensure that
 239       <code class="envar">PLC_ROOT</code> and <code class="envar">PLC_DATA</code> refer to the
 240       right locations. You may also have too many existing loopback
 241       mounts, or your kernel may not support loopback mounting, bind
 242       mounting, or the ext3 filesystem. Try freeing at least one
 243       loopback device, or re-compiling your kernel to support loopback
 244       mounting, bind mounting, and the ext3
 245       filesystem.</p></li>
 246 <li><p><code class="literal">Starting database server</code>: If
 247       this step fails, check
 248       <code class="filename">/plc/root/var/log/pgsql</code> and
 249       <code class="filename">/plc/root/var/log/boot.log</code>. The most common
 250       reason for failure is that the default PostgreSQL port, TCP port
 251       5432, is already in use. Check that you are not running a
 252       PostgreSQL server on the host system.</p></li>
 253 <li><p><code class="literal">Starting web server</code>: If this
 254       step fails, check
 255       <code class="filename">/plc/root/var/log/httpd/error_log</code> and
 256       <code class="filename">/plc/root/var/log/boot.log</code> for obvious
 257       errors. The most common reason for failure is that the default
 258       web ports, TCP ports 80 and 443, are already in use. Check that
 259       you are not running a web server on the host
 260       system.</p></li>
 261 <li><p><code class="literal">Bootstrapping the database</code>:
 262       If this step fails, it is likely that the previous step
 263       (<code class="literal">Starting web server</code>) also failed. Another
 264       reason that it could fail is if <code class="envar">PLC_API_HOST</code> (see
 265       <a href="#ChangingTheConfiguration" title="3.1. Changing the configuration">Section 3.1, “Changing the configuration”</a>) does not resolve to
 266       the host on which the API server has been enabled. By default,
 267       all services, including the API server, are enabled and run on
 268       the same host, so check that <code class="envar">PLC_API_HOST</code> is
 269       either <code class="filename">localhost</code> or resolves to a local IP
 270       address.</p></li>
 271 <li><p><code class="literal">Starting crond</code>: If this step
 272       fails, it is likely that the previous steps (<code class="literal">Starting
 273       web server</code> and <code class="literal">Bootstrapping the
 274       database</code>) also failed. If not, check
 275       <code class="filename">/plc/root/var/log/boot.log</code> for obvious
 276       errors. This step starts the <span><strong class="command">cron</strong></span> service and
 277       generates the initial set of XML files that the Slice Creation
 278       Service uses to determine slice state.</p></li>
 279 </ul></div>
 280 <p> Please also note that SELinux, when enabled, has been
 281     reported to prevent the system from operating smoothly. These
 282     reports were based on attempts made on FC4 and FC5. If you run any
 283     of those linux distributions, you should use the 'Security Level
 284     Configuration' utility and make sure SELinux is not configured as
 285     'Enforcing', but as 'Permissive' at most. </p>
 286 <p>If no failures occur, then MyPLC should be active with a
 287     default configuration. Open a web browser on the host system and
 288     visit <code class="literal">http://localhost/</code>, which should bring you
 289     to the front page of your PLC installation. The password of the
 290     default administrator account
 291     <code class="literal">root@localhost.localdomain</code> (set by
 292     <code class="envar">PLC_ROOT_USER</code>) is <code class="literal">root</code> (set by
 293     <code class="envar">PLC_ROOT_PASSWORD</code>).</p>
 294 <div class="section" lang="en">
 295 <div class="titlepage"><div><div><h3 class="title">
 296 <a name="ChangingTheConfiguration"></a>3.1. Changing the configuration</h3></div></div></div>
 297 <p>After verifying that MyPLC is working correctly, shut it
 298       down and begin changing some of the default variable
 299       values. Shut down MyPLC with <span><strong class="command">service plc stop</strong></span>
 300       (see <a href="#StartingAndStoppingMyPLC" title="Example 2. Starting and stopping MyPLC.">Example 2, “Starting and stopping MyPLC.”</a>). With a text
 301       editor, open the file
 302       <code class="filename">/etc/planetlab/plc_config.xml</code>. This file is
 303       a self-documenting configuration file written in XML. Variables
 304       are divided into categories. Variable identifiers must be
 305       alphanumeric, plus underscore. A variable is referred to
 306       canonically as the uppercase concatenation of its category
 307       identifier, an underscore, and its variable identifier. Thus, a
 308       variable with an <code class="literal">id</code> of
 309       <code class="literal">slice_prefix</code> in the <code class="literal">plc</code>
 310       category is referred to canonically as
 311       <code class="envar">PLC_SLICE_PREFIX</code>.</p>
 312 <p>The reason for this convention is that during MyPLC
 313       startup, <code class="filename">plc_config.xml</code> is translated into
 314       several different languages—shell, PHP, and
 315       Python—so that scripts written in each of these languages
 316       can refer to the same underlying configuration. Most MyPLC
 317       scripts are written in shell, so the convention for shell
 318       variables predominates.</p>
 319 <p>The variables that you should change immediately are:</p>
 320 <div class="itemizedlist"><ul type="disc">
 321 <li><p><code class="envar">PLC_NAME</code>: Change this to the
 322         name of your PLC installation.</p></li>
 323 <li><p><code class="envar">PLC_ROOT_PASSWORD</code>: Change this
 324         to a more secure password.</p></li>
 325 <li><p><code class="envar">PLC_NET_DNS1</code>,
 326         <code class="envar">PLC_NET_DNS2</code>: Change these to the IP addresses
 327         of your primary and secondary DNS servers. Check
 328         <code class="filename">/etc/resolv.conf</code> on your host
 329         filesystem.</p></li>
 330 <li><p><code class="envar">PLC_MAIL_SUPPORT_ADDRESS</code>:
 331         Change this to the e-mail address at which you would like to
 332         receive support requests.</p></li>
 333 <li><p><code class="envar">PLC_DB_HOST</code>,
 334         <code class="envar">PLC_API_HOST</code>, <code class="envar">PLC_WWW_HOST</code>,
 335         <code class="envar">PLC_BOOT_HOST</code>: Change all of these to the
 336         preferred FQDN of your host system.</p></li>
 337 </ul></div>
 338 <p>After changing these variables, save the file, then
 339       restart MyPLC with <span><strong class="command">service plc start</strong></span>. You
 340       should notice that the password of the default administrator
 341       account is no longer <code class="literal">root</code>, and that the
 342       default site name includes the name of your PLC installation
 343       instead of PlanetLab.</p>
 344 </div>
 345 <div class="section" lang="en">
 346 <div class="titlepage"><div><div><h3 class="title">
 347 <a name="id268160"></a>3.2. Installing nodes</h3></div></div></div>
 348 <p>Install your first node by clicking <code class="literal">Add
 349       Node</code> under the <code class="literal">Nodes</code> tab. Fill in
 350       all the appropriate details, then click
 351       <code class="literal">Add</code>. Download the node's configuration file
 352       by clicking <code class="literal">Download configuration file</code> on
 353       the <span class="bold"><strong>Node Details</strong></span> page for the
 354       node. Save it to a floppy disk or USB key as detailed in [<a href="#TechsGuide" title="[TechsGuide]">1</a>].</p>
 355 <p>Follow the rest of the instructions in [<a href="#TechsGuide" title="[TechsGuide]">1</a>] for creating a Boot CD and installing
 356       the node, except download the Boot CD image from the
 357       <code class="filename">/download</code> directory of your PLC
 358       installation, not from PlanetLab Central. The images located
 359       here are customized for your installation. If you change the
 360       hostname of your boot server (<code class="envar">PLC_BOOT_HOST</code>), or
 361       if the SSL certificate of your boot server expires, MyPLC will
 362       regenerate it and rebuild the Boot CD with the new
 363       certificate. If this occurs, you must replace all Boot CDs
 364       created before the certificate was regenerated.</p>
 365 <p>The installation process for a node has significantly
 366       improved since PlanetLab 3.3. It should now take only a few
 367       seconds for a new node to become ready to create slices.</p>
 368 </div>
 369 <div class="section" lang="en">
 370 <div class="titlepage"><div><div><h3 class="title">
 371 <a name="id268236"></a>3.3. Administering nodes</h3></div></div></div>
 372 <p>You may administer nodes as <code class="literal">root</code> by
 373       using the SSH key stored in
 374       <code class="filename">/etc/planetlab/root_ssh_key.rsa</code>.</p>
 375 <div class="example">
 376 <a name="id268257"></a><p class="title"><b>Example 5. Accessing nodes via SSH. Replace
 377         <code class="literal">node</code> with the hostname of the node.</b></p>
 378 <pre class="programlisting">ssh -i /etc/planetlab/root_ssh_key.rsa root@node</pre>
 379 </div>
 380 <p>Besides the standard Linux log files located in
 381       <code class="filename">/var/log</code>, several other files can give you
 382       clues about any problems with active processes:</p>
 383 <div class="itemizedlist"><ul type="disc">
 384 <li><p><code class="filename">/var/log/pl_nm</code>: The log
 385         file for the Node Manager.</p></li>
 386 <li><p><code class="filename">/vservers/pl_conf/var/log/pl_conf</code>:
 387         The log file for the Slice Creation Service.</p></li>
 388 <li><p><code class="filename">/var/log/propd</code>: The log
 389         file for Proper, the service which allows certain slices to
 390         perform certain privileged operations in the root
 391         context.</p></li>
 392 <li><p><code class="filename">/vservers/pl_netflow/var/log/netflow.log</code>:
 393         The log file for PlanetFlow, the network traffic auditing
 394         service.</p></li>
 395 </ul></div>
 396 </div>
 397 <div class="section" lang="en">
 398 <div class="titlepage"><div><div><h3 class="title">
 399 <a name="id268330"></a>3.4. Creating a slice</h3></div></div></div>
 400 <p>Create a slice by clicking <code class="literal">Create Slice</code>
 401       under the <code class="literal">Slices</code> tab. Fill in all the
 402       appropriate details, then click <code class="literal">Create</code>. Add
 403       nodes to the slice by clicking <code class="literal">Manage Nodes</code>
 404       on the <span class="bold"><strong>Slice Details</strong></span> page for
 405       the slice.</p>
 406 <p>A <span><strong class="command">cron</strong></span> job runs every five minutes and
 407       updates the file
 408       <code class="filename">/plc/data/var/www/html/xml/slices-0.5.xml</code>
 409       with information about current slice state. The Slice Creation
 410       Service running on every node polls this file every ten minutes
 411       to determine if it needs to create or delete any slices. You may
 412       accelerate this process manually if desired.</p>
 413 <div class="example">
 414 <a name="id268387"></a><p class="title"><b>Example 6. Forcing slice creation on a node.</b></p>
 415 <pre class="programlisting"># Update slices.xml immediately
 416 service plc start crond
 417
 418 # Kick the Slice Creation Service on a particular node.
 419 ssh -i /etc/planetlab/root_ssh_key.rsa root@node \
 420 vserver pl_conf exec service pl_conf restart</pre>
 421 </div>
 422 </div>
 423 </div>
 424 <div class="appendix" lang="en">
 425 <h2 class="title" style="clear: both">
 426 <a name="id268404"></a>A. Configuration variables</h2>
 427 <p>Listed below is the set of standard configuration variables
 428     and their default values, defined in the template
 429     <code class="filename">/etc/planetlab/default_config.xml</code>. Additional
 430     variables and their defaults may be defined in site-specific XML
 431     templates that should be placed in
 432     <code class="filename">/etc/planetlab/configs/</code>.</p>
 433 <div class="variablelist"><dl>
 434 <dt><span class="term">PLC_NAME</span></dt>
 435 <dd>
 436 <p>
 437                   Type: string</p>
 438 <p>
 439                   Default: PlanetLab Test</p>
 440 <p>The name of this PLC installation. It is used in
 441           the name of the default system site (e.g., PlanetLab Central)
 442           and in the names of various administrative entities (e.g.,
 443           PlanetLab Support).</p>
 444 </dd>
 445 <dt><span class="term">PLC_SLICE_PREFIX</span></dt>
 446 <dd>
 447 <p>
 448                   Type: string</p>
 449 <p>
 450                   Default: pl</p>
 451 <p>The abbreviated name of this PLC
 452           installation. It is used as the prefix for system slices
 453           (e.g., pl_conf). Warning: Currently, this variable should
 454           not be changed.</p>
 455 </dd>
 456 <dt><span class="term">PLC_ROOT_USER</span></dt>
 457 <dd>
 458 <p>
 459                   Type: email</p>
 460 <p>
 461                   Default: root@localhost.localdomain</p>
 462 <p>The name of the initial administrative
 463           account. We recommend that this account be used only to create
 464           additional accounts associated with real
 465           administrators, then disabled.</p>
 466 </dd>
 467 <dt><span class="term">PLC_ROOT_PASSWORD</span></dt>
 468 <dd>
 469 <p>
 470                   Type: password</p>
 471 <p>
 472                   Default: root</p>
 473 <p>The password of the initial administrative
 474           account. Also the password of the root account on the Boot
 475           CD.</p>
 476 </dd>
 477 <dt><span class="term">PLC_ROOT_SSH_KEY_PUB</span></dt>
 478 <dd>
 479 <p>
 480                   Type: file</p>
 481 <p>
 482                   Default: /etc/planetlab/root_ssh_key.pub</p>
 483 <p>The SSH public key used to access the root
 484           account on your nodes.</p>
 485 </dd>
 486 <dt><span class="term">PLC_ROOT_SSH_KEY</span></dt>
 487 <dd>
 488 <p>
 489                   Type: file</p>
 490 <p>
 491                   Default: /etc/planetlab/root_ssh_key.rsa</p>
 492 <p>The SSH private key used to access the root
 493           account on your nodes.</p>
 494 </dd>
 495 <dt><span class="term">PLC_DEBUG_SSH_KEY_PUB</span></dt>
 496 <dd>
 497 <p>
 498                   Type: file</p>
 499 <p>
 500                   Default: /etc/planetlab/debug_ssh_key.pub</p>
 501 <p>The SSH public key used to access the root
 502           account on your nodes when they are in Debug mode.</p>
 503 </dd>
 504 <dt><span class="term">PLC_DEBUG_SSH_KEY</span></dt>
 505 <dd>
 506 <p>
 507                   Type: file</p>
 508 <p>
 509                   Default: /etc/planetlab/debug_ssh_key.rsa</p>
 510 <p>The SSH private key used to access the root
 511           account on your nodes when they are in Debug mode.</p>
 512 </dd>
 513 <dt><span class="term">PLC_ROOT_GPG_KEY_PUB</span></dt>
 514 <dd>
 515 <p>
 516                   Type: file</p>
 517 <p>
 518                   Default: /etc/planetlab/pubring.gpg</p>
 519 <p>The GPG public keyring used to sign the Boot
 520           Manager and all node packages.</p>
 521 </dd>
 522 <dt><span class="term">PLC_ROOT_GPG_KEY</span></dt>
 523 <dd>
 524 <p>
 525                   Type: file</p>
 526 <p>
 527                   Default: /etc/planetlab/secring.gpg</p>
 528 <p>The SSH private key used to access the root
 529           account on your nodes.</p>
 530 </dd>
 531 <dt><span class="term">PLC_NET_DNS1</span></dt>
 532 <dd>
 533 <p>
 534                   Type: ip</p>
 535 <p>
 536                   Default: 128.112.136.10</p>
 537 <p>Primary DNS server address.</p>
 538 </dd>
 539 <dt><span class="term">PLC_NET_DNS2</span></dt>
 540 <dd>
 541 <p>
 542                   Type: ip</p>
 543 <p>
 544                   Default: 128.112.136.12</p>
 545 <p>Secondary DNS server address.</p>
 546 </dd>
 547 <dt><span class="term">PLC_MAIL_ENABLED</span></dt>
 548 <dd>
 549 <p>
 550                   Type: boolean</p>
 551 <p>
 552                   Default: false</p>
 553 <p>Set to false to suppress all e-mail notifications
 554           and warnings.</p>
 555 </dd>
 556 <dt><span class="term">PLC_MAIL_SUPPORT_ADDRESS</span></dt>
 557 <dd>
 558 <p>
 559                   Type: email</p>
 560 <p>
 561                   Default: root+support@localhost.localdomain</p>
 562 <p>This address is used for support
 563           requests. Support requests may include traffic complaints,
 564           security incident reporting, web site malfunctions, and
 565           general requests for information. We recommend that the
 566           address be aliased to a ticketing system such as Request
 567           Tracker.</p>
 568 </dd>
 569 <dt><span class="term">PLC_MAIL_BOOT_ADDRESS</span></dt>
 570 <dd>
 571 <p>
 572                   Type: email</p>
 573 <p>
 574                   Default: root+install-msgs@localhost.localdomain</p>
 575 <p>The API will notify this address when a problem
 576           occurs during node installation or boot.</p>
 577 </dd>
 578 <dt><span class="term">PLC_MAIL_SLICE_ADDRESS</span></dt>
 579 <dd>
 580 <p>
 581                   Type: email</p>
 582 <p>
 583                   Default: root+SLICE@localhost.localdomain</p>
 584 <p>This address template is used for sending
 585           e-mail notifications to slices. SLICE will be replaced with
 586           the name of the slice.</p>
 587 </dd>
 588 <dt><span class="term">PLC_DB_ENABLED</span></dt>
 589 <dd>
 590 <p>
 591                   Type: boolean</p>
 592 <p>
 593                   Default: true</p>
 594 <p>Enable the database server on this
 595           machine.</p>
 596 </dd>
 597 <dt><span class="term">PLC_DB_TYPE</span></dt>
 598 <dd>
 599 <p>
 600                   Type: string</p>
 601 <p>
 602                   Default: postgresql</p>
 603 <p>The type of database server. Currently, only
 604           postgresql is supported.</p>
 605 </dd>
 606 <dt><span class="term">PLC_DB_HOST</span></dt>
 607 <dd>
 608 <p>
 609                   Type: hostname</p>
 610 <p>
 611                   Default: localhost.localdomain</p>
 612 <p>The fully qualified hostname or IP address of
 613           the database server. This hostname must be resolvable and
 614           reachable by the rest of your installation.</p>
 615 </dd>
 616 <dt><span class="term">PLC_DB_PORT</span></dt>
 617 <dd>
 618 <p>
 619                   Type: int</p>
 620 <p>
 621                   Default: 5432</p>
 622 <p>The TCP port number through which the database
 623           server should be accessed.</p>
 624 </dd>
 625 <dt><span class="term">PLC_DB_NAME</span></dt>
 626 <dd>
 627 <p>
 628                   Type: string</p>
 629 <p>
 630                   Default: planetlab3</p>
 631 <p>The name of the database to access.</p>
 632 </dd>
 633 <dt><span class="term">PLC_DB_USER</span></dt>
 634 <dd>
 635 <p>
 636                   Type: string</p>
 637 <p>
 638                   Default: pgsqluser</p>
 639 <p>The username to use when accessing the
 640           database.</p>
 641 </dd>
 642 <dt><span class="term">PLC_DB_PASSWORD</span></dt>
 643 <dd>
 644 <p>
 645                   Type: password</p>
 646 <p>
 647                   Default: </p>
 648 <p>The password to use when accessing the
 649           database. If left blank, one will be
 650           generated.</p>
 651 </dd>
 652 <dt><span class="term">PLC_API_ENABLED</span></dt>
 653 <dd>
 654 <p>
 655                   Type: boolean</p>
 656 <p>
 657                   Default: true</p>
 658 <p>Enable the API server on this
 659           machine.</p>
 660 </dd>
 661 <dt><span class="term">PLC_API_DEBUG</span></dt>
 662 <dd>
 663 <p>
 664                   Type: boolean</p>
 665 <p>
 666                   Default: false</p>
 667 <p>Enable verbose API debugging. Do not enable on
 668           a production system!</p>
 669 </dd>
 670 <dt><span class="term">PLC_API_HOST</span></dt>
 671 <dd>
 672 <p>
 673                   Type: hostname</p>
 674 <p>
 675                   Default: localhost.localdomain</p>
 676 <p>The fully qualified hostname or IP address of
 677           the API server. This hostname must be resolvable and
 678           reachable by the rest of your installation, as well as your
 679           nodes.</p>
 680 </dd>
 681 <dt><span class="term">PLC_API_PORT</span></dt>
 682 <dd>
 683 <p>
 684                   Type: int</p>
 685 <p>
 686                   Default: 80</p>
 687 <p>The TCP port number through which the API
 688           should be accessed. Warning: SSL (port 443) access is not
 689           fully supported by the website code yet. We recommend that
 690           port 80 be used for now and that the API server either run
 691           on the same machine as the web server, or that they both be
 692           on a secure wired network.</p>
 693 </dd>
 694 <dt><span class="term">PLC_API_PATH</span></dt>
 695 <dd>
 696 <p>
 697                   Type: string</p>
 698 <p>
 699                   Default: /PLCAPI/</p>
 700 <p>The base path of the API URL.</p>
 701 </dd>
 702 <dt><span class="term">PLC_API_MAINTENANCE_USER</span></dt>
 703 <dd>
 704 <p>
 705                   Type: string</p>
 706 <p>
 707                   Default: maint@localhost.localdomain</p>
 708 <p>The username of the maintenance account. This
 709           account is used by local scripts that perform automated
 710           tasks, and cannot be used for normal logins.</p>
 711 </dd>
 712 <dt><span class="term">PLC_API_MAINTENANCE_PASSWORD</span></dt>
 713 <dd>
 714 <p>
 715                   Type: password</p>
 716 <p>
 717                   Default: </p>
 718 <p>The password of the maintenance account. If
 719           left blank, one will be generated. We recommend that the
 720           password be changed periodically.</p>
 721 </dd>
 722 <dt><span class="term">PLC_API_MAINTENANCE_SOURCES</span></dt>
 723 <dd>
 724 <p>
 725                   Type: hostname</p>
 726 <p>
 727                   Default: </p>
 728 <p>A space-separated list of IP addresses allowed
 729           to access the API through the maintenance account. The value
 730           of this variable is set automatically to allow only the API,
 731           web, and boot servers, and should not be
 732           changed.</p>
 733 </dd>
 734 <dt><span class="term">PLC_API_SSL_CRT</span></dt>
 735 <dd>
 736 <p>
 737                   Type: file</p>
 738 <p>
 739                   Default: /etc/planetlab/api_ssl.crt</p>
 740 <p>The signed SSL certificate to use for HTTPS
 741           access. If not specified or non-existent, a self-signed
 742           certificate will be generated.</p>
 743 </dd>
 744 <dt><span class="term">PLC_API_SSL_KEY</span></dt>
 745 <dd>
 746 <p>
 747                   Type: file</p>
 748 <p>
 749                   Default: /etc/planetlab/api_ssl.key</p>
 750 <p>The corresponding SSL private key used for
 751           signing the certificate, and for signing slice tickets. If
 752           not specified or non-existent, one will be
 753           generated.</p>
 754 </dd>
 755 <dt><span class="term">PLC_API_SSL_KEY_PUB</span></dt>
 756 <dd>
 757 <p>
 758                   Type: file</p>
 759 <p>
 760                   Default: /etc/planetlab/api_ssl.pub</p>
 761 <p>The corresponding SSL public key. If not
 762           specified or non-existent, one will be
 763           generated.</p>
 764 </dd>
 765 <dt><span class="term">PLC_WWW_ENABLED</span></dt>
 766 <dd>
 767 <p>
 768                   Type: boolean</p>
 769 <p>
 770                   Default: true</p>
 771 <p>Enable the web server on this
 772           machine.</p>
 773 </dd>
 774 <dt><span class="term">PLC_WWW_DEBUG</span></dt>
 775 <dd>
 776 <p>
 777                   Type: boolean</p>
 778 <p>
 779                   Default: false</p>
 780 <p>Enable debugging output on web pages. Do not
 781           enable on a production system!</p>
 782 </dd>
 783 <dt><span class="term">PLC_WWW_HOST</span></dt>
 784 <dd>
 785 <p>
 786                   Type: hostname</p>
 787 <p>
 788                   Default: localhost.localdomain</p>
 789 <p>The fully qualified hostname or IP address of
 790           the web server. This hostname must be resolvable and
 791           reachable by the rest of your installation, as well as your
 792           nodes.</p>
 793 </dd>
 794 <dt><span class="term">PLC_WWW_PORT</span></dt>
 795 <dd>
 796 <p>
 797                   Type: int</p>
 798 <p>
 799                   Default: 80</p>
 800 <p>The TCP port number through which the
 801           unprotected portions of the web site should be
 802           accessed.</p>
 803 </dd>
 804 <dt><span class="term">PLC_WWW_SSL_PORT</span></dt>
 805 <dd>
 806 <p>
 807                   Type: int</p>
 808 <p>
 809                   Default: 443</p>
 810 <p>The TCP port number through which the protected
 811           portions of the web site should be accessed.</p>
 812 </dd>
 813 <dt><span class="term">PLC_WWW_SSL_CRT</span></dt>
 814 <dd>
 815 <p>
 816                   Type: file</p>
 817 <p>
 818                   Default: /etc/planetlab/www_ssl.crt</p>
 819 <p>The signed SSL certificate to use for HTTPS
 820           access. If not specified or non-existent, a self-signed
 821           certificate will be generated.</p>
 822 </dd>
 823 <dt><span class="term">PLC_WWW_SSL_KEY</span></dt>
 824 <dd>
 825 <p>
 826                   Type: file</p>
 827 <p>
 828                   Default: /etc/planetlab/www_ssl.key</p>
 829 <p>The corresponding SSL private key. If not
 830           specified or non-existent, one will be
 831           generated.</p>
 832 </dd>
 833 <dt><span class="term">PLC_BOOT_ENABLED</span></dt>
 834 <dd>
 835 <p>
 836                   Type: boolean</p>
 837 <p>
 838                   Default: true</p>
 839 <p>Enable the boot server on this
 840           machine.</p>
 841 </dd>
 842 <dt><span class="term">PLC_BOOT_HOST</span></dt>
 843 <dd>
 844 <p>
 845                   Type: hostname</p>
 846 <p>
 847                   Default: localhost.localdomain</p>
 848 <p>The fully qualified hostname or IP address of
 849           the boot server. This hostname must be resolvable and
 850           reachable by the rest of your installation, as well as your
 851           nodes.</p>
 852 </dd>
 853 <dt><span class="term">PLC_BOOT_PORT</span></dt>
 854 <dd>
 855 <p>
 856                   Type: int</p>
 857 <p>
 858                   Default: 80</p>
 859 <p>The TCP port number through which the
 860           unprotected portions of the boot server should be
 861           accessed.</p>
 862 </dd>
 863 <dt><span class="term">PLC_BOOT_SSL_PORT</span></dt>
 864 <dd>
 865 <p>
 866                   Type: int</p>
 867 <p>
 868                   Default: 443</p>
 869 <p>The TCP port number through which the protected
 870           portions of the boot server should be
 871           accessed.</p>
 872 </dd>
 873 <dt><span class="term">PLC_BOOT_SSL_CRT</span></dt>
 874 <dd>
 875 <p>
 876                   Type: binary</p>
 877 <p>
 878                   Default: /etc/planetlab/boot_ssl.crt</p>
 879 <p>The signed SSL certificate to use for HTTPS
 880           access. If not specified, or non-existent a self-signed
 881           certificate will be generated.</p>
 882 </dd>
 883 <dt><span class="term">PLC_BOOT_SSL_KEY</span></dt>
 884 <dd>
 885 <p>
 886                   Type: binary</p>
 887 <p>
 888                   Default: /etc/planetlab/boot_ssl.key</p>
 889 <p>The corresponding SSL private key. If not
 890           specified or non-existent, one will be
 891           generated.</p>
 892 </dd>
 893 </dl></div>
 894 </div>
 895 <div class="bibliography">
 896 <div class="titlepage"><div><div><h2 class="title">
 897 <a name="id270529"></a>Bibliography</h2></div></div></div>
 898 <div class="biblioentry">
 899 <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
 900       Technical Contact's Guide</a></i>. </span></p>
 901 </div>
 902 </div>
 903 </div><?php require('footer.php'); ?>