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>Boot Manager Technical Documentation</title>
   7
   8     <author>
   9       <firstname>Aaron</firstname>
  10
  11       <surname>Klingaman</surname>
  12
  13       <email>alk@cs.princeton.edu</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     </revhistory>
  33   </articleinfo>
  34
  35   <section>
  36     <title>Components</title>
  37
  38     <para>The entire Boot Manager system consists of several components that
  39     are designed to work together to provide the functionality outline in the
  40     Boot Manager PDN <citation>1</citation>. These consist of:</para>
  41
  42     <itemizedlist>
  43       <listitem>
  44         <para>A set of API calls available at PlanetLab Central</para>
  45       </listitem>
  46
  47       <listitem>
  48         <para>A package to be run in the boot cd environment on nodes</para>
  49       </listitem>
  50
  51       <listitem>
  52         <para>An appropriate user interface allowing administrators to create
  53         node configuration files</para>
  54       </listitem>
  55     </itemizedlist>
  56
  57     <para>The previous implementation of the software responsible for
  58     installing and booting nodes consisted of a set of boot scripts that the
  59     boot cd would run, depending on the node's current boot state. The logic
  60     behind which script the node was sent to the node existed on the boot
  61     server in the form of PHP scripts. However, the intention with the new
  62     Boot Manager system is to send the same boot manager back for all nodes,
  63     in all boot states, each time the node starts. Then, the boot manager will
  64     run and detiremine which operations to perform on the node, based on the
  65     current boot state. There is no longer any boot state specific logic at
  66     PLC.</para>
  67   </section>
  68
  69   <section>
  70     <title>API Calls</title>
  71
  72     <para>Most of the API calls available as part of the PlanetLab Central API
  73     are intended to be run by users, and thus authentication for these calls
  74     is done with the user's email address and password. However, the API calls
  75     described below will be run by the nodes themselves, so a new
  76     authentication mechanism is required.</para>
  77
  78     <section>
  79       <title>Authentication</title>
  80
  81       <para>As is done with other PLC API calls, the first parameter to all
  82       Boot Manager related calls will be an authentication structure,
  83       consisting of these named fields:</para>
  84
  85       <itemizedlist>
  86         <listitem>
  87           <para>method</para>
  88
  89           <para>The authentication method, only 'hmac' is currently
  90           supported</para>
  91         </listitem>
  92
  93         <listitem>
  94           <para>node_id</para>
  95
  96           <para>The node id, contained on the configuration file.</para>
  97         </listitem>
  98
  99         <listitem>
 100           <para>node_ip</para>
 101
 102           <para>The node's primary IP address. This will be checked with the
 103           node_id against PLC records.</para>
 104         </listitem>
 105
 106         <listitem>
 107           <para>value</para>
 108
 109           <para>The authentication string, depending on method. For the 'hmac'
 110           method, a hash for the call, made from the parameters of the call
 111           the key contained on the configuration file.</para>
 112         </listitem>
 113       </itemizedlist>
 114
 115       <para>Authentication is succesful if PLC is able to create the same hash
 116       from the values usings its own copy of the node key. If the hash values
 117       to not match, then either the keys do not match or the values of the
 118       call were modified in transmision and the node cannot be
 119       authenticated.</para>
 120
 121       <para>TODO: add specifics on how the hash value is produced from the
 122       parameters in the API call.</para>
 123     </section>
 124
 125     <section>
 126       <title>PLC API Calls</title>
 127
 128       <para>Full technical documentation of these functions can be found in
 129       the PlanetLab API documentation.</para>
 130
 131       <itemizedlist>
 132         <listitem>
 133           <para>BootUpdateNode( authentication, update_values )</para>
 134
 135           <para>Update a node record, currenly only allowing the boot state to
 136           change.</para>
 137         </listitem>
 138
 139         <listitem>
 140           <para>BootCheckAuthentication( authentication )</para>
 141
 142           <para>Simply check to see if the node is recognized by the system
 143           and is authorized</para>
 144         </listitem>
 145
 146         <listitem>
 147           <para>BootGetNodeDetails( authentication )</para>
 148
 149           <para>Return details about a node, including its state, what
 150           networks the PLC database has configured for the node.</para>
 151         </listitem>
 152
 153         <listitem>
 154           <para>BootNotifyOwners( authentication, message, include_pi,
 155           include_tech, include_support )</para>
 156
 157           <para>Notify someone about an event that happened on the machine,
 158           and optionally include the site PIs, technical contacts, and
 159           PlanetLab Support</para>
 160         </listitem>
 161
 162         <listitem>
 163           <para>BootUpdateNodeHardware( authentication, pci_entries )</para>
 164
 165           <para>Send the set of hardware this node has and update the record
 166           at PLC.</para>
 167         </listitem>
 168       </itemizedlist>
 169     </section>
 170   </section>
 171
 172   <section>
 173     <title>Core Package</title>
 174
 175     <para>The Boot Manager core package, which is run on the nodes and
 176     contacts the Boot API as necessary, is responsible for the following major
 177     functional units:</para>
 178
 179     <itemizedlist>
 180       <listitem>
 181         <para>Installing nodes with alpina, the PlanetLab installer</para>
 182       </listitem>
 183
 184       <listitem>
 185         <para>Putting a node into a debug state so administrators can track
 186         down problems</para>
 187       </listitem>
 188
 189       <listitem>
 190         <para>Reconfiguring an already installed node to reflect new hardware,
 191         or changed network settings</para>
 192       </listitem>
 193
 194       <listitem>
 195         <para>Booting an already installed node</para>
 196       </listitem>
 197     </itemizedlist>
 198
 199     <section>
 200       <title>Boot States</title>
 201
 202       <para>Each node always has one of four possible boot states.</para>
 203
 204       <orderedlist>
 205         <listitem>
 206           <para>'new'</para>
 207
 208           <para>The boot state cooresponds to a new node that has not yet been
 209           installed, but record of it does exist. When the boot manager
 210           starts, and the node is in this state, the user is prompted to
 211           continue with the installation. The intention here is to prevent a
 212           non-PlanetLab machine (like a user's desktop machine) from becoming
 213           inadvertantly wiped and installed with the PlanetLab node
 214           software.</para>
 215         </listitem>
 216
 217         <listitem>
 218           <para>'reinstall'</para>
 219
 220           <para>In this state, a node will reinstall the node software,
 221           erasing anything that might have been on the disk before.</para>
 222         </listitem>
 223
 224         <listitem>
 225           <para>'boot'</para>
 226
 227           <para>This state cooresponds with nodes that have sucessfully
 228           installed, and can be chain booted to the runtime node
 229           kernel.</para>
 230         </listitem>
 231
 232         <listitem>
 233           <para>'debug'</para>
 234
 235           <para>Regardless of whether or not a machine has been installed,
 236           this state sets up a node to be debugged by administrators.</para>
 237         </listitem>
 238       </orderedlist>
 239     </section>
 240
 241     <section>
 242       <title>Flow Chart</title>
 243
 244       <para>Below is a high level flow chart of the boot manager, from the
 245       time it is executed to when it exits.</para>
 246
 247       <para><figure>
 248           <title>Boot Manager Flow Chart</title>
 249
 250           <mediaobject>
 251             <imageobject>
 252               <imagedata align="left" fileref="boot-manager-flowchart.png"
 253                          scalefit="1" />
 254             </imageobject>
 255           </mediaobject>
 256         </figure></para>
 257     </section>
 258
 259     <section>
 260       <title>Boot CD Environment</title>
 261
 262       <para>The boot manager needs to be able to operate under all currently
 263       supported boot cds. The new 3.0 cd contains software the current 2.x cds
 264       do not contain, including the Logical Volume Manager (LVM) client tools,
 265       RPM, and YUM, among other packages. Given this requirement, the boot cd
 266       will need to download as necessary the extra support files it needs to
 267       run. Depending on the size of these files, they may only be downloaded
 268       by specific steps in the flow chart in figure 1, and thus are not
 269       mentioned.</para>
 270     </section>
 271
 272     <section>
 273       <title>Node Configuration Files</title>
 274
 275       <para>To remain compatible with 2.x boot cds, the format and existing
 276       contents of the configuration files for the nodes will not change. There
 277       will be, however, the addition of three fields:</para>
 278
 279       <orderedlist>
 280         <listitem>
 281           <para>NET_DEVICE</para>
 282
 283           <para>If present, use the device with the specified mac address to
 284           contact PLC. The network on this device will be setup. If not
 285           present, the device represented by 'eth0' will be used.</para>
 286         </listitem>
 287
 288         <listitem>
 289           <para>NODE_KEY</para>
 290
 291           <para>The unique, per-node key to be used during authentication and
 292           identity verification. This is a fixed length, random value that is
 293           only known to the node and PLC.</para>
 294         </listitem>
 295
 296         <listitem>
 297           <para>NODE_ID</para>
 298
 299           <para>The PLC assigned node identifier.</para>
 300         </listitem>
 301       </orderedlist>
 302
 303       <para>Existing 2.x boot cds will look for the configuration files only
 304       on a floppy disk, and the file must be named 'planet.cnf'. The new 3.x
 305       boot cds, however, will initially look for a file named 'plnode.txt' on
 306       either a floppy disk, or burned onto the cd itself. Alternatively, it
 307       will fall back to looking for the original file name,
 308       'planet.cnf'.</para>
 309
 310       <para>An example of a configuration file for a dhcp networked
 311       machine:</para>
 312
 313       <programlisting>IP_METHOD="dhcp"
 314 HOST_NAME="planetlab-1"
 315 DOMAIN_NAME="cs.princeton.edu"
 316 NET_DEVICE="00:06:5B:EC:33:BB"
 317 NODE_KEY="79efbe871722771675de604a227db8386bc6ef482a4b74"
 318 NODE_ID="121"</programlisting>
 319
 320       <para>An example of a configuration file for the same machine, only with
 321       a statically assigned network address:</para>
 322
 323       <programlisting>IP_METHOD="static"
 324 IP_ADDRESS="128.112.139.71"
 325 IP_GATEWAY="128.112.139.65"
 326 IP_NETMASK="255.255.255.192"
 327 IP_NETADDR="128.112.139.127"
 328 IP_BROADCASTADDR="128.112.139.127"
 329 IP_DNS1="128.112.136.10"
 330 IP_DNS2="128.112.136.12"
 331 HOST_NAME="planetlab-1"
 332 DOMAIN_NAME="cs.princeton.edu"
 333 NET_DEVICE="00:06:5B:EC:33:BB"
 334 NODE_KEY="79efbe871722771675de604a227db8386bc6ef482a4b74"
 335 NODE_ID="121"</programlisting>
 336     </section>
 337   </section>
 338
 339   <section>
 340     <title>User Interface for Node Management</title>
 341
 342     <section>
 343       <title>Adding Nodes</title>
 344
 345       <para>New nodes are added to the system explicitly by either a PI or a
 346       tech contact, either directly through the API calls, or by using the
 347       appropriate interfaces on the website. As nodes are added, only their
 348       hostname and ip address are required to be entered. When the node is
 349       brought online, the records at PLC will be updated with the remaining
 350       information.</para>
 351
 352       <para>After a node is added, the user has the option of creating a
 353       configuration file for that node. This is done automatically, and the
 354       user is prompted to download and save the file. This file contains only
 355       the primary network interface information (necessary to contact PLC),
 356       and the per-node key.</para>
 357
 358       <para>The default boot state of a new node is 'new', which requires the
 359       user to confirm the installation at the node, by typing yes on the
 360       console. If this is not desired, as is the case with nodes in a
 361       co-location site, or for a large number of nodes being setup at the same
 362       time, the administrator can change the node state, after the entry is in
 363       the PLC records, from 'new' to 'reinstall'. This will bypass the
 364       confirmation screen, and proceed directly to reinstall the machine (even
 365       if it already had a node installation on it).</para>
 366     </section>
 367
 368     <section>
 369       <title>Updating Node Network Settings</title>
 370
 371       <para>If the primary node network address must be updated, if the node
 372       is moved to a new network for example, then two steps must be performed
 373       to successfully complete the move:</para>
 374
 375       <orderedlist>
 376         <listitem>
 377           <para>The node network will need to be updated at PLC, either
 378           through the API directly or via the website.</para>
 379         </listitem>
 380
 381         <listitem>
 382           <para>Either the floppy file regenerated and put into the machine,
 383           or, update the existing floppy to match the new settings.</para>
 384         </listitem>
 385       </orderedlist>
 386
 387       <para>If the node ip address on the floppy does not Match the record at
 388       PLC, then the node will not boot until they do match. The intention here
 389       is to prevent a malicious user from taking the floppy disk, altering the
 390       network settings, and trying to bring up a new machine with the new
 391       settings.</para>
 392
 393       <para>On the other hand, if a non-primary network address needs to be
 394       updated, then simply updating the records at PLC will suffice. The boot
 395       manager, at next restart, will reconfigure the machine to match the PLC
 396       records.</para>
 397     </section>
 398
 399     <section>
 400       <title>Removing Nodes</title>
 401
 402       <para>Nodes are removed from the system by:</para>
 403
 404       <orderedlist>
 405         <listitem>
 406           <para>Deleting the record of the node at PLC</para>
 407         </listitem>
 408
 409         <listitem>
 410           <para>Shutting down the machine.</para>
 411         </listitem>
 412       </orderedlist>
 413
 414       <para>Once this is done, even if the machine attempts to come back
 415       online, it cannot be authorized with PLC and will not boot.</para>
 416     </section>
 417   </section>
 418
 419   <section>
 420     <title>Common Scenarios</title>
 421
 422     <para>Below are common scenarios that the boot manager might encounter
 423     that would exist outside of the documented procedures for handling nodes.
 424     A full description of how they will be handled follows each.</para>
 425
 426     <itemizedlist>
 427       <listitem>
 428         <para>A configuration file from previously installed and functioning
 429         node is copied or moved to another machine, and the networks settings
 430         are updated on it (but the key is left the same).</para>
 431
 432         <para>Since the authentication for a node consists of matching not
 433         only the node id, but the primary node ip, this step will fail, and
 434         the node will not allow the boot manager to be run. Instead, the new
 435         node must be created at PLC first, and a network configuration file
 436         for it must be generated, with its own node key.</para>
 437       </listitem>
 438
 439       <listitem>
 440         <para>After a node is installed and running, the administrators
 441         mistakenly remove the cd and disk.</para>
 442
 443         <para>The node installer clears all boot records from the disk, so the
 444         node will not boot. Typically, the bios will report no operating
 445         system.</para>
 446       </listitem>
 447     </itemizedlist>
 448   </section>
 449
 450   <bibliography>
 451     <biblioentry>
 452       <abbrev>1</abbrev>
 453
 454       <title>The PlanetLab Boot Manager</title>
 455
 456       <date>January 14, 2005</date>
 457
 458       <author>
 459         <firstname>Aaron</firstname>
 460
 461         <surname>Klingaman</surname>
 462       </author>
 463     </biblioentry>
 464   </bibliography>
 465 </article>