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="id2580765"></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="#id2627573">1. Overview</a></span></dt>
58 <dd><dl><dt><span class="section"><a href="#id2627899">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="#id2627214">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="#id2628411">3.5. Installing nodes</a></span></dt>
68 <dt><span class="section"><a href="#id2679354">3.6. Administering nodes</a></span></dt>
69 <dt><span class="section"><a href="#id2679454">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="#id2680347">4.1. Installation</a></span></dt>
77 <dt><span class="section"><a href="#id2680401">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="#id2680665">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="section"><a href="#id2681106">5. More information : the FAQ wiki page</a></span></dt>
85 <dt><span class="appendix"><a href="#VariablesRuntime">A. Configuration variables (for <span class="emphasis"><em>myplc</em></span>)</a></span></dt>
86 <dt><span class="appendix"><a href="#VariablesDevel">B. Development configuration variables (for <span class="emphasis"><em>myplc-devel</em></span>)</a></span></dt>
87 <dt><span class="bibliography"><a href="#id2684223">Bibliography</a></span></dt>
90 <div class="section" lang="en">
91 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
92 <a name="id2627573"></a>1. Overview</h2></div></div></div>
93 <p>MyPLC is a complete PlanetLab Central (PLC) portable
94 installation contained within a <span><strong class="command">chroot</strong></span>
95 jail. The default installation consists of a web server, an
96 XML-RPC API server, a boot server, and a database server: the core
97 components of PLC. The installation is customized through an
98 easy-to-use graphical interface. All PLC services are started up
99 and shut down through a single script installed on the host
100 system. The usually complex process of installing and
101 administering the PlanetLab backend is reduced by containing PLC
102 services within a virtual filesystem. By packaging it in such a
103 manner, MyPLC may also be run on any modern Linux distribution,
104 and could conceivably even run in a PlanetLab slice.</p>
106 <a name="Architecture"></a><p class="title"><b>Figure 1. MyPLC architecture</b></p>
107 <div class="mediaobject" align="center">
108 <img src="architecture.png" align="middle" width="270" alt="MyPLC architecture"><div class="caption"><p>MyPLC should be viewed as a single application that
109 provides multiple functions and can run on any host
113 <div class="section" lang="en">
114 <div class="titlepage"><div><div><h3 class="title">
115 <a name="id2627899"></a>1.1. Purpose of the <span class="emphasis"><em> myplc-devel
116 </em></span> package </h3></div></div></div>
117 <p> The <span class="emphasis"><em>myplc</em></span> package comes with all
118 required node software, rebuilt from the public PlanetLab CVS
119 repository. If for any reason you need to implement your own
120 customized version of this software, you can use the
121 <span class="emphasis"><em>myplc-devel</em></span> package instead, for setting up
122 your own development environment, including a local CVS
123 repository; you can then freely manage your changes and rebuild
124 your customized version of <span class="emphasis"><em>myplc</em></span>. We also
125 provide good practices, that will then allow you to resync your local
126 CVS repository with any further evolution on the mainstream public
127 PlanetLab software. </p>
130 <div class="section" lang="en">
131 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
132 <a name="Requirements"></a>2. Requirements </h2></div></div></div>
133 <p> <span class="emphasis"><em>myplc</em></span> and
134 <span class="emphasis"><em>myplc-devel</em></span> were designed as
135 <span><strong class="command">chroot</strong></span> jails so as to reduce the requirements on
136 your host operating system. So in theory, these distributions should
137 work on virtually any Linux 2.6 based distribution, whether it
138 supports rpm or not. </p>
139 <p> However, things are never that simple and there indeed are
140 some known limitations to this, so here are a couple notes as a
141 recommended reading before you proceed with the installation.</p>
142 <p> As of 17 August 2006 (i.e <span class="emphasis"><em>myplc-0.5-2</em></span>) :</p>
143 <div class="itemizedlist"><ul type="disc">
144 <li><p> The software is vastly based on <span class="emphasis"><em>Fedora
145 Core 4</em></span>. Please note that the build server at Princeton
146 runs <span class="emphasis"><em>Fedora Core 2</em></span>, togother with a upgraded
150 <p> myplc and myplc-devel are known to work on both
151 <span class="emphasis"><em>Fedora Core 2</em></span> and <span class="emphasis"><em>Fedora Core
152 4</em></span>. Please note however that, on fc4 at least, it is
153 highly recommended to use the <span class="application">Security Level
154 Configuration</span> utility and to <span class="emphasis"><em>switch off
155 SElinux</em></span> on your box because : </p>
156 <div class="itemizedlist"><ul type="circle">
158 myplc requires you to run SElinux as 'Permissive' at most
161 myplc-devel requires you to turn SElinux Off.
165 <li><p> In addition, as far as myplc is concerned, you
166 need to check your firewall configuration since you need, of course,
167 to open up the <span class="emphasis"><em>http</em></span> and
168 <span class="emphasis"><em>https</em></span> ports, so as to accept connections from
169 the managed nodes and from the users desktops. </p></li>
172 <div class="section" lang="en">
173 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
174 <a name="Installation"></a>3. Installating and using MyPLC</h2></div></div></div>
175 <p>Though internally composed of commodity software
176 subpackages, MyPLC should be treated as a monolithic software
177 application. MyPLC is distributed as single RPM package that has
178 no external dependencies, allowing it to be installed on
179 practically any Linux 2.6 based distribution.</p>
180 <div class="section" lang="en">
181 <div class="titlepage"><div><div><h3 class="title">
182 <a name="id2627214"></a>3.1. Installing MyPLC.</h3></div></div></div>
183 <div class="itemizedlist"><ul type="disc">
185 <p>If your distribution supports RPM:</p>
186 <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>
189 <p>If your distribution does not support RPM:</p>
190 <pre class="programlisting"># cd /tmp
191 # wget http://build.planet-lab.org/build/myplc-0_4-rc1/RPMS/i386/myplc-0.4-1.planetlab.i386.rpm
193 # rpm2cpio /tmp/myplc-0.4-1.planetlab.i386.rpm | cpio -diu</pre>
196 <p> The <a href="#FilesInvolvedRuntime" title="3.9. Files and directories
197 involved in myplc">Section 3.9, “ Files and directories
198 involved in <span class="emphasis"><em>myplc</em></span>”</a> below explains in
199 details the installation strategy and the miscellaneous files and
200 directories involved.</p>
202 <div class="section" lang="en">
203 <div class="titlepage"><div><div><h3 class="title">
204 <a name="QuickStart"></a>3.2. QuickStart </h3></div></div></div>
205 <p> On a Red Hat or Fedora host system, it is customary to use
206 the <span><strong class="command">service</strong></span> command to invoke System V init
207 scripts. As the examples suggest, the service must be started as root:</p>
208 <div class="example">
209 <a name="id2627387"></a><p class="title"><b>Example 1. Starting MyPLC:</b></p>
210 <pre class="programlisting"># service plc start</pre>
212 <div class="example">
213 <a name="id2627399"></a><p class="title"><b>Example 2. Stopping MyPLC:</b></p>
214 <pre class="programlisting"># service plc stop</pre>
216 <p> In <a href="#StartupSequence" title="3.8. Understanding the startup sequence">Section 3.8, “Understanding the startup sequence”</a>, we provide greater
217 details that might be helpful in the case where the service does
218 not seem to take off correctly.</p>
219 <p>Like all other registered System V init services, MyPLC is
220 started and shut down automatically when your host system boots
221 and powers off. You may disable automatic startup by invoking the
222 <span><strong class="command">chkconfig</strong></span> command on a Red Hat or Fedora host
224 <div class="example">
225 <a name="id2628050"></a><p class="title"><b>Example 3. Disabling automatic startup of MyPLC.</b></p>
226 <pre class="programlisting"># chkconfig plc off</pre>
228 <div class="example">
229 <a name="id2628063"></a><p class="title"><b>Example 4. Re-enabling automatic startup of MyPLC.</b></p>
230 <pre class="programlisting"># chkconfig plc on</pre>
233 <div class="section" lang="en">
234 <div class="titlepage"><div><div><h3 class="title">
235 <a name="Configuration"></a>3.3. Changing the configuration</h3></div></div></div>
236 <p>After verifying that MyPLC is working correctly, shut it
237 down and begin changing some of the default variable
238 values. Shut down MyPLC with <span><strong class="command">service plc stop</strong></span>
239 (see <a href="#QuickStart" title="3.2. QuickStart ">Section 3.2, “ QuickStart ”</a>). </p>
240 <p> The preferred option for changing the configuration is to
241 use the <span><strong class="command">plc-config-tty</strong></span> tool. This tools comes
242 with the root image, so you need to have it mounted first. The
243 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>
244 guides you to the most useful ones. Here is sample session:
246 <div class="example">
247 <a name="id2628131"></a><p class="title"><b>Example 5. Using plc-config-tty for configuration:</b></p>
248 <pre class="programlisting"># service plc mount
250 # chroot /plc/root su -
251 <plc> # plc-config-tty
252 Config file /etc/planetlab/configs/site.xml located under a non-existing directory
253 Want to create /etc/planetlab/configs [y]/n ? y
254 Created directory /etc/planetlab/configs
255 Enter command (u for usual changes, w to save, ? for help) u
256 == PLC_NAME : [PlanetLab Test] OneLab
257 == PLC_ROOT_USER : [root@localhost.localdomain] root@odie.inria.fr
258 == PLC_ROOT_PASSWORD : [root] plain-passwd
259 == PLC_MAIL_SUPPORT_ADDRESS : [root+support@localhost.localdomain] support@one-lab.org
260 == PLC_DB_HOST : [localhost.localdomain] odie.inria.fr
261 == PLC_API_HOST : [localhost.localdomain] odie.inria.fr
262 == PLC_WWW_HOST : [localhost.localdomain] odie.inria.fr
263 == PLC_BOOT_HOST : [localhost.localdomain] odie.inria.fr
264 == PLC_NET_DNS1 : [127.0.0.1] 138.96.250.248
265 == PLC_NET_DNS2 : [None] 138.96.250.249
266 Enter command (u for usual changes, w to save, ? for help) w
267 Wrote /etc/planetlab/configs/site.xml
269 /etc/planetlab/default_config.xml
270 and /etc/planetlab/configs/site.xml
271 into /etc/planetlab/plc_config.xml
272 You might want to type 'r' (restart plc) or 'q' (quit)
273 Enter command (u for usual changes, w to save, ? for help) r
274 ==================== Stopping plc
276 ==================== Starting plc
278 Enter command (u for usual changes, w to save, ? for help) q
283 <p>If you used this method for configuring, you can skip to
284 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
285 <span><strong class="command">plc-config-tty</strong></span>, you may also use a text
286 editor, but this requires some understanding on how the
287 configuration files are used within myplc. The
288 <span class="emphasis"><em>default</em></span> configuration is stored in a file
289 named <code class="filename">/etc/planetlab/default_config.xml</code>,
290 that is designed to remain intact. You may store your local
291 changes in any file located in the <code class="filename">configs/</code>
292 sub-directory, that are loaded on top of the defaults. Finally
293 the file <code class="filename">/etc/planetlab/plc_config.xml</code> is
294 loaded, and the resulting configuration is stored in the latter
295 file, that is used as a reference.</p>
296 <p> Using a separate file for storing local changes only, as
297 <span><strong class="command">plc-config-tty</strong></span> does, is not a workable option
298 with a text editor because it would involve tedious xml
299 re-assembling. So your local changes should go in
300 <code class="filename">/etc/planetlab/plc_config.xml</code>. Be warned
301 however that any change you might do this way could be lost if
302 you use <span><strong class="command">plc-config-tty</strong></span> later on. </p>
303 <p>This file is a self-documenting configuration file written
304 in XML. Variables are divided into categories. Variable
305 identifiers must be alphanumeric, plus underscore. A variable is
306 referred to canonically as the uppercase concatenation of its
307 category identifier, an underscore, and its variable
308 identifier. Thus, a variable with an <code class="literal">id</code> of
309 <code class="literal">slice_prefix</code> in the <code class="literal">plc</code>
310 category is referred to canonically as
311 <code class="envar">PLC_SLICE_PREFIX</code>.</p>
312 <p>The reason for this convention is that during MyPLC
313 startup, <code class="filename">plc_config.xml</code> is translated into
314 several different languages—shell, PHP, and
315 Python—so that scripts written in each of these languages
316 can refer to the same underlying configuration. Most MyPLC
317 scripts are written in shell, so the convention for shell
318 variables predominates.</p>
319 <p>The variables that you should change immediately are:</p>
320 <div class="itemizedlist"><ul type="disc">
321 <li><p><code class="envar">PLC_NAME</code>: Change this to the
322 name of your PLC installation.</p></li>
323 <li><p><code class="envar">PLC_ROOT_PASSWORD</code>: Change this
324 to a more secure password.</p></li>
325 <li><p><code class="envar">PLC_MAIL_SUPPORT_ADDRESS</code>:
326 Change this to the e-mail address at which you would like to
327 receive support requests.</p></li>
328 <li><p><code class="envar">PLC_DB_HOST</code>,
329 <code class="envar">PLC_DB_IP</code>, <code class="envar">PLC_API_HOST</code>,
330 <code class="envar">PLC_API_IP</code>, <code class="envar">PLC_WWW_HOST</code>,
331 <code class="envar">PLC_WWW_IP</code>, <code class="envar">PLC_BOOT_HOST</code>,
332 <code class="envar">PLC_BOOT_IP</code>: Change all of these to the
333 preferred FQDN and external IP address of your host
336 <p> After changing these variables,
337 save the file, then restart MyPLC with <span><strong class="command">service plc
338 start</strong></span>. You should notice that the password of the
339 default administrator account is no longer
340 <code class="literal">root</code>, and that the default site name includes
341 the name of your PLC installation instead of PlanetLab. As a
342 side effect of these changes, the ISO images for the boot CDs
343 now have new names, so that you can freely remove the ones names
344 after 'PlanetLab Test', which is the default value of
345 <code class="envar">PLC_NAME</code> </p>
347 <div class="section" lang="en">
348 <div class="titlepage"><div><div><h3 class="title">
349 <a name="LoginRealUser"></a>3.4. Login as a real user </h3></div></div></div>
350 <p>Now that myplc is up and running, you can connect to the
351 web site that by default runs on port 80. You can either
352 directly use the default administrator user that you configured
353 in <code class="envar">PLC_ROOT_USER</code> and
354 <code class="envar">PLC_ROOT_PASSWORD</code>, or create a real user through
355 the 'Joining' tab. Do not forget to select both PI and tech
356 roles, and to select the only site created at this stage.
357 Login as the administrator to enable this user, then login as
360 <div class="section" lang="en">
361 <div class="titlepage"><div><div><h3 class="title">
362 <a name="id2628411"></a>3.5. Installing nodes</h3></div></div></div>
363 <p>Install your first node by clicking <code class="literal">Add
364 Node</code> under the <code class="literal">Nodes</code> tab. Fill in
365 all the appropriate details, then click
366 <code class="literal">Add</code>. Download the node's configuration file
367 by clicking <code class="literal">Download configuration file</code> on
368 the <span class="bold"><strong>Node Details</strong></span> page for the
369 node. Save it to a floppy disk or USB key as detailed in [<a href="#TechsGuide" title="[TechsGuide]">1</a>].</p>
370 <p>Follow the rest of the instructions in [<a href="#TechsGuide" title="[TechsGuide]">1</a>] for creating a Boot CD and installing
371 the node, except download the Boot CD image from the
372 <code class="filename">/download</code> directory of your PLC
373 installation, not from PlanetLab Central. The images located
374 here are customized for your installation. If you change the
375 hostname of your boot server (<code class="envar">PLC_BOOT_HOST</code>), or
376 if the SSL certificate of your boot server expires, MyPLC will
377 regenerate it and rebuild the Boot CD with the new
378 certificate. If this occurs, you must replace all Boot CDs
379 created before the certificate was regenerated.</p>
380 <p>The installation process for a node has significantly
381 improved since PlanetLab 3.3. It should now take only a few
382 seconds for a new node to become ready to create slices.</p>
384 <div class="section" lang="en">
385 <div class="titlepage"><div><div><h3 class="title">
386 <a name="id2679354"></a>3.6. Administering nodes</h3></div></div></div>
387 <p>You may administer nodes as <code class="literal">root</code> by
388 using the SSH key stored in
389 <code class="filename">/etc/planetlab/root_ssh_key.rsa</code>.</p>
390 <div class="example">
391 <a name="id2679376"></a><p class="title"><b>Example 6. Accessing nodes via SSH. Replace
392 <code class="literal">node</code> with the hostname of the node.</b></p>
393 <pre class="programlisting">ssh -i /etc/planetlab/root_ssh_key.rsa root@node</pre>
395 <p>Besides the standard Linux log files located in
396 <code class="filename">/var/log</code>, several other files can give you
397 clues about any problems with active processes:</p>
398 <div class="itemizedlist"><ul type="disc">
399 <li><p><code class="filename">/var/log/pl_nm</code>: The log
400 file for the Node Manager.</p></li>
401 <li><p><code class="filename">/vservers/pl_conf/var/log/pl_conf</code>:
402 The log file for the Slice Creation Service.</p></li>
403 <li><p><code class="filename">/var/log/propd</code>: The log
404 file for Proper, the service which allows certain slices to
405 perform certain privileged operations in the root
407 <li><p><code class="filename">/vservers/pl_netflow/var/log/netflow.log</code>:
408 The log file for PlanetFlow, the network traffic auditing
412 <div class="section" lang="en">
413 <div class="titlepage"><div><div><h3 class="title">
414 <a name="id2679454"></a>3.7. Creating a slice</h3></div></div></div>
415 <p>Create a slice by clicking <code class="literal">Create Slice</code>
416 under the <code class="literal">Slices</code> tab. Fill in all the
417 appropriate details, then click <code class="literal">Create</code>. Add
418 nodes to the slice by clicking <code class="literal">Manage Nodes</code>
419 on the <span class="bold"><strong>Slice Details</strong></span> page for
421 <p>A <span><strong class="command">cron</strong></span> job runs every five minutes and
423 <code class="filename">/plc/data/var/www/html/xml/slices-0.5.xml</code>
424 with information about current slice state. The Slice Creation
425 Service running on every node polls this file every ten minutes
426 to determine if it needs to create or delete any slices. You may
427 accelerate this process manually if desired.</p>
428 <div class="example">
429 <a name="id2679517"></a><p class="title"><b>Example 7. Forcing slice creation on a node.</b></p>
430 <pre class="programlisting"># Update slices.xml immediately
431 service plc start crond
433 # Kick the Slice Creation Service on a particular node.
434 ssh -i /etc/planetlab/root_ssh_key.rsa root@node \
435 vserver pl_conf exec service pl_conf restart</pre>
438 <div class="section" lang="en">
439 <div class="titlepage"><div><div><h3 class="title">
440 <a name="StartupSequence"></a>3.8. Understanding the startup sequence</h3></div></div></div>
441 <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
442 any failures. If no failures occur, you should see output similar
443 to the following:</p>
444 <div class="example">
445 <a name="id2679556"></a><p class="title"><b>Example 8. A successful MyPLC startup.</b></p>
446 <pre class="programlisting">Mounting PLC: [ OK ]
447 PLC: Generating network files: [ OK ]
448 PLC: Starting system logger: [ OK ]
449 PLC: Starting database server: [ OK ]
450 PLC: Generating SSL certificates: [ OK ]
451 PLC: Configuring the API: [ OK ]
452 PLC: Updating GPG keys: [ OK ]
453 PLC: Generating SSH keys: [ OK ]
454 PLC: Starting web server: [ OK ]
455 PLC: Bootstrapping the database: [ OK ]
456 PLC: Starting DNS server: [ OK ]
457 PLC: Starting crond: [ OK ]
458 PLC: Rebuilding Boot CD: [ OK ]
459 PLC: Rebuilding Boot Manager: [ OK ]
460 PLC: Signing node packages: [ OK ]
463 <p>If <code class="filename">/plc/root</code> is mounted successfully, a
464 complete log file of the startup process may be found at
465 <code class="filename">/plc/root/var/log/boot.log</code>. Possible reasons
466 for failure of each step include:</p>
467 <div class="itemizedlist"><ul type="disc">
468 <li><p><code class="literal">Mounting PLC</code>: If this step
469 fails, first ensure that you started MyPLC as root. Check
470 <code class="filename">/etc/sysconfig/plc</code> to ensure that
471 <code class="envar">PLC_ROOT</code> and <code class="envar">PLC_DATA</code> refer to the
472 right locations. You may also have too many existing loopback
473 mounts, or your kernel may not support loopback mounting, bind
474 mounting, or the ext3 filesystem. Try freeing at least one
475 loopback device, or re-compiling your kernel to support loopback
476 mounting, bind mounting, and the ext3 filesystem. If you see an
477 error similar to <code class="literal">Permission denied while trying to open
478 /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>
479 <li><p><code class="literal">Starting database server</code>: If
480 this step fails, check
481 <code class="filename">/plc/root/var/log/pgsql</code> and
482 <code class="filename">/plc/root/var/log/boot.log</code>. The most common
483 reason for failure is that the default PostgreSQL port, TCP port
484 5432, is already in use. Check that you are not running a
485 PostgreSQL server on the host system.</p></li>
486 <li><p><code class="literal">Starting web server</code>: If this
488 <code class="filename">/plc/root/var/log/httpd/error_log</code> and
489 <code class="filename">/plc/root/var/log/boot.log</code> for obvious
490 errors. The most common reason for failure is that the default
491 web ports, TCP ports 80 and 443, are already in use. Check that
492 you are not running a web server on the host
494 <li><p><code class="literal">Bootstrapping the database</code>:
495 If this step fails, it is likely that the previous step
496 (<code class="literal">Starting web server</code>) also failed. Another
497 reason that it could fail is if <code class="envar">PLC_API_HOST</code> (see
498 <a href="#Configuration" title="3.3. Changing the configuration">Section 3.3, “Changing the configuration”</a>) does not resolve to
499 the host on which the API server has been enabled. By default,
500 all services, including the API server, are enabled and run on
501 the same host, so check that <code class="envar">PLC_API_HOST</code> is
502 either <code class="filename">localhost</code> or resolves to a local IP
503 address. Also check that <code class="envar">PLC_ROOT_USER</code> looks like
504 an e-mail address.</p></li>
505 <li><p><code class="literal">Starting crond</code>: If this step
506 fails, it is likely that the previous steps (<code class="literal">Starting
507 web server</code> and <code class="literal">Bootstrapping the
508 database</code>) also failed. If not, check
509 <code class="filename">/plc/root/var/log/boot.log</code> for obvious
510 errors. This step starts the <span><strong class="command">cron</strong></span> service and
511 generates the initial set of XML files that the Slice Creation
512 Service uses to determine slice state.</p></li>
514 <p>If no failures occur, then MyPLC should be active with a
515 default configuration. Open a web browser on the host system and
516 visit <code class="literal">http://localhost/</code>, which should bring you
517 to the front page of your PLC installation. The password of the
518 default administrator account
519 <code class="literal">root@localhost.localdomain</code> (set by
520 <code class="envar">PLC_ROOT_USER</code>) is <code class="literal">root</code> (set by
521 <code class="envar">PLC_ROOT_PASSWORD</code>).</p>
523 <div class="section" lang="en">
524 <div class="titlepage"><div><div><h3 class="title">
525 <a name="FilesInvolvedRuntime"></a>3.9. Files and directories
526 involved in <span class="emphasis"><em>myplc</em></span></h3></div></div></div>
527 <p>MyPLC installs the following files and directories:</p>
528 <div class="orderedlist"><ol type="1">
529 <li><p><code class="filename">/plc/root.img</code>: The main
530 root filesystem of the MyPLC application. This file is an
531 uncompressed ext3 filesystem that is loopback mounted on
532 <code class="filename">/plc/root</code> when MyPLC starts. This
533 filesystem, even when mounted, should be treated as an opaque
534 binary that can and will be replaced in its entirety by any
535 upgrade of MyPLC.</p></li>
536 <li><p><code class="filename">/plc/root</code>: The mount point
537 for <code class="filename">/plc/root.img</code>. Once the root filesystem
538 is mounted, all MyPLC services run in a
539 <span><strong class="command">chroot</strong></span> jail based in this
542 <p><code class="filename">/plc/data</code>: The directory where user
543 data and generated files are stored. This directory is bind
544 mounted onto <code class="filename">/plc/root/data</code> so that it is
545 accessible as <code class="filename">/data</code> from within the
546 <span><strong class="command">chroot</strong></span> jail. Files in this directory are
547 marked with <span><strong class="command">%config(noreplace)</strong></span> in the
548 RPM. That is, during an upgrade of MyPLC, if a file has not
549 changed since the last installation or upgrade of MyPLC, it is
550 subject to upgrade and replacement. If the file has changed,
551 the new version of the file will be created with a
552 <code class="filename">.rpmnew</code> extension. Symlinks within the
553 MyPLC root filesystem ensure that the following directories
554 (relative to <code class="filename">/plc/root</code>) are stored
555 outside the MyPLC filesystem image:</p>
556 <div class="itemizedlist"><ul type="disc">
557 <li><p><code class="filename">/etc/planetlab</code>: This
558 directory contains the configuration files, keys, and
559 certificates that define your MyPLC
560 installation.</p></li>
561 <li><p><code class="filename">/var/lib/pgsql</code>: This
562 directory contains PostgreSQL database
564 <li><p><code class="filename">/var/www/html/alpina-logs</code>: This
565 directory contains node installation logs.</p></li>
566 <li><p><code class="filename">/var/www/html/boot</code>: This
567 directory contains the Boot Manager, customized for your MyPLC
568 installation, and its data files.</p></li>
569 <li><p><code class="filename">/var/www/html/download</code>: This
570 directory contains Boot CD images, customized for your MyPLC
571 installation.</p></li>
572 <li><p><code class="filename">/var/www/html/install-rpms</code>: This
573 directory is where you should install node package updates,
574 if any. By default, nodes are installed from the tarball
576 <code class="filename">/var/www/html/boot/PlanetLab-Bootstrap.tar.bz2</code>,
577 which is pre-built from the latest PlanetLab Central
578 sources, and installed as part of your MyPLC
579 installation. However, nodes will attempt to install any
580 newer RPMs located in
581 <code class="filename">/var/www/html/install-rpms/planetlab</code>,
582 after initial installation and periodically thereafter. You
583 must run <span><strong class="command">yum-arch</strong></span> and
584 <span><strong class="command">createrepo</strong></span> to update the
585 <span><strong class="command">yum</strong></span> caches in this directory after
586 installing a new RPM. PlanetLab Central cannot support any
587 changes to this directory.</p></li>
588 <li><p><code class="filename">/var/www/html/xml</code>: This
589 directory contains various XML files that the Slice Creation
590 Service uses to determine the state of slices. These XML
591 files are refreshed periodically by <span><strong class="command">cron</strong></span>
592 jobs running in the MyPLC root.</p></li>
593 <li><p><code class="filename">/root</code>: this is the
594 location of the root-user's homedir, and for your
595 convenience is stored under <code class="filename">/data</code> so
596 that your local customizations survive across
597 updates - this feature is inherited from the
598 <span><strong class="command">myplc-devel</strong></span> package, where it is probably
599 more useful. </p></li>
602 <li><p><a name="MyplcInitScripts"></a><code class="filename">/etc/init.d/plc</code>: This file
603 is a System V init script installed on your host filesystem,
604 that allows you to start up and shut down MyPLC with a single
605 command, as described in <a href="#QuickStart" title="3.2. QuickStart ">Section 3.2, “ QuickStart ”</a>.</p></li>
606 <li><p><code class="filename">/etc/sysconfig/plc</code>: This
607 file is a shell script fragment that defines the variables
608 <code class="envar">PLC_ROOT</code> and <code class="envar">PLC_DATA</code>. By default,
609 the values of these variables are <code class="filename">/plc/root</code>
610 and <code class="filename">/plc/data</code>, respectively. If you wish,
611 you may move your MyPLC installation to another location on your
612 host filesystem and edit the values of these variables
613 appropriately, but you will break the RPM upgrade
614 process. PlanetLab Central cannot support any changes to this
616 <li><p><code class="filename">/etc/planetlab</code>: This
617 symlink to <code class="filename">/plc/data/etc/planetlab</code> is
618 installed on the host system for convenience.</p></li>
622 <div class="section" lang="en">
623 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
624 <a name="DevelopmentEnvironment"></a>4. Rebuilding and customizing MyPLC</h2></div></div></div>
625 <p>The MyPLC package, though distributed as an RPM, is not a
626 traditional package that can be easily rebuilt from SRPM. The
627 requisite build environment is quite extensive and numerous
628 assumptions are made throughout the PlanetLab source code base,
629 that the build environment is based on Fedora Core 4 and that
630 access to a complete Fedora Core 4 mirror is available.</p>
631 <p>For this reason, it is recommended that you only rebuild
632 MyPLC (or any of its components) from within the MyPLC development
633 environment. The MyPLC development environment is similar to MyPLC
634 itself in that it is a portable filesystem contained within a
635 <span><strong class="command">chroot</strong></span> jail. The filesystem contains all the
636 necessary tools required to rebuild MyPLC, as well as a snapshot
637 of the PlanetLab source code base in the form of a local CVS
639 <div class="section" lang="en">
640 <div class="titlepage"><div><div><h3 class="title">
641 <a name="id2680347"></a>4.1. Installation</h3></div></div></div>
642 <p>Install the MyPLC development environment similarly to how
643 you would install MyPLC. You may install both packages on the same
644 host system if you wish. As with MyPLC, the MyPLC development
645 environment should be treated as a monolithic software
646 application, and any files present in the
647 <span><strong class="command">chroot</strong></span> jail should not be modified directly, as
648 they are subject to upgrade.</p>
649 <div class="itemizedlist"><ul type="disc">
651 <p>If your distribution supports RPM:</p>
652 <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>
655 <p>If your distribution does not support RPM:</p>
656 <pre class="programlisting"># cd /tmp
657 # wget http://build.planet-lab.org/build/myplc-0_4-rc2/RPMS/i386/myplc-devel-0.4-2.planetlab.i386.rpm
659 # rpm2cpio /tmp/myplc-devel-0.4-2.planetlab.i386.rpm | cpio -diu</pre>
663 <div class="section" lang="en">
664 <div class="titlepage"><div><div><h3 class="title">
665 <a name="id2680401"></a>4.2. Configuration</h3></div></div></div>
666 <p> The default configuration should work as-is on most
667 sites. Configuring the development package can be achieved in a
668 similar way as for <span class="emphasis"><em>myplc</em></span>, as described in
669 <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
670 <span class="emphasis"><em>-d</em></span> option for supporting the
671 <span class="emphasis"><em>myplc-devel</em></span> case, that can be useful in a
672 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>
674 <div class="section" lang="en">
675 <div class="titlepage"><div><div><h3 class="title">
676 <a name="FilesInvolvedDevel"></a>4.3. Files and directories
677 involved in <span class="emphasis"><em>myplc-devl</em></span></h3></div></div></div>
678 <p>The MyPLC development environment installs the following
679 files and directories:</p>
680 <div class="itemizedlist"><ul type="disc">
681 <li><p><code class="filename">/plc/devel/root.img</code>: The
682 main root filesystem of the MyPLC development environment. This
683 file is an uncompressed ext3 filesystem that is loopback mounted
684 on <code class="filename">/plc/devel/root</code> when the MyPLC
685 development environment is initialized. This filesystem, even
686 when mounted, should be treated as an opaque binary that can and
687 will be replaced in its entirety by any upgrade of the MyPLC
688 development environment.</p></li>
689 <li><p><code class="filename">/plc/devel/root</code>: The mount
691 <code class="filename">/plc/devel/root.img</code>.</p></li>
693 <p><code class="filename">/plc/devel/data</code>: The directory
694 where user data and generated files are stored. This directory
695 is bind mounted onto <code class="filename">/plc/devel/root/data</code>
696 so that it is accessible as <code class="filename">/data</code> from
697 within the <span><strong class="command">chroot</strong></span> jail. Files in this
698 directory are marked with
699 <span><strong class="command">%config(noreplace)</strong></span> in the RPM. Symlinks
700 ensure that the following directories (relative to
701 <code class="filename">/plc/devel/root</code>) are stored outside the
702 root filesystem image:</p>
703 <div class="itemizedlist"><ul type="circle">
704 <li><p><code class="filename">/etc/planetlab</code>: This
705 directory contains the configuration files that define your
706 MyPLC development environment.</p></li>
707 <li><p><code class="filename">/cvs</code>: A
708 snapshot of the PlanetLab source code is stored as a CVS
709 repository in this directory. Files in this directory will
710 <span class="bold"><strong>not</strong></span> be updated by an upgrade of
711 <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
712 PlanetLab source code.</p></li>
713 <li><p><code class="filename">/build</code>:
714 Builds are stored in this directory. This directory is bind
715 mounted onto <code class="filename">/plc/devel/root/build</code> so that
716 it is accessible as <code class="filename">/build</code> from within the
717 <span><strong class="command">chroot</strong></span> jail. The build scripts in this
718 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
720 <li><p><code class="filename">/root</code>: this is the
721 location of the root-user's homedir, and for your
722 convenience is stored under <code class="filename">/data</code> so
723 that your local customizations survive across
727 <li><p><code class="filename">/etc/init.d/plc-devel</code>: This file is
728 a System V init script installed on your host filesystem, that
729 allows you to start up and shut down the MyPLC development
730 environment with a single command.</p></li>
733 <div class="section" lang="en">
734 <div class="titlepage"><div><div><h3 class="title">
735 <a name="id2680665"></a>4.4. Fedora Core 4 mirror requirement</h3></div></div></div>
736 <p>The MyPLC development environment requires access to a
737 complete Fedora Core 4 i386 RPM repository, because several
738 different filesystems based upon Fedora Core 4 are constructed
739 during the process of building MyPLC. You may configure the
740 location of this repository via the
741 <code class="envar">PLC_DEVEL_FEDORA_URL</code> variable in
742 <code class="filename">/plc/devel/data/etc/planetlab/plc_config.xml</code>. The
743 value of the variable should be a URL that points to the top
744 level of a Fedora mirror that provides the
745 <code class="filename">base</code>, <code class="filename">updates</code>, and
746 <code class="filename">extras</code> repositories, e.g.,</p>
747 <div class="itemizedlist"><ul type="disc">
748 <li><p><code class="filename">file:///data/fedora</code></p></li>
749 <li><p><code class="filename">http://coblitz.planet-lab.org/pub/fedora</code></p></li>
750 <li><p><code class="filename">ftp://mirror.cs.princeton.edu/pub/mirrors/fedora</code></p></li>
751 <li><p><code class="filename">ftp://mirror.stanford.edu/pub/mirrors/fedora</code></p></li>
752 <li><p><code class="filename">http://rpmfind.net/linux/fedora</code></p></li>
754 <p>As implied by the list, the repository may be located on
755 the local filesystem, or it may be located on a remote FTP or
756 HTTP server. URLs beginning with <code class="filename">file://</code>
757 should exist at the specified location relative to the root of
758 the <span><strong class="command">chroot</strong></span> jail. For optimum performance and
759 reproducibility, specify
760 <code class="envar">PLC_DEVEL_FEDORA_URL=file:///data/fedora</code> and
761 download all Fedora Core 4 RPMS into
762 <code class="filename">/plc/devel/data/fedora</code> on the host system
763 after installing <code class="filename">myplc-devel</code>. Use a tool
764 such as <span><strong class="command">wget</strong></span> or <span><strong class="command">rsync</strong></span> to
765 download the RPMS from a public mirror:</p>
766 <div class="example">
767 <a name="id2680806"></a><p class="title"><b>Example 9. Setting up a local Fedora Core 4 repository.</b></p>
768 <pre class="programlisting"># mkdir -p /plc/devel/data/fedora
769 # cd /plc/devel/data/fedora
771 # for repo in core/4/i386/os core/updates/4/i386 extras/4/i386 ; do
772 > wget -m -nH --cut-dirs=3 http://coblitz.planet-lab.org/pub/fedora/linux/$repo
775 <p>Change the repository URI and <span><strong class="command">--cut-dirs</strong></span>
776 level as needed to produce a hierarchy that resembles:</p>
777 <pre class="programlisting">/plc/devel/data/fedora/core/4/i386/os
778 /plc/devel/data/fedora/core/updates/4/i386
779 /plc/devel/data/fedora/extras/4/i386</pre>
780 <p>A list of additional Fedora Core 4 mirrors is available at
781 <a href="http://fedora.redhat.com/Download/mirrors.html" target="_top">http://fedora.redhat.com/Download/mirrors.html</a>.</p>
783 <div class="section" lang="en">
784 <div class="titlepage"><div><div><h3 class="title">
785 <a name="BuildingMyPLC"></a>4.5. Building MyPLC</h3></div></div></div>
786 <p>All PlanetLab source code modules are built and installed
787 as RPMS. A set of build scripts, checked into the
788 <code class="filename">build/</code> directory of the PlanetLab CVS
789 repository, eases the task of rebuilding PlanetLab source
791 <p> Before you try building MyPLC, you might check the
792 configuration, in a file named
793 <span class="emphasis"><em>plc_config.xml</em></span> that relies on a very
794 similar model as MyPLC, located in
795 <span class="emphasis"><em>/etc/planetlab</em></span> within the chroot jail, or
796 in <span class="emphasis"><em>/plc/devel/data/etc/planetlab</em></span> from the
797 root context. The set of applicable variables is described in
798 <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>
799 <p>To build MyPLC, or any PlanetLab source code module, from
800 within the MyPLC development environment, execute the following
801 commands as root:</p>
802 <div class="example">
803 <a name="id2680908"></a><p class="title"><b>Example 10. Building MyPLC.</b></p>
804 <pre class="programlisting"># Initialize MyPLC development environment
805 service plc-devel start
807 # Enter development environment
808 chroot /plc/devel/root su -
810 # Check out build scripts into a directory named after the current
811 # date. This is simply a convention, it need not be followed
812 # exactly. See build/build.sh for an example of a build script that
813 # names build directories after CVS tags.
814 DATE=$(date +%Y.%m.%d)
816 cvs -d /cvs checkout -d $DATE build
821 <p>If the build succeeds, a set of binary RPMS will be
823 <code class="filename">/plc/devel/data/build/$DATE/RPMS/</code> that you
825 <code class="filename">/var/www/html/install-rpms/planetlab</code>
826 directory of your MyPLC installation (see <a href="#Installation" title="3. Installating and using MyPLC">Section 3, “Installating and using MyPLC”</a>).</p>
828 <div class="section" lang="en">
829 <div class="titlepage"><div><div><h3 class="title">
830 <a name="UpdatingCVS"></a>4.6. Updating CVS</h3></div></div></div>
831 <p>A complete snapshot of the PlanetLab source code is included
832 with the MyPLC development environment as a CVS repository in
833 <code class="filename">/plc/devel/data/cvs</code>. This CVS repository may
834 be accessed like any other CVS repository. It may be accessed
835 using an interface such as <a href="http://www.freebsd.org/projects/cvsweb.html" target="_top">CVSweb</a>,
836 and file permissions may be altered to allow for fine-grained
837 access control. Although the files are included with the
838 <code class="filename">myplc-devel</code> RPM, they are <span class="bold"><strong>not</strong></span> subject to upgrade once installed. New
839 versions of the <code class="filename">myplc-devel</code> RPM will install
840 updated snapshot repositories in
841 <code class="filename">/plc/devel/data/cvs-%{version}-%{release}</code>,
842 where <code class="literal">%{version}-%{release}</code> is replaced with
843 the version number of the RPM.</p>
844 <p>Because the CVS repository is not automatically upgraded,
845 if you wish to keep your local repository synchronized with the
846 public PlanetLab repository, it is highly recommended that you
847 use CVS's support for vendor branches to track changes, as
848 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>
849 and <a href="http://cvsbook.red-bean.com/cvsbook.html#Tracking%20Third-Party%20Sources%20(Vendor%20Branches)" target="_top">here</a>.
850 Vendor branches ease the task of merging upstream changes with
851 your local modifications. To import a new snapshot into your
852 local repository (for example, if you have just upgraded from
853 <code class="filename">myplc-devel-0.4-2</code> to
854 <code class="filename">myplc-devel-0.4-3</code> and you notice the new
855 repository in <code class="filename">/plc/devel/data/cvs-0.4-3</code>),
856 execute the following commands as root from within the MyPLC
857 development environment:</p>
858 <div class="example">
859 <a name="id2681066"></a><p class="title"><b>Example 11. Updating /data/cvs from /data/cvs-0.4-3.</b></p>
860 <p><span class="bold"><strong>Warning</strong></span>: This may cause
861 severe, irreversible changes to be made to your local
862 repository. Always tag your local repository before
864 <pre class="programlisting"># Initialize MyPLC development environment
865 service plc-devel start
867 # Enter development environment
868 chroot /plc/devel/root su -
871 cvs -d /cvs rtag before-myplc-0_4-3-merge
874 TMP=$(mktemp -d /data/export.XXXXXX)
876 cvs -d /data/cvs-0.4-3 export -r HEAD .
877 cvs -d /cvs import -m "Merging myplc-0.4-3" -ko -I ! . planetlab myplc-0_4-3
881 <p>If there are any merge conflicts, use the command
882 suggested by CVS to help the merge. Explaining how to fix merge
883 conflicts is beyond the scope of this document; consult the CVS
884 documentation for more information on how to use CVS.</p>
887 <div class="section" lang="en">
888 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
889 <a name="id2681106"></a>5. More information : the FAQ wiki page</h2></div></div></div>
890 <p> Please refer to, and feel free to contribute, <a href="https://wiki.planet-lab.org/twiki/bin/view/Planetlab/MyplcFAQ" target="_top">
891 the FAQ page on the Princeton's wiki </a>.</p>
893 <div class="appendix" lang="en">
894 <h2 class="title" style="clear: both">
895 <a name="VariablesRuntime"></a>A. Configuration variables (for <span class="emphasis"><em>myplc</em></span>)</h2>
896 <p>Listed below is the set of standard configuration variables
897 and their default values, defined in the template
898 <code class="filename">/etc/planetlab/default_config.xml</code>. Additional
899 variables and their defaults may be defined in site-specific XML
900 templates that should be placed in
901 <code class="filename">/etc/planetlab/configs/</code>.</p>
902 <p>This information is available online within
903 <span><strong class="command">plc-config-tty</strong></span>, e.g.:</p>
904 <div class="example">
905 <a name="id2681165"></a><p class="title"><b>Example A.1. Advanced usage of plc-config-tty</b></p>
906 <pre class="programlisting"><plc> # plc-config-tty
907 Enter command (u for usual changes, w to save, ? for help) V plc_dns
908 ========== Category = PLC_DNS
910 # Enable the internal DNS server. The server does not provide reverse
911 # resolution and is not a production quality or scalable DNS solution.
912 # Use the internal DNS server only for small deployments or for testing.
916 <p> List of the <span><strong class="command">myplc</strong></span> configuration variables:</p>
917 <div class="variablelist"><dl>
918 <dt><span class="term">PLC_NAME</span></dt>
923 Default: PlanetLab Test</p>
924 <p>The name of this PLC installation. It is used in
925 the name of the default system site (e.g., PlanetLab Central)
926 and in the names of various administrative entities (e.g.,
927 PlanetLab Support).</p>
929 <dt><span class="term">PLC_SLICE_PREFIX</span></dt>
935 <p>The abbreviated name of this PLC
936 installation. It is used as the prefix for system slices
937 (e.g., pl_conf). Warning: Currently, this variable should
940 <dt><span class="term">PLC_ROOT_USER</span></dt>
945 Default: root@localhost.localdomain</p>
946 <p>The name of the initial administrative
947 account. We recommend that this account be used only to create
948 additional accounts associated with real
949 administrators, then disabled.</p>
951 <dt><span class="term">PLC_ROOT_PASSWORD</span></dt>
957 <p>The password of the initial administrative
958 account. Also the password of the root account on the Boot
961 <dt><span class="term">PLC_ROOT_SSH_KEY_PUB</span></dt>
966 Default: /etc/planetlab/root_ssh_key.pub</p>
967 <p>The SSH public key used to access the root
968 account on your nodes.</p>
970 <dt><span class="term">PLC_ROOT_SSH_KEY</span></dt>
975 Default: /etc/planetlab/root_ssh_key.rsa</p>
976 <p>The SSH private key used to access the root
977 account on your nodes.</p>
979 <dt><span class="term">PLC_DEBUG_SSH_KEY_PUB</span></dt>
984 Default: /etc/planetlab/debug_ssh_key.pub</p>
985 <p>The SSH public key used to access the root
986 account on your nodes when they are in Debug mode.</p>
988 <dt><span class="term">PLC_DEBUG_SSH_KEY</span></dt>
993 Default: /etc/planetlab/debug_ssh_key.rsa</p>
994 <p>The SSH private key used to access the root
995 account on your nodes when they are in Debug mode.</p>
997 <dt><span class="term">PLC_ROOT_GPG_KEY_PUB</span></dt>
1002 Default: /etc/planetlab/pubring.gpg</p>
1003 <p>The GPG public keyring used to sign the Boot
1004 Manager and all node packages.</p>
1006 <dt><span class="term">PLC_ROOT_GPG_KEY</span></dt>
1011 Default: /etc/planetlab/secring.gpg</p>
1012 <p>The SSH private key used to access the root
1013 account on your nodes.</p>
1015 <dt><span class="term">PLC_MA_SA_NAMESPACE</span></dt>
1021 <p>The namespace of your MA/SA. This should be a
1022 globally unique value assigned by PlanetLab
1025 <dt><span class="term">PLC_MA_SA_SSL_KEY</span></dt>
1030 Default: /etc/planetlab/ma_sa_ssl.key</p>
1031 <p>The SSL private key used for signing documents
1032 with the signature of your MA/SA. If non-existent, one will
1035 <dt><span class="term">PLC_MA_SA_SSL_CRT</span></dt>
1040 Default: /etc/planetlab/ma_sa_ssl.crt</p>
1041 <p>The corresponding SSL public certificate. By
1042 default, this certificate is self-signed. You may replace
1043 the certificate later with one signed by the PLC root
1046 <dt><span class="term">PLC_MA_SA_CA_SSL_CRT</span></dt>
1051 Default: /etc/planetlab/ma_sa_ca_ssl.crt</p>
1052 <p>If applicable, the certificate of the PLC root
1053 CA. If your MA/SA certificate is self-signed, then this file
1054 is the same as your MA/SA certificate.</p>
1056 <dt><span class="term">PLC_MA_SA_CA_SSL_KEY_PUB</span></dt>
1061 Default: /etc/planetlab/ma_sa_ca_ssl.pub</p>
1062 <p>If applicable, the public key of the PLC root
1063 CA. If your MA/SA certificate is self-signed, then this file
1064 is the same as your MA/SA public key.</p>
1066 <dt><span class="term">PLC_MA_SA_API_CRT</span></dt>
1071 Default: /etc/planetlab/ma_sa_api.xml</p>
1072 <p>The API Certificate is your MA/SA public key
1073 embedded in a digitally signed XML document. By default,
1074 this document is self-signed. You may replace this
1075 certificate later with one signed by the PLC root
1078 <dt><span class="term">PLC_NET_DNS1</span></dt>
1083 Default: 127.0.0.1</p>
1084 <p>Primary DNS server address.</p>
1086 <dt><span class="term">PLC_NET_DNS2</span></dt>
1092 <p>Secondary DNS server address.</p>
1094 <dt><span class="term">PLC_DNS_ENABLED</span></dt>
1100 <p>Enable the internal DNS server. The server does
1101 not provide reverse resolution and is not a production
1102 quality or scalable DNS solution. Use the internal DNS
1103 server only for small deployments or for
1106 <dt><span class="term">PLC_MAIL_ENABLED</span></dt>
1112 <p>Set to false to suppress all e-mail notifications
1115 <dt><span class="term">PLC_MAIL_SUPPORT_ADDRESS</span></dt>
1120 Default: root+support@localhost.localdomain</p>
1121 <p>This address is used for support
1122 requests. Support requests may include traffic complaints,
1123 security incident reporting, web site malfunctions, and
1124 general requests for information. We recommend that the
1125 address be aliased to a ticketing system such as Request
1128 <dt><span class="term">PLC_MAIL_BOOT_ADDRESS</span></dt>
1133 Default: root+install-msgs@localhost.localdomain</p>
1134 <p>The API will notify this address when a problem
1135 occurs during node installation or boot.</p>
1137 <dt><span class="term">PLC_MAIL_SLICE_ADDRESS</span></dt>
1142 Default: root+SLICE@localhost.localdomain</p>
1143 <p>This address template is used for sending
1144 e-mail notifications to slices. SLICE will be replaced with
1145 the name of the slice.</p>
1147 <dt><span class="term">PLC_DB_ENABLED</span></dt>
1153 <p>Enable the database server on this
1156 <dt><span class="term">PLC_DB_TYPE</span></dt>
1161 Default: postgresql</p>
1162 <p>The type of database server. Currently, only
1163 postgresql is supported.</p>
1165 <dt><span class="term">PLC_DB_HOST</span></dt>
1170 Default: localhost.localdomain</p>
1171 <p>The fully qualified hostname of the database
1174 <dt><span class="term">PLC_DB_IP</span></dt>
1179 Default: 127.0.0.1</p>
1180 <p>The IP address of the database server, if not
1181 resolvable by the configured DNS servers.</p>
1183 <dt><span class="term">PLC_DB_PORT</span></dt>
1189 <p>The TCP port number through which the database
1190 server should be accessed.</p>
1192 <dt><span class="term">PLC_DB_NAME</span></dt>
1197 Default: planetlab3</p>
1198 <p>The name of the database to access.</p>
1200 <dt><span class="term">PLC_DB_USER</span></dt>
1205 Default: pgsqluser</p>
1206 <p>The username to use when accessing the
1209 <dt><span class="term">PLC_DB_PASSWORD</span></dt>
1215 <p>The password to use when accessing the
1216 database. If left blank, one will be
1219 <dt><span class="term">PLC_API_ENABLED</span></dt>
1225 <p>Enable the API server on this
1228 <dt><span class="term">PLC_API_DEBUG</span></dt>
1234 <p>Enable verbose API debugging. Do not enable on
1235 a production system!</p>
1237 <dt><span class="term">PLC_API_HOST</span></dt>
1242 Default: localhost.localdomain</p>
1243 <p>The fully qualified hostname of the API
1246 <dt><span class="term">PLC_API_IP</span></dt>
1251 Default: 127.0.0.1</p>
1252 <p>The IP address of the API server, if not
1253 resolvable by the configured DNS servers.</p>
1255 <dt><span class="term">PLC_API_PORT</span></dt>
1261 <p>The TCP port number through which the API
1262 should be accessed. Warning: SSL (port 443) access is not
1263 fully supported by the website code yet. We recommend that
1264 port 80 be used for now and that the API server either run
1265 on the same machine as the web server, or that they both be
1266 on a secure wired network.</p>
1268 <dt><span class="term">PLC_API_PATH</span></dt>
1273 Default: /PLCAPI/</p>
1274 <p>The base path of the API URL.</p>
1276 <dt><span class="term">PLC_API_MAINTENANCE_USER</span></dt>
1281 Default: maint@localhost.localdomain</p>
1282 <p>The username of the maintenance account. This
1283 account is used by local scripts that perform automated
1284 tasks, and cannot be used for normal logins.</p>
1286 <dt><span class="term">PLC_API_MAINTENANCE_PASSWORD</span></dt>
1292 <p>The password of the maintenance account. If
1293 left blank, one will be generated. We recommend that the
1294 password be changed periodically.</p>
1296 <dt><span class="term">PLC_API_MAINTENANCE_SOURCES</span></dt>
1302 <p>A space-separated list of IP addresses allowed
1303 to access the API through the maintenance account. The value
1304 of this variable is set automatically to allow only the API,
1305 web, and boot servers, and should not be
1308 <dt><span class="term">PLC_API_SSL_KEY</span></dt>
1313 Default: /etc/planetlab/api_ssl.key</p>
1314 <p>The SSL private key to use for encrypting HTTPS
1315 traffic. If non-existent, one will be
1318 <dt><span class="term">PLC_API_SSL_CRT</span></dt>
1323 Default: /etc/planetlab/api_ssl.crt</p>
1324 <p>The corresponding SSL public certificate. By
1325 default, this certificate is self-signed. You may replace
1326 the certificate later with one signed by a root
1329 <dt><span class="term">PLC_API_CA_SSL_CRT</span></dt>
1334 Default: /etc/planetlab/api_ca_ssl.crt</p>
1335 <p>The certificate of the root CA, if any, that
1336 signed your server certificate. If your server certificate is
1337 self-signed, then this file is the same as your server
1340 <dt><span class="term">PLC_WWW_ENABLED</span></dt>
1346 <p>Enable the web server on this
1349 <dt><span class="term">PLC_WWW_DEBUG</span></dt>
1355 <p>Enable debugging output on web pages. Do not
1356 enable on a production system!</p>
1358 <dt><span class="term">PLC_WWW_HOST</span></dt>
1363 Default: localhost.localdomain</p>
1364 <p>The fully qualified hostname of the web
1367 <dt><span class="term">PLC_WWW_IP</span></dt>
1372 Default: 127.0.0.1</p>
1373 <p>The IP address of the web server, if not
1374 resolvable by the configured DNS servers.</p>
1376 <dt><span class="term">PLC_WWW_PORT</span></dt>
1382 <p>The TCP port number through which the
1383 unprotected portions of the web site should be
1386 <dt><span class="term">PLC_WWW_SSL_PORT</span></dt>
1392 <p>The TCP port number through which the protected
1393 portions of the web site should be accessed.</p>
1395 <dt><span class="term">PLC_WWW_SSL_KEY</span></dt>
1400 Default: /etc/planetlab/www_ssl.key</p>
1401 <p>The SSL private key to use for encrypting HTTPS
1402 traffic. If non-existent, one will be
1405 <dt><span class="term">PLC_WWW_SSL_CRT</span></dt>
1410 Default: /etc/planetlab/www_ssl.crt</p>
1411 <p>The corresponding SSL public certificate for
1412 the HTTP server. By default, this certificate is
1413 self-signed. You may replace the certificate later with one
1414 signed by a root CA.</p>
1416 <dt><span class="term">PLC_WWW_CA_SSL_CRT</span></dt>
1421 Default: /etc/planetlab/www_ca_ssl.crt</p>
1422 <p>The certificate of the root CA, if any, that
1423 signed your server certificate. If your server certificate is
1424 self-signed, then this file is the same as your server
1427 <dt><span class="term">PLC_BOOT_ENABLED</span></dt>
1433 <p>Enable the boot server on this
1436 <dt><span class="term">PLC_BOOT_HOST</span></dt>
1441 Default: localhost.localdomain</p>
1442 <p>The fully qualified hostname of the boot
1445 <dt><span class="term">PLC_BOOT_IP</span></dt>
1450 Default: 127.0.0.1</p>
1451 <p>The IP address of the boot server, if not
1452 resolvable by the configured DNS servers.</p>
1454 <dt><span class="term">PLC_BOOT_PORT</span></dt>
1460 <p>The TCP port number through which the
1461 unprotected portions of the boot server should be
1464 <dt><span class="term">PLC_BOOT_SSL_PORT</span></dt>
1470 <p>The TCP port number through which the protected
1471 portions of the boot server should be
1474 <dt><span class="term">PLC_BOOT_SSL_KEY</span></dt>
1479 Default: /etc/planetlab/boot_ssl.key</p>
1480 <p>The SSL private key to use for encrypting HTTPS
1483 <dt><span class="term">PLC_BOOT_SSL_CRT</span></dt>
1488 Default: /etc/planetlab/boot_ssl.crt</p>
1489 <p>The corresponding SSL public certificate for
1490 the HTTP server. By default, this certificate is
1491 self-signed. You may replace the certificate later with one
1492 signed by a root CA.</p>
1494 <dt><span class="term">PLC_BOOT_CA_SSL_CRT</span></dt>
1499 Default: /etc/planetlab/boot_ca_ssl.crt</p>
1500 <p>The certificate of the root CA, if any, that
1501 signed your server certificate. If your server certificate is
1502 self-signed, then this file is the same as your server
1507 <div class="appendix" lang="en">
1508 <h2 class="title" style="clear: both">
1509 <a name="VariablesDevel"></a>B. Development configuration variables (for <span class="emphasis"><em>myplc-devel</em></span>)</h2>
1510 <div class="variablelist"><dl>
1511 <dt><span class="term">PLC_DEVEL_FEDORA_RELEASE</span></dt>
1517 <p>Version number of Fedora Core upon which to
1518 base the build environment. Warning: Currently, only Fedora
1519 Core 4 is supported.</p>
1521 <dt><span class="term">PLC_DEVEL_FEDORA_ARCH</span></dt>
1527 <p>Base architecture of the build
1528 environment. Warning: Currently, only i386 is
1531 <dt><span class="term">PLC_DEVEL_FEDORA_URL</span></dt>
1536 Default: file:///data/fedora</p>
1537 <p>Fedora Core mirror from which to install
1540 <dt><span class="term">PLC_DEVEL_CVSROOT</span></dt>
1546 <p>CVSROOT to use when checking out code.</p>
1548 <dt><span class="term">PLC_DEVEL_BOOTSTRAP</span></dt>
1554 <p>Controls whether MyPLC should be built inside
1555 of its own development environment.</p>
1559 <div class="bibliography">
1560 <div class="titlepage"><div><div><h2 class="title">
1561 <a name="id2684223"></a>Bibliography</h2></div></div></div>
1562 <div class="biblioentry">
1563 <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
1564 Technical Contact's Guide</a></i>. </span></p>
1567 </div><?php require('footer.php'); ?>