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="id261154"></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="#id225264">1. Overview</a></span></dt>
  45 <dt><span class="section"><a href="#id225151">2. Installation</a></span></dt>
  46 <dt><span class="section"><a href="#id267561">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="#id268048">3.2. Installing nodes</a></span></dt>
  50 <dt><span class="section"><a href="#id268124">3.3. Administering nodes</a></span></dt>
  51 <dt><span class="section"><a href="#id268217">3.4. Creating a slice</a></span></dt>
  52 </dl></dd>
  53 <dt><span class="bibliography"><a href="#id268292">Bibliography</a></span></dt>
  54 </dl>
  55 </div>
  56 <div class="section" lang="en">
  57 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  58 <a name="id225264"></a>1. Overview</h2></div></div></div>
  59 <p>MyPLC is a complete PlanetLab Central (PLC) portable
  60     installation contained within a <span><strong class="command">chroot</strong></span>
  61     jail. The default installation consists of a web server, an
  62     XML-RPC API server, a boot server, and a database server: the core
  63     components of PLC. The installation is customized through an
  64     easy-to-use graphical interface. All PLC services are started up
  65     and shut down through a single script installed on the host
  66     system. The usually complex process of installing and
  67     administering the PlanetLab backend is reduced by containing PLC
  68     services within a virtual filesystem. By packaging it in such a
  69     manner, MyPLC may also be run on any modern Linux distribution,
  70     and could conceivably even run in a PlanetLab slice.</p>
  71 <div class="figure">
  72 <a name="Architecture"></a><p class="title"><b>Figure 1. MyPLC architecture</b></p>
  73 <div class="mediaobject" align="center">
  74 <img src="architecture.png" align="middle" width="270" alt="MyPLC architecture"><div class="caption"><p>MyPLC should be viewed as a single application that
  75           provides multiple functions and can run on any host
  76           system.</p></div>
  77 </div>
  78 </div>
  79 </div>
  80 <div class="section" lang="en">
  81 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  82 <a name="id225151"></a>2. Installation</h2></div></div></div>
  83 <p>Though internally composed of commodity software
  84     subpackages, MyPLC should be treated as a monolithic software
  85     application. MyPLC is distributed as single RPM package that has
  86     no external dependencies, allowing it to be installed on
  87     practically any Linux 2.6 based distribution:</p>
  88 <div class="example">
  89 <a name="id225162"></a><p class="title"><b>Example 1. Installing MyPLC.</b></p>
  90 <pre class="programlisting"># If your distribution supports RPM
  91 rpm -U myplc-0.3-1.planetlab.i386.rpm
  92
  93 # If your distribution does not support RPM
  94 cd /
  95 rpm2cpio myplc-0.3-1.planetlab.i386.rpm | cpio -diu</pre>
  96 </div>
  97 <p>MyPLC installs the following files and directories:</p>
  98 <div class="itemizedlist"><ul type="disc">
  99 <li><p><code class="filename">/plc/root.img</code>: The main
 100       root filesystem of the MyPLC application. This file is an
 101       uncompressed ext3 filesystem that is loopback mounted on
 102       <code class="filename">/plc/root</code> when MyPLC starts. The
 103       filesystem, even when mounted, should be treated an opaque
 104       binary that can and will be replaced in its entirety by any
 105       upgrade of MyPLC.</p></li>
 106 <li><p><code class="filename">/plc/root</code>: The mount point
 107       for <code class="filename">/plc/root.img</code>. Once the root filesystem
 108       is mounted, all MyPLC services run in a
 109       <span><strong class="command">chroot</strong></span> jail based in this
 110       directory.</p></li>
 111 <li>
 112 <p><code class="filename">/plc/data</code>: The directory where user
 113         data and generated files are stored. This directory is bind
 114         mounted into the <span><strong class="command">chroot</strong></span> jail on
 115         <code class="filename">/data</code>. Files in this directory are marked
 116         with <span><strong class="command">%config(noreplace)</strong></span> in the RPM. That
 117         is, during an upgrade of MyPLC, if a file has not changed
 118         since the last installation or upgrade of MyPLC, it is subject
 119         to upgrade and replacement. If the file has chanegd, the new
 120         version of the file will be created with a
 121         <code class="filename">.rpmnew</code> extension. Symlinks within the
 122         MyPLC root filesystem ensure that the following directories
 123         (relative to <code class="filename">/plc/root</code>) are stored
 124         outside the MyPLC filesystem image:</p>
 125 <div class="itemizedlist"><ul type="circle">
 126 <li><p><code class="filename">/etc/planetlab</code>: This
 127           directory contains the configuration files, keys, and
 128           certificates that define your MyPLC
 129           installation.</p></li>
 130 <li><p><code class="filename">/var/lib/pgsql</code>: This
 131           directory contains PostgreSQL database
 132           files.</p></li>
 133 <li><p><code class="filename">/var/www/html/alpina-logs</code>: This
 134           directory contains node installation logs.</p></li>
 135 <li><p><code class="filename">/var/www/html/boot</code>: This
 136           directory contains the Boot Manager, customized for your MyPLC
 137           installation, and its data files.</p></li>
 138 <li><p><code class="filename">/var/www/html/download</code>: This
 139           directory contains Boot CD images, customized for your MyPLC
 140           installation.</p></li>
 141 <li><p><code class="filename">/var/www/html/install-rpms</code>: This
 142           directory is where you should install node package updates,
 143           if any. By default, nodes are installed from the tarball
 144           located at
 145           <code class="filename">/var/www/html/boot/PlanetLab-Bootstrap.tar.bz2</code>,
 146           which is pre-built from the latest PlanetLab Central
 147           sources, and installed as part of your MyPLC
 148           installation. However, nodes will attempt to install any
 149           newer RPMs located in
 150           <code class="filename">/var/www/html/install-rpms/planetlab</code>,
 151           after initial installation and periodically thereafter. You
 152           must run <span><strong class="command">yum-arch</strong></span> and
 153           <span><strong class="command">createrepo</strong></span> to update the
 154           <span><strong class="command">yum</strong></span> caches in this directory after
 155           installing a new RPM. PlanetLab Central cannot support any
 156           changes to this file.</p></li>
 157 <li><p><code class="filename">/var/www/html/xml</code>: This
 158           directory contains various XML files that the Slice Creation
 159           Service uses to determine the state of slices. These XML
 160           files are refreshed periodically by <span><strong class="command">cron</strong></span>
 161           jobs running in the MyPLC root.</p></li>
 162 </ul></div>
 163 </li>
 164 <li>
 165 <p><code class="filename">/etc/init.d/plc</code>: This file
 166         is a System V init script installed on your host filesystem,
 167         that allows you to start up and shut down MyPLC with a single
 168         command. On a Red Hat or Fedora host system, it is customary to
 169         use the <span><strong class="command">service</strong></span> command to invoke System V
 170         init scripts:</p>
 171 <div class="example">
 172 <a name="StartingAndStoppingMyPLC"></a><p class="title"><b>Example 2. Starting and stopping MyPLC.</b></p>
 173 <pre class="programlisting"># Starting MyPLC
 174 service plc start
 175
 176 # Stopping MyPLC
 177 service plc stop</pre>
 178 </div>
 179 <p>Like all other registered System V init services, MyPLC is
 180         started and shut down automatically when your host system boots
 181         and powers off. You may disable automatic startup by invoking
 182         the <span><strong class="command">chkconfig</strong></span> command on a Red Hat or Fedora
 183         host system:</p>
 184 <div class="example">
 185 <a name="id243437"></a><p class="title"><b>Example 3. Disabling automatic startup of MyPLC.</b></p>
 186 <pre class="programlisting"># Disable automatic startup
 187 chkconfig plc off
 188
 189 # Enable automatic startup
 190 chkconfig plc on</pre>
 191 </div>
 192 </li>
 193 <li><p><code class="filename">/etc/sysconfig/plc</code>: This
 194       file is a shell script fragment that defines the variables
 195       <code class="envar">PLC_ROOT</code> and <code class="envar">PLC_DATA</code>. By default,
 196       the values of these variables are <code class="filename">/plc/root</code>
 197       and <code class="filename">/plc/data</code>, respectively. If you wish,
 198       you may move your MyPLC installation to another location on your
 199       host filesystem and edit the values of these variables
 200       appropriately, but you will break the RPM upgrade
 201       process. PlanetLab Central cannot support any changes to this
 202       file.</p></li>
 203 <li><p><code class="filename">/etc/planetlab</code>: This
 204       symlink to <code class="filename">/plc/data/etc/planetlab</code> is
 205       installed on the host system for convenience.</p></li>
 206 </ul></div>
 207 </div>
 208 <div class="section" lang="en">
 209 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 210 <a name="id267561"></a>3. Quickstart</h2></div></div></div>
 211 <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
 212     root. Observe the output of this command for any failures. If no
 213     failures occur, you should see output similar to the
 214     following:</p>
 215 <div class="example">
 216 <a name="id267681"></a><p class="title"><b>Example 4. A successful MyPLC startup.</b></p>
 217 <pre class="programlisting">Mounting PLC:                                              [  OK  ]
 218 PLC: Generating network files:                             [  OK  ]
 219 PLC: Starting system logger:                               [  OK  ]
 220 PLC: Starting database server:                             [  OK  ]
 221 PLC: Generating SSL certificates:                          [  OK  ]
 222 PLC: Generating SSH keys:                                  [  OK  ]
 223 PLC: Starting web server:                                  [  OK  ]
 224 PLC: Bootstrapping the database:                           [  OK  ]
 225 PLC: Starting crond:                                       [  OK  ]
 226 PLC: Rebuilding Boot CD:                                   [  OK  ]
 227 PLC: Rebuilding Boot Manager:                              [  OK  ]
 228 </pre>
 229 </div>
 230 <p>If <code class="filename">/plc/root</code> is mounted successfully, a
 231     complete log file of the startup process may be found at
 232     <code class="filename">/plc/root/var/log/boot.log</code>. Possible reasons
 233     for failure of each step include:</p>
 234 <div class="itemizedlist"><ul type="disc">
 235 <li><p><code class="literal">Mounting PLC</code>: If this step
 236       fails, first ensure that you started MyPLC as root. Check
 237       <code class="filename">/etc/sysconfig/plc</code> to ensure that
 238       <code class="envar">PLC_ROOT</code> and <code class="envar">PLC_DATA</code> refer to the
 239       right locations. You may also have too many existing loopback
 240       mounts, or your kernel may not support loopback mounting, bind
 241       mounting, or the ext3 filesystem. Try freeing at least one
 242       loopback device, or re-compiling your kernel to support loopback
 243       mounting, bind mounting, and the ext3
 244       filesystem.</p></li>
 245 <li><p><code class="literal">Starting database server</code>: If
 246       this step fails, check
 247       <code class="filename">/plc/root/var/log/pgsql</code> and
 248       <code class="filename">/plc/root/var/log/boot.log</code>. The most common
 249       reason for failure is that the default PostgreSQL port, TCP port
 250       5432, is already in use. Check that you are not running a
 251       PostgreSQL server on the host system.</p></li>
 252 <li><p><code class="literal">Starting web server</code>: If this
 253       step fails, check
 254       <code class="filename">/plc/root/var/log/httpd/error_log</code> and
 255       <code class="filename">/plc/root/var/log/boot.log</code> for obvious
 256       errors. The most common reason for failure is that the default
 257       web ports, TCP ports 80 and 443, are already in use. Check that
 258       you are not running a web server on the host
 259       system.</p></li>
 260 <li><p><code class="literal">Bootstrapping the database</code>:
 261       If this step fails, it is likely that the previous step
 262       (<code class="literal">Starting web server</code>) also failed. Another
 263       reason that it could fail is if <code class="envar">PLC_API_HOST</code> (see
 264       <a href="#ChangingTheConfiguration" title="3.1. Changing the configuration">Section 3.1, “Changing the configuration”</a>) does not resolve to
 265       the host on which the API server has been enabled. By default,
 266       all services, including the API server, are enabled and run on
 267       the same host, so check that <code class="envar">PLC_API_HOST</code> is
 268       either <code class="filename">localhost</code> or resolves to a local IP
 269       address.</p></li>
 270 <li><p><code class="literal">Starting crond</code>: If this step
 271       fails, it is likely that the previous steps (<code class="literal">Starting
 272       web server</code> and <code class="literal">Bootstrapping the
 273       database</code>) also failed. If not, check
 274       <code class="filename">/plc/root/var/log/boot.log</code> for obvious
 275       errors. This step starts the <span><strong class="command">cron</strong></span> service and
 276       generates the initial set of XML files that the Slice Creation
 277       Service uses to determine slice state.</p></li>
 278 </ul></div>
 279 <p>If no failures occur, then MyPLC should be active with a
 280     default configuration. Open a web browser on the host system and
 281     visit <code class="literal">http://localhost/</code>, which should bring you
 282     to the front page of your PLC installation. The password of the
 283     default administrator account
 284     <code class="literal">root@test.planet-lab.org</code> (set by
 285     <code class="envar">PLC_ROOT_USER</code>) is <code class="literal">root</code> (set by
 286     <code class="envar">PLC_ROOT_PASSWORD</code>).</p>
 287 <div class="section" lang="en">
 288 <div class="titlepage"><div><div><h3 class="title">
 289 <a name="ChangingTheConfiguration"></a>3.1. Changing the configuration</h3></div></div></div>
 290 <p>After verifying that MyPLC is working correctly, shut it
 291       down and begin changing some of the default variable
 292       values. Shut down MyPLC with <span><strong class="command">service plc stop</strong></span>
 293       (see <a href="#StartingAndStoppingMyPLC" title="Example 2. Starting and stopping MyPLC.">Example 2, “Starting and stopping MyPLC.”</a>). With a text
 294       editor, open the file
 295       <code class="filename">/etc/planetlab/plc_config.xml</code>. This file is
 296       a self-documenting configuration file written in XML. Variables
 297       are divided into categories. Variable identifiers must be
 298       alphanumeric, plus underscore. A variable is referred to
 299       canonically as the uppercase concatenation of its category
 300       identifier, an underscore, and its variable identifier. Thus, a
 301       variable with an <code class="literal">id</code> of
 302       <code class="literal">slice_prefix</code> in the <code class="literal">plc</code>
 303       category is referred to canonically as
 304       <code class="envar">PLC_SLICE_PREFIX</code>.</p>
 305 <p>The reason for this convention is that during MyPLC
 306       startup, <code class="filename">plc_config.xml</code> is translated into
 307       several different languages—shell, PHP, and
 308       Python—so that scripts written in each of these languages
 309       can refer to the same underlying configuration. Most MyPLC
 310       scripts are written in shell, so the convention for shell
 311       variables predominates.</p>
 312 <p>The variables that you should change immediately are:</p>
 313 <div class="itemizedlist"><ul type="disc">
 314 <li><p><code class="envar">PLC_NAME</code>: Change this to the
 315         name of your PLC installation.</p></li>
 316 <li><p><code class="envar">PLC_ROOT_PASSWORD</code>: Change this
 317         to a more secure password.</p></li>
 318 <li><p><code class="envar">PLC_NET_DNS1</code>,
 319         <code class="envar">PLC_NET_DNS2</code>: Change these to the IP addresses
 320         of your primary and secondary DNS servers. Check
 321         <code class="filename">/etc/resolv.conf</code> on your host
 322         filesystem.</p></li>
 323 <li><p><code class="envar">PLC_MAIL_SUPPORT_ADDRESS</code>:
 324         Change this to the e-mail address at which you would like to
 325         receive support requests.</p></li>
 326 <li><p><code class="envar">PLC_DB_HOST</code>,
 327         <code class="envar">PLC_API_HOST</code>, <code class="envar">PLC_WWW_HOST</code>,
 328         <code class="envar">PLC_BOOT_HOST</code>: Change all of these to the
 329         preferred FQDN of your host system.</p></li>
 330 </ul></div>
 331 <p>After changing these variables, save the file, then
 332       restart MyPLC with <span><strong class="command">service plc start</strong></span>. You
 333       should notice that the password of the default administrator
 334       account is no longer <code class="literal">root</code>, and that the
 335       default site name includes the name of your PLC installation
 336       instead of PlanetLab.</p>
 337 </div>
 338 <div class="section" lang="en">
 339 <div class="titlepage"><div><div><h3 class="title">
 340 <a name="id268048"></a>3.2. Installing nodes</h3></div></div></div>
 341 <p>Install your first node by clicking <code class="literal">Add
 342       Node</code> under the <code class="literal">Nodes</code> tab. Fill in
 343       all the appropriate details, then click
 344       <code class="literal">Add</code>. Download the node's configuration file
 345       by clicking <code class="literal">Download configuration file</code> on
 346       the <span class="bold"><strong>Node Details</strong></span> page for the
 347       node. Save it to a floppy disk or USB key as detailed in [<a href="#TechsGuide" title="[TechsGuide]">1</a>].</p>
 348 <p>Follow the rest of the instructions in [<a href="#TechsGuide" title="[TechsGuide]">1</a>] for creating a Boot CD and installing
 349       the node, except download the Boot CD image from the
 350       <code class="filename">/download</code> directory of your PLC
 351       installation, not from PlanetLab Central. The images located
 352       here are customized for your installation. If you change the
 353       hostname of your boot server (<code class="envar">PLC_BOOT_HOST</code>), or
 354       if the SSL certificate of your boot server expires, MyPLC will
 355       regenerate it and rebuild the Boot CD with the new
 356       certificate. If this occurs, you must replace all Boot CDs
 357       created before the certificate was regenerated.</p>
 358 <p>The installation process for a node has significantly
 359       improved since PlanetLab 3.3. It should now take only a few
 360       seconds for a new node to become ready to create slices.</p>
 361 </div>
 362 <div class="section" lang="en">
 363 <div class="titlepage"><div><div><h3 class="title">
 364 <a name="id268124"></a>3.3. Administering nodes</h3></div></div></div>
 365 <p>You may administer nodes as <code class="literal">root</code> by
 366       using the SSH key stored in
 367       <code class="filename">/etc/planetlab/root_ssh_key.rsa</code>.</p>
 368 <div class="example">
 369 <a name="id268145"></a><p class="title"><b>Example 5. Accessing nodes via SSH. Replace
 370         <code class="literal">node</code> with the hostname of the node.</b></p>
 371 <pre class="programlisting">ssh -i /etc/planetlab/root_ssh_key.rsa root@node</pre>
 372 </div>
 373 <p>Besides the standard Linux log files located in
 374       <code class="filename">/var/log</code>, several other files can give you
 375       clues about any problems with active processes:</p>
 376 <div class="itemizedlist"><ul type="disc">
 377 <li><p><code class="filename">/var/log/pl_nm</code>: The log
 378         file for the Node Manager.</p></li>
 379 <li><p><code class="filename">/vservers/pl_conf/var/log/pl_conf</code>:
 380         The log file for the Slice Creation Service.</p></li>
 381 <li><p><code class="filename">/var/log/propd</code>: The log
 382         file for Proper, the service which allows certain slices to
 383         perform certain privileged operations in the root
 384         context.</p></li>
 385 <li><p><code class="filename">/vserver/pl_netflow/var/log/netflow.log</code>:
 386         The log file for PlanetFlow, the network traffic auditing
 387         service.</p></li>
 388 </ul></div>
 389 </div>
 390 <div class="section" lang="en">
 391 <div class="titlepage"><div><div><h3 class="title">
 392 <a name="id268217"></a>3.4. Creating a slice</h3></div></div></div>
 393 <p>Create a slice by clicking <code class="literal">Create Slice</code>
 394       under the <code class="literal">Slices</code> tab. Fill in all the
 395       appropriate details, then click <code class="literal">Create</code>. Add
 396       nodes to the slice by clicking <code class="literal">Manage Nodes</code>
 397       on the <span class="bold"><strong>Slice Details</strong></span> page for
 398       the slice.</p>
 399 <p>A <span><strong class="command">cron</strong></span> job runs every five minutes and
 400       updates the file
 401       <code class="filename">/plc/data/var/www/html/xml/slices-0.5.xml</code>
 402       with information about current slice state. The Slice Creation
 403       Service running on every node polls this file every ten minutes
 404       to determine if it needs to create or delete any slices. You may
 405       accelerate this process manually if desired.</p>
 406 <div class="example">
 407 <a name="id268275"></a><p class="title"><b>Example 6. Forcing slice creation on a node.</b></p>
 408 <pre class="programlisting"># Update slices.xml immediately
 409 service plc start crond
 410
 411 # Kick the Slice Creation Service on a particular node.
 412 ssh -i /etc/planetlab/root_ssh_key.rsa root@node \
 413 vserver pl_conf exec service pl_conf restart</pre>
 414 </div>
 415 </div>
 416 </div>
 417 <div class="bibliography">
 418 <div class="titlepage"><div><div><h2 class="title">
 419 <a name="id268292"></a>Bibliography</h2></div></div></div>
 420 <div class="biblioentry">
 421 <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
 422       Technical Contact's Guide</a></i>. </span></p>
 423 </div>
 424 </div>
 425 </div><?php require('footer.php'); ?>