3 // DO NOT EDIT. This file was automatically generated from
4 // DocBook XML. See plc_www/doc/README.
6 $_title= "MyPLC User's Guide";
8 require_once('session.php');
9 require_once('header.php');
10 require_once('nav.php');
12 ?><div class="article" lang="en">
13 <div class="titlepage">
15 <div><h1 class="title">
16 <a name="id2795259"></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>
21 <td align="left">Revision 1.0</td>
22 <td align="left">April 7, 2006</td>
23 <td align="left">MLH</td>
25 <tr><td align="left" colspan="3"><p>Initial draft.</p></td></tr>
27 <td align="left">Revision 1.1</td>
28 <td align="left">July 19, 2006</td>
29 <td align="left">MLH</td>
31 <tr><td align="left" colspan="3"><p>Add development environment.</p></td></tr>
33 <div><div class="abstract">
34 <p class="title"><b>Abstract</b></p>
35 <p>This document describes the design, installation, and
36 administration of MyPLC, a complete PlanetLab Central (PLC)
37 portable installation contained within a
38 <span><strong class="command">chroot</strong></span> jail. This document assumes advanced
39 knowledge of the PlanetLab architecture and Linux system
46 <p><b>Table of Contents</b></p>
48 <dt><span class="section"><a href="#id2864719">1. Overview</a></span></dt>
49 <dd><dl><dt><span class="section"><a href="#id2842268">1.1. Purpose of the <span class="emphasis"><em> myplc-devel
50 </em></span> package </a></span></dt></dl></dd>
51 <dt><span class="section"><a href="#Requirements">2. Requirements </a></span></dt>
52 <dt><span class="section"><a href="#Installation">3. Installating and using MyPLC</a></span></dt>
54 <dt><span class="section"><a href="#id2841677">3.1. Installing MyPLC.</a></span></dt>
55 <dt><span class="section"><a href="#QuickStart">3.2. QuickStart </a></span></dt>
56 <dt><span class="section"><a href="#ChangingTheConfiguration">3.3. Changing the configuration</a></span></dt>
57 <dt><span class="section"><a href="#id2842715">3.4. Installing nodes</a></span></dt>
58 <dt><span class="section"><a href="#id2842797">3.5. Administering nodes</a></span></dt>
59 <dt><span class="section"><a href="#id2842898">3.6. Creating a slice</a></span></dt>
60 <dt><span class="section"><a href="#StartupSequence">3.7. Understanding the startup sequence</a></span></dt>
61 <dt><span class="section"><a href="#FilesInvolvedRuntime">3.8. Files and directories
62 involved in <span class="emphasis"><em>myplc</em></span></a></span></dt>
64 <dt><span class="section"><a href="#DevelopmentEnvironment">4. Rebuilding and customizing MyPLC</a></span></dt>
66 <dt><span class="section"><a href="#id2894620">4.1. Installation</a></span></dt>
67 <dt><span class="section"><a href="#FilesInvolvedDevel">4.2. Files and directories
68 involved in <span class="emphasis"><em>myplc-devl</em></span></a></span></dt>
69 <dt><span class="section"><a href="#id2894876">4.3. Fedora Core 4 mirror requirement</a></span></dt>
70 <dt><span class="section"><a href="#BuildingMyPLC">4.4. Building MyPLC</a></span></dt>
71 <dt><span class="section"><a href="#UpdatingCVS">4.5. Updating CVS</a></span></dt>
73 <dt><span class="appendix"><a href="#VariablesRuntime">A. Configuration variables (for <span class="emphasis"><em>myplc</em></span>)</a></span></dt>
74 <dt><span class="appendix"><a href="#VariablesDevel">B. Development configuration variables (for <span class="emphasis"><em>myplc-devel</em></span>)</a></span></dt>
75 <dt><span class="bibliography"><a href="#id2898373">Bibliography</a></span></dt>
78 <div class="section" lang="en">
79 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
80 <a name="id2864719"></a>1. Overview</h2></div></div></div>
81 <p>MyPLC is a complete PlanetLab Central (PLC) portable
82 installation contained within a <span><strong class="command">chroot</strong></span>
83 jail. The default installation consists of a web server, an
84 XML-RPC API server, a boot server, and a database server: the core
85 components of PLC. The installation is customized through an
86 easy-to-use graphical interface. All PLC services are started up
87 and shut down through a single script installed on the host
88 system. The usually complex process of installing and
89 administering the PlanetLab backend is reduced by containing PLC
90 services within a virtual filesystem. By packaging it in such a
91 manner, MyPLC may also be run on any modern Linux distribution,
92 and could conceivably even run in a PlanetLab slice.</p>
94 <a name="Architecture"></a><p class="title"><b>Figure 1. MyPLC architecture</b></p>
95 <div class="mediaobject" align="center">
96 <img src="architecture.png" align="middle" width="270" alt="MyPLC architecture"><div class="caption"><p>MyPLC should be viewed as a single application that
97 provides multiple functions and can run on any host
101 <div class="section" lang="en">
102 <div class="titlepage"><div><div><h3 class="title">
103 <a name="id2842268"></a>1.1. Purpose of the <span class="emphasis"><em> myplc-devel
104 </em></span> package </h3></div></div></div>
105 <p> The <span class="emphasis"><em>myplc</em></span> package comes with all
106 required node software, rebuilt from the public PlanetLab CVS
107 repository. If for any reason you need to implement your own
108 customized version of this software, you can use the
109 <span class="emphasis"><em>myplc-devel</em></span> package instead, for setting up
110 your own development environment, including a local CVS
111 repository; you can then freely manage your changes and rebuild
112 your customized version of <span class="emphasis"><em>myplc</em></span>. We also
113 provide good practices, that will then allow you to resync your local
114 CVS repository with any further evolution on the mainstream public
115 PlanetLab software. </p>
118 <div class="section" lang="en">
119 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
120 <a name="Requirements"></a>2. Requirements </h2></div></div></div>
121 <p> <span class="emphasis"><em>myplc</em></span> and
122 <span class="emphasis"><em>myplc-devel</em></span> were designed as
123 <span><strong class="command">chroot</strong></span> jails so as to reduce the requirements on
124 your host operating system. So in theory, these distributions should
125 work on virtually any Linux 2.6 based distribution, whether it
126 supports rpm or not. </p>
127 <p> However, things are never that simple and there indeed are
128 some known limitations to this, so here are a couple notes as a
129 recommended reading before you proceed with the installation.</p>
130 <p> As of 9 August 2006 (i.e <span class="emphasis"><em>myplc-0.5</em></span>) :</p>
131 <div class="itemizedlist"><ul type="disc">
132 <li><p> The software is vastly based on <span class="emphasis"><em>Fedora
133 Core 4</em></span>. Please note that the build server at Princeton
134 runs <span class="emphasis"><em>Fedora Core 2</em></span>, togother with a upgraded
138 <p> myplc and myplc-devel are known to work on both
139 <span class="emphasis"><em>Fedora Core 2</em></span> and <span class="emphasis"><em>Fedora Core
140 4</em></span>. Please note however that, on fc4 at least, it is
141 highly recommended to use the <span class="application">Security Level
142 Configuration</span> utility and to <span class="emphasis"><em>switch off
143 SElinux</em></span> on your box because : </p>
144 <div class="itemizedlist"><ul type="circle">
146 myplc requires you to run SElinux as 'Permissive' at most
149 myplc-devel requires you to turn SElinux Off.
153 <li><p> In addition, as far as myplc is concerned, you
154 need to check your firewall configuration since you need, of course,
155 to open up the <span class="emphasis"><em>http</em></span> and
156 <span class="emphasis"><em>https</em></span> ports, so as to accept connections from
157 the managed nodes and from the users desktops. </p></li>
160 <div class="section" lang="en">
161 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
162 <a name="Installation"></a>3. Installating and using MyPLC</h2></div></div></div>
163 <p>Though internally composed of commodity software
164 subpackages, MyPLC should be treated as a monolithic software
165 application. MyPLC is distributed as single RPM package that has
166 no external dependencies, allowing it to be installed on
167 practically any Linux 2.6 based distribution.</p>
168 <div class="section" lang="en">
169 <div class="titlepage"><div><div><h3 class="title">
170 <a name="id2841677"></a>3.1. Installing MyPLC.</h3></div></div></div>
171 <div class="itemizedlist"><ul type="disc">
173 <p>If your distribution supports RPM:</p>
174 <pre class="programlisting"># rpm -U http://build.planet-lab.org/build/myplc-0_4-rc1/RPMS/i386/myplc-0.4-1.planetlab.i386.rpm</pre>
177 <p>If your distribution does not support RPM:</p>
178 <pre class="programlisting"># cd /tmp
179 # wget http://build.planet-lab.org/build/myplc-0_4-rc1/RPMS/i386/myplc-0.4-1.planetlab.i386.rpm
181 # rpm2cpio /tmp/myplc-0.4-1.planetlab.i386.rpm | cpio -diu</pre>
184 <p> The <a href="#FilesInvolvedRuntime" title="3.8. Files and directories
185 involved in myplc">Section 3.8, “ Files and directories
186 involved in <span class="emphasis"><em>myplc</em></span>”</a> below explains in
187 details the installation strategy and the miscellaneous files and
188 directories involved.</p>
190 <div class="section" lang="en">
191 <div class="titlepage"><div><div><h3 class="title">
192 <a name="QuickStart"></a>3.2. QuickStart </h3></div></div></div>
193 <p> On a Red Hat or Fedora host system, it is customary to use
194 the <span><strong class="command">service</strong></span> command to invoke System V init
195 scripts. As the examples suggest, the service must be started as root:</p>
196 <div class="example">
197 <a name="id2841851"></a><p class="title"><b>Example 1. Starting MyPLC:</b></p>
198 <pre class="programlisting"># service plc start</pre>
200 <div class="example">
201 <a name="id2841863"></a><p class="title"><b>Example 2. Stopping MyPLC:</b></p>
202 <pre class="programlisting"># service plc stop</pre>
204 <p> In <a href="#StartupSequence" title="3.7. Understanding the startup sequence">Section 3.7, “Understanding the startup sequence”</a>, we provide greater
205 details that might be helpful in the case where the service does
206 not seem to take off correctly.</p>
207 <p>Like all other registered System V init services, MyPLC is
208 started and shut down automatically when your host system boots
209 and powers off. You may disable automatic startup by invoking the
210 <span><strong class="command">chkconfig</strong></span> command on a Red Hat or Fedora host
212 <div class="example">
213 <a name="id2841901"></a><p class="title"><b>Example 3. Disabling automatic startup of MyPLC.</b></p>
214 <pre class="programlisting"># chkconfig plc off</pre>
216 <div class="example">
217 <a name="id2842528"></a><p class="title"><b>Example 4. Re-enabling automatic startup of MyPLC.</b></p>
218 <pre class="programlisting"># chkconfig plc on</pre>
221 <div class="section" lang="en">
222 <div class="titlepage"><div><div><h3 class="title">
223 <a name="ChangingTheConfiguration"></a>3.3. Changing the configuration</h3></div></div></div>
224 <p>After verifying that MyPLC is working correctly, shut it
225 down and begin changing some of the default variable
226 values. Shut down MyPLC with <span><strong class="command">service plc stop</strong></span>
227 (see <a href="#QuickStart" title="3.2. QuickStart ">Section 3.2, “ QuickStart ”</a>). With a text
228 editor, open the file
229 <code class="filename">/etc/planetlab/plc_config.xml</code>. This file is
230 a self-documenting configuration file written in XML. Variables
231 are divided into categories. Variable identifiers must be
232 alphanumeric, plus underscore. A variable is referred to
233 canonically as the uppercase concatenation of its category
234 identifier, an underscore, and its variable identifier. Thus, a
235 variable with an <code class="literal">id</code> of
236 <code class="literal">slice_prefix</code> in the <code class="literal">plc</code>
237 category is referred to canonically as
238 <code class="envar">PLC_SLICE_PREFIX</code>.</p>
239 <p>The reason for this convention is that during MyPLC
240 startup, <code class="filename">plc_config.xml</code> is translated into
241 several different languages—shell, PHP, and
242 Python—so that scripts written in each of these languages
243 can refer to the same underlying configuration. Most MyPLC
244 scripts are written in shell, so the convention for shell
245 variables predominates.</p>
246 <p>The variables that you should change immediately are:</p>
247 <div class="itemizedlist"><ul type="disc">
248 <li><p><code class="envar">PLC_NAME</code>: Change this to the
249 name of your PLC installation.</p></li>
250 <li><p><code class="envar">PLC_ROOT_PASSWORD</code>: Change this
251 to a more secure password.</p></li>
252 <li><p><code class="envar">PLC_MAIL_SUPPORT_ADDRESS</code>:
253 Change this to the e-mail address at which you would like to
254 receive support requests.</p></li>
255 <li><p><code class="envar">PLC_DB_HOST</code>,
256 <code class="envar">PLC_DB_IP</code>, <code class="envar">PLC_API_HOST</code>,
257 <code class="envar">PLC_API_IP</code>, <code class="envar">PLC_WWW_HOST</code>,
258 <code class="envar">PLC_WWW_IP</code>, <code class="envar">PLC_BOOT_HOST</code>,
259 <code class="envar">PLC_BOOT_IP</code>: Change all of these to the
260 preferred FQDN and external IP address of your host
263 <p>The full set of applicable variables is described in <a href="#VariablesDevel" title="B. Development configuration variables (for myplc-devel)">Appendix B, <i>Development configuration variables (for <span class="emphasis"><em>myplc-devel</em></span>)</i></a>. After changing these variables,
264 save the file, then restart MyPLC with <span><strong class="command">service plc
265 start</strong></span>. You should notice that the password of the
266 default administrator account is no longer
267 <code class="literal">root</code>, and that the default site name includes
268 the name of your PLC installation instead of PlanetLab.</p>
270 <div class="section" lang="en">
271 <div class="titlepage"><div><div><h3 class="title">
272 <a name="id2842715"></a>3.4. Installing nodes</h3></div></div></div>
273 <p>Install your first node by clicking <code class="literal">Add
274 Node</code> under the <code class="literal">Nodes</code> tab. Fill in
275 all the appropriate details, then click
276 <code class="literal">Add</code>. Download the node's configuration file
277 by clicking <code class="literal">Download configuration file</code> on
278 the <span class="bold"><strong>Node Details</strong></span> page for the
279 node. Save it to a floppy disk or USB key as detailed in [<a href="#TechsGuide" title="[TechsGuide]">1</a>].</p>
280 <p>Follow the rest of the instructions in [<a href="#TechsGuide" title="[TechsGuide]">1</a>] for creating a Boot CD and installing
281 the node, except download the Boot CD image from the
282 <code class="filename">/download</code> directory of your PLC
283 installation, not from PlanetLab Central. The images located
284 here are customized for your installation. If you change the
285 hostname of your boot server (<code class="envar">PLC_BOOT_HOST</code>), or
286 if the SSL certificate of your boot server expires, MyPLC will
287 regenerate it and rebuild the Boot CD with the new
288 certificate. If this occurs, you must replace all Boot CDs
289 created before the certificate was regenerated.</p>
290 <p>The installation process for a node has significantly
291 improved since PlanetLab 3.3. It should now take only a few
292 seconds for a new node to become ready to create slices.</p>
294 <div class="section" lang="en">
295 <div class="titlepage"><div><div><h3 class="title">
296 <a name="id2842797"></a>3.5. Administering nodes</h3></div></div></div>
297 <p>You may administer nodes as <code class="literal">root</code> by
298 using the SSH key stored in
299 <code class="filename">/etc/planetlab/root_ssh_key.rsa</code>.</p>
300 <div class="example">
301 <a name="id2842820"></a><p class="title"><b>Example 5. Accessing nodes via SSH. Replace
302 <code class="literal">node</code> with the hostname of the node.</b></p>
303 <pre class="programlisting">ssh -i /etc/planetlab/root_ssh_key.rsa root@node</pre>
305 <p>Besides the standard Linux log files located in
306 <code class="filename">/var/log</code>, several other files can give you
307 clues about any problems with active processes:</p>
308 <div class="itemizedlist"><ul type="disc">
309 <li><p><code class="filename">/var/log/pl_nm</code>: The log
310 file for the Node Manager.</p></li>
311 <li><p><code class="filename">/vservers/pl_conf/var/log/pl_conf</code>:
312 The log file for the Slice Creation Service.</p></li>
313 <li><p><code class="filename">/var/log/propd</code>: The log
314 file for Proper, the service which allows certain slices to
315 perform certain privileged operations in the root
317 <li><p><code class="filename">/vservers/pl_netflow/var/log/netflow.log</code>:
318 The log file for PlanetFlow, the network traffic auditing
322 <div class="section" lang="en">
323 <div class="titlepage"><div><div><h3 class="title">
324 <a name="id2842898"></a>3.6. Creating a slice</h3></div></div></div>
325 <p>Create a slice by clicking <code class="literal">Create Slice</code>
326 under the <code class="literal">Slices</code> tab. Fill in all the
327 appropriate details, then click <code class="literal">Create</code>. Add
328 nodes to the slice by clicking <code class="literal">Manage Nodes</code>
329 on the <span class="bold"><strong>Slice Details</strong></span> page for
331 <p>A <span><strong class="command">cron</strong></span> job runs every five minutes and
333 <code class="filename">/plc/data/var/www/html/xml/slices-0.5.xml</code>
334 with information about current slice state. The Slice Creation
335 Service running on every node polls this file every ten minutes
336 to determine if it needs to create or delete any slices. You may
337 accelerate this process manually if desired.</p>
338 <div class="example">
339 <a name="id2842960"></a><p class="title"><b>Example 6. Forcing slice creation on a node.</b></p>
340 <pre class="programlisting"># Update slices.xml immediately
341 service plc start crond
343 # Kick the Slice Creation Service on a particular node.
344 ssh -i /etc/planetlab/root_ssh_key.rsa root@node \
345 vserver pl_conf exec service pl_conf restart</pre>
348 <div class="section" lang="en">
349 <div class="titlepage"><div><div><h3 class="title">
350 <a name="StartupSequence"></a>3.7. Understanding the startup sequence</h3></div></div></div>
351 <p>During service startup described in <a href="#QuickStart" title="3.2. QuickStart ">Section 3.2, “ QuickStart ”</a>, observe the output of this command for
352 any failures. If no failures occur, you should see output similar
353 to the following:</p>
354 <div class="example">
355 <a name="id2893858"></a><p class="title"><b>Example 7. A successful MyPLC startup.</b></p>
356 <pre class="programlisting">Mounting PLC: [ OK ]
357 PLC: Generating network files: [ OK ]
358 PLC: Starting system logger: [ OK ]
359 PLC: Starting database server: [ OK ]
360 PLC: Generating SSL certificates: [ OK ]
361 PLC: Configuring the API: [ OK ]
362 PLC: Updating GPG keys: [ OK ]
363 PLC: Generating SSH keys: [ OK ]
364 PLC: Starting web server: [ OK ]
365 PLC: Bootstrapping the database: [ OK ]
366 PLC: Starting DNS server: [ OK ]
367 PLC: Starting crond: [ OK ]
368 PLC: Rebuilding Boot CD: [ OK ]
369 PLC: Rebuilding Boot Manager: [ OK ]
370 PLC: Signing node packages: [ OK ]
373 <p>If <code class="filename">/plc/root</code> is mounted successfully, a
374 complete log file of the startup process may be found at
375 <code class="filename">/plc/root/var/log/boot.log</code>. Possible reasons
376 for failure of each step include:</p>
377 <div class="itemizedlist"><ul type="disc">
378 <li><p><code class="literal">Mounting PLC</code>: If this step
379 fails, first ensure that you started MyPLC as root. Check
380 <code class="filename">/etc/sysconfig/plc</code> to ensure that
381 <code class="envar">PLC_ROOT</code> and <code class="envar">PLC_DATA</code> refer to the
382 right locations. You may also have too many existing loopback
383 mounts, or your kernel may not support loopback mounting, bind
384 mounting, or the ext3 filesystem. Try freeing at least one
385 loopback device, or re-compiling your kernel to support loopback
386 mounting, bind mounting, and the ext3 filesystem. If you see an
387 error similar to <code class="literal">Permission denied while trying to open
388 /plc/root.img</code>, then SELinux may be enabled. See <a href="#Requirements" title="2. Requirements ">Section 2, “ Requirements ”</a> above for details.</p></li>
389 <li><p><code class="literal">Starting database server</code>: If
390 this step fails, check
391 <code class="filename">/plc/root/var/log/pgsql</code> and
392 <code class="filename">/plc/root/var/log/boot.log</code>. The most common
393 reason for failure is that the default PostgreSQL port, TCP port
394 5432, is already in use. Check that you are not running a
395 PostgreSQL server on the host system.</p></li>
396 <li><p><code class="literal">Starting web server</code>: If this
398 <code class="filename">/plc/root/var/log/httpd/error_log</code> and
399 <code class="filename">/plc/root/var/log/boot.log</code> for obvious
400 errors. The most common reason for failure is that the default
401 web ports, TCP ports 80 and 443, are already in use. Check that
402 you are not running a web server on the host
404 <li><p><code class="literal">Bootstrapping the database</code>:
405 If this step fails, it is likely that the previous step
406 (<code class="literal">Starting web server</code>) also failed. Another
407 reason that it could fail is if <code class="envar">PLC_API_HOST</code> (see
408 <a href="#ChangingTheConfiguration" title="3.3. Changing the configuration">Section 3.3, “Changing the configuration”</a>) does not resolve to
409 the host on which the API server has been enabled. By default,
410 all services, including the API server, are enabled and run on
411 the same host, so check that <code class="envar">PLC_API_HOST</code> is
412 either <code class="filename">localhost</code> or resolves to a local IP
414 <li><p><code class="literal">Starting crond</code>: If this step
415 fails, it is likely that the previous steps (<code class="literal">Starting
416 web server</code> and <code class="literal">Bootstrapping the
417 database</code>) also failed. If not, check
418 <code class="filename">/plc/root/var/log/boot.log</code> for obvious
419 errors. This step starts the <span><strong class="command">cron</strong></span> service and
420 generates the initial set of XML files that the Slice Creation
421 Service uses to determine slice state.</p></li>
423 <p>If no failures occur, then MyPLC should be active with a
424 default configuration. Open a web browser on the host system and
425 visit <code class="literal">http://localhost/</code>, which should bring you
426 to the front page of your PLC installation. The password of the
427 default administrator account
428 <code class="literal">root@localhost.localdomain</code> (set by
429 <code class="envar">PLC_ROOT_USER</code>) is <code class="literal">root</code> (set by
430 <code class="envar">PLC_ROOT_PASSWORD</code>).</p>
432 <div class="section" lang="en">
433 <div class="titlepage"><div><div><h3 class="title">
434 <a name="FilesInvolvedRuntime"></a>3.8. Files and directories
435 involved in <span class="emphasis"><em>myplc</em></span></h3></div></div></div>
436 <p>MyPLC installs the following files and directories:</p>
437 <div class="orderedlist"><ol type="1">
438 <li><p><code class="filename">/plc/root.img</code>: The main
439 root filesystem of the MyPLC application. This file is an
440 uncompressed ext3 filesystem that is loopback mounted on
441 <code class="filename">/plc/root</code> when MyPLC starts. This
442 filesystem, even when mounted, should be treated as an opaque
443 binary that can and will be replaced in its entirety by any
444 upgrade of MyPLC.</p></li>
445 <li><p><code class="filename">/plc/root</code>: The mount point
446 for <code class="filename">/plc/root.img</code>. Once the root filesystem
447 is mounted, all MyPLC services run in a
448 <span><strong class="command">chroot</strong></span> jail based in this
451 <p><code class="filename">/plc/data</code>: The directory where user
452 data and generated files are stored. This directory is bind
453 mounted onto <code class="filename">/plc/root/data</code> so that it is
454 accessible as <code class="filename">/data</code> from within the
455 <span><strong class="command">chroot</strong></span> jail. Files in this directory are
456 marked with <span><strong class="command">%config(noreplace)</strong></span> in the
457 RPM. That is, during an upgrade of MyPLC, if a file has not
458 changed since the last installation or upgrade of MyPLC, it is
459 subject to upgrade and replacement. If the file has changed,
460 the new version of the file will be created with a
461 <code class="filename">.rpmnew</code> extension. Symlinks within the
462 MyPLC root filesystem ensure that the following directories
463 (relative to <code class="filename">/plc/root</code>) are stored
464 outside the MyPLC filesystem image:</p>
465 <div class="itemizedlist"><ul type="disc">
466 <li><p><code class="filename">/etc/planetlab</code>: This
467 directory contains the configuration files, keys, and
468 certificates that define your MyPLC
469 installation.</p></li>
470 <li><p><code class="filename">/var/lib/pgsql</code>: This
471 directory contains PostgreSQL database
473 <li><p><code class="filename">/var/www/html/alpina-logs</code>: This
474 directory contains node installation logs.</p></li>
475 <li><p><code class="filename">/var/www/html/boot</code>: This
476 directory contains the Boot Manager, customized for your MyPLC
477 installation, and its data files.</p></li>
478 <li><p><code class="filename">/var/www/html/download</code>: This
479 directory contains Boot CD images, customized for your MyPLC
480 installation.</p></li>
481 <li><p><code class="filename">/var/www/html/install-rpms</code>: This
482 directory is where you should install node package updates,
483 if any. By default, nodes are installed from the tarball
485 <code class="filename">/var/www/html/boot/PlanetLab-Bootstrap.tar.bz2</code>,
486 which is pre-built from the latest PlanetLab Central
487 sources, and installed as part of your MyPLC
488 installation. However, nodes will attempt to install any
489 newer RPMs located in
490 <code class="filename">/var/www/html/install-rpms/planetlab</code>,
491 after initial installation and periodically thereafter. You
492 must run <span><strong class="command">yum-arch</strong></span> and
493 <span><strong class="command">createrepo</strong></span> to update the
494 <span><strong class="command">yum</strong></span> caches in this directory after
495 installing a new RPM. PlanetLab Central cannot support any
496 changes to this directory.</p></li>
497 <li><p><code class="filename">/var/www/html/xml</code>: This
498 directory contains various XML files that the Slice Creation
499 Service uses to determine the state of slices. These XML
500 files are refreshed periodically by <span><strong class="command">cron</strong></span>
501 jobs running in the MyPLC root.</p></li>
504 <li><p><a name="MyplcInitScripts"></a><code class="filename">/etc/init.d/plc</code>: This file
505 is a System V init script installed on your host filesystem,
506 that allows you to start up and shut down MyPLC with a single
507 command, as described in <a href="#QuickStart" title="3.2. QuickStart ">Section 3.2, “ QuickStart ”</a>.</p></li>
508 <li><p><code class="filename">/etc/sysconfig/plc</code>: This
509 file is a shell script fragment that defines the variables
510 <code class="envar">PLC_ROOT</code> and <code class="envar">PLC_DATA</code>. By default,
511 the values of these variables are <code class="filename">/plc/root</code>
512 and <code class="filename">/plc/data</code>, respectively. If you wish,
513 you may move your MyPLC installation to another location on your
514 host filesystem and edit the values of these variables
515 appropriately, but you will break the RPM upgrade
516 process. PlanetLab Central cannot support any changes to this
518 <li><p><code class="filename">/etc/planetlab</code>: This
519 symlink to <code class="filename">/plc/data/etc/planetlab</code> is
520 installed on the host system for convenience.</p></li>
524 <div class="section" lang="en">
525 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
526 <a name="DevelopmentEnvironment"></a>4. Rebuilding and customizing MyPLC</h2></div></div></div>
527 <p>The MyPLC package, though distributed as an RPM, is not a
528 traditional package that can be easily rebuilt from SRPM. The
529 requisite build environment is quite extensive and numerous
530 assumptions are made throughout the PlanetLab source code base,
531 that the build environment is based on Fedora Core 4 and that
532 access to a complete Fedora Core 4 mirror is available.</p>
533 <p>For this reason, it is recommended that you only rebuild
534 MyPLC (or any of its components) from within the MyPLC development
535 environment. The MyPLC development environment is similar to MyPLC
536 itself in that it is a portable filesystem contained within a
537 <span><strong class="command">chroot</strong></span> jail. The filesystem contains all the
538 necessary tools required to rebuild MyPLC, as well as a snapshot
539 of the PlanetLab source code base in the form of a local CVS
541 <div class="section" lang="en">
542 <div class="titlepage"><div><div><h3 class="title">
543 <a name="id2894620"></a>4.1. Installation</h3></div></div></div>
544 <p>Install the MyPLC development environment similarly to how
545 you would install MyPLC. You may install both packages on the same
546 host system if you wish. As with MyPLC, the MyPLC development
547 environment should be treated as a monolithic software
548 application, and any files present in the
549 <span><strong class="command">chroot</strong></span> jail should not be modified directly, as
550 they are subject to upgrade.</p>
551 <div class="itemizedlist"><ul type="disc">
553 <p>If your distribution supports RPM:</p>
554 <pre class="programlisting"># rpm -U http://build.planet-lab.org/build/myplc-0_4-rc2/RPMS/i386/myplc-devel-0.4-2.planetlab.i386.rpm</pre>
557 <p>If your distribution does not support RPM:</p>
558 <pre class="programlisting"># cd /tmp
559 # wget http://build.planet-lab.org/build/myplc-0_4-rc2/RPMS/i386/myplc-devel-0.4-2.planetlab.i386.rpm
561 # rpm2cpio /tmp/myplc-devel-0.4-2.planetlab.i386.rpm | cpio -diu</pre>
565 <div class="section" lang="en">
566 <div class="titlepage"><div><div><h3 class="title">
567 <a name="FilesInvolvedDevel"></a>4.2. Files and directories
568 involved in <span class="emphasis"><em>myplc-devl</em></span></h3></div></div></div>
569 <p>The MyPLC development environment installs the following
570 files and directories:</p>
571 <div class="itemizedlist"><ul type="disc">
572 <li><p><code class="filename">/plc/devel/root.img</code>: The
573 main root filesystem of the MyPLC development environment. This
574 file is an uncompressed ext3 filesystem that is loopback mounted
575 on <code class="filename">/plc/devel/root</code> when the MyPLC
576 development environment is initialized. This filesystem, even
577 when mounted, should be treated as an opaque binary that can and
578 will be replaced in its entirety by any upgrade of the MyPLC
579 development environment.</p></li>
580 <li><p><code class="filename">/plc/devel/root</code>: The mount
582 <code class="filename">/plc/devel/root.img</code>.</p></li>
584 <p><code class="filename">/plc/devel/data</code>: The directory
585 where user data and generated files are stored. This directory
586 is bind mounted onto <code class="filename">/plc/devel/root/data</code>
587 so that it is accessible as <code class="filename">/data</code> from
588 within the <span><strong class="command">chroot</strong></span> jail. Files in this
589 directory are marked with
590 <span><strong class="command">%config(noreplace)</strong></span> in the RPM. Symlinks
591 ensure that the following directories (relative to
592 <code class="filename">/plc/devel/root</code>) are stored outside the
593 root filesystem image:</p>
594 <div class="itemizedlist"><ul type="circle">
595 <li><p><code class="filename">/etc/planetlab</code>: This
596 directory contains the configuration files that define your
597 MyPLC development environment.</p></li>
598 <li><p><code class="filename">/cvs</code>: A
599 snapshot of the PlanetLab source code is stored as a CVS
600 repository in this directory. Files in this directory will
601 <span class="bold"><strong>not</strong></span> be updated by an upgrade of
602 <code class="filename">myplc-devel</code>. See <a href="#UpdatingCVS" title="4.5. Updating CVS">Section 4.5, “Updating CVS”</a> for more information about updating
603 PlanetLab source code.</p></li>
604 <li><p><code class="filename">/build</code>:
605 Builds are stored in this directory. This directory is bind
606 mounted onto <code class="filename">/plc/devel/root/build</code> so that
607 it is accessible as <code class="filename">/build</code> from within the
608 <span><strong class="command">chroot</strong></span> jail. The build scripts in this
609 directory are themselves source controlled; see <a href="#BuildingMyPLC" title="4.4. Building MyPLC">Section 4.4, “Building MyPLC”</a> for more information about executing
613 <li><p><code class="filename">/etc/init.d/plc-devel</code>: This file is
614 a System V init script installed on your host filesystem, that
615 allows you to start up and shut down the MyPLC development
616 environment with a single command.</p></li>
619 <div class="section" lang="en">
620 <div class="titlepage"><div><div><h3 class="title">
621 <a name="id2894876"></a>4.3. Fedora Core 4 mirror requirement</h3></div></div></div>
622 <p>The MyPLC development environment requires access to a
623 complete Fedora Core 4 i386 RPM repository, because several
624 different filesystems based upon Fedora Core 4 are constructed
625 during the process of building MyPLC. You may configure the
626 location of this repository via the
627 <code class="envar">PLC_DEVEL_FEDORA_URL</code> variable in
628 <code class="filename">/plc/devel/data/etc/planetlab/plc_config.xml</code>. The
629 value of the variable should be a URL that points to the top
630 level of a Fedora mirror that provides the
631 <code class="filename">base</code>, <code class="filename">updates</code>, and
632 <code class="filename">extras</code> repositories, e.g.,</p>
633 <div class="itemizedlist"><ul type="disc">
634 <li><p><code class="filename">file:///data/fedora</code></p></li>
635 <li><p><code class="filename">http://coblitz.planet-lab.org/pub/fedora</code></p></li>
636 <li><p><code class="filename">ftp://mirror.cs.princeton.edu/pub/mirrors/fedora</code></p></li>
637 <li><p><code class="filename">ftp://mirror.stanford.edu/pub/mirrors/fedora</code></p></li>
638 <li><p><code class="filename">http://rpmfind.net/linux/fedora</code></p></li>
640 <p>As implied by the list, the repository may be located on
641 the local filesystem, or it may be located on a remote FTP or
642 HTTP server. URLs beginning with <code class="filename">file://</code>
643 should exist at the specified location relative to the root of
644 the <span><strong class="command">chroot</strong></span> jail. For optimum performance and
645 reproducibility, specify
646 <code class="envar">PLC_DEVEL_FEDORA_URL=file:///data/fedora</code> and
647 download all Fedora Core 4 RPMS into
648 <code class="filename">/plc/devel/data/fedora</code> on the host system
649 after installing <code class="filename">myplc-devel</code>. Use a tool
650 such as <span><strong class="command">wget</strong></span> or <span><strong class="command">rsync</strong></span> to
651 download the RPMS from a public mirror:</p>
652 <div class="example">
653 <a name="id2895018"></a><p class="title"><b>Example 8. Setting up a local Fedora Core 4 repository.</b></p>
654 <pre class="programlisting"># mkdir -p /plc/devel/data/fedora
655 # cd /plc/devel/data/fedora
657 # for repo in core/4/i386/os core/updates/4/i386 extras/4/i386 ; do
658 > wget -m -nH --cut-dirs=3 http://coblitz.planet-lab.org/pub/fedora/linux/$repo
661 <p>Change the repository URI and <span><strong class="command">--cut-dirs</strong></span>
662 level as needed to produce a hierarchy that resembles:</p>
663 <pre class="programlisting">/plc/devel/data/fedora/core/4/i386/os
664 /plc/devel/data/fedora/core/updates/4/i386
665 /plc/devel/data/fedora/extras/4/i386</pre>
666 <p>A list of additional Fedora Core 4 mirrors is available at
667 <a href="http://fedora.redhat.com/Download/mirrors.html" target="_top">http://fedora.redhat.com/Download/mirrors.html</a>.</p>
669 <div class="section" lang="en">
670 <div class="titlepage"><div><div><h3 class="title">
671 <a name="BuildingMyPLC"></a>4.4. Building MyPLC</h3></div></div></div>
672 <p>All PlanetLab source code modules are built and installed
673 as RPMS. A set of build scripts, checked into the
674 <code class="filename">build/</code> directory of the PlanetLab CVS
675 repository, eases the task of rebuilding PlanetLab source
677 <p> Before you try building MyPLC, you might check the
678 configuration, in a file named
679 <span class="emphasis"><em>plc_config.xml</em></span> that relies on a very
680 similar model as MyPLC, located in
681 <span class="emphasis"><em>/etc/planetlab</em></span> within the chroot jail, or
682 in <span class="emphasis"><em>/plc/devel/data/etc/planetlab</em></span> from the
683 root context. The set of applicable variables is described in
684 <a href="#VariablesDevel" title="B. Development configuration variables (for myplc-devel)">Appendix B, <i>Development configuration variables (for <span class="emphasis"><em>myplc-devel</em></span>)</i></a>. </p>
685 <p>To build MyPLC, or any PlanetLab source code module, from
686 within the MyPLC development environment, execute the following
687 commands as root:</p>
688 <div class="example">
689 <a name="id2895119"></a><p class="title"><b>Example 9. Building MyPLC.</b></p>
690 <pre class="programlisting"># Initialize MyPLC development environment
691 service plc-devel start
693 # Enter development environment
694 chroot /plc/devel/root su -
696 # Check out build scripts into a directory named after the current
697 # date. This is simply a convention, it need not be followed
698 # exactly. See build/build.sh for an example of a build script that
699 # names build directories after CVS tags.
700 DATE=$(date +%Y.%m.%d)
702 cvs -d /cvs checkout -d $DATE build
707 <p>If the build succeeds, a set of binary RPMS will be
709 <code class="filename">/plc/devel/data/build/$DATE/RPMS/</code> that you
711 <code class="filename">/var/www/html/install-rpms/planetlab</code>
712 directory of your MyPLC installation (see <a href="#Installation" title="3. Installating and using MyPLC">Section 3, “Installating and using MyPLC”</a>).</p>
714 <div class="section" lang="en">
715 <div class="titlepage"><div><div><h3 class="title">
716 <a name="UpdatingCVS"></a>4.5. Updating CVS</h3></div></div></div>
717 <p>A complete snapshot of the PlanetLab source code is included
718 with the MyPLC development environment as a CVS repository in
719 <code class="filename">/plc/devel/data/cvs</code>. This CVS repository may
720 be accessed like any other CVS repository. It may be accessed
721 using an interface such as <a href="http://www.freebsd.org/projects/cvsweb.html" target="_top">CVSweb</a>,
722 and file permissions may be altered to allow for fine-grained
723 access control. Although the files are included with the
724 <code class="filename">myplc-devel</code> RPM, they are <span class="bold"><strong>not</strong></span> subject to upgrade once installed. New
725 versions of the <code class="filename">myplc-devel</code> RPM will install
726 updated snapshot repositories in
727 <code class="filename">/plc/devel/data/cvs-%{version}-%{release}</code>,
728 where <code class="literal">%{version}-%{release}</code> is replaced with
729 the version number of the RPM.</p>
730 <p>Because the CVS repository is not automatically upgraded,
731 if you wish to keep your local repository synchronized with the
732 public PlanetLab repository, it is highly recommended that you
733 use CVS's support for <a href="http://ximbiot.com/cvs/wiki/index.php?title=CVS--Concurrent_Versions_System_v1.12.12.1:_Tracking_third-party_sources" target="_top">vendor
734 branches</a> to track changes. Vendor branches ease the task
735 of merging upstream changes with your local modifications. To
736 import a new snapshot into your local repository (for example,
737 if you have just upgraded from
738 <code class="filename">myplc-devel-0.4-2</code> to
739 <code class="filename">myplc-devel-0.4-3</code> and you notice the new
740 repository in <code class="filename">/plc/devel/data/cvs-0.4-3</code>),
741 execute the following commands as root from within the MyPLC
742 development environment:</p>
743 <div class="example">
744 <a name="id2895270"></a><p class="title"><b>Example 10. Updating /data/cvs from /data/cvs-0.4-3.</b></p>
745 <p><span class="bold"><strong>Warning</strong></span>: This may cause
746 severe, irreversible changes to be made to your local
747 repository. Always tag your local repository before
749 <pre class="programlisting"># Initialize MyPLC development environment
750 service plc-devel start
752 # Enter development environment
753 chroot /plc/devel/root su -
756 cvs -d /cvs rtag before-myplc-0_4-3-merge
759 TMP=$(mktemp -d /data/export.XXXXXX)
761 cvs -d /data/cvs-0.4-3 export -r HEAD .
762 cvs -d /cvs import -m "PlanetLab sources from myplc-0.4-3" -ko -I ! . planetlab myplc-0_4-3
766 <p>If there any merge conflicts, use the command suggested by
767 CVS to help the merge. Explaining how to fix merge conflicts is
768 beyond the scope of this document; consult the CVS documentation
769 for more information on how to use CVS.</p>
772 <div class="appendix" lang="en">
773 <h2 class="title" style="clear: both">
774 <a name="VariablesRuntime"></a>A. Configuration variables (for <span class="emphasis"><em>myplc</em></span>)</h2>
775 <p>Listed below is the set of standard configuration variables
776 and their default values, defined in the template
777 <code class="filename">/etc/planetlab/default_config.xml</code>. Additional
778 variables and their defaults may be defined in site-specific XML
779 templates that should be placed in
780 <code class="filename">/etc/planetlab/configs/</code>.</p>
781 <div class="variablelist"><dl>
782 <dt><span class="term">PLC_NAME</span></dt>
787 Default: PlanetLab Test</p>
788 <p>The name of this PLC installation. It is used in
789 the name of the default system site (e.g., PlanetLab Central)
790 and in the names of various administrative entities (e.g.,
791 PlanetLab Support).</p>
793 <dt><span class="term">PLC_SLICE_PREFIX</span></dt>
799 <p>The abbreviated name of this PLC
800 installation. It is used as the prefix for system slices
801 (e.g., pl_conf). Warning: Currently, this variable should
804 <dt><span class="term">PLC_ROOT_USER</span></dt>
809 Default: root@localhost.localdomain</p>
810 <p>The name of the initial administrative
811 account. We recommend that this account be used only to create
812 additional accounts associated with real
813 administrators, then disabled.</p>
815 <dt><span class="term">PLC_ROOT_PASSWORD</span></dt>
821 <p>The password of the initial administrative
822 account. Also the password of the root account on the Boot
825 <dt><span class="term">PLC_ROOT_SSH_KEY_PUB</span></dt>
830 Default: /etc/planetlab/root_ssh_key.pub</p>
831 <p>The SSH public key used to access the root
832 account on your nodes.</p>
834 <dt><span class="term">PLC_ROOT_SSH_KEY</span></dt>
839 Default: /etc/planetlab/root_ssh_key.rsa</p>
840 <p>The SSH private key used to access the root
841 account on your nodes.</p>
843 <dt><span class="term">PLC_DEBUG_SSH_KEY_PUB</span></dt>
848 Default: /etc/planetlab/debug_ssh_key.pub</p>
849 <p>The SSH public key used to access the root
850 account on your nodes when they are in Debug mode.</p>
852 <dt><span class="term">PLC_DEBUG_SSH_KEY</span></dt>
857 Default: /etc/planetlab/debug_ssh_key.rsa</p>
858 <p>The SSH private key used to access the root
859 account on your nodes when they are in Debug mode.</p>
861 <dt><span class="term">PLC_ROOT_GPG_KEY_PUB</span></dt>
866 Default: /etc/planetlab/pubring.gpg</p>
867 <p>The GPG public keyring used to sign the Boot
868 Manager and all node packages.</p>
870 <dt><span class="term">PLC_ROOT_GPG_KEY</span></dt>
875 Default: /etc/planetlab/secring.gpg</p>
876 <p>The SSH private key used to access the root
877 account on your nodes.</p>
879 <dt><span class="term">PLC_MA_SA_NAMESPACE</span></dt>
885 <p>The namespace of your MA/SA. This should be a
886 globally unique value assigned by PlanetLab
889 <dt><span class="term">PLC_MA_SA_SSL_KEY</span></dt>
894 Default: /etc/planetlab/ma_sa_ssl.key</p>
895 <p>The SSL private key used for signing documents
896 with the signature of your MA/SA. If non-existent, one will
899 <dt><span class="term">PLC_MA_SA_SSL_CRT</span></dt>
904 Default: /etc/planetlab/ma_sa_ssl.crt</p>
905 <p>The corresponding SSL public certificate. By
906 default, this certificate is self-signed. You may replace
907 the certificate later with one signed by the PLC root
910 <dt><span class="term">PLC_MA_SA_CA_SSL_CRT</span></dt>
915 Default: /etc/planetlab/ma_sa_ca_ssl.crt</p>
916 <p>If applicable, the certificate of the PLC root
917 CA. If your MA/SA certificate is self-signed, then this file
918 is the same as your MA/SA certificate.</p>
920 <dt><span class="term">PLC_MA_SA_CA_SSL_KEY_PUB</span></dt>
925 Default: /etc/planetlab/ma_sa_ca_ssl.pub</p>
926 <p>If applicable, the public key of the PLC root
927 CA. If your MA/SA certificate is self-signed, then this file
928 is the same as your MA/SA public key.</p>
930 <dt><span class="term">PLC_MA_SA_API_CRT</span></dt>
935 Default: /etc/planetlab/ma_sa_api.xml</p>
936 <p>The API Certificate is your MA/SA public key
937 embedded in a digitally signed XML document. By default,
938 this document is self-signed. You may replace this
939 certificate later with one signed by the PLC root
942 <dt><span class="term">PLC_NET_DNS1</span></dt>
947 Default: 127.0.0.1</p>
948 <p>Primary DNS server address.</p>
950 <dt><span class="term">PLC_NET_DNS2</span></dt>
956 <p>Secondary DNS server address.</p>
958 <dt><span class="term">PLC_DNS_ENABLED</span></dt>
964 <p>Enable the internal DNS server. The server does
965 not provide reverse resolution and is not a production
966 quality or scalable DNS solution. Use the internal DNS
967 server only for small deployments or for
970 <dt><span class="term">PLC_MAIL_ENABLED</span></dt>
976 <p>Set to false to suppress all e-mail notifications
979 <dt><span class="term">PLC_MAIL_SUPPORT_ADDRESS</span></dt>
984 Default: root+support@localhost.localdomain</p>
985 <p>This address is used for support
986 requests. Support requests may include traffic complaints,
987 security incident reporting, web site malfunctions, and
988 general requests for information. We recommend that the
989 address be aliased to a ticketing system such as Request
992 <dt><span class="term">PLC_MAIL_BOOT_ADDRESS</span></dt>
997 Default: root+install-msgs@localhost.localdomain</p>
998 <p>The API will notify this address when a problem
999 occurs during node installation or boot.</p>
1001 <dt><span class="term">PLC_MAIL_SLICE_ADDRESS</span></dt>
1006 Default: root+SLICE@localhost.localdomain</p>
1007 <p>This address template is used for sending
1008 e-mail notifications to slices. SLICE will be replaced with
1009 the name of the slice.</p>
1011 <dt><span class="term">PLC_DB_ENABLED</span></dt>
1017 <p>Enable the database server on this
1020 <dt><span class="term">PLC_DB_TYPE</span></dt>
1025 Default: postgresql</p>
1026 <p>The type of database server. Currently, only
1027 postgresql is supported.</p>
1029 <dt><span class="term">PLC_DB_HOST</span></dt>
1034 Default: localhost.localdomain</p>
1035 <p>The fully qualified hostname of the database
1038 <dt><span class="term">PLC_DB_IP</span></dt>
1043 Default: 127.0.0.1</p>
1044 <p>The IP address of the database server, if not
1045 resolvable by the configured DNS servers.</p>
1047 <dt><span class="term">PLC_DB_PORT</span></dt>
1053 <p>The TCP port number through which the database
1054 server should be accessed.</p>
1056 <dt><span class="term">PLC_DB_NAME</span></dt>
1061 Default: planetlab3</p>
1062 <p>The name of the database to access.</p>
1064 <dt><span class="term">PLC_DB_USER</span></dt>
1069 Default: pgsqluser</p>
1070 <p>The username to use when accessing the
1073 <dt><span class="term">PLC_DB_PASSWORD</span></dt>
1079 <p>The password to use when accessing the
1080 database. If left blank, one will be
1083 <dt><span class="term">PLC_API_ENABLED</span></dt>
1089 <p>Enable the API server on this
1092 <dt><span class="term">PLC_API_DEBUG</span></dt>
1098 <p>Enable verbose API debugging. Do not enable on
1099 a production system!</p>
1101 <dt><span class="term">PLC_API_HOST</span></dt>
1106 Default: localhost.localdomain</p>
1107 <p>The fully qualified hostname of the API
1110 <dt><span class="term">PLC_API_IP</span></dt>
1115 Default: 127.0.0.1</p>
1116 <p>The IP address of the API server, if not
1117 resolvable by the configured DNS servers.</p>
1119 <dt><span class="term">PLC_API_PORT</span></dt>
1125 <p>The TCP port number through which the API
1126 should be accessed. Warning: SSL (port 443) access is not
1127 fully supported by the website code yet. We recommend that
1128 port 80 be used for now and that the API server either run
1129 on the same machine as the web server, or that they both be
1130 on a secure wired network.</p>
1132 <dt><span class="term">PLC_API_PATH</span></dt>
1137 Default: /PLCAPI/</p>
1138 <p>The base path of the API URL.</p>
1140 <dt><span class="term">PLC_API_MAINTENANCE_USER</span></dt>
1145 Default: maint@localhost.localdomain</p>
1146 <p>The username of the maintenance account. This
1147 account is used by local scripts that perform automated
1148 tasks, and cannot be used for normal logins.</p>
1150 <dt><span class="term">PLC_API_MAINTENANCE_PASSWORD</span></dt>
1156 <p>The password of the maintenance account. If
1157 left blank, one will be generated. We recommend that the
1158 password be changed periodically.</p>
1160 <dt><span class="term">PLC_API_MAINTENANCE_SOURCES</span></dt>
1166 <p>A space-separated list of IP addresses allowed
1167 to access the API through the maintenance account. The value
1168 of this variable is set automatically to allow only the API,
1169 web, and boot servers, and should not be
1172 <dt><span class="term">PLC_API_SSL_KEY</span></dt>
1177 Default: /etc/planetlab/api_ssl.key</p>
1178 <p>The SSL private key to use for encrypting HTTPS
1179 traffic. If non-existent, one will be
1182 <dt><span class="term">PLC_API_SSL_CRT</span></dt>
1187 Default: /etc/planetlab/api_ssl.crt</p>
1188 <p>The corresponding SSL public certificate. By
1189 default, this certificate is self-signed. You may replace
1190 the certificate later with one signed by a root
1193 <dt><span class="term">PLC_API_CA_SSL_CRT</span></dt>
1198 Default: /etc/planetlab/api_ca_ssl.crt</p>
1199 <p>The certificate of the root CA, if any, that
1200 signed your server certificate. If your server certificate is
1201 self-signed, then this file is the same as your server
1204 <dt><span class="term">PLC_WWW_ENABLED</span></dt>
1210 <p>Enable the web server on this
1213 <dt><span class="term">PLC_WWW_DEBUG</span></dt>
1219 <p>Enable debugging output on web pages. Do not
1220 enable on a production system!</p>
1222 <dt><span class="term">PLC_WWW_HOST</span></dt>
1227 Default: localhost.localdomain</p>
1228 <p>The fully qualified hostname of the web
1231 <dt><span class="term">PLC_WWW_IP</span></dt>
1236 Default: 127.0.0.1</p>
1237 <p>The IP address of the web server, if not
1238 resolvable by the configured DNS servers.</p>
1240 <dt><span class="term">PLC_WWW_PORT</span></dt>
1246 <p>The TCP port number through which the
1247 unprotected portions of the web site should be
1250 <dt><span class="term">PLC_WWW_SSL_PORT</span></dt>
1256 <p>The TCP port number through which the protected
1257 portions of the web site should be accessed.</p>
1259 <dt><span class="term">PLC_WWW_SSL_KEY</span></dt>
1264 Default: /etc/planetlab/www_ssl.key</p>
1265 <p>The SSL private key to use for encrypting HTTPS
1266 traffic. If non-existent, one will be
1269 <dt><span class="term">PLC_WWW_SSL_CRT</span></dt>
1274 Default: /etc/planetlab/www_ssl.crt</p>
1275 <p>The corresponding SSL public certificate for
1276 the HTTP server. By default, this certificate is
1277 self-signed. You may replace the certificate later with one
1278 signed by a root CA.</p>
1280 <dt><span class="term">PLC_WWW_CA_SSL_CRT</span></dt>
1285 Default: /etc/planetlab/www_ca_ssl.crt</p>
1286 <p>The certificate of the root CA, if any, that
1287 signed your server certificate. If your server certificate is
1288 self-signed, then this file is the same as your server
1291 <dt><span class="term">PLC_BOOT_ENABLED</span></dt>
1297 <p>Enable the boot server on this
1300 <dt><span class="term">PLC_BOOT_HOST</span></dt>
1305 Default: localhost.localdomain</p>
1306 <p>The fully qualified hostname of the boot
1309 <dt><span class="term">PLC_BOOT_IP</span></dt>
1314 Default: 127.0.0.1</p>
1315 <p>The IP address of the boot server, if not
1316 resolvable by the configured DNS servers.</p>
1318 <dt><span class="term">PLC_BOOT_PORT</span></dt>
1324 <p>The TCP port number through which the
1325 unprotected portions of the boot server should be
1328 <dt><span class="term">PLC_BOOT_SSL_PORT</span></dt>
1334 <p>The TCP port number through which the protected
1335 portions of the boot server should be
1338 <dt><span class="term">PLC_BOOT_SSL_KEY</span></dt>
1343 Default: /etc/planetlab/boot_ssl.key</p>
1344 <p>The SSL private key to use for encrypting HTTPS
1347 <dt><span class="term">PLC_BOOT_SSL_CRT</span></dt>
1352 Default: /etc/planetlab/boot_ssl.crt</p>
1353 <p>The corresponding SSL public certificate for
1354 the HTTP server. By default, this certificate is
1355 self-signed. You may replace the certificate later with one
1356 signed by a root CA.</p>
1358 <dt><span class="term">PLC_BOOT_CA_SSL_CRT</span></dt>
1363 Default: /etc/planetlab/boot_ca_ssl.crt</p>
1364 <p>The certificate of the root CA, if any, that
1365 signed your server certificate. If your server certificate is
1366 self-signed, then this file is the same as your server
1371 <div class="appendix" lang="en">
1372 <h2 class="title" style="clear: both">
1373 <a name="VariablesDevel"></a>B. Development configuration variables (for <span class="emphasis"><em>myplc-devel</em></span>)</h2>
1374 <div class="variablelist"><dl>
1375 <dt><span class="term">PLC_DEVEL_FEDORA_RELEASE</span></dt>
1381 <p>Version number of Fedora Core upon which to
1382 base the build environment. Warning: Currently, only Fedora
1383 Core 4 is supported.</p>
1385 <dt><span class="term">PLC_DEVEL_FEDORA_ARCH</span></dt>
1391 <p>Base architecture of the build
1392 environment. Warning: Currently, only i386 is
1395 <dt><span class="term">PLC_DEVEL_FEDORA_URL</span></dt>
1400 Default: file:///usr/share/mirrors/fedora</p>
1401 <p>Fedora Core mirror from which to install
1404 <dt><span class="term">PLC_DEVEL_CVSROOT</span></dt>
1410 <p>CVSROOT to use when checking out code.</p>
1412 <dt><span class="term">PLC_DEVEL_BOOTSTRAP</span></dt>
1418 <p>Controls whether MyPLC should be built inside
1419 of its own development environment.</p>
1423 <div class="bibliography">
1424 <div class="titlepage"><div><div><h2 class="title">
1425 <a name="id2898373"></a>Bibliography</h2></div></div></div>
1426 <div class="biblioentry">
1427 <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
1428 Technical Contact's Guide</a></i>. </span></p>
1431 </div><?php require('footer.php'); ?>
1432 dummy 1.11 for cathing up with the xml numbering
1435 // DO NOT EDIT. This file was automatically generated from
1436 // DocBook XML. See plc_www/doc/README.
1438 $_title= "MyPLC User's Guide";
1440 require_once('session.php');
1441 require_once('header.php');
1442 require_once('nav.php');
1444 ?><div class="article" lang="en">
1445 <div class="titlepage">
1447 <div><h1 class="title">
1448 <a name="id2795259"></a>MyPLC User's Guide</h1></div>
1449 <div><div class="author"><h3 class="author"><span class="firstname">Mark Huang</span></h3></div></div>
1450 <div><div class="revhistory"><table border="1" width="100%" summary="Revision history">
1451 <tr><th align="left" valign="top" colspan="3"><b>Revision History</b></th></tr>
1453 <td align="left">Revision 1.0</td>
1454 <td align="left">April 7, 2006</td>
1455 <td align="left">MLH</td>
1457 <tr><td align="left" colspan="3"><p>Initial draft.</p></td></tr>
1459 <td align="left">Revision 1.1</td>
1460 <td align="left">July 19, 2006</td>
1461 <td align="left">MLH</td>
1463 <tr><td align="left" colspan="3"><p>Add development environment.</p></td></tr>
1464 </table></div></div>
1465 <div><div class="abstract">
1466 <p class="title"><b>Abstract</b></p>
1467 <p>This document describes the design, installation, and
1468 administration of MyPLC, a complete PlanetLab Central (PLC)
1469 portable installation contained within a
1470 <span><strong class="command">chroot</strong></span> jail. This document assumes advanced
1471 knowledge of the PlanetLab architecture and Linux system
1478 <p><b>Table of Contents</b></p>
1480 <dt><span class="section"><a href="#id2864719">1. Overview</a></span></dt>
1481 <dd><dl><dt><span class="section"><a href="#id2842268">1.1. Purpose of the <span class="emphasis"><em> myplc-devel
1482 </em></span> package </a></span></dt></dl></dd>
1483 <dt><span class="section"><a href="#Requirements">2. Requirements </a></span></dt>
1484 <dt><span class="section"><a href="#Installation">3. Installating and using MyPLC</a></span></dt>
1486 <dt><span class="section"><a href="#id2841677">3.1. Installing MyPLC.</a></span></dt>
1487 <dt><span class="section"><a href="#QuickStart">3.2. QuickStart </a></span></dt>
1488 <dt><span class="section"><a href="#ChangingTheConfiguration">3.3. Changing the configuration</a></span></dt>
1489 <dt><span class="section"><a href="#id2842715">3.4. Installing nodes</a></span></dt>
1490 <dt><span class="section"><a href="#id2842797">3.5. Administering nodes</a></span></dt>
1491 <dt><span class="section"><a href="#id2842898">3.6. Creating a slice</a></span></dt>
1492 <dt><span class="section"><a href="#StartupSequence">3.7. Understanding the startup sequence</a></span></dt>
1493 <dt><span class="section"><a href="#FilesInvolvedRuntime">3.8. Files and directories
1494 involved in <span class="emphasis"><em>myplc</em></span></a></span></dt>
1496 <dt><span class="section"><a href="#DevelopmentEnvironment">4. Rebuilding and customizing MyPLC</a></span></dt>
1498 <dt><span class="section"><a href="#id2894620">4.1. Installation</a></span></dt>
1499 <dt><span class="section"><a href="#FilesInvolvedDevel">4.2. Files and directories
1500 involved in <span class="emphasis"><em>myplc-devl</em></span></a></span></dt>
1501 <dt><span class="section"><a href="#id2894876">4.3. Fedora Core 4 mirror requirement</a></span></dt>
1502 <dt><span class="section"><a href="#BuildingMyPLC">4.4. Building MyPLC</a></span></dt>
1503 <dt><span class="section"><a href="#UpdatingCVS">4.5. Updating CVS</a></span></dt>
1505 <dt><span class="appendix"><a href="#VariablesRuntime">A. Configuration variables (for <span class="emphasis"><em>myplc</em></span>)</a></span></dt>
1506 <dt><span class="appendix"><a href="#VariablesDevel">B. Development configuration variables (for <span class="emphasis"><em>myplc-devel</em></span>)</a></span></dt>
1507 <dt><span class="bibliography"><a href="#id2898373">Bibliography</a></span></dt>
1510 <div class="section" lang="en">
1511 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1512 <a name="id2864719"></a>1. Overview</h2></div></div></div>
1513 <p>MyPLC is a complete PlanetLab Central (PLC) portable
1514 installation contained within a <span><strong class="command">chroot</strong></span>
1515 jail. The default installation consists of a web server, an
1516 XML-RPC API server, a boot server, and a database server: the core
1517 components of PLC. The installation is customized through an
1518 easy-to-use graphical interface. All PLC services are started up
1519 and shut down through a single script installed on the host
1520 system. The usually complex process of installing and
1521 administering the PlanetLab backend is reduced by containing PLC
1522 services within a virtual filesystem. By packaging it in such a
1523 manner, MyPLC may also be run on any modern Linux distribution,
1524 and could conceivably even run in a PlanetLab slice.</p>
1525 <div class="figure">
1526 <a name="Architecture"></a><p class="title"><b>Figure 1. MyPLC architecture</b></p>
1527 <div class="mediaobject" align="center">
1528 <img src="architecture.png" align="middle" width="270" alt="MyPLC architecture"><div class="caption"><p>MyPLC should be viewed as a single application that
1529 provides multiple functions and can run on any host
1533 <div class="section" lang="en">
1534 <div class="titlepage"><div><div><h3 class="title">
1535 <a name="id2842268"></a>1.1. Purpose of the <span class="emphasis"><em> myplc-devel
1536 </em></span> package </h3></div></div></div>
1537 <p> The <span class="emphasis"><em>myplc</em></span> package comes with all
1538 required node software, rebuilt from the public PlanetLab CVS
1539 repository. If for any reason you need to implement your own
1540 customized version of this software, you can use the
1541 <span class="emphasis"><em>myplc-devel</em></span> package instead, for setting up
1542 your own development environment, including a local CVS
1543 repository; you can then freely manage your changes and rebuild
1544 your customized version of <span class="emphasis"><em>myplc</em></span>. We also
1545 provide good practices, that will then allow you to resync your local
1546 CVS repository with any further evolution on the mainstream public
1547 PlanetLab software. </p>
1550 <div class="section" lang="en">
1551 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1552 <a name="Requirements"></a>2. Requirements </h2></div></div></div>
1553 <p> <span class="emphasis"><em>myplc</em></span> and
1554 <span class="emphasis"><em>myplc-devel</em></span> were designed as
1555 <span><strong class="command">chroot</strong></span> jails so as to reduce the requirements on
1556 your host operating system. So in theory, these distributions should
1557 work on virtually any Linux 2.6 based distribution, whether it
1558 supports rpm or not. </p>
1559 <p> However, things are never that simple and there indeed are
1560 some known limitations to this, so here are a couple notes as a
1561 recommended reading before you proceed with the installation.</p>
1562 <p> As of 9 August 2006 (i.e <span class="emphasis"><em>myplc-0.5</em></span>) :</p>
1563 <div class="itemizedlist"><ul type="disc">
1564 <li><p> The software is vastly based on <span class="emphasis"><em>Fedora
1565 Core 4</em></span>. Please note that the build server at Princeton
1566 runs <span class="emphasis"><em>Fedora Core 2</em></span>, togother with a upgraded
1570 <p> myplc and myplc-devel are known to work on both
1571 <span class="emphasis"><em>Fedora Core 2</em></span> and <span class="emphasis"><em>Fedora Core
1572 4</em></span>. Please note however that, on fc4 at least, it is
1573 highly recommended to use the <span class="application">Security Level
1574 Configuration</span> utility and to <span class="emphasis"><em>switch off
1575 SElinux</em></span> on your box because : </p>
1576 <div class="itemizedlist"><ul type="circle">
1578 myplc requires you to run SElinux as 'Permissive' at most
1581 myplc-devel requires you to turn SElinux Off.
1585 <li><p> In addition, as far as myplc is concerned, you
1586 need to check your firewall configuration since you need, of course,
1587 to open up the <span class="emphasis"><em>http</em></span> and
1588 <span class="emphasis"><em>https</em></span> ports, so as to accept connections from
1589 the managed nodes and from the users desktops. </p></li>
1592 <div class="section" lang="en">
1593 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1594 <a name="Installation"></a>3. Installating and using MyPLC</h2></div></div></div>
1595 <p>Though internally composed of commodity software
1596 subpackages, MyPLC should be treated as a monolithic software
1597 application. MyPLC is distributed as single RPM package that has
1598 no external dependencies, allowing it to be installed on
1599 practically any Linux 2.6 based distribution.</p>
1600 <div class="section" lang="en">
1601 <div class="titlepage"><div><div><h3 class="title">
1602 <a name="id2841677"></a>3.1. Installing MyPLC.</h3></div></div></div>
1603 <div class="itemizedlist"><ul type="disc">
1605 <p>If your distribution supports RPM:</p>
1606 <pre class="programlisting"># rpm -U http://build.planet-lab.org/build/myplc-0_4-rc1/RPMS/i386/myplc-0.4-1.planetlab.i386.rpm</pre>
1609 <p>If your distribution does not support RPM:</p>
1610 <pre class="programlisting"># cd /tmp
1611 # wget http://build.planet-lab.org/build/myplc-0_4-rc1/RPMS/i386/myplc-0.4-1.planetlab.i386.rpm
1613 # rpm2cpio /tmp/myplc-0.4-1.planetlab.i386.rpm | cpio -diu</pre>
1616 <p> The <a href="#FilesInvolvedRuntime" title="3.8. Files and directories
1617 involved in myplc">Section 3.8, “ Files and directories
1618 involved in <span class="emphasis"><em>myplc</em></span>”</a> below explains in
1619 details the installation strategy and the miscellaneous files and
1620 directories involved.</p>
1622 <div class="section" lang="en">
1623 <div class="titlepage"><div><div><h3 class="title">
1624 <a name="QuickStart"></a>3.2. QuickStart </h3></div></div></div>
1625 <p> On a Red Hat or Fedora host system, it is customary to use
1626 the <span><strong class="command">service</strong></span> command to invoke System V init
1627 scripts. As the examples suggest, the service must be started as root:</p>
1628 <div class="example">
1629 <a name="id2841851"></a><p class="title"><b>Example 1. Starting MyPLC:</b></p>
1630 <pre class="programlisting"># service plc start</pre>
1632 <div class="example">
1633 <a name="id2841863"></a><p class="title"><b>Example 2. Stopping MyPLC:</b></p>
1634 <pre class="programlisting"># service plc stop</pre>
1636 <p> In <a href="#StartupSequence" title="3.7. Understanding the startup sequence">Section 3.7, “Understanding the startup sequence”</a>, we provide greater
1637 details that might be helpful in the case where the service does
1638 not seem to take off correctly.</p>
1639 <p>Like all other registered System V init services, MyPLC is
1640 started and shut down automatically when your host system boots
1641 and powers off. You may disable automatic startup by invoking the
1642 <span><strong class="command">chkconfig</strong></span> command on a Red Hat or Fedora host
1644 <div class="example">
1645 <a name="id2841901"></a><p class="title"><b>Example 3. Disabling automatic startup of MyPLC.</b></p>
1646 <pre class="programlisting"># chkconfig plc off</pre>
1648 <div class="example">
1649 <a name="id2842528"></a><p class="title"><b>Example 4. Re-enabling automatic startup of MyPLC.</b></p>
1650 <pre class="programlisting"># chkconfig plc on</pre>
1653 <div class="section" lang="en">
1654 <div class="titlepage"><div><div><h3 class="title">
1655 <a name="ChangingTheConfiguration"></a>3.3. Changing the configuration</h3></div></div></div>
1656 <p>After verifying that MyPLC is working correctly, shut it
1657 down and begin changing some of the default variable
1658 values. Shut down MyPLC with <span><strong class="command">service plc stop</strong></span>
1659 (see <a href="#QuickStart" title="3.2. QuickStart ">Section 3.2, “ QuickStart ”</a>). With a text
1660 editor, open the file
1661 <code class="filename">/etc/planetlab/plc_config.xml</code>. This file is
1662 a self-documenting configuration file written in XML. Variables
1663 are divided into categories. Variable identifiers must be
1664 alphanumeric, plus underscore. A variable is referred to
1665 canonically as the uppercase concatenation of its category
1666 identifier, an underscore, and its variable identifier. Thus, a
1667 variable with an <code class="literal">id</code> of
1668 <code class="literal">slice_prefix</code> in the <code class="literal">plc</code>
1669 category is referred to canonically as
1670 <code class="envar">PLC_SLICE_PREFIX</code>.</p>
1671 <p>The reason for this convention is that during MyPLC
1672 startup, <code class="filename">plc_config.xml</code> is translated into
1673 several different languages—shell, PHP, and
1674 Python—so that scripts written in each of these languages
1675 can refer to the same underlying configuration. Most MyPLC
1676 scripts are written in shell, so the convention for shell
1677 variables predominates.</p>
1678 <p>The variables that you should change immediately are:</p>
1679 <div class="itemizedlist"><ul type="disc">
1680 <li><p><code class="envar">PLC_NAME</code>: Change this to the
1681 name of your PLC installation.</p></li>
1682 <li><p><code class="envar">PLC_ROOT_PASSWORD</code>: Change this
1683 to a more secure password.</p></li>
1684 <li><p><code class="envar">PLC_MAIL_SUPPORT_ADDRESS</code>:
1685 Change this to the e-mail address at which you would like to
1686 receive support requests.</p></li>
1687 <li><p><code class="envar">PLC_DB_HOST</code>,
1688 <code class="envar">PLC_DB_IP</code>, <code class="envar">PLC_API_HOST</code>,
1689 <code class="envar">PLC_API_IP</code>, <code class="envar">PLC_WWW_HOST</code>,
1690 <code class="envar">PLC_WWW_IP</code>, <code class="envar">PLC_BOOT_HOST</code>,
1691 <code class="envar">PLC_BOOT_IP</code>: Change all of these to the
1692 preferred FQDN and external IP address of your host
1695 <p>The full set of applicable variables is described in <a href="#VariablesDevel" title="B. Development configuration variables (for myplc-devel)">Appendix B, <i>Development configuration variables (for <span class="emphasis"><em>myplc-devel</em></span>)</i></a>. After changing these variables,
1696 save the file, then restart MyPLC with <span><strong class="command">service plc
1697 start</strong></span>. You should notice that the password of the
1698 default administrator account is no longer
1699 <code class="literal">root</code>, and that the default site name includes
1700 the name of your PLC installation instead of PlanetLab.</p>
1702 <div class="section" lang="en">
1703 <div class="titlepage"><div><div><h3 class="title">
1704 <a name="id2842715"></a>3.4. Installing nodes</h3></div></div></div>
1705 <p>Install your first node by clicking <code class="literal">Add
1706 Node</code> under the <code class="literal">Nodes</code> tab. Fill in
1707 all the appropriate details, then click
1708 <code class="literal">Add</code>. Download the node's configuration file
1709 by clicking <code class="literal">Download configuration file</code> on
1710 the <span class="bold"><strong>Node Details</strong></span> page for the
1711 node. Save it to a floppy disk or USB key as detailed in [<a href="#TechsGuide" title="[TechsGuide]">1</a>].</p>
1712 <p>Follow the rest of the instructions in [<a href="#TechsGuide" title="[TechsGuide]">1</a>] for creating a Boot CD and installing
1713 the node, except download the Boot CD image from the
1714 <code class="filename">/download</code> directory of your PLC
1715 installation, not from PlanetLab Central. The images located
1716 here are customized for your installation. If you change the
1717 hostname of your boot server (<code class="envar">PLC_BOOT_HOST</code>), or
1718 if the SSL certificate of your boot server expires, MyPLC will
1719 regenerate it and rebuild the Boot CD with the new
1720 certificate. If this occurs, you must replace all Boot CDs
1721 created before the certificate was regenerated.</p>
1722 <p>The installation process for a node has significantly
1723 improved since PlanetLab 3.3. It should now take only a few
1724 seconds for a new node to become ready to create slices.</p>
1726 <div class="section" lang="en">
1727 <div class="titlepage"><div><div><h3 class="title">
1728 <a name="id2842797"></a>3.5. Administering nodes</h3></div></div></div>
1729 <p>You may administer nodes as <code class="literal">root</code> by
1730 using the SSH key stored in
1731 <code class="filename">/etc/planetlab/root_ssh_key.rsa</code>.</p>
1732 <div class="example">
1733 <a name="id2842820"></a><p class="title"><b>Example 5. Accessing nodes via SSH. Replace
1734 <code class="literal">node</code> with the hostname of the node.</b></p>
1735 <pre class="programlisting">ssh -i /etc/planetlab/root_ssh_key.rsa root@node</pre>
1737 <p>Besides the standard Linux log files located in
1738 <code class="filename">/var/log</code>, several other files can give you
1739 clues about any problems with active processes:</p>
1740 <div class="itemizedlist"><ul type="disc">
1741 <li><p><code class="filename">/var/log/pl_nm</code>: The log
1742 file for the Node Manager.</p></li>
1743 <li><p><code class="filename">/vservers/pl_conf/var/log/pl_conf</code>:
1744 The log file for the Slice Creation Service.</p></li>
1745 <li><p><code class="filename">/var/log/propd</code>: The log
1746 file for Proper, the service which allows certain slices to
1747 perform certain privileged operations in the root
1749 <li><p><code class="filename">/vservers/pl_netflow/var/log/netflow.log</code>:
1750 The log file for PlanetFlow, the network traffic auditing
1754 <div class="section" lang="en">
1755 <div class="titlepage"><div><div><h3 class="title">
1756 <a name="id2842898"></a>3.6. Creating a slice</h3></div></div></div>
1757 <p>Create a slice by clicking <code class="literal">Create Slice</code>
1758 under the <code class="literal">Slices</code> tab. Fill in all the
1759 appropriate details, then click <code class="literal">Create</code>. Add
1760 nodes to the slice by clicking <code class="literal">Manage Nodes</code>
1761 on the <span class="bold"><strong>Slice Details</strong></span> page for
1763 <p>A <span><strong class="command">cron</strong></span> job runs every five minutes and
1765 <code class="filename">/plc/data/var/www/html/xml/slices-0.5.xml</code>
1766 with information about current slice state. The Slice Creation
1767 Service running on every node polls this file every ten minutes
1768 to determine if it needs to create or delete any slices. You may
1769 accelerate this process manually if desired.</p>
1770 <div class="example">
1771 <a name="id2842960"></a><p class="title"><b>Example 6. Forcing slice creation on a node.</b></p>
1772 <pre class="programlisting"># Update slices.xml immediately
1773 service plc start crond
1775 # Kick the Slice Creation Service on a particular node.
1776 ssh -i /etc/planetlab/root_ssh_key.rsa root@node \
1777 vserver pl_conf exec service pl_conf restart</pre>
1780 <div class="section" lang="en">
1781 <div class="titlepage"><div><div><h3 class="title">
1782 <a name="StartupSequence"></a>3.7. Understanding the startup sequence</h3></div></div></div>
1783 <p>During service startup described in <a href="#QuickStart" title="3.2. QuickStart ">Section 3.2, “ QuickStart ”</a>, observe the output of this command for
1784 any failures. If no failures occur, you should see output similar
1785 to the following:</p>
1786 <div class="example">
1787 <a name="id2893858"></a><p class="title"><b>Example 7. A successful MyPLC startup.</b></p>
1788 <pre class="programlisting">Mounting PLC: [ OK ]
1789 PLC: Generating network files: [ OK ]
1790 PLC: Starting system logger: [ OK ]
1791 PLC: Starting database server: [ OK ]
1792 PLC: Generating SSL certificates: [ OK ]
1793 PLC: Configuring the API: [ OK ]
1794 PLC: Updating GPG keys: [ OK ]
1795 PLC: Generating SSH keys: [ OK ]
1796 PLC: Starting web server: [ OK ]
1797 PLC: Bootstrapping the database: [ OK ]
1798 PLC: Starting DNS server: [ OK ]
1799 PLC: Starting crond: [ OK ]
1800 PLC: Rebuilding Boot CD: [ OK ]
1801 PLC: Rebuilding Boot Manager: [ OK ]
1802 PLC: Signing node packages: [ OK ]
1805 <p>If <code class="filename">/plc/root</code> is mounted successfully, a
1806 complete log file of the startup process may be found at
1807 <code class="filename">/plc/root/var/log/boot.log</code>. Possible reasons
1808 for failure of each step include:</p>
1809 <div class="itemizedlist"><ul type="disc">
1810 <li><p><code class="literal">Mounting PLC</code>: If this step
1811 fails, first ensure that you started MyPLC as root. Check
1812 <code class="filename">/etc/sysconfig/plc</code> to ensure that
1813 <code class="envar">PLC_ROOT</code> and <code class="envar">PLC_DATA</code> refer to the
1814 right locations. You may also have too many existing loopback
1815 mounts, or your kernel may not support loopback mounting, bind
1816 mounting, or the ext3 filesystem. Try freeing at least one
1817 loopback device, or re-compiling your kernel to support loopback
1818 mounting, bind mounting, and the ext3 filesystem. If you see an
1819 error similar to <code class="literal">Permission denied while trying to open
1820 /plc/root.img</code>, then SELinux may be enabled. See <a href="#Requirements" title="2. Requirements ">Section 2, “ Requirements ”</a> above for details.</p></li>
1821 <li><p><code class="literal">Starting database server</code>: If
1822 this step fails, check
1823 <code class="filename">/plc/root/var/log/pgsql</code> and
1824 <code class="filename">/plc/root/var/log/boot.log</code>. The most common
1825 reason for failure is that the default PostgreSQL port, TCP port
1826 5432, is already in use. Check that you are not running a
1827 PostgreSQL server on the host system.</p></li>
1828 <li><p><code class="literal">Starting web server</code>: If this
1830 <code class="filename">/plc/root/var/log/httpd/error_log</code> and
1831 <code class="filename">/plc/root/var/log/boot.log</code> for obvious
1832 errors. The most common reason for failure is that the default
1833 web ports, TCP ports 80 and 443, are already in use. Check that
1834 you are not running a web server on the host
1836 <li><p><code class="literal">Bootstrapping the database</code>:
1837 If this step fails, it is likely that the previous step
1838 (<code class="literal">Starting web server</code>) also failed. Another
1839 reason that it could fail is if <code class="envar">PLC_API_HOST</code> (see
1840 <a href="#ChangingTheConfiguration" title="3.3. Changing the configuration">Section 3.3, “Changing the configuration”</a>) does not resolve to
1841 the host on which the API server has been enabled. By default,
1842 all services, including the API server, are enabled and run on
1843 the same host, so check that <code class="envar">PLC_API_HOST</code> is
1844 either <code class="filename">localhost</code> or resolves to a local IP
1846 <li><p><code class="literal">Starting crond</code>: If this step
1847 fails, it is likely that the previous steps (<code class="literal">Starting
1848 web server</code> and <code class="literal">Bootstrapping the
1849 database</code>) also failed. If not, check
1850 <code class="filename">/plc/root/var/log/boot.log</code> for obvious
1851 errors. This step starts the <span><strong class="command">cron</strong></span> service and
1852 generates the initial set of XML files that the Slice Creation
1853 Service uses to determine slice state.</p></li>
1855 <p>If no failures occur, then MyPLC should be active with a
1856 default configuration. Open a web browser on the host system and
1857 visit <code class="literal">http://localhost/</code>, which should bring you
1858 to the front page of your PLC installation. The password of the
1859 default administrator account
1860 <code class="literal">root@localhost.localdomain</code> (set by
1861 <code class="envar">PLC_ROOT_USER</code>) is <code class="literal">root</code> (set by
1862 <code class="envar">PLC_ROOT_PASSWORD</code>).</p>
1864 <div class="section" lang="en">
1865 <div class="titlepage"><div><div><h3 class="title">
1866 <a name="FilesInvolvedRuntime"></a>3.8. Files and directories
1867 involved in <span class="emphasis"><em>myplc</em></span></h3></div></div></div>
1868 <p>MyPLC installs the following files and directories:</p>
1869 <div class="orderedlist"><ol type="1">
1870 <li><p><code class="filename">/plc/root.img</code>: The main
1871 root filesystem of the MyPLC application. This file is an
1872 uncompressed ext3 filesystem that is loopback mounted on
1873 <code class="filename">/plc/root</code> when MyPLC starts. This
1874 filesystem, even when mounted, should be treated as an opaque
1875 binary that can and will be replaced in its entirety by any
1876 upgrade of MyPLC.</p></li>
1877 <li><p><code class="filename">/plc/root</code>: The mount point
1878 for <code class="filename">/plc/root.img</code>. Once the root filesystem
1879 is mounted, all MyPLC services run in a
1880 <span><strong class="command">chroot</strong></span> jail based in this
1883 <p><code class="filename">/plc/data</code>: The directory where user
1884 data and generated files are stored. This directory is bind
1885 mounted onto <code class="filename">/plc/root/data</code> so that it is
1886 accessible as <code class="filename">/data</code> from within the
1887 <span><strong class="command">chroot</strong></span> jail. Files in this directory are
1888 marked with <span><strong class="command">%config(noreplace)</strong></span> in the
1889 RPM. That is, during an upgrade of MyPLC, if a file has not
1890 changed since the last installation or upgrade of MyPLC, it is
1891 subject to upgrade and replacement. If the file has changed,
1892 the new version of the file will be created with a
1893 <code class="filename">.rpmnew</code> extension. Symlinks within the
1894 MyPLC root filesystem ensure that the following directories
1895 (relative to <code class="filename">/plc/root</code>) are stored
1896 outside the MyPLC filesystem image:</p>
1897 <div class="itemizedlist"><ul type="disc">
1898 <li><p><code class="filename">/etc/planetlab</code>: This
1899 directory contains the configuration files, keys, and
1900 certificates that define your MyPLC
1901 installation.</p></li>
1902 <li><p><code class="filename">/var/lib/pgsql</code>: This
1903 directory contains PostgreSQL database
1905 <li><p><code class="filename">/var/www/html/alpina-logs</code>: This
1906 directory contains node installation logs.</p></li>
1907 <li><p><code class="filename">/var/www/html/boot</code>: This
1908 directory contains the Boot Manager, customized for your MyPLC
1909 installation, and its data files.</p></li>
1910 <li><p><code class="filename">/var/www/html/download</code>: This
1911 directory contains Boot CD images, customized for your MyPLC
1912 installation.</p></li>
1913 <li><p><code class="filename">/var/www/html/install-rpms</code>: This
1914 directory is where you should install node package updates,
1915 if any. By default, nodes are installed from the tarball
1917 <code class="filename">/var/www/html/boot/PlanetLab-Bootstrap.tar.bz2</code>,
1918 which is pre-built from the latest PlanetLab Central
1919 sources, and installed as part of your MyPLC
1920 installation. However, nodes will attempt to install any
1921 newer RPMs located in
1922 <code class="filename">/var/www/html/install-rpms/planetlab</code>,
1923 after initial installation and periodically thereafter. You
1924 must run <span><strong class="command">yum-arch</strong></span> and
1925 <span><strong class="command">createrepo</strong></span> to update the
1926 <span><strong class="command">yum</strong></span> caches in this directory after
1927 installing a new RPM. PlanetLab Central cannot support any
1928 changes to this directory.</p></li>
1929 <li><p><code class="filename">/var/www/html/xml</code>: This
1930 directory contains various XML files that the Slice Creation
1931 Service uses to determine the state of slices. These XML
1932 files are refreshed periodically by <span><strong class="command">cron</strong></span>
1933 jobs running in the MyPLC root.</p></li>
1936 <li><p><a name="MyplcInitScripts"></a><code class="filename">/etc/init.d/plc</code>: This file
1937 is a System V init script installed on your host filesystem,
1938 that allows you to start up and shut down MyPLC with a single
1939 command, as described in <a href="#QuickStart" title="3.2. QuickStart ">Section 3.2, “ QuickStart ”</a>.</p></li>
1940 <li><p><code class="filename">/etc/sysconfig/plc</code>: This
1941 file is a shell script fragment that defines the variables
1942 <code class="envar">PLC_ROOT</code> and <code class="envar">PLC_DATA</code>. By default,
1943 the values of these variables are <code class="filename">/plc/root</code>
1944 and <code class="filename">/plc/data</code>, respectively. If you wish,
1945 you may move your MyPLC installation to another location on your
1946 host filesystem and edit the values of these variables
1947 appropriately, but you will break the RPM upgrade
1948 process. PlanetLab Central cannot support any changes to this
1950 <li><p><code class="filename">/etc/planetlab</code>: This
1951 symlink to <code class="filename">/plc/data/etc/planetlab</code> is
1952 installed on the host system for convenience.</p></li>
1956 <div class="section" lang="en">
1957 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1958 <a name="DevelopmentEnvironment"></a>4. Rebuilding and customizing MyPLC</h2></div></div></div>
1959 <p>The MyPLC package, though distributed as an RPM, is not a
1960 traditional package that can be easily rebuilt from SRPM. The
1961 requisite build environment is quite extensive and numerous
1962 assumptions are made throughout the PlanetLab source code base,
1963 that the build environment is based on Fedora Core 4 and that
1964 access to a complete Fedora Core 4 mirror is available.</p>
1965 <p>For this reason, it is recommended that you only rebuild
1966 MyPLC (or any of its components) from within the MyPLC development
1967 environment. The MyPLC development environment is similar to MyPLC
1968 itself in that it is a portable filesystem contained within a
1969 <span><strong class="command">chroot</strong></span> jail. The filesystem contains all the
1970 necessary tools required to rebuild MyPLC, as well as a snapshot
1971 of the PlanetLab source code base in the form of a local CVS
1973 <div class="section" lang="en">
1974 <div class="titlepage"><div><div><h3 class="title">
1975 <a name="id2894620"></a>4.1. Installation</h3></div></div></div>
1976 <p>Install the MyPLC development environment similarly to how
1977 you would install MyPLC. You may install both packages on the same
1978 host system if you wish. As with MyPLC, the MyPLC development
1979 environment should be treated as a monolithic software
1980 application, and any files present in the
1981 <span><strong class="command">chroot</strong></span> jail should not be modified directly, as
1982 they are subject to upgrade.</p>
1983 <div class="itemizedlist"><ul type="disc">
1985 <p>If your distribution supports RPM:</p>
1986 <pre class="programlisting"># rpm -U http://build.planet-lab.org/build/myplc-0_4-rc2/RPMS/i386/myplc-devel-0.4-2.planetlab.i386.rpm</pre>
1989 <p>If your distribution does not support RPM:</p>
1990 <pre class="programlisting"># cd /tmp
1991 # wget http://build.planet-lab.org/build/myplc-0_4-rc2/RPMS/i386/myplc-devel-0.4-2.planetlab.i386.rpm
1993 # rpm2cpio /tmp/myplc-devel-0.4-2.planetlab.i386.rpm | cpio -diu</pre>
1997 <div class="section" lang="en">
1998 <div class="titlepage"><div><div><h3 class="title">
1999 <a name="FilesInvolvedDevel"></a>4.2. Files and directories
2000 involved in <span class="emphasis"><em>myplc-devl</em></span></h3></div></div></div>
2001 <p>The MyPLC development environment installs the following
2002 files and directories:</p>
2003 <div class="itemizedlist"><ul type="disc">
2004 <li><p><code class="filename">/plc/devel/root.img</code>: The
2005 main root filesystem of the MyPLC development environment. This
2006 file is an uncompressed ext3 filesystem that is loopback mounted
2007 on <code class="filename">/plc/devel/root</code> when the MyPLC
2008 development environment is initialized. This filesystem, even
2009 when mounted, should be treated as an opaque binary that can and
2010 will be replaced in its entirety by any upgrade of the MyPLC
2011 development environment.</p></li>
2012 <li><p><code class="filename">/plc/devel/root</code>: The mount
2014 <code class="filename">/plc/devel/root.img</code>.</p></li>
2016 <p><code class="filename">/plc/devel/data</code>: The directory
2017 where user data and generated files are stored. This directory
2018 is bind mounted onto <code class="filename">/plc/devel/root/data</code>
2019 so that it is accessible as <code class="filename">/data</code> from
2020 within the <span><strong class="command">chroot</strong></span> jail. Files in this
2021 directory are marked with
2022 <span><strong class="command">%config(noreplace)</strong></span> in the RPM. Symlinks
2023 ensure that the following directories (relative to
2024 <code class="filename">/plc/devel/root</code>) are stored outside the
2025 root filesystem image:</p>
2026 <div class="itemizedlist"><ul type="circle">
2027 <li><p><code class="filename">/etc/planetlab</code>: This
2028 directory contains the configuration files that define your
2029 MyPLC development environment.</p></li>
2030 <li><p><code class="filename">/cvs</code>: A
2031 snapshot of the PlanetLab source code is stored as a CVS
2032 repository in this directory. Files in this directory will
2033 <span class="bold"><strong>not</strong></span> be updated by an upgrade of
2034 <code class="filename">myplc-devel</code>. See <a href="#UpdatingCVS" title="4.5. Updating CVS">Section 4.5, “Updating CVS”</a> for more information about updating
2035 PlanetLab source code.</p></li>
2036 <li><p><code class="filename">/build</code>:
2037 Builds are stored in this directory. This directory is bind
2038 mounted onto <code class="filename">/plc/devel/root/build</code> so that
2039 it is accessible as <code class="filename">/build</code> from within the
2040 <span><strong class="command">chroot</strong></span> jail. The build scripts in this
2041 directory are themselves source controlled; see <a href="#BuildingMyPLC" title="4.4. Building MyPLC">Section 4.4, “Building MyPLC”</a> for more information about executing
2045 <li><p><code class="filename">/etc/init.d/plc-devel</code>: This file is
2046 a System V init script installed on your host filesystem, that
2047 allows you to start up and shut down the MyPLC development
2048 environment with a single command.</p></li>
2051 <div class="section" lang="en">
2052 <div class="titlepage"><div><div><h3 class="title">
2053 <a name="id2894876"></a>4.3. Fedora Core 4 mirror requirement</h3></div></div></div>
2054 <p>The MyPLC development environment requires access to a
2055 complete Fedora Core 4 i386 RPM repository, because several
2056 different filesystems based upon Fedora Core 4 are constructed
2057 during the process of building MyPLC. You may configure the
2058 location of this repository via the
2059 <code class="envar">PLC_DEVEL_FEDORA_URL</code> variable in
2060 <code class="filename">/plc/devel/data/etc/planetlab/plc_config.xml</code>. The
2061 value of the variable should be a URL that points to the top
2062 level of a Fedora mirror that provides the
2063 <code class="filename">base</code>, <code class="filename">updates</code>, and
2064 <code class="filename">extras</code> repositories, e.g.,</p>
2065 <div class="itemizedlist"><ul type="disc">
2066 <li><p><code class="filename">file:///data/fedora</code></p></li>
2067 <li><p><code class="filename">http://coblitz.planet-lab.org/pub/fedora</code></p></li>
2068 <li><p><code class="filename">ftp://mirror.cs.princeton.edu/pub/mirrors/fedora</code></p></li>
2069 <li><p><code class="filename">ftp://mirror.stanford.edu/pub/mirrors/fedora</code></p></li>
2070 <li><p><code class="filename">http://rpmfind.net/linux/fedora</code></p></li>
2072 <p>As implied by the list, the repository may be located on
2073 the local filesystem, or it may be located on a remote FTP or
2074 HTTP server. URLs beginning with <code class="filename">file://</code>
2075 should exist at the specified location relative to the root of
2076 the <span><strong class="command">chroot</strong></span> jail. For optimum performance and
2077 reproducibility, specify
2078 <code class="envar">PLC_DEVEL_FEDORA_URL=file:///data/fedora</code> and
2079 download all Fedora Core 4 RPMS into
2080 <code class="filename">/plc/devel/data/fedora</code> on the host system
2081 after installing <code class="filename">myplc-devel</code>. Use a tool
2082 such as <span><strong class="command">wget</strong></span> or <span><strong class="command">rsync</strong></span> to
2083 download the RPMS from a public mirror:</p>
2084 <div class="example">
2085 <a name="id2895018"></a><p class="title"><b>Example 8. Setting up a local Fedora Core 4 repository.</b></p>
2086 <pre class="programlisting"># mkdir -p /plc/devel/data/fedora
2087 # cd /plc/devel/data/fedora
2089 # for repo in core/4/i386/os core/updates/4/i386 extras/4/i386 ; do
2090 > wget -m -nH --cut-dirs=3 http://coblitz.planet-lab.org/pub/fedora/linux/$repo
2093 <p>Change the repository URI and <span><strong class="command">--cut-dirs</strong></span>
2094 level as needed to produce a hierarchy that resembles:</p>
2095 <pre class="programlisting">/plc/devel/data/fedora/core/4/i386/os
2096 /plc/devel/data/fedora/core/updates/4/i386
2097 /plc/devel/data/fedora/extras/4/i386</pre>
2098 <p>A list of additional Fedora Core 4 mirrors is available at
2099 <a href="http://fedora.redhat.com/Download/mirrors.html" target="_top">http://fedora.redhat.com/Download/mirrors.html</a>.</p>
2101 <div class="section" lang="en">
2102 <div class="titlepage"><div><div><h3 class="title">
2103 <a name="BuildingMyPLC"></a>4.4. Building MyPLC</h3></div></div></div>
2104 <p>All PlanetLab source code modules are built and installed
2105 as RPMS. A set of build scripts, checked into the
2106 <code class="filename">build/</code> directory of the PlanetLab CVS
2107 repository, eases the task of rebuilding PlanetLab source
2109 <p> Before you try building MyPLC, you might check the
2110 configuration, in a file named
2111 <span class="emphasis"><em>plc_config.xml</em></span> that relies on a very
2112 similar model as MyPLC, located in
2113 <span class="emphasis"><em>/etc/planetlab</em></span> within the chroot jail, or
2114 in <span class="emphasis"><em>/plc/devel/data/etc/planetlab</em></span> from the
2115 root context. The set of applicable variables is described in
2116 <a href="#VariablesDevel" title="B. Development configuration variables (for myplc-devel)">Appendix B, <i>Development configuration variables (for <span class="emphasis"><em>myplc-devel</em></span>)</i></a>. </p>
2117 <p>To build MyPLC, or any PlanetLab source code module, from
2118 within the MyPLC development environment, execute the following
2119 commands as root:</p>
2120 <div class="example">
2121 <a name="id2895119"></a><p class="title"><b>Example 9. Building MyPLC.</b></p>
2122 <pre class="programlisting"># Initialize MyPLC development environment
2123 service plc-devel start
2125 # Enter development environment
2126 chroot /plc/devel/root su -
2128 # Check out build scripts into a directory named after the current
2129 # date. This is simply a convention, it need not be followed
2130 # exactly. See build/build.sh for an example of a build script that
2131 # names build directories after CVS tags.
2132 DATE=$(date +%Y.%m.%d)
2134 cvs -d /cvs checkout -d $DATE build
2139 <p>If the build succeeds, a set of binary RPMS will be
2141 <code class="filename">/plc/devel/data/build/$DATE/RPMS/</code> that you
2143 <code class="filename">/var/www/html/install-rpms/planetlab</code>
2144 directory of your MyPLC installation (see <a href="#Installation" title="3. Installating and using MyPLC">Section 3, “Installating and using MyPLC”</a>).</p>
2146 <div class="section" lang="en">
2147 <div class="titlepage"><div><div><h3 class="title">
2148 <a name="UpdatingCVS"></a>4.5. Updating CVS</h3></div></div></div>
2149 <p>A complete snapshot of the PlanetLab source code is included
2150 with the MyPLC development environment as a CVS repository in
2151 <code class="filename">/plc/devel/data/cvs</code>. This CVS repository may
2152 be accessed like any other CVS repository. It may be accessed
2153 using an interface such as <a href="http://www.freebsd.org/projects/cvsweb.html" target="_top">CVSweb</a>,
2154 and file permissions may be altered to allow for fine-grained
2155 access control. Although the files are included with the
2156 <code class="filename">myplc-devel</code> RPM, they are <span class="bold"><strong>not</strong></span> subject to upgrade once installed. New
2157 versions of the <code class="filename">myplc-devel</code> RPM will install
2158 updated snapshot repositories in
2159 <code class="filename">/plc/devel/data/cvs-%{version}-%{release}</code>,
2160 where <code class="literal">%{version}-%{release}</code> is replaced with
2161 the version number of the RPM.</p>
2162 <p>Because the CVS repository is not automatically upgraded,
2163 if you wish to keep your local repository synchronized with the
2164 public PlanetLab repository, it is highly recommended that you
2165 use CVS's support for <a href="http://ximbiot.com/cvs/wiki/index.php?title=CVS--Concurrent_Versions_System_v1.12.12.1:_Tracking_third-party_sources" target="_top">vendor
2166 branches</a> to track changes. Vendor branches ease the task
2167 of merging upstream changes with your local modifications. To
2168 import a new snapshot into your local repository (for example,
2169 if you have just upgraded from
2170 <code class="filename">myplc-devel-0.4-2</code> to
2171 <code class="filename">myplc-devel-0.4-3</code> and you notice the new
2172 repository in <code class="filename">/plc/devel/data/cvs-0.4-3</code>),
2173 execute the following commands as root from within the MyPLC
2174 development environment:</p>
2175 <div class="example">
2176 <a name="id2895270"></a><p class="title"><b>Example 10. Updating /data/cvs from /data/cvs-0.4-3.</b></p>
2177 <p><span class="bold"><strong>Warning</strong></span>: This may cause
2178 severe, irreversible changes to be made to your local
2179 repository. Always tag your local repository before
2181 <pre class="programlisting"># Initialize MyPLC development environment
2182 service plc-devel start
2184 # Enter development environment
2185 chroot /plc/devel/root su -
2188 cvs -d /cvs rtag before-myplc-0_4-3-merge
2191 TMP=$(mktemp -d /data/export.XXXXXX)
2193 cvs -d /data/cvs-0.4-3 export -r HEAD .
2194 cvs -d /cvs import -m "PlanetLab sources from myplc-0.4-3" -ko -I ! . planetlab myplc-0_4-3
2198 <p>If there any merge conflicts, use the command suggested by
2199 CVS to help the merge. Explaining how to fix merge conflicts is
2200 beyond the scope of this document; consult the CVS documentation
2201 for more information on how to use CVS.</p>
2204 <div class="appendix" lang="en">
2205 <h2 class="title" style="clear: both">
2206 <a name="VariablesRuntime"></a>A. Configuration variables (for <span class="emphasis"><em>myplc</em></span>)</h2>
2207 <p>Listed below is the set of standard configuration variables
2208 and their default values, defined in the template
2209 <code class="filename">/etc/planetlab/default_config.xml</code>. Additional
2210 variables and their defaults may be defined in site-specific XML
2211 templates that should be placed in
2212 <code class="filename">/etc/planetlab/configs/</code>.</p>
2213 <div class="variablelist"><dl>
2214 <dt><span class="term">PLC_NAME</span></dt>
2219 Default: PlanetLab Test</p>
2220 <p>The name of this PLC installation. It is used in
2221 the name of the default system site (e.g., PlanetLab Central)
2222 and in the names of various administrative entities (e.g.,
2223 PlanetLab Support).</p>
2225 <dt><span class="term">PLC_SLICE_PREFIX</span></dt>
2231 <p>The abbreviated name of this PLC
2232 installation. It is used as the prefix for system slices
2233 (e.g., pl_conf). Warning: Currently, this variable should
2236 <dt><span class="term">PLC_ROOT_USER</span></dt>
2241 Default: root@localhost.localdomain</p>
2242 <p>The name of the initial administrative
2243 account. We recommend that this account be used only to create
2244 additional accounts associated with real
2245 administrators, then disabled.</p>
2247 <dt><span class="term">PLC_ROOT_PASSWORD</span></dt>
2253 <p>The password of the initial administrative
2254 account. Also the password of the root account on the Boot
2257 <dt><span class="term">PLC_ROOT_SSH_KEY_PUB</span></dt>
2262 Default: /etc/planetlab/root_ssh_key.pub</p>
2263 <p>The SSH public key used to access the root
2264 account on your nodes.</p>
2266 <dt><span class="term">PLC_ROOT_SSH_KEY</span></dt>
2271 Default: /etc/planetlab/root_ssh_key.rsa</p>
2272 <p>The SSH private key used to access the root
2273 account on your nodes.</p>
2275 <dt><span class="term">PLC_DEBUG_SSH_KEY_PUB</span></dt>
2280 Default: /etc/planetlab/debug_ssh_key.pub</p>
2281 <p>The SSH public key used to access the root
2282 account on your nodes when they are in Debug mode.</p>
2284 <dt><span class="term">PLC_DEBUG_SSH_KEY</span></dt>
2289 Default: /etc/planetlab/debug_ssh_key.rsa</p>
2290 <p>The SSH private key used to access the root
2291 account on your nodes when they are in Debug mode.</p>
2293 <dt><span class="term">PLC_ROOT_GPG_KEY_PUB</span></dt>
2298 Default: /etc/planetlab/pubring.gpg</p>
2299 <p>The GPG public keyring used to sign the Boot
2300 Manager and all node packages.</p>
2302 <dt><span class="term">PLC_ROOT_GPG_KEY</span></dt>
2307 Default: /etc/planetlab/secring.gpg</p>
2308 <p>The SSH private key used to access the root
2309 account on your nodes.</p>
2311 <dt><span class="term">PLC_MA_SA_NAMESPACE</span></dt>
2317 <p>The namespace of your MA/SA. This should be a
2318 globally unique value assigned by PlanetLab
2321 <dt><span class="term">PLC_MA_SA_SSL_KEY</span></dt>
2326 Default: /etc/planetlab/ma_sa_ssl.key</p>
2327 <p>The SSL private key used for signing documents
2328 with the signature of your MA/SA. If non-existent, one will
2331 <dt><span class="term">PLC_MA_SA_SSL_CRT</span></dt>
2336 Default: /etc/planetlab/ma_sa_ssl.crt</p>
2337 <p>The corresponding SSL public certificate. By
2338 default, this certificate is self-signed. You may replace
2339 the certificate later with one signed by the PLC root
2342 <dt><span class="term">PLC_MA_SA_CA_SSL_CRT</span></dt>
2347 Default: /etc/planetlab/ma_sa_ca_ssl.crt</p>
2348 <p>If applicable, the certificate of the PLC root
2349 CA. If your MA/SA certificate is self-signed, then this file
2350 is the same as your MA/SA certificate.</p>
2352 <dt><span class="term">PLC_MA_SA_CA_SSL_KEY_PUB</span></dt>
2357 Default: /etc/planetlab/ma_sa_ca_ssl.pub</p>
2358 <p>If applicable, the public key of the PLC root
2359 CA. If your MA/SA certificate is self-signed, then this file
2360 is the same as your MA/SA public key.</p>
2362 <dt><span class="term">PLC_MA_SA_API_CRT</span></dt>
2367 Default: /etc/planetlab/ma_sa_api.xml</p>
2368 <p>The API Certificate is your MA/SA public key
2369 embedded in a digitally signed XML document. By default,
2370 this document is self-signed. You may replace this
2371 certificate later with one signed by the PLC root
2374 <dt><span class="term">PLC_NET_DNS1</span></dt>
2379 Default: 127.0.0.1</p>
2380 <p>Primary DNS server address.</p>
2382 <dt><span class="term">PLC_NET_DNS2</span></dt>
2388 <p>Secondary DNS server address.</p>
2390 <dt><span class="term">PLC_DNS_ENABLED</span></dt>
2396 <p>Enable the internal DNS server. The server does
2397 not provide reverse resolution and is not a production
2398 quality or scalable DNS solution. Use the internal DNS
2399 server only for small deployments or for
2402 <dt><span class="term">PLC_MAIL_ENABLED</span></dt>
2408 <p>Set to false to suppress all e-mail notifications
2411 <dt><span class="term">PLC_MAIL_SUPPORT_ADDRESS</span></dt>
2416 Default: root+support@localhost.localdomain</p>
2417 <p>This address is used for support
2418 requests. Support requests may include traffic complaints,
2419 security incident reporting, web site malfunctions, and
2420 general requests for information. We recommend that the
2421 address be aliased to a ticketing system such as Request
2424 <dt><span class="term">PLC_MAIL_BOOT_ADDRESS</span></dt>
2429 Default: root+install-msgs@localhost.localdomain</p>
2430 <p>The API will notify this address when a problem
2431 occurs during node installation or boot.</p>
2433 <dt><span class="term">PLC_MAIL_SLICE_ADDRESS</span></dt>
2438 Default: root+SLICE@localhost.localdomain</p>
2439 <p>This address template is used for sending
2440 e-mail notifications to slices. SLICE will be replaced with
2441 the name of the slice.</p>
2443 <dt><span class="term">PLC_DB_ENABLED</span></dt>
2449 <p>Enable the database server on this
2452 <dt><span class="term">PLC_DB_TYPE</span></dt>
2457 Default: postgresql</p>
2458 <p>The type of database server. Currently, only
2459 postgresql is supported.</p>
2461 <dt><span class="term">PLC_DB_HOST</span></dt>
2466 Default: localhost.localdomain</p>
2467 <p>The fully qualified hostname of the database
2470 <dt><span class="term">PLC_DB_IP</span></dt>
2475 Default: 127.0.0.1</p>
2476 <p>The IP address of the database server, if not
2477 resolvable by the configured DNS servers.</p>
2479 <dt><span class="term">PLC_DB_PORT</span></dt>
2485 <p>The TCP port number through which the database
2486 server should be accessed.</p>
2488 <dt><span class="term">PLC_DB_NAME</span></dt>
2493 Default: planetlab3</p>
2494 <p>The name of the database to access.</p>
2496 <dt><span class="term">PLC_DB_USER</span></dt>
2501 Default: pgsqluser</p>
2502 <p>The username to use when accessing the
2505 <dt><span class="term">PLC_DB_PASSWORD</span></dt>
2511 <p>The password to use when accessing the
2512 database. If left blank, one will be
2515 <dt><span class="term">PLC_API_ENABLED</span></dt>
2521 <p>Enable the API server on this
2524 <dt><span class="term">PLC_API_DEBUG</span></dt>
2530 <p>Enable verbose API debugging. Do not enable on
2531 a production system!</p>
2533 <dt><span class="term">PLC_API_HOST</span></dt>
2538 Default: localhost.localdomain</p>
2539 <p>The fully qualified hostname of the API
2542 <dt><span class="term">PLC_API_IP</span></dt>
2547 Default: 127.0.0.1</p>
2548 <p>The IP address of the API server, if not
2549 resolvable by the configured DNS servers.</p>
2551 <dt><span class="term">PLC_API_PORT</span></dt>
2557 <p>The TCP port number through which the API
2558 should be accessed. Warning: SSL (port 443) access is not
2559 fully supported by the website code yet. We recommend that
2560 port 80 be used for now and that the API server either run
2561 on the same machine as the web server, or that they both be
2562 on a secure wired network.</p>
2564 <dt><span class="term">PLC_API_PATH</span></dt>
2569 Default: /PLCAPI/</p>
2570 <p>The base path of the API URL.</p>
2572 <dt><span class="term">PLC_API_MAINTENANCE_USER</span></dt>
2577 Default: maint@localhost.localdomain</p>
2578 <p>The username of the maintenance account. This
2579 account is used by local scripts that perform automated
2580 tasks, and cannot be used for normal logins.</p>
2582 <dt><span class="term">PLC_API_MAINTENANCE_PASSWORD</span></dt>
2588 <p>The password of the maintenance account. If
2589 left blank, one will be generated. We recommend that the
2590 password be changed periodically.</p>
2592 <dt><span class="term">PLC_API_MAINTENANCE_SOURCES</span></dt>
2598 <p>A space-separated list of IP addresses allowed
2599 to access the API through the maintenance account. The value
2600 of this variable is set automatically to allow only the API,
2601 web, and boot servers, and should not be
2604 <dt><span class="term">PLC_API_SSL_KEY</span></dt>
2609 Default: /etc/planetlab/api_ssl.key</p>
2610 <p>The SSL private key to use for encrypting HTTPS
2611 traffic. If non-existent, one will be
2614 <dt><span class="term">PLC_API_SSL_CRT</span></dt>
2619 Default: /etc/planetlab/api_ssl.crt</p>
2620 <p>The corresponding SSL public certificate. By
2621 default, this certificate is self-signed. You may replace
2622 the certificate later with one signed by a root
2625 <dt><span class="term">PLC_API_CA_SSL_CRT</span></dt>
2630 Default: /etc/planetlab/api_ca_ssl.crt</p>
2631 <p>The certificate of the root CA, if any, that
2632 signed your server certificate. If your server certificate is
2633 self-signed, then this file is the same as your server
2636 <dt><span class="term">PLC_WWW_ENABLED</span></dt>
2642 <p>Enable the web server on this
2645 <dt><span class="term">PLC_WWW_DEBUG</span></dt>
2651 <p>Enable debugging output on web pages. Do not
2652 enable on a production system!</p>
2654 <dt><span class="term">PLC_WWW_HOST</span></dt>
2659 Default: localhost.localdomain</p>
2660 <p>The fully qualified hostname of the web
2663 <dt><span class="term">PLC_WWW_IP</span></dt>
2668 Default: 127.0.0.1</p>
2669 <p>The IP address of the web server, if not
2670 resolvable by the configured DNS servers.</p>
2672 <dt><span class="term">PLC_WWW_PORT</span></dt>
2678 <p>The TCP port number through which the
2679 unprotected portions of the web site should be
2682 <dt><span class="term">PLC_WWW_SSL_PORT</span></dt>
2688 <p>The TCP port number through which the protected
2689 portions of the web site should be accessed.</p>
2691 <dt><span class="term">PLC_WWW_SSL_KEY</span></dt>
2696 Default: /etc/planetlab/www_ssl.key</p>
2697 <p>The SSL private key to use for encrypting HTTPS
2698 traffic. If non-existent, one will be
2701 <dt><span class="term">PLC_WWW_SSL_CRT</span></dt>
2706 Default: /etc/planetlab/www_ssl.crt</p>
2707 <p>The corresponding SSL public certificate for
2708 the HTTP server. By default, this certificate is
2709 self-signed. You may replace the certificate later with one
2710 signed by a root CA.</p>
2712 <dt><span class="term">PLC_WWW_CA_SSL_CRT</span></dt>
2717 Default: /etc/planetlab/www_ca_ssl.crt</p>
2718 <p>The certificate of the root CA, if any, that
2719 signed your server certificate. If your server certificate is
2720 self-signed, then this file is the same as your server
2723 <dt><span class="term">PLC_BOOT_ENABLED</span></dt>
2729 <p>Enable the boot server on this
2732 <dt><span class="term">PLC_BOOT_HOST</span></dt>
2737 Default: localhost.localdomain</p>
2738 <p>The fully qualified hostname of the boot
2741 <dt><span class="term">PLC_BOOT_IP</span></dt>
2746 Default: 127.0.0.1</p>
2747 <p>The IP address of the boot server, if not
2748 resolvable by the configured DNS servers.</p>
2750 <dt><span class="term">PLC_BOOT_PORT</span></dt>
2756 <p>The TCP port number through which the
2757 unprotected portions of the boot server should be
2760 <dt><span class="term">PLC_BOOT_SSL_PORT</span></dt>
2766 <p>The TCP port number through which the protected
2767 portions of the boot server should be
2770 <dt><span class="term">PLC_BOOT_SSL_KEY</span></dt>
2775 Default: /etc/planetlab/boot_ssl.key</p>
2776 <p>The SSL private key to use for encrypting HTTPS
2779 <dt><span class="term">PLC_BOOT_SSL_CRT</span></dt>
2784 Default: /etc/planetlab/boot_ssl.crt</p>
2785 <p>The corresponding SSL public certificate for
2786 the HTTP server. By default, this certificate is
2787 self-signed. You may replace the certificate later with one
2788 signed by a root CA.</p>
2790 <dt><span class="term">PLC_BOOT_CA_SSL_CRT</span></dt>
2795 Default: /etc/planetlab/boot_ca_ssl.crt</p>
2796 <p>The certificate of the root CA, if any, that
2797 signed your server certificate. If your server certificate is
2798 self-signed, then this file is the same as your server
2803 <div class="appendix" lang="en">
2804 <h2 class="title" style="clear: both">
2805 <a name="VariablesDevel"></a>B. Development configuration variables (for <span class="emphasis"><em>myplc-devel</em></span>)</h2>
2806 <div class="variablelist"><dl>
2807 <dt><span class="term">PLC_DEVEL_FEDORA_RELEASE</span></dt>
2813 <p>Version number of Fedora Core upon which to
2814 base the build environment. Warning: Currently, only Fedora
2815 Core 4 is supported.</p>
2817 <dt><span class="term">PLC_DEVEL_FEDORA_ARCH</span></dt>
2823 <p>Base architecture of the build
2824 environment. Warning: Currently, only i386 is
2827 <dt><span class="term">PLC_DEVEL_FEDORA_URL</span></dt>
2832 Default: file:///usr/share/mirrors/fedora</p>
2833 <p>Fedora Core mirror from which to install
2836 <dt><span class="term">PLC_DEVEL_CVSROOT</span></dt>
2842 <p>CVSROOT to use when checking out code.</p>
2844 <dt><span class="term">PLC_DEVEL_BOOTSTRAP</span></dt>
2850 <p>Controls whether MyPLC should be built inside
2851 of its own development environment.</p>
2855 <div class="bibliography">
2856 <div class="titlepage"><div><div><h2 class="title">
2857 <a name="id2898373"></a>Bibliography</h2></div></div></div>
2858 <div class="biblioentry">
2859 <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
2860 Technical Contact's Guide</a></i>. </span></p>
2863 </div><?php require('footer.php'); ?>
2864 dummy 1.12 for cathing up with the xml numbering