doc/myplc.xml.in

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3 "@DOCBOOK-43@" [
   4   <!ENTITY Variables SYSTEM "plc_variables.xml">
   5 ]>
   6 <article>
   7   <articleinfo>
   8     <title>MyPLC User's Guide</title>
   9
  10     <authorgroup>
  11     <author> <firstname>Mark  </firstname> <surname>Huang</surname> </author>
  12     <author> <firstname>Thierry </firstname> <surname>Parmentelat</surname> </author>
  13     </authorgroup>
  14
  15     <affiliation>
  16       <orgname>Princeton University</orgname>
  17     </affiliation>
  18
  19     <abstract>
  20       <para>This document describes the design, installation, and
  21       administration of MyPLC, a complete PlanetLab Central (PLC)
  22       portable installation. 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         <date>April 7, 2006</date>
  31         <authorinitials>MLH</authorinitials>
  32         <revdescription><para>Initial draft.</para></revdescription>
  33       </revision>
  34       <revision>
  35         <revnumber>1.1</revnumber>
  36         <date>July 19, 2006</date>
  37         <authorinitials>MLH</authorinitials>
  38         <revdescription><para>Add development environment.</para></revdescription>
  39       </revision>
  40       <revision>
  41         <revnumber>1.2</revnumber>
  42         <date>August 18, 2006</date>
  43         <authorinitials>TPT</authorinitials>
  44         <revdescription>
  45         <para>Review section on configuration and introduce <command>plc-config-tty</command>.</para>
  46         <para>Present implementation details last.</para>
  47         </revdescription>
  48       </revision>
  49       <revision>
  50         <revnumber>1.3</revnumber>
  51         <date>May 9, 2008</date>
  52         <authorinitials>TPT</authorinitials>
  53         <revdescription>
  54           <para>
  55             Review for 4.2 : focus on new packaging <emphasis>myplc-native</emphasis>.
  56           </para>
  57           <para>
  58             Removed deprecated <emphasis>myplc-devel</emphasis>.
  59           </para>
  60         </revdescription>
  61       </revision>
  62     </revhistory>
  63   </articleinfo>
  64
  65   <section>
  66     <title>Overview</title>
  67
  68     <para>MyPLC is a complete PlanetLab Central (PLC) portable
  69     installation. The default installation consists of a web server, an
  70     XML-RPC API server, a boot server, and a database server: the core
  71     components of PLC. The installation is customized through an
  72     easy-to-use graphical interface. All PLC services are started up
  73     and shut down through a single script installed on the host
  74     system.</para>
  75
  76     <figure id="Architecture">
  77       <title>MyPLC architecture</title>
  78       <mediaobject>
  79         <imageobject>
  80           <imagedata fileref="architecture.eps" format="EPS" align="center" scale="50" />
  81         </imageobject>
  82         <imageobject>
  83           <imagedata fileref="architecture.png" format="PNG" align="center" scale="50" />
  84         </imageobject>
  85         <textobject>
  86           <phrase>MyPLC architecture</phrase>
  87         </textobject>
  88       </mediaobject>
  89     </figure>
  90   </section>
  91
  92
  93   <section> <title> Historical Notes</title>
  94
  95     <para> This document focuses on the new packaging named
  96     <emphasis>myplc-native</emphasis> as introduced in the 4.2 release
  97     of PlanetLab. </para>
  98
  99     <para> The former, chroot-based, packaging known as simply
 100     <emphasis>myplc</emphasis> might still be present in this release
 101     but its usage is not recommended anymore. </para>
 102
 103     <para> With 4.2, the general architecture of the build system has
 104     drastically changed as well. Rather than providing a static chroot
 105     image for building the software, that was formerly known as
 106     <emphasis>myplc-devel</emphasis>, the current paradigm is to
 107     create a fresh vserver and to rely on yum to install all needed
 108     development tools. More details on how to set up such an
 109     environment can be found at <ulink
 110     url="http://svn.planet-lab.org/wiki/VserverCentos" /> that
 111     describes how to turn a CentOS5 box into a vserver-capable host
 112     system.
 113     </para>
 114
 115   </section>
 116
 117   <section id="Requirements"> <title> Requirements </title>
 118
 119   <para> The recommended way to deploy MyPLC relies on
 120   <emphasis>vserver</emphasis>. Here again, please refer to <ulink
 121   url="http://svn.planet-lab.org/wiki/VserverCentos" /> for how to set
 122   up such en environment. As of PlanetLab 4.2, the recommended Linux
 123   distribution here is CentOS5, because there are publicly available
 124   resources that allow a smooth setup. </para>
 125
 126   <para> As of PlanetLab 4.2, the current focus is on Fedora 8. This
 127   means that you should create a fresh Fedora 8 vserver in your
 128   vserver-capable CentOS box, and perform all subsequent installations
 129   from that place as described below. Although you might find builds
 130   for other Linux distributions, it is recommended for new users to
 131   use this particular variant.
 132   </para>
 133
 134   <para> It is also possible to perform these installations from a
 135   fresh Fedora 8 installation. However, having a vserver-capable box
 136   instead provides much more flexibility and is thus recommended, in
 137   particular in terms of future upgrades of the system. </para>
 138
 139   <para> In addition, there have been numerous reports that SELINUX
 140   should be turned off for running myplc in former releases. This is
 141   part of the instructions provided to set up vserver, and please
 142   keep this in mind if you plan on running MyPLC in a dedicated Fedora
 143   8 box.</para>
 144
 145   <para> Last, you need to check your firewall configuration(s) since
 146   it is required, of course, to open up the <emphasis>http</emphasis>
 147   and <emphasis>https</emphasis> ports, so as to accept connections
 148   from the managed nodes and from the users desktops, and possibly
 149   <emphasis>ssh</emphasis> as well. </para>
 150
 151   </section>
 152
 153   <section id="Installation">
 154     <title>Installing and using MyPLC</title>
 155
 156     <section>
 157       <title>Locating a build.</title>
 158       <para>The following locations are entry points for locating the
 159       build you plan on using.</para>
 160       <itemizedlist>
 161         <listitem> <para> <ulink url="http://build.planet-lab.org/" />
 162         is maintained by the PlanetLab team at Princeton
 163         University. </para>
 164         </listitem>
 165         <listitem> <para> <ulink url="http://build.one-lab.org/" /> is
 166         maintained by the OneLab team at INRIA. </para>
 167         </listitem>
 168       </itemizedlist>
 169       <para> There are currently two so-called PlanetLab
 170       Distributions known as <emphasis>planetlab</emphasis> and
 171       <emphasis>onelab</emphasis>. planet-lab.org generally builds
 172       only the <emphasis>planetlab</emphasis> flavour, while both
 173       flavours are generally available at one-lab.org.</para>
 174     </section>
 175
 176     <section>
 177       <title> Note on IP addressing</title>
 178       <para> Once you've located the build you want to use, it is
 179       strongly advised to assign this vserver a unique IP address, and
 180       to avoid sharing the hosting box's one. To that end, the typical
 181       sentence for creating such a vserver would be:</para>
 182
 183       <example><title>Creating the vserver</title>
 184       <programlisting><![CDATA[# vtest-init-vserver.sh -p linux32 myvserver \
 185       http://build.one-lab.org/4.2/planetlab-4.2-rc2.1lab-f8-32/RPMS \
 186       -- --netdev eth0 --interface 138.96.250.134 --hostname myvserver.inria.fr]]>
 187       </programlisting> </example>
 188
 189       <para>
 190         In this example, we have chosen to use a planetlab flavour,
 191         based on rc2.1lab, for i386 (this is what the final 32 stands
 192         for).
 193       </para>
 194
 195     </section>
 196
 197     <section>
 198       <title>Setting up yum </title>
 199
 200       <para> If you do not use the convenience script mentioned above, you need to
 201       create an entry in your yum configuration:</para>
 202
 203       <example><title>Setting up yum repository </title>
 204       <programlisting>
 205         <![CDATA[[myvserver] # cd /etc/yum.repos.d
 206 [myvserver] # cat > myplc.repo
 207 [myplc]
 208 name= MyPLC
 209 baseurl=http://build.one-lab.org/4.2/planetlab-4.2-rc2.1lab-f8-32/RPMS
 210 enabled=1
 211 gpgcheck=0
 212 ^D
 213 [myvserver] #]]>
 214       </programlisting>
 215       </example>
 216
 217     </section>
 218
 219     <section>
 220       <title>Installing MyPLC.</title>
 221
 222       <para>
 223         To actually install myplc at that stage, just run:
 224       </para>
 225
 226       <example><title>Installing MyPLC </title>
 227       <programlisting><![CDATA[[myvserver] # yum -y install myplc-native]]>
 228       </programlisting>
 229       </example>
 230
 231       <para> The <xref linkend="FilesInvolvedRuntime" /> below explains in
 232       details the installation strategy and the miscellaneous files and
 233       directories involved.</para>
 234
 235     </section>
 236
 237     <section id="QuickStart"> <title> QuickStart </title>
 238
 239     <para> On a Red Hat or Fedora host system, it is customary to use
 240     the <command>service</command> command to invoke System V init
 241     scripts. As the examples suggest, the service must be started as root:</para>
 242
 243     <example><title>Starting MyPLC:</title>
 244           <programlisting><![CDATA[[myvserver] # service plc start]]></programlisting>
 245     </example>
 246     <example><title>Stopping MyPLC:</title>
 247           <programlisting><![CDATA[[myvserver] # service plc stop]]></programlisting>
 248     </example>
 249
 250     <para> In <xref linkend="StartupSequence" />, we provide greater
 251     details that might be helpful in the case where the service does
 252     not seem to take off correctly.</para>
 253
 254     <para>Like all other registered System V init services, MyPLC is
 255     started and shut down automatically when your host system boots
 256     and powers off. You may disable automatic startup by invoking the
 257     <command>chkconfig</command> command on a Red Hat or Fedora host
 258     system:</para>
 259
 260     <example> <title>Disabling automatic startup of MyPLC.</title>
 261     <programlisting><![CDATA[# chkconfig plc off]]></programlisting></example>
 262     <example> <title>Re-enabling automatic startup of MyPLC.</title>
 263     <programlisting><![CDATA[# chkconfig plc on]]></programlisting></example>
 264
 265     </section>
 266
 267     <section id="Configuration">
 268       <title>Changing the configuration</title>
 269
 270       <para>After verifying that MyPLC is working correctly, shut it
 271       down and begin changing some of the default variable
 272       values. Shut down MyPLC with <command>service plc stop</command>
 273       (see <xref linkend="QuickStart" />). </para>
 274
 275       <para> The preferred option for changing the configuration is to
 276       use the <command>plc-config-tty</command> tool. The
 277       full set of applicable variables is described in <xref
 278       linkend="VariablesRuntime"/>, but using the <command>u</command>
 279       guides you to the most useful ones.
 280       Here is sample session:
 281       </para>
 282
 283       <example><title>Using plc-config-tty for configuration:</title>
 284           <programlisting><![CDATA[<myvserver> # plc-config-tty
 285 Enter command (u for usual changes, w to save, ? for help) u
 286 == PLC_NAME : [PlanetLab Test] OneLab
 287 == PLC_SLICE_PREFIX : [pl] thone
 288 == PLC_ROOT_USER : [root@localhost.localdomain] root@onelab-plc.inria.fr
 289 == PLC_ROOT_PASSWORD : [root] plain-passwd
 290 == PLC_MAIL_ENABLED : [false] true
 291 == PLC_MAIL_SUPPORT_ADDRESS : [root+support@localhost.localdomain] support@one-lab.org
 292 == PLC_BOOT_HOST : [localhost.localdomain] onelab-plc.inria.fr
 293 == PLC_NET_DNS1 : [127.0.0.1] 138.96.250.248
 294 == PLC_NET_DNS2 : [None] 138.96.250.249
 295 Enter command (u for usual changes, w to save, ? for help) w
 296 Wrote /etc/planetlab/configs/site.xml
 297 Merged
 298         /etc/planetlab/default_config.xml
 299 and     /etc/planetlab/configs/site.xml
 300 into    /etc/planetlab/plc_config.xml
 301 You might want to type 'r' (restart plc) or 'q' (quit)
 302 Enter command (u for usual changes, w to save, ? for help) r
 303 ==================== Stopping plc
 304 ...
 305 ==================== Starting plc
 306 ...
 307 Enter command (u for usual changes, w to save, ? for help) q
 308 [myvserver] # ]]></programlisting>
 309     </example>
 310
 311       <para>The variables that you should change immediately are:</para>
 312
 313       <itemizedlist>
 314         <listitem><para>
 315           <envar>PLC_NAME</envar>: Change this to the name of your PLC installation.
 316         </para></listitem>
 317         <listitem><para>
 318           <envar>PLC_SLICE_PREFIX</envar>: Pick some
 319           reasonable, short value; <emphasis> this is especially crucial if you
 320           plan on federating with other PLCs</emphasis>.
 321         </para></listitem>
 322         <listitem><para>
 323           <envar>PLC_ROOT_PASSWORD</envar>: Change this to a more
 324           secure password.
 325         </para></listitem>
 326         <listitem><para>
 327           <envar>PLC_MAIL_SUPPORT_ADDRESS</envar>:
 328           Change this to the e-mail address at which you would like to
 329         receive support requests.
 330         </para></listitem>
 331         <listitem><para>
 332           <envar>PLC_DB_HOST</envar>, <envar>PLC_API_HOST</envar>,
 333           <envar>PLC_WWW_HOST</envar>, <envar>PLC_BOOT_HOST</envar>,
 334           Change all of these to the preferred FQDN address of your
 335         host system. The corresponding <envar>*_IP</envar> values can
 336         be safely ignored if the FQDN can be resolved through DNS.
 337         </para></listitem>
 338       </itemizedlist>
 339
 340       <para> After changing these variables, make sure that you save
 341       (w) and restart your plc (r), as shown in the above example.
 342       You should notice that the password of the default administrator
 343       account is no longer <literal>root</literal>, and that the
 344       default site name includes the name of your PLC installation
 345       instead of PlanetLab. As a side effect of these changes, the ISO
 346       images for the boot CDs now have new names, so that you can
 347       freely remove the ones names after 'PlanetLab Test', which is
 348       the default value of <envar>PLC_NAME</envar> </para>
 349
 350       <para>If you used the above method method for configuring, you
 351       can skip to <xref linkend="LoginRealUser" />. As an alternative
 352       to using <command>plc-config-tty</command>, you may also use a
 353       text editor, but this requires some understanding on how the
 354       configuration files are used within myplc. The
 355       <emphasis>default</emphasis> configuration is stored in a file
 356       named <filename>/etc/planetlab/default_config.xml</filename>,
 357       that is designed to remain intact. You may store your local
 358       changes in a file named
 359       <filename>/etc/planetlab/configs/site.xml</filename>, that gets
 360       loaded on top of the defaults. The resulting complete
 361       configuration is stored in the file
 362       <filename>/etc/planetlab/plc_config.xml</filename> that is used
 363       as the reference. If you use this strategy, be sure to issue the
 364       following command to refresh this file:</para>
 365
 366       <example><title> Refreshing <filename> plc_config.xml
 367       </filename> after a manual change in<filename>
 368       site.xml</filename> </title>
 369       <programlisting><![CDATA[[myvserver] # service plc reload]]></programlisting>
 370       </example>
 371
 372       <para>The defaults configuration file is a self-documenting
 373       configuration file written in XML. Variables are divided into
 374       categories. Variable identifiers must be alphanumeric, plus
 375       underscore. A variable is referred to canonically as the
 376       uppercase concatenation of its category identifier, an
 377       underscore, and its variable identifier. Thus, a variable with
 378       an <literal>id</literal> of <literal>slice_prefix</literal> in
 379       the <literal>plc</literal> category is referred to canonically
 380       as <envar>PLC_SLICE_PREFIX</envar>.</para>
 381
 382       <para>The reason for this convention is that during MyPLC
 383       startup, <filename>plc_config.xml</filename> is translated into
 384       several different languages&mdash;shell, PHP, and
 385       Python&mdash;so that scripts written in each of these languages
 386       can refer to the same underlying configuration. Most MyPLC
 387       scripts are written in shell, so the convention for shell
 388       variables predominates.</para>
 389
 390       </section>
 391
 392       <section id="LoginRealUser"> <title> Login as a real user </title>
 393
 394       <para>Now that myplc is up and running, you can connect to the
 395       web site that by default runs on port 80. You can either
 396       directly use the default administrator user that you configured
 397       in <envar>PLC_ROOT_USER</envar> and
 398       <envar>PLC_ROOT_PASSWORD</envar>, or create a real user through
 399       the 'Joining' tab. Do not forget to  select both PI and tech
 400       roles, and to select the only site created at this stage.
 401       Login as the administrator to enable this user, then login as
 402       the real user.</para>
 403       </section>
 404
 405     <section>
 406       <title>Installing nodes</title>
 407
 408       <para>Install your first node by clicking <literal>Add
 409       Node</literal> under the <literal>Nodes</literal> tab. Fill in
 410       all the appropriate details, then click
 411       <literal>Add</literal>. Download the node's boot material,
 412       please refer to <xref linkend="TechsGuide" /> for more details
 413       about this stage.</para>
 414
 415       <para>Please keep in mind that this boot medium is customized
 416       for your particular instance, and contains details such as the
 417       host that your configured as <envar>PLC_BOOT_HOST</envar>), or
 418       the SSL certificate of your boot server that might expire. So
 419       changes in your configuration may require you to replace all
 420       your boot CD's.</para>
 421
 422     </section>
 423
 424     <section>
 425       <title>Administering nodes</title>
 426
 427       <para>You may administer nodes as <literal>root</literal> by
 428       using the SSH key stored in
 429       <filename>/etc/planetlab/root_ssh_key.rsa</filename>.</para>
 430
 431       <example>
 432         <title>Accessing nodes via SSH. Replace
 433         <literal>node</literal> with the hostname of the node.</title>
 434
 435         <programlisting>[myvserver] # ssh -i /etc/planetlab/root_ssh_key.rsa root@node</programlisting>
 436       </example>
 437
 438       <para>From the node's root context, besides the standard Linux
 439       log files located in <filename>/var/log</filename>, several
 440       other files can give you clues about any problems with active
 441       processes:</para>
 442
 443       <itemizedlist>
 444         <listitem><para><filename>/var/log/nm</filename>: The log
 445         file for the Node Manager.</para></listitem>
 446
 447         <listitem><para><filename>/vservers/slicename/var/log/nm</filename>:
 448         The log file for the Node Manager operations that perform
 449         within the slice's vserver.</para></listitem>
 450
 451       </itemizedlist>
 452     </section>
 453
 454     <section>
 455       <title>Creating a slice</title>
 456
 457       <para>Create a slice by clicking <literal>Create Slice</literal>
 458       under the <literal>Slices</literal> tab. Fill in all the
 459       appropriate details, then click <literal>Create</literal>. Add
 460       nodes to the slice by clicking <literal>Manage Nodes</literal>
 461       on the <command>Slice Details</command> page for
 462       the slice.</para>
 463
 464       <para>
 465         Slice creation is performed by the NodeManager. In some
 466         particular cases you may wish to restart it manually, here is
 467         how to do this:
 468       </para>
 469
 470       <example>
 471         <title>Forcing slice creation on a node.</title>
 472
 473         <programlisting><![CDATA[[myvserver] # ssh -i /etc/planetlab/root_ssh_key.rsa root@node service nm restart]]>
 474         </programlisting>
 475       </example>
 476     </section>
 477
 478   <section id="StartupSequence">
 479     <title>Understanding the startup sequence</title>
 480
 481     <para>During service startup described in <xref
 482     linkend="QuickStart" />, observe the output of this command for
 483     any failures. If no failures occur, you should see output similar
 484     to the following. <command>Please note that as of this writing, with 4.2
 485     the system logger step might fail, this is harmless!</command></para>
 486
 487     <example>
 488       <title>A successful MyPLC startup.</title>
 489
 490       <programlisting><![CDATA[
 491 PLC: Generating network files:                             [  OK  ]
 492 PLC: Starting system logger:                               [  OK  ]
 493 PLC: Starting database server:                             [  OK  ]
 494 PLC: Generating SSL certificates:                          [  OK  ]
 495 PLC: Configuring the API:                                  [  OK  ]
 496 PLC: Updating GPG keys:                                    [  OK  ]
 497 PLC: Generating SSH keys:                                  [  OK  ]
 498 PLC: Starting web server:                                  [  OK  ]
 499 PLC: Bootstrapping the database:                           [  OK  ]
 500 PLC: Starting DNS server:                                  [  OK  ]
 501 PLC: Starting crond:                                       [  OK  ]
 502 PLC: Rebuilding Boot CD:                                   [  OK  ]
 503 PLC: Rebuilding Boot Manager:                              [  OK  ]
 504 PLC: Signing node packages:                                [  OK  ]
 505 ]]></programlisting>
 506     </example>
 507
 508     <para>A complete log file of the startup process may be found at
 509     <filename>/var/log/boot.log</filename>. Possible reasons
 510     for failure of each step include:</para>
 511
 512     <itemizedlist>
 513       <listitem><para><literal>Starting database server</literal>: If
 514       this step fails, check
 515       <filename>/var/log/pgsql</filename> and
 516       <filename>/var/log/boot.log</filename>. The most common
 517       reason for failure is that the default PostgreSQL port, TCP port
 518       5432, is already in use. Check that you are not running a
 519       PostgreSQL server on the host system.</para></listitem>
 520
 521       <listitem><para><literal>Starting web server</literal>: If this
 522       step fails, check
 523       <filename>/var/log/httpd/error_log</filename> and
 524       <filename>/var/log/boot.log</filename> for obvious
 525       errors. The most common reason for failure is that the default
 526       web ports, TCP ports 80 and 443, are already in use. Check that
 527       you are not running a web server on the host
 528       system.</para></listitem>
 529
 530       <listitem><para><literal>Bootstrapping the database</literal>:
 531       If this step fails, it is likely that the previous step
 532       (<literal>Starting web server</literal>) also failed. Another
 533       reason that it could fail is if <envar>PLC_API_HOST</envar> (see
 534       <xref linkend="Configuration" />) does not resolve to
 535       the host on which the API server has been enabled. By default,
 536       all services, including the API server, are enabled and run on
 537       the same host, so check that <envar>PLC_API_HOST</envar> is
 538       either <filename>localhost</filename> or resolves to a local IP
 539       address. Also check that <envar>PLC_ROOT_USER</envar> looks like
 540       an e-mail address.</para></listitem>
 541
 542       <listitem><para><literal>Starting crond</literal>: If this step
 543       fails, it is likely that the previous steps (<literal>Starting
 544       web server</literal> and <literal>Bootstrapping the
 545       database</literal>) also failed. If not, check
 546       <filename>/var/log/boot.log</filename> for obvious
 547       errors. This step starts the <command>cron</command> service and
 548       generates the initial set of XML files that the Slice Creation
 549       Service uses to determine slice state.</para></listitem>
 550     </itemizedlist>
 551
 552     <para>If no failures occur, then MyPLC should be active with a
 553     default configuration. Open a web browser on the host system and
 554     visit <literal>http://localhost/</literal>, which should bring you
 555     to the front page of your PLC installation. The default password
 556     for the administrator account
 557     <literal>root@localhost.localdomain</literal> (set by
 558     <envar>PLC_ROOT_USER</envar>) is <literal>root</literal> (set by
 559     <envar>PLC_ROOT_PASSWORD</envar>).</para>
 560     </section>
 561
 562     <section id="FilesInvolvedRuntime">
 563
 564       <title>
 565         Files and directories involved in <emphasis>myplc</emphasis>
 566       </title>
 567       <para>
 568         The various places where is stored the persistent
 569         information pertaining to your own deployment are
 570       </para>
 571       <itemizedlist>
 572         <listitem><para><filename>/etc/planetlab</filename>: This
 573         directory contains the configuration files, keys, and
 574         certificates that define your MyPLC
 575         installation.</para></listitem>
 576
 577         <listitem><para><filename>/var/lib/pgsql</filename>: This
 578         directory contains PostgreSQL database
 579         files.</para></listitem>
 580
 581         <listitem><para><filename>/var/www/html/boot</filename>: This
 582         directory contains the Boot Manager, customized for your MyPLC
 583         installation, and its data files.</para></listitem>
 584
 585         <listitem><para><filename>/var/www/html/download</filename>:
 586         This directory contains Boot CD images, customized for your
 587         MyPLC installation.</para></listitem>
 588
 589         <listitem><para><filename>/var/www/html/install-rpms</filename>:
 590         This directory is where you should install node package
 591         updates, if any. By default, nodes are installed from the
 592         tarball located at
 593         <filename>/var/www/html/boot/PlanetLab-Bootstrap.tar.bz2</filename>,
 594         which is pre-built from the latest PlanetLab Central sources,
 595         and installed as part of your MyPLC installation. However,
 596         nodes will attempt to install any newer RPMs located in
 597         <filename>/var/www/html/install-rpms/planetlab</filename>,
 598         after initial installation and periodically thereafter. You
 599         must run
 600         <programlisting><![CDATA[[myvserver] # service plc start packages]]></programlisting>
 601         command to update the
 602         <command>yum</command> caches in this directory after
 603         installing a new RPM. </para>
 604
 605         <para>
 606           If you wish to upgrade all your nodes RPMs from a more
 607           recent build, you should take advantage of the
 608           <filename>noderepo</filename> RPM, as described in <ulink
 609           url="http://svn.planet-lab.org/wiki/NodeFamily" />
 610         </para>
 611         </listitem>
 612       </itemizedlist>
 613
 614   </section>
 615   </section>
 616
 617   <section id="DevelopmentEnvironment">
 618
 619     <title>Rebuilding and customizing MyPLC</title>
 620
 621     <para>
 622       Please refer to the following resources for setting up a build environment:
 623     </para>
 624
 625     <itemizedlist>
 626       <listitem>
 627         <para>
 628           <ulink url="http://svn.planet-lab.org/wiki/VserverCentos" />
 629           will get you started for setting up vserver, launching a
 630           nightly build or running the build manually.
 631         </para>
 632       </listitem>
 633       <listitem>
 634         <para>
 635           <ulink url="http://svn.planet-lab.org/svn/build/trunk/" />
 636           and in particular the various README files, provide some
 637           help on how to use advanced features of the build.
 638         </para>
 639       </listitem>
 640     </itemizedlist>
 641   </section>
 642
 643   <appendix id="VariablesRuntime">
 644     <title>Configuration variables</title>
 645
 646     <para>
 647       Listed below is the set of standard configuration variables
 648       together with their default values, as defined in the template
 649       <filename>/etc/planetlab/default_config.xml</filename>.
 650     </para>
 651     <para>
 652       This information is available online within
 653       <command>plc-config-tty</command>, e.g.:
 654     </para>
 655
 656 <example>
 657   <title>Advanced usage of plc-config-tty</title>
 658   <programlisting><![CDATA[[myvserver] # plc-config-tty
 659 Enter command (u for usual changes, w to save, ? for help) V plc_dns
 660 ========== Category = PLC_DNS
 661 ### Enable DNS
 662 # Enable the internal DNS server. The server does not provide reverse
 663 # resolution and is not a production quality or scalable DNS solution.
 664 # Use the internal DNS server only for small deployments or for testing.
 665 PLC_DNS_ENABLED
 666 ]]></programlisting></example>
 667
 668   <para> List of the <command>myplc</command> configuration variables:</para>
 669    &Variables;
 670   </appendix>
 671
 672   <bibliography>
 673     <title>Bibliography</title>
 674
 675     <biblioentry id="UsersGuide">
 676       <title><ulink
 677       url="http://www.planet-lab.org/doc/guides/user">PlanetLab
 678       User's Guide</ulink></title>
 679     </biblioentry>
 680
 681     <biblioentry id="PIsGuide">
 682       <title><ulink
 683       url="http://www.planet-lab.org/doc/guides/pi">PlanetLab
 684       Principal Investigator's Guide</ulink></title>
 685     </biblioentry>
 686
 687     <biblioentry id="TechsGuide">
 688       <author><firstname>Mark</firstname><surname>Huang</surname></author>
 689       <title><ulink
 690       url="http://www.planet-lab.org/doc/guides/tech">PlanetLab
 691       Technical Contact's Guide</ulink></title>
 692     </biblioentry>
 693
 694   </bibliography>
 695 </article>