documentation/boot-manager-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>BootManager 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>March 15, 2005</date>
  25
  26         <authorinitials>AK</authorinitials>
  27
  28         <revdescription>
  29           <para>Initial draft.</para>
  30         </revdescription>
  31       </revision>
  32
  33       <revision>
  34         <revnumber>1.1</revnumber>
  35
  36         <date>May 31, 2005</date>
  37
  38         <authorinitials>AK</authorinitials>
  39
  40         <revdescription>
  41           <para>Updated post implementation and deployment.</para>
  42         </revdescription>
  43       </revision>
  44
  45       <revision>
  46         <revnumber>1.2</revnumber>
  47
  48         <date>November 16, 2005</date>
  49
  50         <authorinitials>AK</authorinitials>
  51
  52         <revdescription>
  53           <para>Add section on where source code is, and other updates to make
  54           it consistent with implementation.</para>
  55         </revdescription>
  56       </revision>
  57
  58       <revision>
  59         <revnumber>1.3</revnumber>
  60
  61         <date>March 17, 2006</date>
  62
  63         <authorinitials>AK</authorinitials>
  64
  65         <revdescription>
  66           <para>Reworked various wording to fit in correctly with new
  67           architecture terminology.</para>
  68
  69           <para>Updated to match PlanetLab Core Specification.</para>
  70         </revdescription>
  71       </revision>
  72     </revhistory>
  73   </articleinfo>
  74
  75   <section>
  76     <title>Overview</title>
  77
  78     <para>This document describes the implementation of the package called the
  79     BootManager at a technical level. The BootManager is used in conjunction
  80     with the PlanetLab BootCD to securely boot nodes, including remote
  81     installation, debugging, and validation. It is the primary method used by
  82     the PlanetLab Central Management Authority (MA) to manage nodes.</para>
  83   </section>
  84
  85   <section>
  86     <title>Components</title>
  87
  88     <para>The entire BootManager system consists of several primary
  89     components. These consist of:</para>
  90
  91     <itemizedlist>
  92       <listitem>
  93         <para>The existing, stardard MA provided calls to allow principals to
  94         add and manage node records</para>
  95       </listitem>
  96
  97       <listitem>
  98         <para>New MA API calls, for use by principals, to generate
  99         node-specific configuration files</para>
 100       </listitem>
 101
 102       <listitem>
 103         <para>New MA API calls with a new authentication mechanism for
 104         node-based MA calls</para>
 105       </listitem>
 106
 107       <listitem>
 108         <para>A code package to be run in the boot cd environment on nodes
 109         containing core install/validate/boot logic</para>
 110       </listitem>
 111     </itemizedlist>
 112
 113     <para>The intention with the BootManager system is to send the same script
 114     back for all nodes (consisting of the core BootManager code), in all boot
 115     states, each time the node starts. Then, the BootManager will run and
 116     detiremine which operations to perform on the node, based on the current
 117     boot state. All state based logic for the node boot, install, debug, and
 118     reconfigure operations are contained in one place; there is no boot state
 119     specific logic located on the MA servers.</para>
 120   </section>
 121
 122   <section>
 123     <title>Soure Code</title>
 124
 125     <para>All BootManager source code is located in the repository
 126     'bootmanager' on the PlanetLab CVS system. For information on how to
 127     access CVS, consult the PlanetLab website. Unless otherwise noted, all
 128     file references refer to this repository.</para>
 129   </section>
 130
 131   <section>
 132     <title> Management Authority Node Fields</title>
 133
 134     <para>The following fields MA database fields are directly applicable to
 135     the BootManager operation, and to the node-related API calls (detailed
 136     below).</para>
 137
 138     <section>
 139       <title>node_id</title>
 140
 141       <para>An integer unique identifier for a specific node.</para>
 142     </section>
 143
 144     <section>
 145       <title>node_key</title>
 146
 147       <para>This is a per-node, unique value that forms the basis of the node
 148       authentication mechanism detailed below. When a new node record is added
 149       to the MA by a principal, it is automatically assigned a new, random
 150       key, and distributed out of band to the nodes. This shared secret is
 151       then used for node authentication. The contents of node_key are
 152       generated using this command:</para>
 153
 154       <para><programlisting>openssl rand -base64 32</programlisting></para>
 155
 156       <para>Any = (equals) characters are removed from the string.</para>
 157     </section>
 158
 159     <section>
 160       <title>boot_state</title>
 161
 162       <para>Each node always has one of four possible boot states, stored as a
 163       string, refered to as boot_state. These are:</para>
 164
 165       <orderedlist>
 166         <listitem>
 167           <para>'inst'</para>
 168
 169           <para>Install. The boot state cooresponds to a new node that has not
 170           yet been installed, but record of it does exist. When the boot
 171           manager starts, and the node is in this state, the user is prompted
 172           to continue with the installation. The intention here is to prevent
 173           a non-PlanetLab machine (like a user's desktop machine) from
 174           becoming inadvertantly wiped and installed with the PlanetLab node
 175           software. This is the default state for new nodes.</para>
 176         </listitem>
 177
 178         <listitem>
 179           <para>'rins'</para>
 180
 181           <para>Reinstall. In this state, a node will reinstall the node
 182           software, erasing anything that might have been on the disk
 183           before.</para>
 184         </listitem>
 185
 186         <listitem>
 187           <para>'boot'</para>
 188
 189           <para>Boot. This state cooresponds with nodes that have sucessfully
 190           installed, and can be chain booted to the runtime node
 191           kernel.</para>
 192         </listitem>
 193
 194         <listitem>
 195           <para>'dbg'</para>
 196
 197           <para>Debug. Regardless of whether or not a machine has been
 198           installed, this state sets up a node to be debugged by
 199           administrators.</para>
 200         </listitem>
 201       </orderedlist>
 202     </section>
 203   </section>
 204
 205   <section>
 206     <title>Existing Management Authority API Calls</title>
 207
 208     <para>These calls, take from the PlanetLab Core Specification and extended
 209     with additional parameters, are used by Principals to maintain the set of
 210     nodes managed by a MA. See the Core Specification for more information.
 211     The MA may provide an easy to use interface, such as a web interface, that
 212     calls these directly.</para>
 213
 214     <para><itemizedlist>
 215         <listitem>
 216           <para>AddNode( authentication, node_values )</para>
 217
 218           <para>Add a new node record. node_values contains hostname,
 219           ipaddress, and the new fields: boot_state. The resultant node_id is
 220           returned.</para>
 221         </listitem>
 222
 223         <listitem>
 224           <para>UpdateNode( authentication, node_id, update_values )</para>
 225
 226           <para>Update an existing node record. update_values can include
 227           hostname, ipaddress, and the new fields: boot_state.</para>
 228         </listitem>
 229
 230         <listitem>
 231           <para>DeleteNode( authentication, node_id )</para>
 232
 233           <para>Delete a node record.</para>
 234         </listitem>
 235       </itemizedlist></para>
 236   </section>
 237
 238   <section>
 239     <title>New Management Authority API Calls</title>
 240
 241     <para>The API calls available as part of the MA API that are intended to
 242     be run by principals leverage existing authentication mechanisms. However,
 243     the API calls described below that will be run by the nodes themselves
 244     need a new authentication mechanism.</para>
 245
 246     <section>
 247       <title>Node Authentication</title>
 248
 249       <para>As is done with other MA API calls, the first parameter to all
 250       BootManager related calls will be an authentication structure,
 251       consisting of these named fields:</para>
 252
 253       <itemizedlist>
 254         <listitem>
 255           <para>AuthMethod</para>
 256
 257           <para>The authentication method, only 'hmac' is currently
 258           supported</para>
 259         </listitem>
 260
 261         <listitem>
 262           <para>node_id</para>
 263
 264           <para>The node id, contained in the configuration file on the
 265           node.</para>
 266         </listitem>
 267
 268         <listitem>
 269           <para>node_ip</para>
 270
 271           <para>The node's primary IP address. This will be checked with the
 272           node_id against MA records.</para>
 273         </listitem>
 274
 275         <listitem>
 276           <para>value</para>
 277
 278           <para>The authentication string, depending on method. For the 'hmac'
 279           method, a hash for the call using the HMAC algorithm, made from the
 280           parameters of the call the key contained on the configuration file.
 281           For specifics on how this is created, see below.</para>
 282         </listitem>
 283       </itemizedlist>
 284
 285       <para>Authentication is succesful if the MA is able to create the same
 286       hash from the values usings its own copy of the NODE_KEY. If the hash
 287       values to not match, then either the keys do not match or the values of
 288       the call were modified in transmision and the node cannot be
 289       authenticated.</para>
 290
 291       <para>Both the BootManager and the authentication functions at the MA
 292       must agree on a method for creating the hash values for each call. This
 293       hash is essentially a finger print of the method call, and is created by
 294       this algorithm:</para>
 295
 296       <orderedlist>
 297         <listitem>
 298           <para>Take the value of every part of each parameter, except the
 299           authentication structure, and convert them to strings. For arrays,
 300           each element is used. For dictionaries, not only is the value of all
 301           the items used, but the keys themselves. Embedded types (arrays or
 302           dictionaries inside arrays or dictionaries, etc), also have all
 303           values extracted.</para>
 304         </listitem>
 305
 306         <listitem>
 307           <para>Alphabetically sort all the parameters.</para>
 308         </listitem>
 309
 310         <listitem>
 311           <para>Concatenate them into a single string.</para>
 312         </listitem>
 313
 314         <listitem>
 315           <para>Prepend the string with the method name and [, and append
 316           ].</para>
 317         </listitem>
 318       </orderedlist>
 319
 320       <para>The implementation of this algorithm is in the function
 321       serialize_params in the file source/BootAPI.py. The same algorithm is
 322       located in the 'plc_api' repository, in the function serialize_params in
 323       the file PLC/Auth.py.</para>
 324
 325       <para>The resultant string is fed into the HMAC algorithm with the node
 326       key, and the resultant hash value is used in the authentication
 327       structure.</para>
 328
 329       <para>This authentication method makes a number of assumptions, detailed
 330       below.</para>
 331
 332       <orderedlist>
 333         <listitem>
 334           <para>All calls made to the MA are done over SSL, so the details of
 335           the authentication structure cannot be viewed by 3rd parties. If, in
 336           the future, non-SSL based calls are desired, a sequence number or
 337           some other value making each call unique will would be required to
 338           prevent replay attacks. In fact, the current use of SSL negates the
 339           need to create and send hashes across - technically, the key itself
 340           could be sent directly to the MA, assuming the connection is made to
 341           an HTTPS server with a third party signed SSL certificate.</para>
 342         </listitem>
 343
 344         <listitem>
 345           <para>Athough calls are done over SSL, they use the Python class
 346           libary xmlrpclib, which does not do SSL certificate
 347           verification.</para>
 348         </listitem>
 349       </orderedlist>
 350     </section>
 351
 352     <section>
 353       <title>New API Calls</title>
 354
 355       <para>The calls available to the BootManager, that accept the above
 356       authentication, are:</para>
 357
 358       <itemizedlist>
 359         <listitem>
 360           <para>BootUpdateNode( authentication, update_values )</para>
 361
 362           <para>Update a node record, including its boot state, primary
 363           network, or ssh host key.</para>
 364         </listitem>
 365
 366         <listitem>
 367           <para>BootCheckAuthentication( authentication )</para>
 368
 369           <para>Simply check to see if the node is recognized by the system
 370           and is authorized.</para>
 371         </listitem>
 372
 373         <listitem>
 374           <para>BootGetNodeDetails( authentication )</para>
 375
 376           <para>Return details about a node, including its state, what
 377           networks the MA database has configured for the node, and what the
 378           model of the node is.</para>
 379         </listitem>
 380
 381         <listitem>
 382           <para>BootNotifyOwners( authentication, message, include_pi,
 383           include_tech, include_support )</para>
 384
 385           <para>Notify someone about an event that happened on the machine,
 386           and optionally include the site PIs, technical contacts, and
 387           PlanetLab Support.</para>
 388         </listitem>
 389       </itemizedlist>
 390
 391       <para>The new calls used by principals, using existing authentication
 392       methods, are:</para>
 393
 394       <para><itemizedlist>
 395           <listitem>
 396             <para>GenerateNodeConfigurationFile( authentication, node_id
 397             )</para>
 398
 399             <para>Generate a configuration file to be used by the BootManager
 400             and the BootCD to configure the network for the node during boot.
 401             This resultant file also contains the node_id and node_key values.
 402             A new node_key is generated each time. The full contents and
 403             format of this file is detailed below.</para>
 404           </listitem>
 405         </itemizedlist></para>
 406     </section>
 407   </section>
 408
 409   <section>
 410     <title>Core Software Package</title>
 411
 412     <para>The BootManager core package, which is run on the nodes and contacts
 413     the MA API as necessary, is responsible for the following major functional
 414     units:</para>
 415
 416     <itemizedlist>
 417       <listitem>
 418         <para>Configuring node hardware and installing the PlanetLab operating
 419         system</para>
 420       </listitem>
 421
 422       <listitem>
 423         <para>Putting a node into a debug state so administrators can track
 424         down problems</para>
 425       </listitem>
 426
 427       <listitem>
 428         <para>Reconfiguring an already installed node to reflect new hardware,
 429         or changed network settings</para>
 430       </listitem>
 431
 432       <listitem>
 433         <para>Booting an already installed node into the PlanetLab operating
 434         system</para>
 435       </listitem>
 436     </itemizedlist>
 437
 438     <section>
 439       <title>BootManager Flow Chart</title>
 440
 441       <para>Below is a high level flow chart of the BootManager, from the time
 442       it is executed to when it exits. This core state machine is located in
 443       source/BootManager.py.</para>
 444
 445       <para><figure>
 446           <title>BootManager Flow Chart</title>
 447
 448           <mediaobject>
 449             <imageobject>
 450               <imagedata align="left" fileref="boot-manager-flowchart.png"
 451                          scalefit="1" />
 452             </imageobject>
 453           </mediaobject>
 454         </figure></para>
 455
 456       <para></para>
 457     </section>
 458
 459     <section>
 460       <title>Example Execution Session</title>
 461
 462       <para>Below is one example session of the BootManager, for a new node
 463       being installed then booted.</para>
 464
 465       <para><figure>
 466           <title>Example Execution Session</title>
 467
 468           <mediaobject>
 469             <imageobject>
 470               <imagedata align="left" fileref="bootmanager-sequence.png"
 471                          scalefit="1" />
 472             </imageobject>
 473           </mediaobject>
 474         </figure></para>
 475
 476       <para></para>
 477     </section>
 478
 479     <section>
 480       <title>Boot CD Environment</title>
 481
 482       <para>The BootManager needs to be able to operate under all currently
 483       supported boot cds. The new 3.0 cd contains software the current 2.x cds
 484       do not contain, including the Logical Volume Manager (LVM) client tools,
 485       RPM, and YUM, among other packages. Given this requirement, the boot cd
 486       will need to download as necessary the extra support files it needs to
 487       run. Depending on the size of these files, they may only be downloaded
 488       by specific steps in the flow chart in figure 1, and thus are not
 489       mentioned.</para>
 490
 491       <para>See the PlanetLab BootCD Documentation for more information about
 492       the current, 3.x boot cds, how they are build, and what they provide to
 493       the BootManager.</para>
 494     </section>
 495
 496     <section>
 497       <title>Node Configuration Files</title>
 498
 499       <para>To remain compatible with 2.x boot cds, the format and existing
 500       contents of the configuration files for the nodes will not change. There
 501       will be, however, the addition of three fields:</para>
 502
 503       <orderedlist>
 504         <listitem>
 505           <para>NET_DEVICE</para>
 506
 507           <para>If present, use the device with the specified mac address to
 508           contact the MA. The network on this device will be setup. If not
 509           present, the device represented by 'eth0' will be used.</para>
 510         </listitem>
 511
 512         <listitem>
 513           <para>NODE_KEY</para>
 514
 515           <para>The unique, per-node key to be used during authentication and
 516           identity verification. This is a fixed length, random value that is
 517           only known to the node and the MA database.</para>
 518         </listitem>
 519
 520         <listitem>
 521           <para>NODE_ID</para>
 522
 523           <para>The MA assigned node identifier.</para>
 524         </listitem>
 525       </orderedlist>
 526
 527       <para>An example of a configuration file for a dhcp networked
 528       machine:</para>
 529
 530       <programlisting>IP_METHOD="dhcp"
 531 HOST_NAME="planetlab-1"
 532 DOMAIN_NAME="cs.princeton.edu"
 533 NET_DEVICE="00:06:5B:EC:33:BB"
 534 NODE_KEY="79efbe871722771675de604a227db8386bc6ef482a4b74"
 535 NODE_ID="121"</programlisting>
 536
 537       <para>An example of a configuration file for the same machine, only with
 538       a statically assigned network address:</para>
 539
 540       <programlisting>IP_METHOD="static"
 541 IP_ADDRESS="128.112.139.71"
 542 IP_GATEWAY="128.112.139.65"
 543 IP_NETMASK="255.255.255.192"
 544 IP_NETADDR="128.112.139.127"
 545 IP_BROADCASTADDR="128.112.139.127"
 546 IP_DNS1="128.112.136.10"
 547 IP_DNS2="128.112.136.12"
 548 HOST_NAME="planetlab-1"
 549 DOMAIN_NAME="cs.princeton.edu"
 550 NET_DEVICE="00:06:5B:EC:33:BB"
 551 NODE_KEY="79efbe871722771675de604a227db8386bc6ef482a4b74"
 552 NODE_ID="121"</programlisting>
 553
 554       <para>Existing 2.x boot cds will look for the configuration files only
 555       on a floppy disk, and the file must be named 'planet.cnf'. The new 3.x
 556       boot cds, however, will initially look for a file named 'plnode.txt' on
 557       either a floppy disk, or burned onto the cd itself. Alternatively, it
 558       will fall back to looking for the original file name, 'planet.cnf'. This
 559       initial file reading is performed by the boot cd itself to bring the
 560       nodes network online, so it can download and execute the
 561       BootManager.</para>
 562
 563       <para>However, the BootManager will also need to identify the location
 564       of and read in the file, so it can get the extra fields not initially
 565       used to bring the network online (primarily node_key and node_id). Below
 566       is the search order that the BootManager will use to locate a
 567       file.</para>
 568
 569       <para>Configuration file location search order:<informaltable>
 570           <tgroup cols="6">
 571             <tbody>
 572               <row>
 573                 <entry>File name</entry>
 574
 575                 <entry>Floppy drive</entry>
 576
 577                 <entry>Flash devices</entry>
 578
 579                 <entry>Root file system, in /</entry>
 580
 581                 <entry>CDRom, in /usr/boot</entry>
 582
 583                 <entry>CDRom, in /usr</entry>
 584               </row>
 585
 586               <row>
 587                 <entry>plode.txt</entry>
 588
 589                 <entry>1</entry>
 590
 591                 <entry>2</entry>
 592
 593                 <entry>4</entry>
 594
 595                 <entry>5</entry>
 596
 597                 <entry>6</entry>
 598               </row>
 599
 600               <row>
 601                 <entry>planet.cnf</entry>
 602
 603                 <entry>3</entry>
 604
 605                 <entry></entry>
 606
 607                 <entry></entry>
 608
 609                 <entry></entry>
 610
 611                 <entry></entry>
 612               </row>
 613             </tbody>
 614           </tgroup>
 615         </informaltable></para>
 616     </section>
 617
 618     <section>
 619       <title>BootManager Configuration</title>
 620
 621       <para>All run time configuration options for the BootManager exist in a
 622       single file located at source/configuration. These values are described
 623       below. These values cannot be changed on the fly - they must be changed
 624       and a new BootManager package built and signed.</para>
 625
 626       <itemizedlist>
 627         <listitem>
 628           <para><literal>VERSION</literal></para>
 629
 630           <para>The current BootManager version. During install, written out
 631           to /etc/planetlab/install_version</para>
 632         </listitem>
 633
 634         <listitem>
 635           <para><literal>BOOT_API_SERVER</literal></para>
 636
 637           <para>The full URL of the API server to contact for authenticated
 638           operations.</para>
 639         </listitem>
 640
 641         <listitem>
 642           <para><literal>TEMP_PATH</literal></para>
 643
 644           <para>A writable path on the boot cd we can use for temporary
 645           storage of files.</para>
 646         </listitem>
 647
 648         <listitem>
 649           <para><literal>SYSIMG_PATH</literal></para>
 650
 651           <para>The path were we will mount the node logical volumes during
 652           any step that requires access to the disks.</para>
 653         </listitem>
 654
 655         <listitem>
 656           <para>CACERT_PATH</para>
 657
 658           <para>Variable not used anymore.</para>
 659         </listitem>
 660
 661         <listitem>
 662           <para><literal>NONCE_FILE</literal></para>
 663
 664           <para>Variable not used anymore.</para>
 665         </listitem>
 666
 667         <listitem>
 668           <para><literal>PLCONF_DIR</literal></para>
 669
 670           <para>The path that PlanetLab node configuration files will be
 671           created in during install. This should not be changed from
 672           /etc/planetlab, as this path is assumed in other PlanetLab
 673           components.</para>
 674         </listitem>
 675
 676         <listitem>
 677           <para><literal>SUPPORT_FILE_DIR</literal></para>
 678
 679           <para>A path on the boot server where per-step additional files may
 680           be located. For example, the packages that include the tools to
 681           allow older 2.x version boot cds to partition disks with LVM.</para>
 682         </listitem>
 683
 684         <listitem>
 685           <para><literal>ROOT_SIZE</literal></para>
 686
 687           <para>During install, this sets the size of the node root partition.
 688           It must be large enough to house all the node operational software.
 689           It does not store any user/slice files. Include 'G' suffix in this
 690           value, indicating gigabytes.</para>
 691         </listitem>
 692
 693         <listitem>
 694           <para><literal>SWAP_SIZE</literal></para>
 695
 696           <para>How much swap to configure the node with during install.
 697           Include 'G' suffix in this value, indicating gigabytes.</para>
 698         </listitem>
 699
 700         <listitem>
 701           <para><literal>SKIP_HARDWARE_REQUIREMENT_CHECK</literal></para>
 702
 703           <para>Whether or not to skip any of the hardware requirement checks,
 704           including total disk and memory size constraints.</para>
 705         </listitem>
 706
 707         <listitem>
 708           <para><literal>MINIMUM_MEMORY</literal></para>
 709
 710           <para>How much memory is required by a running PlanetLab node. If a
 711           machine contains less physical memory than this value, the install
 712           will not proceed.</para>
 713         </listitem>
 714
 715         <listitem>
 716           <para><literal>MINIMUM_DISK_SIZE</literal></para>
 717
 718           <para>The size of the small disk we are willing to attempt to use
 719           during the install, in gigabytes. Do not include any
 720           suffixes.</para>
 721         </listitem>
 722
 723         <listitem>
 724           <para><literal>TOTAL_MINIMUM_DISK_SIZE</literal></para>
 725
 726           <para>The size of all usable disks must be at least this sizse, in
 727           gigabytes. Do not include any suffixes.</para>
 728         </listitem>
 729
 730         <listitem>
 731           <para><literal>INSTALL_LANGS</literal></para>
 732
 733           <para>Which language support to install. This value is used by RPM,
 734           and is used in writting /etc/rpm/macros before any RPMs are
 735           installed.</para>
 736         </listitem>
 737
 738         <listitem>
 739           <para><literal>NUM_AUTH_FAILURES_BEFORE_DEBUG</literal></para>
 740
 741           <para>How many authentication failures the BootManager is willing to
 742           except for any set of calls, before stopping and putting the node
 743           into a debug mode.</para>
 744         </listitem>
 745       </itemizedlist>
 746     </section>
 747
 748     <section>
 749       <title>Installer Hardware Detection</title>
 750
 751       <para>When a node is being installed, the BootManager must identify
 752       which hardware the machine has that is applicable to a running node, and
 753       configure the node properly so it can boot properly post-install. The
 754       general procedure for doing so is outline in this section. It is
 755       implemented in the <filename>source/systeminfo.py</filename>
 756       file.</para>
 757
 758       <para>The process for identifying which kernel module needs to be load
 759       is:</para>
 760
 761       <orderedlist>
 762         <listitem>
 763           <para>Create a lookup table of all modules, and which PCI ids
 764           coorespond to this module.</para>
 765         </listitem>
 766
 767         <listitem>
 768           <para>For each PCI device on the system, lookup its module in the
 769           first table.</para>
 770         </listitem>
 771
 772         <listitem>
 773           <para>If a module is found, put in into one of two categories of
 774           modules, either network module or scsi module, based on the PCI
 775           device class.</para>
 776         </listitem>
 777
 778         <listitem>
 779           <para>For each network module, write out an 'eth&lt;index&gt;' entry
 780           in the modprobe.conf configuration file.</para>
 781         </listitem>
 782
 783         <listitem>
 784           <para>For each scsi module, write out a
 785           'scsi_hostadapter&lt;index&gt;' entry in the modprobe.conf
 786           configuration file.</para>
 787         </listitem>
 788       </orderedlist>
 789
 790       <para>This process is fairly straight forward, and is simplified by the
 791       fact that we currently do not need support for USB, sound, or video
 792       devices when the node is fully running. The boot cd itself uses a
 793       similar process, but includes USB devices. Consult the boot cd technical
 794       documentation for more information.</para>
 795
 796       <para>The creation of the PCI id to kernel module table lookup uses
 797       three different sources of information, and merges them together into a
 798       single table for easier lookups. With these three sources of
 799       information, a fairly comprehensive lookup table can be generated for
 800       the devices that PlanetLab nodes need to have configured. They
 801       include:</para>
 802
 803       <orderedlist>
 804         <listitem>
 805           <para>The installed <filename>/usr/share/hwdata/pcitable
 806           </filename>file</para>
 807
 808           <para>Created at the time the hwdata rpm was built, this file
 809           contains mappings of PCI ids to devices for a large number of
 810           devices. It is not necessarily complete, and doesn't take into
 811           account the modules that are actually available by the built
 812           PlanetLab kernel, which is a subset of the full set available
 813           (again, PlanetLab nodes do not have a use for network or video
 814           drivers, and thus are not typically built).</para>
 815         </listitem>
 816
 817         <listitem>
 818           <para>From the built kernel, the <filename>modules.pcimap</filename>
 819           from the <filename>/lib/modules/&lt;kernelversion&gt;/</filename>
 820           directory.</para>
 821
 822           <para>This file is generated at the time the kernel is installed,
 823           and pulls the PCI ids out of each module, for the modules list they
 824           devices they support. Not all modules list all devices they sort,
 825           and some contain wild cards (that match any device of a single
 826           manufacturer).</para>
 827         </listitem>
 828
 829         <listitem>
 830           <para>From the built kernel, the <filename>modules.dep</filename>
 831           from the <filename>/lib/modules/&lt;kernelversion&gt;/</filename>
 832           directory.</para>
 833
 834           <para>This file is also generated at the time the kernel is
 835           installed, but lists the dependencies between various modules. It is
 836           used to generate a list of modules that are actually
 837           available.</para>
 838         </listitem>
 839       </orderedlist>
 840
 841       <para>It should be noted here that SATA (Serial ATA) devices have been
 842       known to exist with both a PCI SCSI device class, and with a PCI IDE
 843       device class. Under linux 2.6 kernels, all SATA modules need to be
 844       listed in modprobe.conf under 'scsi_hostadapter' lines. This case is
 845       handled in the hardware loading scripts by making the assumption that if
 846       an IDE device matches a loadable module, it should be put in the
 847       modprobe.conf file, as 'real' IDE drivers are all currently built into
 848       the kernel, and do not need to be loaded. SATA devices that have a PCI
 849       SCSI device class are easily identified.</para>
 850
 851       <para>It is enssential that the modprobe.conf configuration file contain
 852       the correct drivers for the disks on the system, if they are present, as
 853       during kernel installation the creation of the initrd (initial ramdisk)
 854       which is responsible for booting the system uses this file to identify
 855       which drivers to include in it. A failure to do this typically results
 856       in an kernel panic at boot with a 'no init found' message.</para>
 857     </section>
 858   </section>
 859
 860   <section>
 861     <title>Backward Compatibility</title>
 862
 863     <para>This section only applies to those interested in sections of the
 864     BootManager that exist for backward compatibility with nodes not
 865     containing the NODE_KEY. This does not affect any nodes added to the
 866     system after deployment of the BootManager.</para>
 867
 868     <para>Given the large number of nodes in PlanetLab, and the lack of direct
 869     physical access to them, the process of updating all configuration files
 870     to include the new NODE_ID and NODE_KEY will take a fairly significant
 871     amount of time. Rather than delay deployment of the BootManager until all
 872     machines are updated, alternative methods for aquiring these values is
 873     used for these nodes.</para>
 874
 875     <para>First, the NODE_ID value. For any machine already part of PlanetLab,
 876     there exists a record of its IP address and MAC address in PlanetLab
 877     central. To get the NODE_ID value, if it is not located in the
 878     configuration file, the BootManager uses a standard HTTP POST request to a
 879     known php page on the boot server, sending the IP and MAC address of the
 880     node. This php page queries the MA database (by using a PHP page, not
 881     through the MA API), and returns a NODE_ID if the node is part of
 882     PlanetLab, -1 otherwise.</para>
 883
 884     <para>Second, the NODE_KEY value. All Boot CDs currently in use, at the
 885     time they request a script from the MA to run, send in the request a
 886     randomly generated value called a boot_nonce, usually 32 bytes or larger.
 887     During normal BootManager operation, this value is ignored. However, in
 888     the absense of a node key, we can use this value. Although it is not as
 889     secure as a typical node key (because it is not distributed through
 890     external mechanisms, but is generated by the node itself), it can be used
 891     if we validate that the IP address of the node making the request matches
 892     the MA record. This means that nodes behind firewalls can no longer be
 893     allowed in this situation.</para>
 894   </section>
 895 </article>