--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<article>
+ <articleinfo>
+ <title>BootCD v3.x Technical Documentation</title>
+
+ <author>
+ <firstname>Aaron</firstname>
+
+ <surname>Klingaman</surname>
+
+ <email>alk@absarokasoft.com</email>
+ </author>
+
+ <affiliation>
+ <orgname>Princeton University</orgname>
+ </affiliation>
+
+ <revhistory>
+ <revision>
+ <revnumber>1.0</revnumber>
+
+ <date>November 17, 2005</date>
+
+ <authorinitials>AK</authorinitials>
+
+ <revdescription>
+ <para>Initial draft.</para>
+ </revdescription>
+ </revision>
+ </revhistory>
+ </articleinfo>
+
+ <section>
+ <title>Overview</title>
+
+ <para>This document describes in detail how the PlanetLab boot CD is built
+ and operates when running on a node. Older boot CDs, including 2.x cds,
+ are not the focus of this document, and are no longer being deployed on
+ production systems.</para>
+ </section>
+
+ <section>
+ <title>Background</title>
+
+ <para>Since the early days of PlanetLab, all production nodes are
+ configured during setup to only start up off of the cdrom, with a
+ PlanetLab boot cd always left in the drive. The intention is to allow a
+ machine to be able to restart into a known environment, for debugging
+ system problems, or as a way to still access the machine but not have any
+ potentially compromised code to run if the system is believed to be
+ compromised.</para>
+ </section>
+
+ <section>
+ <title>Soure Code</title>
+
+ <para>All 3.x boot cd source code is located in the repository 'bootcd_v3'
+ on the PlanetLab CVS system. For information on how to access CVS, consult
+ the PlanetLab website. Unless otherwise noted, all file references refer
+ to this repository.</para>
+ </section>
+
+ <section>
+ <title>Basic Operation</title>
+
+ <para>The operation of the boot cd, when a machine is started off of one,
+ is fairly straightforward. Essentially, it loads a Linux kernel,
+ configures the hardware and network, and fetches a signed script to
+ execute. This generic operation allows for the boot cds to be used for any
+ number of operations, whether they are installing machines or debug
+ problems.</para>
+
+ <para>The full operation of a boot cd, from the moment it is booted, is
+ described in the following diagram.</para>
+
+ <figure>
+ <title>BootCD Operation Flowchart</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="bootcd-flowchart.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+
+ <section>
+ <title>Security</title>
+
+ <para>Ensuring that the boot cd provided a secure node boot mechanism was
+ a primary concern during its development. The following requirements we
+ used:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>The boot cd should be immutable. At any point, a PlanetLab
+ administrator should be able to reboot a machine into a known safe
+ environment to inspect or debug the node.</para>
+ </listitem>
+
+ <listitem>
+ <para>The cd should verify that the servers it contacts for executable
+ scripts should be PlanetLab Central servers, and not someone posing as
+ one.</para>
+ </listitem>
+
+ <listitem>
+ <para>The scripts executed are to be signed by PlanetLab
+ Central.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>Accomplishing 1. is fairly easy: simply require the cds to be burned
+ onto a write once media. Once that is accomplished, it is up to local site
+ administrators to ensure physical security of the node so the cd is not
+ switched out. Further work may be done by executed scripts to validate a
+ boot cd, if necessary (though not currently implemented).</para>
+
+ <para>Number two is accomplished through the use of SSL certificates. The
+ PlanetLab Central boot server, running Apache at the time of this writing,
+ uses a self signed SSL certificate. The boot cd, for each server it is to
+ contact (a primary server, and a backup server), contains the CA
+ certificates for those servers. Using the URL downloading tool curl, the
+ scripts on the cd can ensure they are contacting a PlanetLab boot server,
+ and not someone attempting to spoof one.</para>
+
+ <para>Number is accomplished through the use of GPG public and private
+ keys. There exists at PlanetLab Central a GPG private key that is used to
+ sign the scripts downloaded and executed by the cd. The public key is
+ located on the cd, and used to validate the signatures of the packages
+ before execution.</para>
+ </section>
+
+ <section>
+ <title>Hardware Detection</title>
+
+ <para>After the Linux kernel is loaded, the first operation is to load the
+ applicable hardware modules for devices on the system, including network
+ drivers, disk drivers, and any others. This process is nearly identical to
+ the process the BootManager uses. During the initial boot cd build
+ process, the script sources/merge_hw_table.py from the bootmanager
+ repository is invoked to create a lookup table to map PCI ids onto kernel
+ modules. For more information about how this script operates, consult the
+ BootManager technical documentation.</para>
+ </section>
+
+ <section>
+ <title>Building A BootCD</title>
+
+ <para>Previous PlanetLab boot cds were essentially boot cds from other
+ projects, modified for use with PlanetLab. With the introduction of
+ version 3.0 of the boot cd, they are now built from scratch. By doing
+ this, we can ensure that the packages contain on the cd are fully up to
+ date, only the packages we need for booting operations are installed (thus
+ reducing the cd size), and the hardware detection mechanisms match that of
+ the node installer (BootManager).</para>
+
+ <para>Though the cds are built from scratch, the process to build a cd is
+ relatively simple, and are as follows:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>The build process is currently only tested with and known to
+ work with Fedora Core 2. You'll need root access on a FC2
+ machine.</para>
+ </listitem>
+
+ <listitem>
+ <para>Check out the boot cd repository from PlanetLab CVS:</para>
+
+ <para><programlisting>cvs -d :pserver:anon@cvs.planet-lab.org:/cvs co bootcd_v3</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>Initiate the build by running, from the bootcd_v3
+ directory:</para>
+
+ <para><programlisting>./build.sh build default</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>When complete, the resultant iso image will be located in
+ configurations/default/</para>
+ </listitem>
+ </orderedlist>
+
+ <para>The default configuration built above produces a boot cd that is
+ configured to contact the primary PlanetLab boot servers. To build a
+ custom boot cd that contacts a different server, with a different SSL
+ certificate and GPG key, you will need to create a custom
+ configuration:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Change into the bootcd_v3/configurations directory:</para>
+
+ <para><programlisting>cd bootcd_v3/configurations</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>Copy the entire default directory, creating a new one with a
+ short name for the custom configuration. The name is only used during
+ the build process, and is not part of the actual cd.</para>
+
+ <para><programlisting>cp -r default mycustomcd</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>Edit the configuration file in the new directory. That file
+ contains various fields that allow for the cd operation to be
+ customized, see the section, Build Configuration Options for more
+ information.</para>
+ </listitem>
+
+ <listitem>
+ <para>Once complete, the custom cd can be built with:</para>
+
+ <para><programlisting>./build.sh build mycustomcd</programlisting></para>
+ </listitem>
+ </orderedlist>
+
+ <section>
+ <title>Build Configuration Options</title>
+
+ <para>The configuration file for builds (the default being located at
+ configurations/default/configuration, contains the following values that
+ can be modified to result in a custom build boot cd:</para>
+
+ <para><itemizedlist>
+ <listitem>
+ <para>EXTRA_VERSION</para>
+
+ <para>Set this to add extra version information to this cd. This
+ will be added to the result ISO name, and on the cd. By doing so,
+ you will be able to differentiate the cds from PlanetLab Boot cds
+ (which have no extra version.</para>
+ </listitem>
+
+ <listitem>
+ <para>DESCRIPTION</para>
+
+ <para>A simple text description, one line, of the boot cd.</para>
+ </listitem>
+
+ <listitem>
+ <para>ROOT_PASSWORD</para>
+
+ <para>The encrypted password to use for the root account on the
+ boot cd. Only applies to the boot cd, not the root account on an
+ installed and fully running node.</para>
+ </listitem>
+
+ <listitem>
+ <para>PRIMARY_SERVER / BACKUP_SERVER</para>
+
+ <para>The hostname of the server to attempt to contact first, and
+ a backup server if that one fails.</para>
+ </listitem>
+
+ <listitem>
+ <para>PRIMARY_SERVER_PORT / BACKUP_SERVER_PORT</para>
+
+ <para>Which SSL port on the server we should contact (default SSL
+ port is 443). This rarely will need to be changed.</para>
+ </listitem>
+
+ <listitem>
+ <para>PRIMARY_SERVER_PATH / BACKUP_SERVER_PATH</para>
+
+ <para>The path containing the script this cd should download and
+ execute. Can either be a path to an exact file, like
+ /boot/bootscript, or, can be a directory or dynamically executed
+ file, like /boot/index.php or just /boot. In this case, the
+ resultant output of that file/directory should be a signed and
+ executable script.</para>
+ </listitem>
+
+ <listitem>
+ <para>PRIMARY_SERVER_CERT / BACKUP_SERVER_CERT</para>
+
+ <para>The SSL CA certificate(s) for the above server(s). This is
+ used to validate that the server we are contacting has not been
+ spoofed.</para>
+ </listitem>
+
+ <listitem>
+ <para>PRIMARY_SERVER_GPG / BACKUP_SERVER_GPG</para>
+
+ <para>The GPG public key(s) of the private key(s) that was used to
+ sign the script that will be returned by PRIMARY_SERVER_PATH or
+ BACKUP_SERVER_PATH</para>
+ </listitem>
+
+ <listitem>
+ <para>NODE_CONFIGURATION_FILE</para>
+
+ <para>If this cd is to be used exclusively by a single node, that
+ node's network configuration file can be placed on the cd. This is
+ the path on the local system to that configuration file, which
+ will be copied to a known location on the cd and used during boot
+ up.</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>With regard to file paths: for the locations of the keys,
+ certificates, and optionally node configuration files, it is easiest to
+ place these files inside the directory with the bootcd configuration
+ file, and simply use the name of the file for the value. See the default
+ configuration file for an example.</para>
+ </section>
+
+ <section>
+ <title>Build Package Sources</title>
+
+ <para>The packages installed during the build process are
+ downloaded from the boot server specified by the
+ <parameter>PRIMARY_SERVER</parameter> variable, described
+ above. The build script installs the packages defined by the
+ <parameter>BootCD</parameter> yum group. This group should be
+ defined in a <filename>yumgroups.xml</filename> file located at
+ <filename>install-rpms/planetlab/yumgroups.xml</filename> in the
+ document root of the boot server.</para>
+ </section>
+ </section>
+</article>
git://git.onelab.eu / bootcd.git / blobdiff