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 16, 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 straight forward. 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   </section>
  78
  79   <section>
  80     <title>Hardware Detection</title>
  81
  82     <para>When a node is being installed, the BootManager must identify which
  83     hardware the machine has that is applicable to a running node, and
  84     configure the node properly so it can boot properly post-install. The
  85     general procedure for doing so is outline in this section. It is
  86     implemented in the <filename>source/systeminfo.py</filename> file.</para>
  87
  88     <para>The process for identifying which kernel module needs to be load
  89     is:</para>
  90
  91     <orderedlist>
  92       <listitem>
  93         <para>Create a lookup table of all modules, and which PCI ids
  94         coorespond to this module.</para>
  95       </listitem>
  96
  97       <listitem>
  98         <para>For each PCI device on the system, lookup its module in the
  99         first table.</para>
 100       </listitem>
 101
 102       <listitem>
 103         <para>If a module is found, put in into one of two categories of
 104         modules, either network module or scsi module, based on the PCI device
 105         class.</para>
 106       </listitem>
 107
 108       <listitem>
 109         <para>For each network module, write out an 'eth&lt;index&gt;' entry
 110         in the modprobe.conf configuration file.</para>
 111       </listitem>
 112
 113       <listitem>
 114         <para>For each scsi module, write out a
 115         'scsi_hostadapter&lt;index&gt;' entry in the modprobe.conf
 116         configuration file.</para>
 117       </listitem>
 118     </orderedlist>
 119
 120     <para>This process is fairly straight forward, and is simplified by the
 121     fact that we currently do not need support for USB, sound, or video
 122     devices when the node is fully running. The boot cd itself uses a similar
 123     process, but includes USB devices. Consult the boot cd technical
 124     documentation for more information.</para>
 125
 126     <para>The creation of the PCI id to kernel module table lookup uses three
 127     different sources of information, and merges them together into a single
 128     table for easier lookups. With these three sources of information, a
 129     fairly comprehensive lookup table can be generated for the devices that
 130     PlanetLab nodes need to have configured. They include:</para>
 131
 132     <orderedlist>
 133       <listitem>
 134         <para>The installed <filename>/usr/share/hwdata/pcitable
 135         </filename>file</para>
 136
 137         <para>Created at the time the hwdata rpm was built, this file contains
 138         mappings of PCI ids to devices for a large number of devices. It is
 139         not necessarily complete, and doesn't take into account the modules
 140         that are actually available by the built PlanetLab kernel, which is a
 141         subset of the full set available (again, PlanetLab nodes do not have a
 142         use for network or video drivers, and thus are not typically
 143         built).</para>
 144       </listitem>
 145
 146       <listitem>
 147         <para>From the built kernel, the <filename>modules.pcimap</filename>
 148         from the <filename>/lib/modules/&lt;kernelversion&gt;/</filename>
 149         directory.</para>
 150
 151         <para>This file is generated at the time the kernel is installed, and
 152         pulls the PCI ids out of each module, for the modules list they
 153         devices they support. Not all modules list all devices they sort, and
 154         some contain wild cards (that match any device of a single
 155         manufacturer).</para>
 156       </listitem>
 157
 158       <listitem>
 159         <para>From the built kernel, the <filename>modules.dep</filename> from
 160         the <filename>/lib/modules/&lt;kernelversion&gt;/</filename>
 161         directory.</para>
 162
 163         <para>This file is also generated at the time the kernel is installed,
 164         but lists the dependencies between various modules. It is used to
 165         generate a list of modules that are actually available.</para>
 166       </listitem>
 167     </orderedlist>
 168
 169     <para>It should be noted here that SATA (Serial ATA) devices have been
 170     known to exist with both a PCI SCSI device class, and with a PCI IDE
 171     device class. Under linux 2.6 kernels, all SATA modules need to be listed
 172     in modprobe.conf under 'scsi_hostadapter' lines. This case is handled in
 173     the hardware loading scripts by making the assumption that if an IDE
 174     device matches a loadable module, it should be put in the modprobe.conf
 175     file, as 'real' IDE drivers are all currently built into the kernel, and
 176     do not need to be loaded. SATA devices that have a PCI SCSI device class
 177     are easily identified.</para>
 178
 179     <para>It is enssential that the modprobe.conf configuration file contain
 180     the correct drivers for the disks on the system, if they are present, as
 181     during kernel installation the creation of the initrd (initial ramdisk)
 182     which is responsible for booting the system uses this file to identify
 183     which drivers to include in it. A failure to do this typically results in
 184     an kernel panic at boot with a 'no init found' message.</para>
 185   </section>
 186 </article>