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