1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
6 <title>BootCD v3.x Technical Documentation</title>
9 <firstname>Aaron</firstname>
11 <surname>Klingaman</surname>
13 <email>alk@absarokasoft.com</email>
17 <orgname>Princeton University</orgname>
22 <revnumber>1.0</revnumber>
24 <date>November 17, 2005</date>
26 <authorinitials>AK</authorinitials>
29 <para>Initial draft.</para>
36 <title>Overview</title>
38 <para>This document describes in detail how the PlanetLab boot CD is built
39 and operates when running on a node. Older boot CDs, including 2.x cds,
40 are not the focus of this document, and are no longer being deployed on
41 production systems.</para>
45 <title>Background</title>
47 <para>Since the early days of PlanetLab, all production nodes are
48 configured during setup to only start up off of the cdrom, with a
49 PlanetLab boot cd always left in the drive. The intention is to allow a
50 machine to be able to restart into a known environment, for debugging
51 system problems, or as a way to still access the machine but not have any
52 potentially compromised code to run if the system is believed to be
57 <title>Soure Code</title>
59 <para>All 3.x boot cd source code is located in the repository 'bootcd_v3'
60 on the PlanetLab CVS system. For information on how to access CVS, consult
61 the PlanetLab website. Unless otherwise noted, all file references refer
62 to this repository.</para>
66 <title>Basic Operation</title>
68 <para>The operation of the boot cd, when a machine is started off of one,
69 is fairly straightforward. Essentially, it loads a Linux kernel,
70 configures the hardware and network, and fetches a signed script to
71 execute. This generic operation allows for the boot cds to be used for any
72 number of operations, whether they are installing machines or debug
75 <para>The full operation of a boot cd, from the moment it is booted, is
76 described in the following diagram.</para>
79 <title>BootCD Operation Flowchart</title>
83 <imagedata fileref="bootcd-flowchart.png" />
90 <title>Security</title>
92 <para>Ensuring that the boot cd provided a secure node boot mechanism was
93 a primary concern during its development. The following requirements we
98 <para>The boot cd should be immutable. At any point, a PlanetLab
99 administrator should be able to reboot a machine into a known safe
100 environment to inspect or debug the node.</para>
104 <para>The cd should verify that the servers it contacts for executable
105 scripts should be PlanetLab Central servers, and not someone posing as
110 <para>The scripts executed are to be signed by PlanetLab
115 <para>Accomplishing 1. is fairly easy: simply require the cds to be burned
116 onto a write once media. Once that is accomplished, it is up to local site
117 administrators to ensure physical security of the node so the cd is not
118 switched out. Further work may be done by executed scripts to validate a
119 boot cd, if necessary (though not currently implemented).</para>
121 <para>Number two is accomplished through the use of SSL certificates. The
122 PlanetLab Central boot server, running Apache at the time of this writing,
123 uses a self signed SSL certificate. The boot cd, for each server it is to
124 contact (a primary server, and a backup server), contains the CA
125 certificates for those servers. Using the URL downloading tool curl, the
126 scripts on the cd can ensure they are contacting a PlanetLab boot server,
127 and not someone attempting to spoof one.</para>
129 <para>Number is accomplished through the use of GPG public and private
130 keys. There exists at PlanetLab Central a GPG private key that is used to
131 sign the scripts downloaded and executed by the cd. The public key is
132 located on the cd, and used to validate the signatures of the packages
133 before execution.</para>
137 <title>Hardware Detection</title>
139 <para>After the Linux kernel is loaded, the first operation is to load the
140 applicable hardware modules for devices on the system, including network
141 drivers, disk drivers, and any others. This process is nearly identical to
142 the process the BootManager uses. During the initial boot cd build
143 process, the script sources/merge_hw_table.py from the bootmanager
144 repository is invoked to create a lookup table to map PCI ids onto kernel
145 modules. For more information about how this script operates, consult the
146 BootManager technical documentation.</para>
150 <title>Building A BootCD</title>
152 <para>Previous PlanetLab boot cds were essentially boot cds from other
153 projects, modified for use with PlanetLab. With the introduction of
154 version 3.0 of the boot cd, they are now built from scratch. By doing
155 this, we can ensure that the packages contain on the cd are fully up to
156 date, only the packages we need for booting operations are installed (thus
157 reducing the cd size), and the hardware detection mechanisms match that of
158 the node installer (BootManager).</para>
160 <para>Though the cds are built from scratch, the process to build a cd is
161 relatively simple, and are as follows:</para>
165 <para>The build process is currently only tested with and known to
166 work with Fedora Core 2. You'll need root access on a FC2
171 <para>Check out the boot cd repository from PlanetLab CVS:</para>
173 <para><programlisting>cvs -d :pserver:anon@cvs.planet-lab.org:/cvs co bootcd_v3</programlisting></para>
177 <para>Initiate the build by running, from the bootcd_v3
180 <para><programlisting>./build.sh build default</programlisting></para>
184 <para>When complete, the resultant iso image will be located in
185 configurations/default/</para>
189 <para>The default configuration built above produces a boot cd that is
190 configured to contact the primary PlanetLab boot servers. To build a
191 custom boot cd that contacts a different server, with a different SSL
192 certificate and GPG key, you will need to create a custom
193 configuration:</para>
197 <para>Change into the bootcd_v3/configurations directory:</para>
199 <para><programlisting>cd bootcd_v3/configurations</programlisting></para>
203 <para>Copy the entire default directory, creating a new one with a
204 short name for the custom configuration. The name is only used during
205 the build process, and is not part of the actual cd.</para>
207 <para><programlisting>cp -r default mycustomcd</programlisting></para>
211 <para>Edit the configuration file in the new directory. That file
212 contains various fields that allow for the cd operation to be
213 customized, see the section, Build Configuration Options for more
218 <para>Once complete, the custom cd can be built with:</para>
220 <para><programlisting>./build.sh build mycustomcd</programlisting></para>
225 <title>Build Configuration Options</title>
227 <para>The configuration file for builds (the default being located at
228 configurations/default/configuration, contains the following values that
229 can be modified to result in a custom build boot cd:</para>
233 <para>EXTRA_VERSION</para>
235 <para>Set this to add extra version information to this cd. This
236 will be added to the result ISO name, and on the cd. By doing so,
237 you will be able to differentiate the cds from PlanetLab Boot cds
238 (which have no extra version.</para>
242 <para>DESCRIPTION</para>
244 <para>A simple text description, one line, of the boot cd.</para>
248 <para>ROOT_PASSWORD</para>
250 <para>The encrypted password to use for the root account on the
251 boot cd. Only applies to the boot cd, not the root account on an
252 installed and fully running node.</para>
256 <para>PRIMARY_SERVER / BACKUP_SERVER</para>
258 <para>The hostname of the server to attempt to contact first, and
259 a backup server if that one fails.</para>
263 <para>PRIMARY_SERVER_PORT / BACKUP_SERVER_PORT</para>
265 <para>Which SSL port on the server we should contact (default SSL
266 port is 443). This rarely will need to be changed.</para>
270 <para>PRIMARY_SERVER_PATH / BACKUP_SERVER_PATH</para>
272 <para>The path containing the script this cd should download and
273 execute. Can either be a path to an exact file, like
274 /boot/bootscript, or, can be a directory or dynamically executed
275 file, like /boot/index.php or just /boot. In this case, the
276 resultant output of that file/directory should be a signed and
277 executable script.</para>
281 <para>PRIMARY_SERVER_CERT / BACKUP_SERVER_CERT</para>
283 <para>The SSL CA certificate(s) for the above server(s). This is
284 used to validate that the server we are contacting has not been
289 <para>PRIMARY_SERVER_GPG / BACKUP_SERVER_GPG</para>
291 <para>The GPG public key(s) of the private key(s) that was used to
292 sign the script that will be returned by PRIMARY_SERVER_PATH or
293 BACKUP_SERVER_PATH</para>
297 <para>NODE_CONFIGURATION_FILE</para>
299 <para>If this cd is to be used exclusively by a single node, that
300 node's network configuration file can be placed on the cd. This is
301 the path on the local system to that configuration file, which
302 will be copied to a known location on the cd and used during boot
305 </itemizedlist></para>
307 <para>With regard to file paths: for the locations of the keys,
308 certificates, and optionally node configuration files, it is easiest to
309 place these files inside the directory with the bootcd configuration
310 file, and simply use the name of the file for the value. See the default
311 configuration file for an example.</para>
315 <title>Build Package Sources</title>
317 <para>The packages installed during the build process are
318 downloaded from the boot server specified by the
319 <parameter>PRIMARY_SERVER</parameter> variable, described
320 above. The build script installs the packages defined by the
321 <parameter>BootCD</parameter> yum group. This group should be
322 defined in a <filename>yumgroups.xml</filename> file located at
323 <filename>install-rpms/planetlab/yumgroups.xml</filename> in the
324 document root of the boot server.</para>