From 4ae5f0792fc96aff127331b76c8d9dce049308e2 Mon Sep 17 00:00:00 2001 From: Aaron Klingaman Date: Wed, 16 Nov 2005 23:04:12 +0000 Subject: [PATCH] working draft of boot cd v3 documentation --- documentation/bootcd-tech-doc.xml | 186 ++++++++++++++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 documentation/bootcd-tech-doc.xml diff --git a/documentation/bootcd-tech-doc.xml b/documentation/bootcd-tech-doc.xml new file mode 100644 index 0000000..0b1c7bb --- /dev/null +++ b/documentation/bootcd-tech-doc.xml @@ -0,0 +1,186 @@ + + +
+ + BootCD v3.x Technical Documentation + + + Aaron + + Klingaman + + alk@absarokasoft.com + + + + Princeton University + + + + + 1.0 + + November 16, 2005 + + AK + + + Initial draft. + + + + + +
+ Overview + + 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. +
+ +
+ Background + + 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. +
+ +
+ Soure Code + + 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. +
+ +
+ Basic Operation + + The operation of the boot cd, when a machine is started off of one, + is fairly straight forward. 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. + + The full operation of a boot cd, from the moment it is booted, is + described in the following diagram. +
+ +
+ Hardware Detection + + When a node is being installed, the BootManager must identify which + hardware the machine has that is applicable to a running node, and + configure the node properly so it can boot properly post-install. The + general procedure for doing so is outline in this section. It is + implemented in the source/systeminfo.py file. + + The process for identifying which kernel module needs to be load + is: + + + + Create a lookup table of all modules, and which PCI ids + coorespond to this module. + + + + For each PCI device on the system, lookup its module in the + first table. + + + + If a module is found, put in into one of two categories of + modules, either network module or scsi module, based on the PCI device + class. + + + + For each network module, write out an 'eth<index>' entry + in the modprobe.conf configuration file. + + + + For each scsi module, write out a + 'scsi_hostadapter<index>' entry in the modprobe.conf + configuration file. + + + + This process is fairly straight forward, and is simplified by the + fact that we currently do not need support for USB, sound, or video + devices when the node is fully running. The boot cd itself uses a similar + process, but includes USB devices. Consult the boot cd technical + documentation for more information. + + The creation of the PCI id to kernel module table lookup uses three + different sources of information, and merges them together into a single + table for easier lookups. With these three sources of information, a + fairly comprehensive lookup table can be generated for the devices that + PlanetLab nodes need to have configured. They include: + + + + The installed /usr/share/hwdata/pcitable + file + + Created at the time the hwdata rpm was built, this file contains + mappings of PCI ids to devices for a large number of devices. It is + not necessarily complete, and doesn't take into account the modules + that are actually available by the built PlanetLab kernel, which is a + subset of the full set available (again, PlanetLab nodes do not have a + use for network or video drivers, and thus are not typically + built). + + + + From the built kernel, the modules.pcimap + from the /lib/modules/<kernelversion>/ + directory. + + This file is generated at the time the kernel is installed, and + pulls the PCI ids out of each module, for the modules list they + devices they support. Not all modules list all devices they sort, and + some contain wild cards (that match any device of a single + manufacturer). + + + + From the built kernel, the modules.dep from + the /lib/modules/<kernelversion>/ + directory. + + This file is also generated at the time the kernel is installed, + but lists the dependencies between various modules. It is used to + generate a list of modules that are actually available. + + + + It should be noted here that SATA (Serial ATA) devices have been + known to exist with both a PCI SCSI device class, and with a PCI IDE + device class. Under linux 2.6 kernels, all SATA modules need to be listed + in modprobe.conf under 'scsi_hostadapter' lines. This case is handled in + the hardware loading scripts by making the assumption that if an IDE + device matches a loadable module, it should be put in the modprobe.conf + file, as 'real' IDE drivers are all currently built into the kernel, and + do not need to be loaded. SATA devices that have a PCI SCSI device class + are easily identified. + + It is enssential that the modprobe.conf configuration file contain + the correct drivers for the disks on the system, if they are present, as + during kernel installation the creation of the initrd (initial ramdisk) + which is responsible for booting the system uses this file to identify + which drivers to include in it. A failure to do this typically results in + an kernel panic at boot with a 'no init found' message. +
+
\ No newline at end of file -- 2.43.0