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="id2703030"></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 <td align="left">Revision 1.2</td>
34 <td align="left">August 18, 2006</td>
35 <td align="left">TPT</td>
37 <tr><td align="left" colspan="3">
38 <p>Review section on configuration and introduce <span><strong class="command">plc-config-tty</strong></span>.</p>
39 <p>Present implementation details last.</p>
42 <div><div class="abstract">
43 <p class="title"><b>Abstract</b></p>
44 <p>This document describes the design, installation, and
45 administration of MyPLC, a complete PlanetLab Central (PLC)
46 portable installation contained within a
47 <span><strong class="command">chroot</strong></span> jail. This document assumes advanced
48 knowledge of the PlanetLab architecture and Linux system
55 <p><b>Table of Contents</b></p>
57 <dt><span class="section"><a href="#id2749839">1. Overview</a></span></dt>
58 <dd><dl><dt><span class="section"><a href="#id2750165">1.1. Purpose of the <span class="emphasis"><em> myplc-devel
59 </em></span> package </a></span></dt></dl></dd>
60 <dt><span class="section"><a href="#Requirements">2. Requirements </a></span></dt>
61 <dt><span class="section"><a href="#Installation">3. Installating and using MyPLC</a></span></dt>
63 <dt><span class="section"><a href="#id2749479">3.1. Installing MyPLC.</a></span></dt>
64 <dt><span class="section"><a href="#QuickStart">3.2. QuickStart </a></span></dt>
65 <dt><span class="section"><a href="#Configuration">3.3. Changing the configuration</a></span></dt>
66 <dt><span class="section"><a href="#LoginRealUser">3.4. Login as a real user </a></span></dt>
67 <dt><span class="section"><a href="#id2750676">3.5. Installing nodes</a></span></dt>
68 <dt><span class="section"><a href="#id2801620">3.6. Administering nodes</a></span></dt>
69 <dt><span class="section"><a href="#id2801720">3.7. Creating a slice</a></span></dt>
70 <dt><span class="section"><a href="#StartupSequence">3.8. Understanding the startup sequence</a></span></dt>
71 <dt><span class="section"><a href="#FilesInvolvedRuntime">3.9. Files and directories
72 involved in <span class="emphasis"><em>myplc</em></span></a></span></dt>
74 <dt><span class="section"><a href="#DevelopmentEnvironment">4. Rebuilding and customizing MyPLC</a></span></dt>
76 <dt><span class="section"><a href="#id2802612">4.1. Installation</a></span></dt>
77 <dt><span class="section"><a href="#id2802667">4.2. Configuration</a></span></dt>
78 <dt><span class="section"><a href="#FilesInvolvedDevel">4.3. Files and directories
79 involved in <span class="emphasis"><em>myplc-devl</em></span></a></span></dt>
80 <dt><span class="section"><a href="#id2802931">4.4. Fedora Core 4 mirror requirement</a></span></dt>
81 <dt><span class="section"><a href="#BuildingMyPLC">4.5. Building MyPLC</a></span></dt>
82 <dt><span class="section"><a href="#UpdatingCVS">4.6. Updating CVS</a></span></dt>
84 <dt><span class="appendix"><a href="#VariablesRuntime">A. Configuration variables (for <span class="emphasis"><em>myplc</em></span>)</a></span></dt>
85 <dt><span class="appendix"><a href="#VariablesDevel">B. Development configuration variables (for <span class="emphasis"><em>myplc-devel</em></span>)</a></span></dt>
86 <dt><span class="bibliography"><a href="#id2806472">Bibliography</a></span></dt>
89 <div class="section" lang="en">
90 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
91 <a name="id2749839"></a>1. Overview</h2></div></div></div>
92 <p>MyPLC is a complete PlanetLab Central (PLC) portable
93 installation contained within a <span><strong class="command">chroot</strong></span>
94 jail. The default installation consists of a web server, an
95 XML-RPC API server, a boot server, and a database server: the core
96 components of PLC. The installation is customized through an
97 easy-to-use graphical interface. All PLC services are started up
98 and shut down through a single script installed on the host
99 system. The usually complex process of installing and
100 administering the PlanetLab backend is reduced by containing PLC
101 services within a virtual filesystem. By packaging it in such a
102 manner, MyPLC may also be run on any modern Linux distribution,
103 and could conceivably even run in a PlanetLab slice.</p>
105 <a name="Architecture"></a><p class="title"><b>Figure 1. MyPLC architecture</b></p>
106 <div class="mediaobject" align="center">
107 <img src="architecture.png" align="middle" width="270" alt="MyPLC architecture"><div class="caption"><p>MyPLC should be viewed as a single application that
108 provides multiple functions and can run on any host
112 <div class="section" lang="en">
113 <div class="titlepage"><div><div><h3 class="title">
114 <a name="id2750165"></a>1.1. Purpose of the <span class="emphasis"><em> myplc-devel
115 </em></span> package </h3></div></div></div>
116 <p> The <span class="emphasis"><em>myplc</em></span> package comes with all
117 required node software, rebuilt from the public PlanetLab CVS
118 repository. If for any reason you need to implement your own
119 customized version of this software, you can use the
120 <span class="emphasis"><em>myplc-devel</em></span> package instead, for setting up
121 your own development environment, including a local CVS
122 repository; you can then freely manage your changes and rebuild
123 your customized version of <span class="emphasis"><em>myplc</em></span>. We also
124 provide good practices, that will then allow you to resync your local
125 CVS repository with any further evolution on the mainstream public
126 PlanetLab software. </p>
129 <div class="section" lang="en">
130 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
131 <a name="Requirements"></a>2. Requirements </h2></div></div></div>
132 <p> <span class="emphasis"><em>myplc</em></span> and
133 <span class="emphasis"><em>myplc-devel</em></span> were designed as
134 <span><strong class="command">chroot</strong></span> jails so as to reduce the requirements on
135 your host operating system. So in theory, these distributions should
136 work on virtually any Linux 2.6 based distribution, whether it
137 supports rpm or not. </p>
138 <p> However, things are never that simple and there indeed are
139 some known limitations to this, so here are a couple notes as a
140 recommended reading before you proceed with the installation.</p>
141 <p> As of 17 August 2006 (i.e <span class="emphasis"><em>myplc-0.5-2</em></span>) :</p>
142 <div class="itemizedlist"><ul type="disc">
143 <li><p> The software is vastly based on <span class="emphasis"><em>Fedora
144 Core 4</em></span>. Please note that the build server at Princeton
145 runs <span class="emphasis"><em>Fedora Core 2</em></span>, togother with a upgraded
149 <p> myplc and myplc-devel are known to work on both
150 <span class="emphasis"><em>Fedora Core 2</em></span> and <span class="emphasis"><em>Fedora Core
151 4</em></span>. Please note however that, on fc4 at least, it is
152 highly recommended to use the <span class="application">Security Level
153 Configuration</span> utility and to <span class="emphasis"><em>switch off
154 SElinux</em></span> on your box because : </p>
155 <div class="itemizedlist"><ul type="circle">
157 myplc requires you to run SElinux as 'Permissive' at most
160 myplc-devel requires you to turn SElinux Off.
164 <li><p> In addition, as far as myplc is concerned, you
165 need to check your firewall configuration since you need, of course,
166 to open up the <span class="emphasis"><em>http</em></span> and
167 <span class="emphasis"><em>https</em></span> ports, so as to accept connections from
168 the managed nodes and from the users desktops. </p></li>
171 <div class="section" lang="en">
172 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
173 <a name="Installation"></a>3. Installating and using MyPLC</h2></div></div></div>
174 <p>Though internally composed of commodity software
175 subpackages, MyPLC should be treated as a monolithic software
176 application. MyPLC is distributed as single RPM package that has
177 no external dependencies, allowing it to be installed on
178 practically any Linux 2.6 based distribution.</p>
179 <div class="section" lang="en">
180 <div class="titlepage"><div><div><h3 class="title">
181 <a name="id2749479"></a>3.1. Installing MyPLC.</h3></div></div></div>
182 <div class="itemizedlist"><ul type="disc">
184 <p>If your distribution supports RPM:</p>
185 <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>
188 <p>If your distribution does not support RPM:</p>
189 <pre class="programlisting"># cd /tmp
190 # wget http://build.planet-lab.org/build/myplc-0_4-rc1/RPMS/i386/myplc-0.4-1.planetlab.i386.rpm
192 # rpm2cpio /tmp/myplc-0.4-1.planetlab.i386.rpm | cpio -diu</pre>
195 <p> The <a href="#FilesInvolvedRuntime" title="3.9. Files and directories
196 involved in myplc">Section 3.9, “ Files and directories
197 involved in <span class="emphasis"><em>myplc</em></span>”</a> below explains in
198 details the installation strategy and the miscellaneous files and
199 directories involved.</p>
201 <div class="section" lang="en">
202 <div class="titlepage"><div><div><h3 class="title">
203 <a name="QuickStart"></a>3.2. QuickStart </h3></div></div></div>
204 <p> On a Red Hat or Fedora host system, it is customary to use
205 the <span><strong class="command">service</strong></span> command to invoke System V init
206 scripts. As the examples suggest, the service must be started as root:</p>
207 <div class="example">
208 <a name="id2749652"></a><p class="title"><b>Example 1. Starting MyPLC:</b></p>
209 <pre class="programlisting"># service plc start</pre>
211 <div class="example">
212 <a name="id2749665"></a><p class="title"><b>Example 2. Stopping MyPLC:</b></p>
213 <pre class="programlisting"># service plc stop</pre>
215 <p> In <a href="#StartupSequence" title="3.8. Understanding the startup sequence">Section 3.8, “Understanding the startup sequence”</a>, we provide greater
216 details that might be helpful in the case where the service does
217 not seem to take off correctly.</p>
218 <p>Like all other registered System V init services, MyPLC is
219 started and shut down automatically when your host system boots
220 and powers off. You may disable automatic startup by invoking the
221 <span><strong class="command">chkconfig</strong></span> command on a Red Hat or Fedora host
223 <div class="example">
224 <a name="id2750316"></a><p class="title"><b>Example 3. Disabling automatic startup of MyPLC.</b></p>
225 <pre class="programlisting"># chkconfig plc off</pre>
227 <div class="example">
228 <a name="id2750328"></a><p class="title"><b>Example 4. Re-enabling automatic startup of MyPLC.</b></p>
229 <pre class="programlisting"># chkconfig plc on</pre>
232 <div class="section" lang="en">
233 <div class="titlepage"><div><div><h3 class="title">
234 <a name="Configuration"></a>3.3. Changing the configuration</h3></div></div></div>
235 <p>After verifying that MyPLC is working correctly, shut it
236 down and begin changing some of the default variable
237 values. Shut down MyPLC with <span><strong class="command">service plc stop</strong></span>
238 (see <a href="#QuickStart" title="3.2. QuickStart ">Section 3.2, “ QuickStart ”</a>). </p>
239 <p> The preferred option for changing the configuration is to
240 use the <span><strong class="command">plc-config-tty</strong></span> tool. This tools comes
241 with the root image, so you need to have it mounted first. The
242 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>, but using the <span><strong class="command">u</strong></span>
243 guides you to the most useful ones. Here is sample session:
245 <div class="example">
246 <a name="id2750396"></a><p class="title"><b>Example 5. Using plc-config-tty for configuration:</b></p>
247 <pre class="programlisting"># service plc mount
249 # chroot /plc/root su -
250 <plc> # plc-config-tty
251 Config file /etc/planetlab/configs/site.xml located under a non-existing directory
252 Want to create /etc/planetlab/configs [y]/n ? y
253 Created directory /etc/planetlab/configs
254 Enter command (u for usual changes, w to save, ? for help) u
255 == PLC_NAME : [PlanetLab Test] OneLab
256 == PLC_ROOT_USER : [root@localhost.localdomain] root@odie.inria.fr
257 == PLC_ROOT_PASSWORD : [root] plain-passwd
258 == PLC_MAIL_SUPPORT_ADDRESS : [root+support@localhost.localdomain] support@one-lab.org
259 == PLC_DB_HOST : [localhost.localdomain] odie.inria.fr
260 == PLC_API_HOST : [localhost.localdomain] odie.inria.fr
261 == PLC_WWW_HOST : [localhost.localdomain] odie.inria.fr
262 == PLC_BOOT_HOST : [localhost.localdomain] odie.inria.fr
263 == PLC_NET_DNS1 : [127.0.0.1] 138.96.250.248
264 == PLC_NET_DNS2 : [None] 138.96.250.249
265 Enter command (u for usual changes, w to save, ? for help) w
266 Wrote /etc/planetlab/configs/site.xml
268 /etc/planetlab/default_config.xml
269 and /etc/planetlab/configs/site.xml
270 into /etc/planetlab/plc_config.xml
271 You might want to type 'r' (restart plc) or 'q' (quit)
272 Enter command (u for usual changes, w to save, ? for help) r
273 ==================== Stopping plc
275 ==================== Starting plc
277 Enter command (u for usual changes, w to save, ? for help) q
282 <p>If you used this method for configuring, you can skip to
283 the <a href="#LoginRealUser" title="3.4. Login as a real user ">Section 3.4, “ Login as a real user ”</a>. As an alternative to using
284 <span><strong class="command">plc-config-tty</strong></span>, you may also use a text
285 editor, but this requires some understanding on how the
286 configuration files are used within myplc. The
287 <span class="emphasis"><em>default</em></span> configuration is stored in a file
288 named <code class="filename">/etc/planetlab/default_config.xml</code>,
289 that is designed to remain intact. You may store your local
290 changes in any file located in the <code class="filename">configs/</code>
291 sub-directory, that are loaded on top of the defaults. Finally
292 the file <code class="filename">/etc/planetlab/plc_config.xml</code> is
293 loaded, and the resulting configuration is stored in the latter
294 file, that is used as a reference.</p>
295 <p> Using a separate file for storing local changes only, as
296 <span><strong class="command">plc-config-tty</strong></span> does, is not a workable option
297 with a text editor because it would involve tedious xml
298 re-assembling. So your local changes should go in
299 <code class="filename">/etc/planetlab/plc_config.xml</code>. Be warned
300 however that any change you might do this way could be lost if
301 you use <span><strong class="command">plc-config-tty</strong></span> later on. </p>
302 <p>This file is a self-documenting configuration file written
303 in XML. Variables are divided into categories. Variable
304 identifiers must be alphanumeric, plus underscore. A variable is
305 referred to canonically as the uppercase concatenation of its
306 category identifier, an underscore, and its variable
307 identifier. Thus, a variable with an <code class="literal">id</code> of
308 <code class="literal">slice_prefix</code> in the <code class="literal">plc</code>
309 category is referred to canonically as
310 <code class="envar">PLC_SLICE_PREFIX</code>.</p>
311 <p>The reason for this convention is that during MyPLC
312 startup, <code class="filename">plc_config.xml</code> is translated into
313 several different languages—shell, PHP, and
314 Python—so that scripts written in each of these languages
315 can refer to the same underlying configuration. Most MyPLC
316 scripts are written in shell, so the convention for shell
317 variables predominates.</p>
318 <p>The variables that you should change immediately are:</p>
319 <div class="itemizedlist"><ul type="disc">
320 <li><p><code class="envar">PLC_NAME</code>: Change this to the
321 name of your PLC installation.</p></li>
322 <li><p><code class="envar">PLC_ROOT_PASSWORD</code>: Change this
323 to a more secure password.</p></li>
324 <li><p><code class="envar">PLC_MAIL_SUPPORT_ADDRESS</code>:
325 Change this to the e-mail address at which you would like to
326 receive support requests.</p></li>
327 <li><p><code class="envar">PLC_DB_HOST</code>,
328 <code class="envar">PLC_DB_IP</code>, <code class="envar">PLC_API_HOST</code>,
329 <code class="envar">PLC_API_IP</code>, <code class="envar">PLC_WWW_HOST</code>,
330 <code class="envar">PLC_WWW_IP</code>, <code class="envar">PLC_BOOT_HOST</code>,
331 <code class="envar">PLC_BOOT_IP</code>: Change all of these to the
332 preferred FQDN and external IP address of your host
335 <p> After changing these variables,
336 save the file, then restart MyPLC with <span><strong class="command">service plc
337 start</strong></span>. You should notice that the password of the
338 default administrator account is no longer
339 <code class="literal">root</code>, and that the default site name includes
340 the name of your PLC installation instead of PlanetLab. As a
341 side effect of these changes, the ISO images for the boot CDs
342 now have new names, so that you can freely remove the ones names
343 after 'PlanetLab Test', which is the default value of
344 <code class="envar">PLC_NAME</code> </p>
346 <div class="section" lang="en">
347 <div class="titlepage"><div><div><h3 class="title">
348 <a name="LoginRealUser"></a>3.4. Login as a real user </h3></div></div></div>
349 <p>Now that myplc is up and running, you can connect to the
350 web site that by default runs on port 80. You can either
351 directly use the default administrator user that you configured
352 in <code class="envar">PLC_ROOT_USER</code> and
353 <code class="envar">PLC_ROOT_PASSWORD</code>, or create a real user through
354 the 'Joining' tab. Do not forget to select both PI and tech
355 roles, and to select the only site created at this stage.
356 Login as the administrator to enable this user, then login as
359 <div class="section" lang="en">
360 <div class="titlepage"><div><div><h3 class="title">
361 <a name="id2750676"></a>3.5. Installing nodes</h3></div></div></div>
362 <p>Install your first node by clicking <code class="literal">Add
363 Node</code> under the <code class="literal">Nodes</code> tab. Fill in
364 all the appropriate details, then click
365 <code class="literal">Add</code>. Download the node's configuration file
366 by clicking <code class="literal">Download configuration file</code> on
367 the <span class="bold"><strong>Node Details</strong></span> page for the
368 node. Save it to a floppy disk or USB key as detailed in [<a href="#TechsGuide" title="[TechsGuide]">1</a>].</p>
369 <p>Follow the rest of the instructions in [<a href="#TechsGuide" title="[TechsGuide]">1</a>] for creating a Boot CD and installing
370 the node, except download the Boot CD image from the
371 <code class="filename">/download</code> directory of your PLC
372 installation, not from PlanetLab Central. The images located
373 here are customized for your installation. If you change the
374 hostname of your boot server (<code class="envar">PLC_BOOT_HOST</code>), or
375 if the SSL certificate of your boot server expires, MyPLC will
376 regenerate it and rebuild the Boot CD with the new
377 certificate. If this occurs, you must replace all Boot CDs
378 created before the certificate was regenerated.</p>
379 <p>The installation process for a node has significantly
380 improved since PlanetLab 3.3. It should now take only a few
381 seconds for a new node to become ready to create slices.</p>
383 <div class="section" lang="en">
384 <div class="titlepage"><div><div><h3 class="title">
385 <a name="id2801620"></a>3.6. Administering nodes</h3></div></div></div>
386 <p>You may administer nodes as <code class="literal">root</code> by
387 using the SSH key stored in
388 <code class="filename">/etc/planetlab/root_ssh_key.rsa</code>.</p>
389 <div class="example">
390 <a name="id2801642"></a><p class="title"><b>Example 6. Accessing nodes via SSH. Replace
391 <code class="literal">node</code> with the hostname of the node.</b></p>
392 <pre class="programlisting">ssh -i /etc/planetlab/root_ssh_key.rsa root@node</pre>
394 <p>Besides the standard Linux log files located in
395 <code class="filename">/var/log</code>, several other files can give you
396 clues about any problems with active processes:</p>
397 <div class="itemizedlist"><ul type="disc">
398 <li><p><code class="filename">/var/log/pl_nm</code>: The log
399 file for the Node Manager.</p></li>
400 <li><p><code class="filename">/vservers/pl_conf/var/log/pl_conf</code>:
401 The log file for the Slice Creation Service.</p></li>
402 <li><p><code class="filename">/var/log/propd</code>: The log
403 file for Proper, the service which allows certain slices to
404 perform certain privileged operations in the root
406 <li><p><code class="filename">/vservers/pl_netflow/var/log/netflow.log</code>:
407 The log file for PlanetFlow, the network traffic auditing
411 <div class="section" lang="en">
412 <div class="titlepage"><div><div><h3 class="title">
413 <a name="id2801720"></a>3.7. Creating a slice</h3></div></div></div>
414 <p>Create a slice by clicking <code class="literal">Create Slice</code>
415 under the <code class="literal">Slices</code> tab. Fill in all the
416 appropriate details, then click <code class="literal">Create</code>. Add
417 nodes to the slice by clicking <code class="literal">Manage Nodes</code>
418 on the <span class="bold"><strong>Slice Details</strong></span> page for
420 <p>A <span><strong class="command">cron</strong></span> job runs every five minutes and
422 <code class="filename">/plc/data/var/www/html/xml/slices-0.5.xml</code>
423 with information about current slice state. The Slice Creation
424 Service running on every node polls this file every ten minutes
425 to determine if it needs to create or delete any slices. You may
426 accelerate this process manually if desired.</p>
427 <div class="example">
428 <a name="id2801783"></a><p class="title"><b>Example 7. Forcing slice creation on a node.</b></p>
429 <pre class="programlisting"># Update slices.xml immediately
430 service plc start crond
432 # Kick the Slice Creation Service on a particular node.
433 ssh -i /etc/planetlab/root_ssh_key.rsa root@node \
434 vserver pl_conf exec service pl_conf restart</pre>
437 <div class="section" lang="en">
438 <div class="titlepage"><div><div><h3 class="title">
439 <a name="StartupSequence"></a>3.8. Understanding the startup sequence</h3></div></div></div>
440 <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
441 any failures. If no failures occur, you should see output similar
442 to the following:</p>
443 <div class="example">
444 <a name="id2801822"></a><p class="title"><b>Example 8. A successful MyPLC startup.</b></p>
445 <pre class="programlisting">Mounting PLC: [ OK ]
446 PLC: Generating network files: [ OK ]
447 PLC: Starting system logger: [ OK ]
448 PLC: Starting database server: [ OK ]
449 PLC: Generating SSL certificates: [ OK ]
450 PLC: Configuring the API: [ OK ]
451 PLC: Updating GPG keys: [ OK ]
452 PLC: Generating SSH keys: [ OK ]
453 PLC: Starting web server: [ OK ]
454 PLC: Bootstrapping the database: [ OK ]
455 PLC: Starting DNS server: [ OK ]
456 PLC: Starting crond: [ OK ]
457 PLC: Rebuilding Boot CD: [ OK ]
458 PLC: Rebuilding Boot Manager: [ OK ]
459 PLC: Signing node packages: [ OK ]
462 <p>If <code class="filename">/plc/root</code> is mounted successfully, a
463 complete log file of the startup process may be found at
464 <code class="filename">/plc/root/var/log/boot.log</code>. Possible reasons
465 for failure of each step include:</p>
466 <div class="itemizedlist"><ul type="disc">
467 <li><p><code class="literal">Mounting PLC</code>: If this step
468 fails, first ensure that you started MyPLC as root. Check
469 <code class="filename">/etc/sysconfig/plc</code> to ensure that
470 <code class="envar">PLC_ROOT</code> and <code class="envar">PLC_DATA</code> refer to the
471 right locations. You may also have too many existing loopback
472 mounts, or your kernel may not support loopback mounting, bind
473 mounting, or the ext3 filesystem. Try freeing at least one
474 loopback device, or re-compiling your kernel to support loopback
475 mounting, bind mounting, and the ext3 filesystem. If you see an
476 error similar to <code class="literal">Permission denied while trying to open
477 /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>
478 <li><p><code class="literal">Starting database server</code>: If
479 this step fails, check
480 <code class="filename">/plc/root/var/log/pgsql</code> and
481 <code class="filename">/plc/root/var/log/boot.log</code>. The most common
482 reason for failure is that the default PostgreSQL port, TCP port
483 5432, is already in use. Check that you are not running a
484 PostgreSQL server on the host system.</p></li>
485 <li><p><code class="literal">Starting web server</code>: If this
487 <code class="filename">/plc/root/var/log/httpd/error_log</code> and
488 <code class="filename">/plc/root/var/log/boot.log</code> for obvious
489 errors. The most common reason for failure is that the default
490 web ports, TCP ports 80 and 443, are already in use. Check that
491 you are not running a web server on the host
493 <li><p><code class="literal">Bootstrapping the database</code>:
494 If this step fails, it is likely that the previous step
495 (<code class="literal">Starting web server</code>) also failed. Another
496 reason that it could fail is if <code class="envar">PLC_API_HOST</code> (see
497 <a href="#Configuration" title="3.3. Changing the configuration">Section 3.3, “Changing the configuration”</a>) does not resolve to
498 the host on which the API server has been enabled. By default,
499 all services, including the API server, are enabled and run on
500 the same host, so check that <code class="envar">PLC_API_HOST</code> is
501 either <code class="filename">localhost</code> or resolves to a local IP
502 address. Also check that <code class="envar">PLC_ROOT_USER</code> looks like
503 an e-mail address.</p></li>
504 <li><p><code class="literal">Starting crond</code>: If this step
505 fails, it is likely that the previous steps (<code class="literal">Starting
506 web server</code> and <code class="literal">Bootstrapping the
507 database</code>) also failed. If not, check
508 <code class="filename">/plc/root/var/log/boot.log</code> for obvious
509 errors. This step starts the <span><strong class="command">cron</strong></span> service and
510 generates the initial set of XML files that the Slice Creation
511 Service uses to determine slice state.</p></li>
513 <p>If no failures occur, then MyPLC should be active with a
514 default configuration. Open a web browser on the host system and
515 visit <code class="literal">http://localhost/</code>, which should bring you
516 to the front page of your PLC installation. The password of the
517 default administrator account
518 <code class="literal">root@localhost.localdomain</code> (set by
519 <code class="envar">PLC_ROOT_USER</code>) is <code class="literal">root</code> (set by
520 <code class="envar">PLC_ROOT_PASSWORD</code>).</p>
522 <div class="section" lang="en">
523 <div class="titlepage"><div><div><h3 class="title">
524 <a name="FilesInvolvedRuntime"></a>3.9. Files and directories
525 involved in <span class="emphasis"><em>myplc</em></span></h3></div></div></div>
526 <p>MyPLC installs the following files and directories:</p>
527 <div class="orderedlist"><ol type="1">
528 <li><p><code class="filename">/plc/root.img</code>: The main
529 root filesystem of the MyPLC application. This file is an
530 uncompressed ext3 filesystem that is loopback mounted on
531 <code class="filename">/plc/root</code> when MyPLC starts. This
532 filesystem, even when mounted, should be treated as an opaque
533 binary that can and will be replaced in its entirety by any
534 upgrade of MyPLC.</p></li>
535 <li><p><code class="filename">/plc/root</code>: The mount point
536 for <code class="filename">/plc/root.img</code>. Once the root filesystem
537 is mounted, all MyPLC services run in a
538 <span><strong class="command">chroot</strong></span> jail based in this
541 <p><code class="filename">/plc/data</code>: The directory where user
542 data and generated files are stored. This directory is bind
543 mounted onto <code class="filename">/plc/root/data</code> so that it is
544 accessible as <code class="filename">/data</code> from within the
545 <span><strong class="command">chroot</strong></span> jail. Files in this directory are
546 marked with <span><strong class="command">%config(noreplace)</strong></span> in the
547 RPM. That is, during an upgrade of MyPLC, if a file has not
548 changed since the last installation or upgrade of MyPLC, it is
549 subject to upgrade and replacement. If the file has changed,
550 the new version of the file will be created with a
551 <code class="filename">.rpmnew</code> extension. Symlinks within the
552 MyPLC root filesystem ensure that the following directories
553 (relative to <code class="filename">/plc/root</code>) are stored
554 outside the MyPLC filesystem image:</p>
555 <div class="itemizedlist"><ul type="disc">
556 <li><p><code class="filename">/etc/planetlab</code>: This
557 directory contains the configuration files, keys, and
558 certificates that define your MyPLC
559 installation.</p></li>
560 <li><p><code class="filename">/var/lib/pgsql</code>: This
561 directory contains PostgreSQL database
563 <li><p><code class="filename">/var/www/html/alpina-logs</code>: This
564 directory contains node installation logs.</p></li>
565 <li><p><code class="filename">/var/www/html/boot</code>: This
566 directory contains the Boot Manager, customized for your MyPLC
567 installation, and its data files.</p></li>
568 <li><p><code class="filename">/var/www/html/download</code>: This
569 directory contains Boot CD images, customized for your MyPLC
570 installation.</p></li>
571 <li><p><code class="filename">/var/www/html/install-rpms</code>: This
572 directory is where you should install node package updates,
573 if any. By default, nodes are installed from the tarball
575 <code class="filename">/var/www/html/boot/PlanetLab-Bootstrap.tar.bz2</code>,
576 which is pre-built from the latest PlanetLab Central
577 sources, and installed as part of your MyPLC
578 installation. However, nodes will attempt to install any
579 newer RPMs located in
580 <code class="filename">/var/www/html/install-rpms/planetlab</code>,
581 after initial installation and periodically thereafter. You
582 must run <span><strong class="command">yum-arch</strong></span> and
583 <span><strong class="command">createrepo</strong></span> to update the
584 <span><strong class="command">yum</strong></span> caches in this directory after
585 installing a new RPM. PlanetLab Central cannot support any
586 changes to this directory.</p></li>
587 <li><p><code class="filename">/var/www/html/xml</code>: This
588 directory contains various XML files that the Slice Creation
589 Service uses to determine the state of slices. These XML
590 files are refreshed periodically by <span><strong class="command">cron</strong></span>
591 jobs running in the MyPLC root.</p></li>
592 <li><p><code class="filename">/root</code>: this is the
593 location of the root-user's homedir, and for your
594 convenience is stored under <code class="filename">/data</code> so
595 that your local customizations survive across
596 updates - this feature is inherited from the
597 <span><strong class="command">myplc-devel</strong></span> package, where it is probably
598 more useful. </p></li>
601 <li><p><a name="MyplcInitScripts"></a><code class="filename">/etc/init.d/plc</code>: This file
602 is a System V init script installed on your host filesystem,
603 that allows you to start up and shut down MyPLC with a single
604 command, as described in <a href="#QuickStart" title="3.2. QuickStart ">Section 3.2, “ QuickStart ”</a>.</p></li>
605 <li><p><code class="filename">/etc/sysconfig/plc</code>: This
606 file is a shell script fragment that defines the variables
607 <code class="envar">PLC_ROOT</code> and <code class="envar">PLC_DATA</code>. By default,
608 the values of these variables are <code class="filename">/plc/root</code>
609 and <code class="filename">/plc/data</code>, respectively. If you wish,
610 you may move your MyPLC installation to another location on your
611 host filesystem and edit the values of these variables
612 appropriately, but you will break the RPM upgrade
613 process. PlanetLab Central cannot support any changes to this
615 <li><p><code class="filename">/etc/planetlab</code>: This
616 symlink to <code class="filename">/plc/data/etc/planetlab</code> is
617 installed on the host system for convenience.</p></li>
621 <div class="section" lang="en">
622 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
623 <a name="DevelopmentEnvironment"></a>4. Rebuilding and customizing MyPLC</h2></div></div></div>
624 <p>The MyPLC package, though distributed as an RPM, is not a
625 traditional package that can be easily rebuilt from SRPM. The
626 requisite build environment is quite extensive and numerous
627 assumptions are made throughout the PlanetLab source code base,
628 that the build environment is based on Fedora Core 4 and that
629 access to a complete Fedora Core 4 mirror is available.</p>
630 <p>For this reason, it is recommended that you only rebuild
631 MyPLC (or any of its components) from within the MyPLC development
632 environment. The MyPLC development environment is similar to MyPLC
633 itself in that it is a portable filesystem contained within a
634 <span><strong class="command">chroot</strong></span> jail. The filesystem contains all the
635 necessary tools required to rebuild MyPLC, as well as a snapshot
636 of the PlanetLab source code base in the form of a local CVS
638 <div class="section" lang="en">
639 <div class="titlepage"><div><div><h3 class="title">
640 <a name="id2802612"></a>4.1. Installation</h3></div></div></div>
641 <p>Install the MyPLC development environment similarly to how
642 you would install MyPLC. You may install both packages on the same
643 host system if you wish. As with MyPLC, the MyPLC development
644 environment should be treated as a monolithic software
645 application, and any files present in the
646 <span><strong class="command">chroot</strong></span> jail should not be modified directly, as
647 they are subject to upgrade.</p>
648 <div class="itemizedlist"><ul type="disc">
650 <p>If your distribution supports RPM:</p>
651 <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>
654 <p>If your distribution does not support RPM:</p>
655 <pre class="programlisting"># cd /tmp
656 # wget http://build.planet-lab.org/build/myplc-0_4-rc2/RPMS/i386/myplc-devel-0.4-2.planetlab.i386.rpm
658 # rpm2cpio /tmp/myplc-devel-0.4-2.planetlab.i386.rpm | cpio -diu</pre>
662 <div class="section" lang="en">
663 <div class="titlepage"><div><div><h3 class="title">
664 <a name="id2802667"></a>4.2. Configuration</h3></div></div></div>
665 <p> The default configuration should work as-is on most
666 sites. Configuring the development package can be achieved in a
667 similar way as for <span class="emphasis"><em>myplc</em></span>, as described in
668 <a href="#Configuration" title="3.3. Changing the configuration">Section 3.3, “Changing the configuration”</a>. <span><strong class="command">plc-config-tty</strong></span> supports a
669 <span class="emphasis"><em>-d</em></span> option for supporting the
670 <span class="emphasis"><em>myplc-devel</em></span> case, that can be useful in a
671 context where it would not guess it by itself. Refer to <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> for a list of variables.</p>
673 <div class="section" lang="en">
674 <div class="titlepage"><div><div><h3 class="title">
675 <a name="FilesInvolvedDevel"></a>4.3. Files and directories
676 involved in <span class="emphasis"><em>myplc-devl</em></span></h3></div></div></div>
677 <p>The MyPLC development environment installs the following
678 files and directories:</p>
679 <div class="itemizedlist"><ul type="disc">
680 <li><p><code class="filename">/plc/devel/root.img</code>: The
681 main root filesystem of the MyPLC development environment. This
682 file is an uncompressed ext3 filesystem that is loopback mounted
683 on <code class="filename">/plc/devel/root</code> when the MyPLC
684 development environment is initialized. This filesystem, even
685 when mounted, should be treated as an opaque binary that can and
686 will be replaced in its entirety by any upgrade of the MyPLC
687 development environment.</p></li>
688 <li><p><code class="filename">/plc/devel/root</code>: The mount
690 <code class="filename">/plc/devel/root.img</code>.</p></li>
692 <p><code class="filename">/plc/devel/data</code>: The directory
693 where user data and generated files are stored. This directory
694 is bind mounted onto <code class="filename">/plc/devel/root/data</code>
695 so that it is accessible as <code class="filename">/data</code> from
696 within the <span><strong class="command">chroot</strong></span> jail. Files in this
697 directory are marked with
698 <span><strong class="command">%config(noreplace)</strong></span> in the RPM. Symlinks
699 ensure that the following directories (relative to
700 <code class="filename">/plc/devel/root</code>) are stored outside the
701 root filesystem image:</p>
702 <div class="itemizedlist"><ul type="circle">
703 <li><p><code class="filename">/etc/planetlab</code>: This
704 directory contains the configuration files that define your
705 MyPLC development environment.</p></li>
706 <li><p><code class="filename">/cvs</code>: A
707 snapshot of the PlanetLab source code is stored as a CVS
708 repository in this directory. Files in this directory will
709 <span class="bold"><strong>not</strong></span> be updated by an upgrade of
710 <code class="filename">myplc-devel</code>. See <a href="#UpdatingCVS" title="4.6. Updating CVS">Section 4.6, “Updating CVS”</a> for more information about updating
711 PlanetLab source code.</p></li>
712 <li><p><code class="filename">/build</code>:
713 Builds are stored in this directory. This directory is bind
714 mounted onto <code class="filename">/plc/devel/root/build</code> so that
715 it is accessible as <code class="filename">/build</code> from within the
716 <span><strong class="command">chroot</strong></span> jail. The build scripts in this
717 directory are themselves source controlled; see <a href="#BuildingMyPLC" title="4.5. Building MyPLC">Section 4.5, “Building MyPLC”</a> for more information about executing
719 <li><p><code class="filename">/root</code>: this is the
720 location of the root-user's homedir, and for your
721 convenience is stored under <code class="filename">/data</code> so
722 that your local customizations survive across
726 <li><p><code class="filename">/etc/init.d/plc-devel</code>: This file is
727 a System V init script installed on your host filesystem, that
728 allows you to start up and shut down the MyPLC development
729 environment with a single command.</p></li>
732 <div class="section" lang="en">
733 <div class="titlepage"><div><div><h3 class="title">
734 <a name="id2802931"></a>4.4. Fedora Core 4 mirror requirement</h3></div></div></div>
735 <p>The MyPLC development environment requires access to a
736 complete Fedora Core 4 i386 RPM repository, because several
737 different filesystems based upon Fedora Core 4 are constructed
738 during the process of building MyPLC. You may configure the
739 location of this repository via the
740 <code class="envar">PLC_DEVEL_FEDORA_URL</code> variable in
741 <code class="filename">/plc/devel/data/etc/planetlab/plc_config.xml</code>. The
742 value of the variable should be a URL that points to the top
743 level of a Fedora mirror that provides the
744 <code class="filename">base</code>, <code class="filename">updates</code>, and
745 <code class="filename">extras</code> repositories, e.g.,</p>
746 <div class="itemizedlist"><ul type="disc">
747 <li><p><code class="filename">file:///data/fedora</code></p></li>
748 <li><p><code class="filename">http://coblitz.planet-lab.org/pub/fedora</code></p></li>
749 <li><p><code class="filename">ftp://mirror.cs.princeton.edu/pub/mirrors/fedora</code></p></li>
750 <li><p><code class="filename">ftp://mirror.stanford.edu/pub/mirrors/fedora</code></p></li>
751 <li><p><code class="filename">http://rpmfind.net/linux/fedora</code></p></li>
753 <p>As implied by the list, the repository may be located on
754 the local filesystem, or it may be located on a remote FTP or
755 HTTP server. URLs beginning with <code class="filename">file://</code>
756 should exist at the specified location relative to the root of
757 the <span><strong class="command">chroot</strong></span> jail. For optimum performance and
758 reproducibility, specify
759 <code class="envar">PLC_DEVEL_FEDORA_URL=file:///data/fedora</code> and
760 download all Fedora Core 4 RPMS into
761 <code class="filename">/plc/devel/data/fedora</code> on the host system
762 after installing <code class="filename">myplc-devel</code>. Use a tool
763 such as <span><strong class="command">wget</strong></span> or <span><strong class="command">rsync</strong></span> to
764 download the RPMS from a public mirror:</p>
765 <div class="example">
766 <a name="id2803072"></a><p class="title"><b>Example 9. Setting up a local Fedora Core 4 repository.</b></p>
767 <pre class="programlisting"># mkdir -p /plc/devel/data/fedora
768 # cd /plc/devel/data/fedora
770 # for repo in core/4/i386/os core/updates/4/i386 extras/4/i386 ; do
771 > wget -m -nH --cut-dirs=3 http://coblitz.planet-lab.org/pub/fedora/linux/$repo
774 <p>Change the repository URI and <span><strong class="command">--cut-dirs</strong></span>
775 level as needed to produce a hierarchy that resembles:</p>
776 <pre class="programlisting">/plc/devel/data/fedora/core/4/i386/os
777 /plc/devel/data/fedora/core/updates/4/i386
778 /plc/devel/data/fedora/extras/4/i386</pre>
779 <p>A list of additional Fedora Core 4 mirrors is available at
780 <a href="http://fedora.redhat.com/Download/mirrors.html" target="_top">http://fedora.redhat.com/Download/mirrors.html</a>.</p>
782 <div class="section" lang="en">
783 <div class="titlepage"><div><div><h3 class="title">
784 <a name="BuildingMyPLC"></a>4.5. Building MyPLC</h3></div></div></div>
785 <p>All PlanetLab source code modules are built and installed
786 as RPMS. A set of build scripts, checked into the
787 <code class="filename">build/</code> directory of the PlanetLab CVS
788 repository, eases the task of rebuilding PlanetLab source
790 <p> Before you try building MyPLC, you might check the
791 configuration, in a file named
792 <span class="emphasis"><em>plc_config.xml</em></span> that relies on a very
793 similar model as MyPLC, located in
794 <span class="emphasis"><em>/etc/planetlab</em></span> within the chroot jail, or
795 in <span class="emphasis"><em>/plc/devel/data/etc/planetlab</em></span> from the
796 root context. The set of applicable variables is described in
797 <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>
798 <p>To build MyPLC, or any PlanetLab source code module, from
799 within the MyPLC development environment, execute the following
800 commands as root:</p>
801 <div class="example">
802 <a name="id2803174"></a><p class="title"><b>Example 10. Building MyPLC.</b></p>
803 <pre class="programlisting"># Initialize MyPLC development environment
804 service plc-devel start
806 # Enter development environment
807 chroot /plc/devel/root su -
809 # Check out build scripts into a directory named after the current
810 # date. This is simply a convention, it need not be followed
811 # exactly. See build/build.sh for an example of a build script that
812 # names build directories after CVS tags.
813 DATE=$(date +%Y.%m.%d)
815 cvs -d /cvs checkout -d $DATE build
820 <p>If the build succeeds, a set of binary RPMS will be
822 <code class="filename">/plc/devel/data/build/$DATE/RPMS/</code> that you
824 <code class="filename">/var/www/html/install-rpms/planetlab</code>
825 directory of your MyPLC installation (see <a href="#Installation" title="3. Installating and using MyPLC">Section 3, “Installating and using MyPLC”</a>).</p>
827 <div class="section" lang="en">
828 <div class="titlepage"><div><div><h3 class="title">
829 <a name="UpdatingCVS"></a>4.6. Updating CVS</h3></div></div></div>
830 <p>A complete snapshot of the PlanetLab source code is included
831 with the MyPLC development environment as a CVS repository in
832 <code class="filename">/plc/devel/data/cvs</code>. This CVS repository may
833 be accessed like any other CVS repository. It may be accessed
834 using an interface such as <a href="http://www.freebsd.org/projects/cvsweb.html" target="_top">CVSweb</a>,
835 and file permissions may be altered to allow for fine-grained
836 access control. Although the files are included with the
837 <code class="filename">myplc-devel</code> RPM, they are <span class="bold"><strong>not</strong></span> subject to upgrade once installed. New
838 versions of the <code class="filename">myplc-devel</code> RPM will install
839 updated snapshot repositories in
840 <code class="filename">/plc/devel/data/cvs-%{version}-%{release}</code>,
841 where <code class="literal">%{version}-%{release}</code> is replaced with
842 the version number of the RPM.</p>
843 <p>Because the CVS repository is not automatically upgraded,
844 if you wish to keep your local repository synchronized with the
845 public PlanetLab repository, it is highly recommended that you
846 use CVS's support for vendor branches to track changes, as
847 described <a href="http://ximbiot.com/cvs/wiki/index.php?title=CVS--Concurrent_Versions_System_v1.12.12.1:_Tracking_third-party_sources" target="_top">here</a>
848 and <a href="http://cvsbook.red-bean.com/cvsbook.html#Tracking%20Third-Party%20Sources%20(Vendor%20Branches)" target="_top">here</a>.
849 Vendor branches ease the task of merging upstream changes with
850 your local modifications. To import a new snapshot into your
851 local repository (for example, if you have just upgraded from
852 <code class="filename">myplc-devel-0.4-2</code> to
853 <code class="filename">myplc-devel-0.4-3</code> and you notice the new
854 repository in <code class="filename">/plc/devel/data/cvs-0.4-3</code>),
855 execute the following commands as root from within the MyPLC
856 development environment:</p>
857 <div class="example">
858 <a name="id2803332"></a><p class="title"><b>Example 11. Updating /data/cvs from /data/cvs-0.4-3.</b></p>
859 <p><span class="bold"><strong>Warning</strong></span>: This may cause
860 severe, irreversible changes to be made to your local
861 repository. Always tag your local repository before
863 <pre class="programlisting"># Initialize MyPLC development environment
864 service plc-devel start
866 # Enter development environment
867 chroot /plc/devel/root su -
870 cvs -d /cvs rtag before-myplc-0_4-3-merge
873 TMP=$(mktemp -d /data/export.XXXXXX)
875 cvs -d /data/cvs-0.4-3 export -r HEAD .
876 cvs -d /cvs import -m "Merging myplc-0.4-3" -ko -I ! . planetlab myplc-0_4-3
880 <p>If there are any merge conflicts, use the command
881 suggested by CVS to help the merge. Explaining how to fix merge
882 conflicts is beyond the scope of this document; consult the CVS
883 documentation for more information on how to use CVS.</p>
886 <div class="appendix" lang="en">
887 <h2 class="title" style="clear: both">
888 <a name="VariablesRuntime"></a>A. Configuration variables (for <span class="emphasis"><em>myplc</em></span>)</h2>
889 <p>Listed below is the set of standard configuration variables
890 and their default values, defined in the template
891 <code class="filename">/etc/planetlab/default_config.xml</code>. Additional
892 variables and their defaults may be defined in site-specific XML
893 templates that should be placed in
894 <code class="filename">/etc/planetlab/configs/</code>.</p>
895 <p>This information is available online within
896 <span><strong class="command">plc-config-tty</strong></span>, e.g.:</p>
897 <div class="example">
898 <a name="id2803414"></a><p class="title"><b>Example A.1. Advanced usage of plc-config-tty</b></p>
899 <pre class="programlisting"><plc> # plc-config-tty
900 Enter command (u for usual changes, w to save, ? for help) V plc_dns
901 ========== Category = PLC_DNS
903 # Enable the internal DNS server. The server does not provide reverse
904 # resolution and is not a production quality or scalable DNS solution.
905 # Use the internal DNS server only for small deployments or for testing.
909 <p> List of the <span><strong class="command">myplc</strong></span> configuration variables:</p>
910 <div class="variablelist"><dl>
911 <dt><span class="term">PLC_NAME</span></dt>
916 Default: PlanetLab Test</p>
917 <p>The name of this PLC installation. It is used in
918 the name of the default system site (e.g., PlanetLab Central)
919 and in the names of various administrative entities (e.g.,
920 PlanetLab Support).</p>
922 <dt><span class="term">PLC_SLICE_PREFIX</span></dt>
928 <p>The abbreviated name of this PLC
929 installation. It is used as the prefix for system slices
930 (e.g., pl_conf). Warning: Currently, this variable should
933 <dt><span class="term">PLC_ROOT_USER</span></dt>
938 Default: root@localhost.localdomain</p>
939 <p>The name of the initial administrative
940 account. We recommend that this account be used only to create
941 additional accounts associated with real
942 administrators, then disabled.</p>
944 <dt><span class="term">PLC_ROOT_PASSWORD</span></dt>
950 <p>The password of the initial administrative
951 account. Also the password of the root account on the Boot
954 <dt><span class="term">PLC_ROOT_SSH_KEY_PUB</span></dt>
959 Default: /etc/planetlab/root_ssh_key.pub</p>
960 <p>The SSH public key used to access the root
961 account on your nodes.</p>
963 <dt><span class="term">PLC_ROOT_SSH_KEY</span></dt>
968 Default: /etc/planetlab/root_ssh_key.rsa</p>
969 <p>The SSH private key used to access the root
970 account on your nodes.</p>
972 <dt><span class="term">PLC_DEBUG_SSH_KEY_PUB</span></dt>
977 Default: /etc/planetlab/debug_ssh_key.pub</p>
978 <p>The SSH public key used to access the root
979 account on your nodes when they are in Debug mode.</p>
981 <dt><span class="term">PLC_DEBUG_SSH_KEY</span></dt>
986 Default: /etc/planetlab/debug_ssh_key.rsa</p>
987 <p>The SSH private key used to access the root
988 account on your nodes when they are in Debug mode.</p>
990 <dt><span class="term">PLC_ROOT_GPG_KEY_PUB</span></dt>
995 Default: /etc/planetlab/pubring.gpg</p>
996 <p>The GPG public keyring used to sign the Boot
997 Manager and all node packages.</p>
999 <dt><span class="term">PLC_ROOT_GPG_KEY</span></dt>
1004 Default: /etc/planetlab/secring.gpg</p>
1005 <p>The SSH private key used to access the root
1006 account on your nodes.</p>
1008 <dt><span class="term">PLC_MA_SA_NAMESPACE</span></dt>
1014 <p>The namespace of your MA/SA. This should be a
1015 globally unique value assigned by PlanetLab
1018 <dt><span class="term">PLC_MA_SA_SSL_KEY</span></dt>
1023 Default: /etc/planetlab/ma_sa_ssl.key</p>
1024 <p>The SSL private key used for signing documents
1025 with the signature of your MA/SA. If non-existent, one will
1028 <dt><span class="term">PLC_MA_SA_SSL_CRT</span></dt>
1033 Default: /etc/planetlab/ma_sa_ssl.crt</p>
1034 <p>The corresponding SSL public certificate. By
1035 default, this certificate is self-signed. You may replace
1036 the certificate later with one signed by the PLC root
1039 <dt><span class="term">PLC_MA_SA_CA_SSL_CRT</span></dt>
1044 Default: /etc/planetlab/ma_sa_ca_ssl.crt</p>
1045 <p>If applicable, the certificate of the PLC root
1046 CA. If your MA/SA certificate is self-signed, then this file
1047 is the same as your MA/SA certificate.</p>
1049 <dt><span class="term">PLC_MA_SA_CA_SSL_KEY_PUB</span></dt>
1054 Default: /etc/planetlab/ma_sa_ca_ssl.pub</p>
1055 <p>If applicable, the public key of the PLC root
1056 CA. If your MA/SA certificate is self-signed, then this file
1057 is the same as your MA/SA public key.</p>
1059 <dt><span class="term">PLC_MA_SA_API_CRT</span></dt>
1064 Default: /etc/planetlab/ma_sa_api.xml</p>
1065 <p>The API Certificate is your MA/SA public key
1066 embedded in a digitally signed XML document. By default,
1067 this document is self-signed. You may replace this
1068 certificate later with one signed by the PLC root
1071 <dt><span class="term">PLC_NET_DNS1</span></dt>
1076 Default: 127.0.0.1</p>
1077 <p>Primary DNS server address.</p>
1079 <dt><span class="term">PLC_NET_DNS2</span></dt>
1085 <p>Secondary DNS server address.</p>
1087 <dt><span class="term">PLC_DNS_ENABLED</span></dt>
1093 <p>Enable the internal DNS server. The server does
1094 not provide reverse resolution and is not a production
1095 quality or scalable DNS solution. Use the internal DNS
1096 server only for small deployments or for
1099 <dt><span class="term">PLC_MAIL_ENABLED</span></dt>
1105 <p>Set to false to suppress all e-mail notifications
1108 <dt><span class="term">PLC_MAIL_SUPPORT_ADDRESS</span></dt>
1113 Default: root+support@localhost.localdomain</p>
1114 <p>This address is used for support
1115 requests. Support requests may include traffic complaints,
1116 security incident reporting, web site malfunctions, and
1117 general requests for information. We recommend that the
1118 address be aliased to a ticketing system such as Request
1121 <dt><span class="term">PLC_MAIL_BOOT_ADDRESS</span></dt>
1126 Default: root+install-msgs@localhost.localdomain</p>
1127 <p>The API will notify this address when a problem
1128 occurs during node installation or boot.</p>
1130 <dt><span class="term">PLC_MAIL_SLICE_ADDRESS</span></dt>
1135 Default: root+SLICE@localhost.localdomain</p>
1136 <p>This address template is used for sending
1137 e-mail notifications to slices. SLICE will be replaced with
1138 the name of the slice.</p>
1140 <dt><span class="term">PLC_DB_ENABLED</span></dt>
1146 <p>Enable the database server on this
1149 <dt><span class="term">PLC_DB_TYPE</span></dt>
1154 Default: postgresql</p>
1155 <p>The type of database server. Currently, only
1156 postgresql is supported.</p>
1158 <dt><span class="term">PLC_DB_HOST</span></dt>
1163 Default: localhost.localdomain</p>
1164 <p>The fully qualified hostname of the database
1167 <dt><span class="term">PLC_DB_IP</span></dt>
1172 Default: 127.0.0.1</p>
1173 <p>The IP address of the database server, if not
1174 resolvable by the configured DNS servers.</p>
1176 <dt><span class="term">PLC_DB_PORT</span></dt>
1182 <p>The TCP port number through which the database
1183 server should be accessed.</p>
1185 <dt><span class="term">PLC_DB_NAME</span></dt>
1190 Default: planetlab3</p>
1191 <p>The name of the database to access.</p>
1193 <dt><span class="term">PLC_DB_USER</span></dt>
1198 Default: pgsqluser</p>
1199 <p>The username to use when accessing the
1202 <dt><span class="term">PLC_DB_PASSWORD</span></dt>
1208 <p>The password to use when accessing the
1209 database. If left blank, one will be
1212 <dt><span class="term">PLC_API_ENABLED</span></dt>
1218 <p>Enable the API server on this
1221 <dt><span class="term">PLC_API_DEBUG</span></dt>
1227 <p>Enable verbose API debugging. Do not enable on
1228 a production system!</p>
1230 <dt><span class="term">PLC_API_HOST</span></dt>
1235 Default: localhost.localdomain</p>
1236 <p>The fully qualified hostname of the API
1239 <dt><span class="term">PLC_API_IP</span></dt>
1244 Default: 127.0.0.1</p>
1245 <p>The IP address of the API server, if not
1246 resolvable by the configured DNS servers.</p>
1248 <dt><span class="term">PLC_API_PORT</span></dt>
1254 <p>The TCP port number through which the API
1255 should be accessed. Warning: SSL (port 443) access is not
1256 fully supported by the website code yet. We recommend that
1257 port 80 be used for now and that the API server either run
1258 on the same machine as the web server, or that they both be
1259 on a secure wired network.</p>
1261 <dt><span class="term">PLC_API_PATH</span></dt>
1266 Default: /PLCAPI/</p>
1267 <p>The base path of the API URL.</p>
1269 <dt><span class="term">PLC_API_MAINTENANCE_USER</span></dt>
1274 Default: maint@localhost.localdomain</p>
1275 <p>The username of the maintenance account. This
1276 account is used by local scripts that perform automated
1277 tasks, and cannot be used for normal logins.</p>
1279 <dt><span class="term">PLC_API_MAINTENANCE_PASSWORD</span></dt>
1285 <p>The password of the maintenance account. If
1286 left blank, one will be generated. We recommend that the
1287 password be changed periodically.</p>
1289 <dt><span class="term">PLC_API_MAINTENANCE_SOURCES</span></dt>
1295 <p>A space-separated list of IP addresses allowed
1296 to access the API through the maintenance account. The value
1297 of this variable is set automatically to allow only the API,
1298 web, and boot servers, and should not be
1301 <dt><span class="term">PLC_API_SSL_KEY</span></dt>
1306 Default: /etc/planetlab/api_ssl.key</p>
1307 <p>The SSL private key to use for encrypting HTTPS
1308 traffic. If non-existent, one will be
1311 <dt><span class="term">PLC_API_SSL_CRT</span></dt>
1316 Default: /etc/planetlab/api_ssl.crt</p>
1317 <p>The corresponding SSL public certificate. By
1318 default, this certificate is self-signed. You may replace
1319 the certificate later with one signed by a root
1322 <dt><span class="term">PLC_API_CA_SSL_CRT</span></dt>
1327 Default: /etc/planetlab/api_ca_ssl.crt</p>
1328 <p>The certificate of the root CA, if any, that
1329 signed your server certificate. If your server certificate is
1330 self-signed, then this file is the same as your server
1333 <dt><span class="term">PLC_WWW_ENABLED</span></dt>
1339 <p>Enable the web server on this
1342 <dt><span class="term">PLC_WWW_DEBUG</span></dt>
1348 <p>Enable debugging output on web pages. Do not
1349 enable on a production system!</p>
1351 <dt><span class="term">PLC_WWW_HOST</span></dt>
1356 Default: localhost.localdomain</p>
1357 <p>The fully qualified hostname of the web
1360 <dt><span class="term">PLC_WWW_IP</span></dt>
1365 Default: 127.0.0.1</p>
1366 <p>The IP address of the web server, if not
1367 resolvable by the configured DNS servers.</p>
1369 <dt><span class="term">PLC_WWW_PORT</span></dt>
1375 <p>The TCP port number through which the
1376 unprotected portions of the web site should be
1379 <dt><span class="term">PLC_WWW_SSL_PORT</span></dt>
1385 <p>The TCP port number through which the protected
1386 portions of the web site should be accessed.</p>
1388 <dt><span class="term">PLC_WWW_SSL_KEY</span></dt>
1393 Default: /etc/planetlab/www_ssl.key</p>
1394 <p>The SSL private key to use for encrypting HTTPS
1395 traffic. If non-existent, one will be
1398 <dt><span class="term">PLC_WWW_SSL_CRT</span></dt>
1403 Default: /etc/planetlab/www_ssl.crt</p>
1404 <p>The corresponding SSL public certificate for
1405 the HTTP server. By default, this certificate is
1406 self-signed. You may replace the certificate later with one
1407 signed by a root CA.</p>
1409 <dt><span class="term">PLC_WWW_CA_SSL_CRT</span></dt>
1414 Default: /etc/planetlab/www_ca_ssl.crt</p>
1415 <p>The certificate of the root CA, if any, that
1416 signed your server certificate. If your server certificate is
1417 self-signed, then this file is the same as your server
1420 <dt><span class="term">PLC_BOOT_ENABLED</span></dt>
1426 <p>Enable the boot server on this
1429 <dt><span class="term">PLC_BOOT_HOST</span></dt>
1434 Default: localhost.localdomain</p>
1435 <p>The fully qualified hostname of the boot
1438 <dt><span class="term">PLC_BOOT_IP</span></dt>
1443 Default: 127.0.0.1</p>
1444 <p>The IP address of the boot server, if not
1445 resolvable by the configured DNS servers.</p>
1447 <dt><span class="term">PLC_BOOT_PORT</span></dt>
1453 <p>The TCP port number through which the
1454 unprotected portions of the boot server should be
1457 <dt><span class="term">PLC_BOOT_SSL_PORT</span></dt>
1463 <p>The TCP port number through which the protected
1464 portions of the boot server should be
1467 <dt><span class="term">PLC_BOOT_SSL_KEY</span></dt>
1472 Default: /etc/planetlab/boot_ssl.key</p>
1473 <p>The SSL private key to use for encrypting HTTPS
1476 <dt><span class="term">PLC_BOOT_SSL_CRT</span></dt>
1481 Default: /etc/planetlab/boot_ssl.crt</p>
1482 <p>The corresponding SSL public certificate for
1483 the HTTP server. By default, this certificate is
1484 self-signed. You may replace the certificate later with one
1485 signed by a root CA.</p>
1487 <dt><span class="term">PLC_BOOT_CA_SSL_CRT</span></dt>
1492 Default: /etc/planetlab/boot_ca_ssl.crt</p>
1493 <p>The certificate of the root CA, if any, that
1494 signed your server certificate. If your server certificate is
1495 self-signed, then this file is the same as your server
1500 <div class="appendix" lang="en">
1501 <h2 class="title" style="clear: both">
1502 <a name="VariablesDevel"></a>B. Development configuration variables (for <span class="emphasis"><em>myplc-devel</em></span>)</h2>
1503 <div class="variablelist"><dl>
1504 <dt><span class="term">PLC_DEVEL_FEDORA_RELEASE</span></dt>
1510 <p>Version number of Fedora Core upon which to
1511 base the build environment. Warning: Currently, only Fedora
1512 Core 4 is supported.</p>
1514 <dt><span class="term">PLC_DEVEL_FEDORA_ARCH</span></dt>
1520 <p>Base architecture of the build
1521 environment. Warning: Currently, only i386 is
1524 <dt><span class="term">PLC_DEVEL_FEDORA_URL</span></dt>
1529 Default: file:///data/fedora</p>
1530 <p>Fedora Core mirror from which to install
1533 <dt><span class="term">PLC_DEVEL_CVSROOT</span></dt>
1539 <p>CVSROOT to use when checking out code.</p>
1541 <dt><span class="term">PLC_DEVEL_BOOTSTRAP</span></dt>
1547 <p>Controls whether MyPLC should be built inside
1548 of its own development environment.</p>
1552 <div class="bibliography">
1553 <div class="titlepage"><div><div><h2 class="title">
1554 <a name="id2806472"></a>Bibliography</h2></div></div></div>
1555 <div class="biblioentry">
1556 <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
1557 Technical Contact's Guide</a></i>. </span></p>
1560 </div><?php require('footer.php'); ?>