documentation/bootcd-tech-doc.xml

   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">
   4 <article>
   5   <articleinfo>
   6     <title>BootCD v3.x Technical Documentation</title>
   7
   8     <author>
   9       <firstname>Aaron</firstname>
  10
  11       <surname>Klingaman</surname>
  12
  13       <email>alk@absarokasoft.com</email>
  14     </author>
  15
  16     <affiliation>
  17       <orgname>Princeton University</orgname>
  18     </affiliation>
  19
  20     <revhistory>
  21       <revision>
  22         <revnumber>1.0</revnumber>
  23
  24         <date>November 17, 2005</date>
  25
  26         <authorinitials>AK</authorinitials>
  27
  28         <revdescription>
  29           <para>Initial draft.</para>
  30         </revdescription>
  31       </revision>
  32     </revhistory>
  33   </articleinfo>
  34
  35   <section>
  36     <title>Overview</title>
  37
  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>
  42   </section>
  43
  44   <section>
  45     <title>Background</title>
  46
  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
  53     compromised.</para>
  54   </section>
  55
  56   <section>
  57     <title>Soure Code</title>
  58
  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>
  63   </section>
  64
  65   <section>
  66     <title>Basic Operation</title>
  67
  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
  73     problems.</para>
  74
  75     <para>The full operation of a boot cd, from the moment it is booted, is
  76     described in the following diagram.</para>
  77
  78     <figure>
  79       <title>BootCD Operation Flowchart</title>
  80
  81       <mediaobject>
  82         <imageobject>
  83           <imagedata fileref="bootcd-flowchart.png" />
  84         </imageobject>
  85       </mediaobject>
  86     </figure>
  87   </section>
  88
  89   <section>
  90     <title>Security</title>
  91
  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
  94     used:</para>
  95
  96     <orderedlist>
  97       <listitem>
  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>
 101       </listitem>
 102
 103       <listitem>
 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
 106         one.</para>
 107       </listitem>
 108
 109       <listitem>
 110         <para>The scripts executed are to be signed by PlanetLab
 111         Central.</para>
 112       </listitem>
 113     </orderedlist>
 114
 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>
 120
 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>
 128
 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>
 134   </section>
 135
 136   <section>
 137     <title>Hardware Detection</title>
 138
 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>
 147   </section>
 148
 149   <section>
 150     <title>Building A BootCD</title>
 151
 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>
 159
 160     <para>Though the cds are built from scratch, the process to build a cd is
 161     relatively simple, and are as follows:</para>
 162
 163     <orderedlist>
 164       <listitem>
 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
 167         machine.</para>
 168       </listitem>
 169
 170       <listitem>
 171         <para>Check out the boot cd repository from PlanetLab CVS:</para>
 172
 173         <para><programlisting>cvs -d :pserver:anon@cvs.planet-lab.org:/cvs co bootcd_v3</programlisting></para>
 174       </listitem>
 175
 176       <listitem>
 177         <para>Initiate the build by running, from the bootcd_v3
 178         directory:</para>
 179
 180         <para><programlisting>./build.sh build default</programlisting></para>
 181       </listitem>
 182
 183       <listitem>
 184         <para>When complete, the resultant iso image will be located in
 185         configurations/default/</para>
 186       </listitem>
 187     </orderedlist>
 188
 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>
 194
 195     <orderedlist>
 196       <listitem>
 197         <para>Change into the bootcd_v3/configurations directory:</para>
 198
 199         <para><programlisting>cd bootcd_v3/configurations</programlisting></para>
 200       </listitem>
 201
 202       <listitem>
 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>
 206
 207         <para><programlisting>cp -r default mycustomcd</programlisting></para>
 208       </listitem>
 209
 210       <listitem>
 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
 214         information.</para>
 215       </listitem>
 216
 217       <listitem>
 218         <para>Once complete, the custom cd can be built with:</para>
 219
 220         <para><programlisting>./build.sh build mycustomcd</programlisting></para>
 221       </listitem>
 222     </orderedlist>
 223
 224     <section>
 225       <title>Build Configuration Options</title>
 226
 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>
 230
 231       <para><itemizedlist>
 232           <listitem>
 233             <para>EXTRA_VERSION</para>
 234
 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>
 239           </listitem>
 240
 241           <listitem>
 242             <para>DESCRIPTION</para>
 243
 244             <para>A simple text description, one line, of the boot cd.</para>
 245           </listitem>
 246
 247           <listitem>
 248             <para>ROOT_PASSWORD</para>
 249
 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>
 253           </listitem>
 254
 255           <listitem>
 256             <para>PRIMARY_SERVER / BACKUP_SERVER</para>
 257
 258             <para>The hostname of the server to attempt to contact first, and
 259             a backup server if that one fails.</para>
 260           </listitem>
 261
 262           <listitem>
 263             <para>PRIMARY_SERVER_PORT / BACKUP_SERVER_PORT</para>
 264
 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>
 267           </listitem>
 268
 269           <listitem>
 270             <para>PRIMARY_SERVER_PATH / BACKUP_SERVER_PATH</para>
 271
 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>
 278           </listitem>
 279
 280           <listitem>
 281             <para>PRIMARY_SERVER_CERT / BACKUP_SERVER_CERT</para>
 282
 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
 285             spoofed.</para>
 286           </listitem>
 287
 288           <listitem>
 289             <para>PRIMARY_SERVER_GPG / BACKUP_SERVER_GPG</para>
 290
 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>
 294           </listitem>
 295
 296           <listitem>
 297             <para>NODE_CONFIGURATION_FILE</para>
 298
 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
 303             up.</para>
 304           </listitem>
 305         </itemizedlist></para>
 306
 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>
 312     </section>
 313
 314     <section>
 315       <title>Build Package Sources</title>
 316
 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>
 325     </section>
 326   </section>
 327 </article>