doc/myplc.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
   4   <!ENTITY Variables SYSTEM "variables.xml">
   5 ]>
   6 <article>
   7   <articleinfo>
   8     <title>MyPLC User's Guide</title>
   9
  10     <author>
  11       <firstname>Mark Huang</firstname>
  12     </author>
  13
  14     <affiliation>
  15       <orgname>Princeton University</orgname>
  16     </affiliation>
  17
  18     <abstract>
  19       <para>This document describes the design, installation, and
  20       administration of MyPLC, a complete PlanetLab Central (PLC)
  21       portable installation contained within a
  22       <command>chroot</command> jail. This document assumes advanced
  23       knowledge of the PlanetLab architecture and Linux system
  24       administration.</para>
  25     </abstract>
  26
  27     <revhistory>
  28       <revision>
  29         <revnumber>1.0</revnumber>
  30
  31         <date>April 7, 2006</date>
  32
  33         <authorinitials>MLH</authorinitials>
  34
  35         <revdescription>
  36           <para>Initial draft.</para>
  37         </revdescription>
  38       </revision>
  39     </revhistory>
  40   </articleinfo>
  41
  42   <section>
  43     <title>Overview</title>
  44
  45     <para>MyPLC is a complete PlanetLab Central (PLC) portable
  46     installation contained within a <command>chroot</command>
  47     jail. The default installation consists of a web server, an
  48     XML-RPC API server, a boot server, and a database server: the core
  49     components of PLC. The installation is customized through an
  50     easy-to-use graphical interface. All PLC services are started up
  51     and shut down through a single script installed on the host
  52     system. The usually complex process of installing and
  53     administering the PlanetLab backend is reduced by containing PLC
  54     services within a virtual filesystem. By packaging it in such a
  55     manner, MyPLC may also be run on any modern Linux distribution,
  56     and could conceivably even run in a PlanetLab slice.</para>
  57
  58     <figure id="Architecture">
  59       <title>MyPLC architecture</title>
  60       <mediaobject>
  61         <imageobject>
  62           <imagedata fileref="architecture.eps" format="EPS" align="center" scale="50" />
  63         </imageobject>
  64         <imageobject>
  65           <imagedata fileref="architecture.png" format="PNG" align="center" scale="50" />
  66         </imageobject>
  67         <textobject>
  68           <phrase>MyPLC architecture</phrase>
  69         </textobject>
  70         <caption>
  71           <para>MyPLC should be viewed as a single application that
  72           provides multiple functions and can run on any host
  73           system.</para>
  74         </caption>
  75       </mediaobject>
  76     </figure>
  77   </section>
  78
  79   <section>
  80     <title>Installation</title>
  81
  82     <para>Though internally composed of commodity software
  83     subpackages, MyPLC should be treated as a monolithic software
  84     application. MyPLC is distributed as single RPM package that has
  85     no external dependencies, allowing it to be installed on
  86     practically any Linux 2.6 based distribution:</para>
  87
  88     <example>
  89       <title>Installing MyPLC.</title>
  90
  91         <programlisting><![CDATA[# 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]]></programlisting>
  97     </example>
  98
  99     <para>MyPLC installs the following files and directories:</para>
 100
 101     <itemizedlist>
 102
 103       <listitem><para><filename>/plc/root.img</filename>: The main
 104       root filesystem of the MyPLC application. This file is an
 105       uncompressed ext3 filesystem that is loopback mounted on
 106       <filename>/plc/root</filename> when MyPLC starts. The
 107       filesystem, even when mounted, should be treated an opaque
 108       binary that can and will be replaced in its entirety by any
 109       upgrade of MyPLC.</para></listitem>
 110
 111       <listitem><para><filename>/plc/root</filename>: The mount point
 112       for <filename>/plc/root.img</filename>. Once the root filesystem
 113       is mounted, all MyPLC services run in a
 114       <command>chroot</command> jail based in this
 115       directory.</para></listitem>
 116
 117       <listitem>
 118         <para><filename>/plc/data</filename>: The directory where user
 119         data and generated files are stored. This directory is bind
 120         mounted into the <command>chroot</command> jail on
 121         <filename>/data</filename>. Files in this directory are marked
 122         with <command>%config(noreplace)</command> in the RPM. That
 123         is, during an upgrade of MyPLC, if a file has not changed
 124         since the last installation or upgrade of MyPLC, it is subject
 125         to upgrade and replacement. If the file has chanegd, the new
 126         version of the file will be created with a
 127         <filename>.rpmnew</filename> extension. Symlinks within the
 128         MyPLC root filesystem ensure that the following directories
 129         (relative to <filename>/plc/root</filename>) are stored
 130         outside the MyPLC filesystem image:</para>
 131
 132         <itemizedlist>
 133           <listitem><para><filename>/etc/planetlab</filename>: This
 134           directory contains the configuration files, keys, and
 135           certificates that define your MyPLC
 136           installation.</para></listitem>
 137
 138           <listitem><para><filename>/var/lib/pgsql</filename>: This
 139           directory contains PostgreSQL database
 140           files.</para></listitem>
 141
 142           <listitem><para><filename>/var/www/html/alpina-logs</filename>: This
 143           directory contains node installation logs.</para></listitem>
 144
 145           <listitem><para><filename>/var/www/html/boot</filename>: This
 146           directory contains the Boot Manager, customized for your MyPLC
 147           installation, and its data files.</para></listitem>
 148
 149           <listitem><para><filename>/var/www/html/download</filename>: This
 150           directory contains Boot CD images, customized for your MyPLC
 151           installation.</para></listitem>
 152
 153           <listitem><para><filename>/var/www/html/install-rpms</filename>: This
 154           directory is where you should install node package updates,
 155           if any. By default, nodes are installed from the tarball
 156           located at
 157           <filename>/var/www/html/boot/PlanetLab-Bootstrap.tar.bz2</filename>,
 158           which is pre-built from the latest PlanetLab Central
 159           sources, and installed as part of your MyPLC
 160           installation. However, nodes will attempt to install any
 161           newer RPMs located in
 162           <filename>/var/www/html/install-rpms/planetlab</filename>,
 163           after initial installation and periodically thereafter. You
 164           must run <command>yum-arch</command> and
 165           <command>createrepo</command> to update the
 166           <command>yum</command> caches in this directory after
 167           installing a new RPM. PlanetLab Central cannot support any
 168           changes to this directory.</para></listitem>
 169
 170           <listitem><para><filename>/var/www/html/xml</filename>: This
 171           directory contains various XML files that the Slice Creation
 172           Service uses to determine the state of slices. These XML
 173           files are refreshed periodically by <command>cron</command>
 174           jobs running in the MyPLC root.</para></listitem>
 175         </itemizedlist>
 176       </listitem>
 177
 178       <listitem>
 179         <para><filename>/etc/init.d/plc</filename>: This file
 180         is a System V init script installed on your host filesystem,
 181         that allows you to start up and shut down MyPLC with a single
 182         command. On a Red Hat or Fedora host system, it is customary to
 183         use the <command>service</command> command to invoke System V
 184         init scripts:</para>
 185
 186         <example id="StartingAndStoppingMyPLC">
 187           <title>Starting and stopping MyPLC.</title>
 188
 189           <programlisting><![CDATA[# Starting MyPLC
 190 service plc start
 191
 192 # Stopping MyPLC
 193 service plc stop]]></programlisting>
 194         </example>
 195
 196         <para>Like all other registered System V init services, MyPLC is
 197         started and shut down automatically when your host system boots
 198         and powers off. You may disable automatic startup by invoking
 199         the <command>chkconfig</command> command on a Red Hat or Fedora
 200         host system:</para>
 201
 202         <example>
 203           <title>Disabling automatic startup of MyPLC.</title>
 204
 205           <programlisting><![CDATA[# Disable automatic startup
 206 chkconfig plc off
 207
 208 # Enable automatic startup
 209 chkconfig plc on]]></programlisting>
 210         </example>
 211       </listitem>
 212
 213       <listitem><para><filename>/etc/sysconfig/plc</filename>: This
 214       file is a shell script fragment that defines the variables
 215       <envar>PLC_ROOT</envar> and <envar>PLC_DATA</envar>. By default,
 216       the values of these variables are <filename>/plc/root</filename>
 217       and <filename>/plc/data</filename>, respectively. If you wish,
 218       you may move your MyPLC installation to another location on your
 219       host filesystem and edit the values of these variables
 220       appropriately, but you will break the RPM upgrade
 221       process. PlanetLab Central cannot support any changes to this
 222       file.</para></listitem>
 223
 224       <listitem><para><filename>/etc/planetlab</filename>: This
 225       symlink to <filename>/plc/data/etc/planetlab</filename> is
 226       installed on the host system for convenience.</para></listitem>
 227     </itemizedlist>
 228   </section>
 229
 230   <section>
 231     <title>Quickstart</title>
 232
 233     <para>Once installed, start MyPLC (see <xref
 234     linkend="StartingAndStoppingMyPLC" />). MyPLC must be started as
 235     root. Observe the output of this command for any failures. If no
 236     failures occur, you should see output similar to the
 237     following:</para>
 238
 239     <example>
 240       <title>A successful MyPLC startup.</title>
 241
 242       <programlisting><![CDATA[Mounting PLC:                                              [  OK  ]
 243 PLC: Generating network files:                             [  OK  ]
 244 PLC: Starting system logger:                               [  OK  ]
 245 PLC: Starting database server:                             [  OK  ]
 246 PLC: Generating SSL certificates:                          [  OK  ]
 247 PLC: Configuring the API:                                  [  OK  ]
 248 PLC: Updating GPG keys:                                    [  OK  ]
 249 PLC: Generating SSH keys:                                  [  OK  ]
 250 PLC: Starting web server:                                  [  OK  ]
 251 PLC: Bootstrapping the database:                           [  OK  ]
 252 PLC: Starting DNS server:                                  [  OK  ]
 253 PLC: Starting crond:                                       [  OK  ]
 254 PLC: Rebuilding Boot CD:                                   [  OK  ]
 255 PLC: Rebuilding Boot Manager:                              [  OK  ]
 256 PLC: Signing node packages:                                [  OK  ]
 257 ]]></programlisting>
 258     </example>
 259
 260     <para>If <filename>/plc/root</filename> is mounted successfully, a
 261     complete log file of the startup process may be found at
 262     <filename>/plc/root/var/log/boot.log</filename>. Possible reasons
 263     for failure of each step include:</para>
 264
 265     <itemizedlist>
 266       <listitem><para><literal>Mounting PLC</literal>: If this step
 267       fails, first ensure that you started MyPLC as root. Check
 268       <filename>/etc/sysconfig/plc</filename> to ensure that
 269       <envar>PLC_ROOT</envar> and <envar>PLC_DATA</envar> refer to the
 270       right locations. You may also have too many existing loopback
 271       mounts, or your kernel may not support loopback mounting, bind
 272       mounting, or the ext3 filesystem. Try freeing at least one
 273       loopback device, or re-compiling your kernel to support loopback
 274       mounting, bind mounting, and the ext3 filesystem. SELinux may
 275       also be enabled. If you install MyPLC on Fedora Core 4 or 5, use
 276       the <application>Security Level Configuration</application>
 277       utility to configure SELinux to be
 278       <literal>Permissive</literal>.</para></listitem>
 279
 280       <listitem><para><literal>Starting database server</literal>: If
 281       this step fails, check
 282       <filename>/plc/root/var/log/pgsql</filename> and
 283       <filename>/plc/root/var/log/boot.log</filename>. The most common
 284       reason for failure is that the default PostgreSQL port, TCP port
 285       5432, is already in use. Check that you are not running a
 286       PostgreSQL server on the host system.</para></listitem>
 287
 288       <listitem><para><literal>Starting web server</literal>: If this
 289       step fails, check
 290       <filename>/plc/root/var/log/httpd/error_log</filename> and
 291       <filename>/plc/root/var/log/boot.log</filename> for obvious
 292       errors. The most common reason for failure is that the default
 293       web ports, TCP ports 80 and 443, are already in use. Check that
 294       you are not running a web server on the host
 295       system.</para></listitem>
 296
 297       <listitem><para><literal>Bootstrapping the database</literal>:
 298       If this step fails, it is likely that the previous step
 299       (<literal>Starting web server</literal>) also failed. Another
 300       reason that it could fail is if <envar>PLC_API_HOST</envar> (see
 301       <xref linkend="ChangingTheConfiguration" />) does not resolve to
 302       the host on which the API server has been enabled. By default,
 303       all services, including the API server, are enabled and run on
 304       the same host, so check that <envar>PLC_API_HOST</envar> is
 305       either <filename>localhost</filename> or resolves to a local IP
 306       address.</para></listitem>
 307
 308       <listitem><para><literal>Starting crond</literal>: If this step
 309       fails, it is likely that the previous steps (<literal>Starting
 310       web server</literal> and <literal>Bootstrapping the
 311       database</literal>) also failed. If not, check
 312       <filename>/plc/root/var/log/boot.log</filename> for obvious
 313       errors. This step starts the <command>cron</command> service and
 314       generates the initial set of XML files that the Slice Creation
 315       Service uses to determine slice state.</para></listitem>
 316     </itemizedlist>
 317
 318     <para>If no failures occur, then MyPLC should be active with a
 319     default configuration. Open a web browser on the host system and
 320     visit <literal>http://localhost/</literal>, which should bring you
 321     to the front page of your PLC installation. The password of the
 322     default administrator account
 323     <literal>root@localhost.localdomain</literal> (set by
 324     <envar>PLC_ROOT_USER</envar>) is <literal>root</literal> (set by
 325     <envar>PLC_ROOT_PASSWORD</envar>).</para>
 326
 327     <section id="ChangingTheConfiguration">
 328       <title>Changing the configuration</title>
 329
 330       <para>After verifying that MyPLC is working correctly, shut it
 331       down and begin changing some of the default variable
 332       values. Shut down MyPLC with <command>service plc stop</command>
 333       (see <xref linkend="StartingAndStoppingMyPLC" />). With a text
 334       editor, open the file
 335       <filename>/etc/planetlab/plc_config.xml</filename>. This file is
 336       a self-documenting configuration file written in XML. Variables
 337       are divided into categories. Variable identifiers must be
 338       alphanumeric, plus underscore. A variable is referred to
 339       canonically as the uppercase concatenation of its category
 340       identifier, an underscore, and its variable identifier. Thus, a
 341       variable with an <literal>id</literal> of
 342       <literal>slice_prefix</literal> in the <literal>plc</literal>
 343       category is referred to canonically as
 344       <envar>PLC_SLICE_PREFIX</envar>.</para>
 345
 346       <para>The reason for this convention is that during MyPLC
 347       startup, <filename>plc_config.xml</filename> is translated into
 348       several different languages&mdash;shell, PHP, and
 349       Python&mdash;so that scripts written in each of these languages
 350       can refer to the same underlying configuration. Most MyPLC
 351       scripts are written in shell, so the convention for shell
 352       variables predominates.</para>
 353
 354       <para>The variables that you should change immediately are:</para>
 355
 356       <itemizedlist>
 357         <listitem><para><envar>PLC_NAME</envar>: Change this to the
 358         name of your PLC installation.</para></listitem>
 359         <listitem><para><envar>PLC_ROOT_PASSWORD</envar>: Change this
 360         to a more secure password.</para></listitem>
 361
 362         <listitem><para><envar>PLC_MAIL_SUPPORT_ADDRESS</envar>:
 363         Change this to the e-mail address at which you would like to
 364         receive support requests.</para></listitem>
 365
 366         <listitem><para><envar>PLC_DB_HOST</envar>,
 367         <envar>PLC_DB_IP</envar>, <envar>PLC_API_HOST</envar>,
 368         <envar>PLC_API_IP</envar>, <envar>PLC_WWW_HOST</envar>,
 369         <envar>PLC_WWW_IP</envar>, <envar>PLC_BOOT_HOST</envar>,
 370         <envar>PLC_BOOT_IP</envar>: Change all of these to the
 371         preferred FQDN and external IP address of your host
 372         system.</para></listitem>
 373       </itemizedlist>
 374
 375       <para>After changing these variables, save the file, then
 376       restart MyPLC with <command>service plc start</command>. You
 377       should notice that the password of the default administrator
 378       account is no longer <literal>root</literal>, and that the
 379       default site name includes the name of your PLC installation
 380       instead of PlanetLab.</para>
 381     </section>
 382
 383     <section>
 384       <title>Installing nodes</title>
 385
 386       <para>Install your first node by clicking <literal>Add
 387       Node</literal> under the <literal>Nodes</literal> tab. Fill in
 388       all the appropriate details, then click
 389       <literal>Add</literal>. Download the node's configuration file
 390       by clicking <literal>Download configuration file</literal> on
 391       the <emphasis role="bold">Node Details</emphasis> page for the
 392       node. Save it to a floppy disk or USB key as detailed in <xref
 393       linkend="TechsGuide" />.</para>
 394
 395       <para>Follow the rest of the instructions in <xref
 396       linkend="TechsGuide" /> for creating a Boot CD and installing
 397       the node, except download the Boot CD image from the
 398       <filename>/download</filename> directory of your PLC
 399       installation, not from PlanetLab Central. The images located
 400       here are customized for your installation. If you change the
 401       hostname of your boot server (<envar>PLC_BOOT_HOST</envar>), or
 402       if the SSL certificate of your boot server expires, MyPLC will
 403       regenerate it and rebuild the Boot CD with the new
 404       certificate. If this occurs, you must replace all Boot CDs
 405       created before the certificate was regenerated.</para>
 406
 407       <para>The installation process for a node has significantly
 408       improved since PlanetLab 3.3. It should now take only a few
 409       seconds for a new node to become ready to create slices.</para>
 410     </section>
 411
 412     <section>
 413       <title>Administering nodes</title>
 414
 415       <para>You may administer nodes as <literal>root</literal> by
 416       using the SSH key stored in
 417       <filename>/etc/planetlab/root_ssh_key.rsa</filename>.</para>
 418
 419       <example>
 420         <title>Accessing nodes via SSH. Replace
 421         <literal>node</literal> with the hostname of the node.</title>
 422
 423         <programlisting>ssh -i /etc/planetlab/root_ssh_key.rsa root@node</programlisting>
 424       </example>
 425
 426       <para>Besides the standard Linux log files located in
 427       <filename>/var/log</filename>, several other files can give you
 428       clues about any problems with active processes:</para>
 429
 430       <itemizedlist>
 431         <listitem><para><filename>/var/log/pl_nm</filename>: The log
 432         file for the Node Manager.</para></listitem>
 433
 434         <listitem><para><filename>/vservers/pl_conf/var/log/pl_conf</filename>:
 435         The log file for the Slice Creation Service.</para></listitem>
 436
 437         <listitem><para><filename>/var/log/propd</filename>: The log
 438         file for Proper, the service which allows certain slices to
 439         perform certain privileged operations in the root
 440         context.</para></listitem>
 441
 442         <listitem><para><filename>/vservers/pl_netflow/var/log/netflow.log</filename>:
 443         The log file for PlanetFlow, the network traffic auditing
 444         service.</para></listitem>
 445       </itemizedlist>
 446     </section>
 447
 448     <section>
 449       <title>Creating a slice</title>
 450
 451       <para>Create a slice by clicking <literal>Create Slice</literal>
 452       under the <literal>Slices</literal> tab. Fill in all the
 453       appropriate details, then click <literal>Create</literal>. Add
 454       nodes to the slice by clicking <literal>Manage Nodes</literal>
 455       on the <emphasis role="bold">Slice Details</emphasis> page for
 456       the slice.</para>
 457
 458       <para>A <command>cron</command> job runs every five minutes and
 459       updates the file
 460       <filename>/plc/data/var/www/html/xml/slices-0.5.xml</filename>
 461       with information about current slice state. The Slice Creation
 462       Service running on every node polls this file every ten minutes
 463       to determine if it needs to create or delete any slices. You may
 464       accelerate this process manually if desired.</para>
 465
 466       <example>
 467         <title>Forcing slice creation on a node.</title>
 468
 469         <programlisting><![CDATA[# Update slices.xml immediately
 470 service plc start crond
 471
 472 # Kick the Slice Creation Service on a particular node.
 473 ssh -i /etc/planetlab/root_ssh_key.rsa root@node \
 474 vserver pl_conf exec service pl_conf restart]]></programlisting>
 475       </example>
 476     </section>
 477   </section>
 478
 479   <appendix>
 480     <title>Configuration variables</title>
 481
 482     <para>Listed below is the set of standard configuration variables
 483     and their default values, defined in the template
 484     <filename>/etc/planetlab/default_config.xml</filename>. Additional
 485     variables and their defaults may be defined in site-specific XML
 486     templates that should be placed in
 487     <filename>/etc/planetlab/configs/</filename>.</para>
 488
 489     &Variables;
 490   </appendix>
 491
 492   <bibliography>
 493     <title>Bibliography</title>
 494
 495     <biblioentry id="TechsGuide">
 496       <author><firstname>Mark</firstname><surname>Huang</surname></author>
 497       <title><ulink
 498       url="http://www.planet-lab.org/doc/TechsGuide.php">PlanetLab
 499       Technical Contact's Guide</ulink></title>
 500     </biblioentry>
 501   </bibliography>
 502 </article>