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