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 14, 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 Mangaer (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   </section>
 272
 273   <section>
 274     <title>User Interface for Node Management</title>
 275
 276     <section>
 277       <title>Adding Nodes</title>
 278
 279       <para>New nodes are added to the system explicitly by either a PI or a
 280       tech contact, either directly through the API calls, or by using the
 281       appropriate interfaces on the website. As nodes are added, only their
 282       hostname and ip address are required to be entered. When the node is
 283       brought online, the records at PLC will be updated with the remaining
 284       information.</para>
 285
 286       <para>After a node is added, the user has the option of creating a
 287       configuration file for that node. This is done automatically, and the
 288       user is prompted to download and save the file. This file contains only
 289       the primary network interface information (necessary to contact PLC),
 290       and the per-node key.</para>
 291
 292       <para>The default boot state of a new node is 'new', which requires the
 293       user to confirm the installation at the node, by typing yes on the
 294       console. If this is not desired, as is the case with nodes in a
 295       colocation site, or for a large number of nodes being setup at the same
 296       time, the administrator can change the node state, after the entry is in
 297       the PLC records, from 'new' to 'reinstall'. This will bypass the
 298       confirmation screen, and proceed directly to reinstall the machine (even
 299       if it already had a node installation on it).</para>
 300     </section>
 301
 302     <section>
 303       <title>Updating Node Network Settings</title>
 304
 305       <para>If the primary node network address must be updated, if the node
 306       is moved to a new network for example, then two steps must be performed
 307       to successfully complete the move:</para>
 308
 309       <orderedlist>
 310         <listitem>
 311           <para>The node network will need to be updated at PLC, either
 312           through the API directly or via the website.</para>
 313         </listitem>
 314
 315         <listitem>
 316           <para>Either the floppy file regenerated and put into the machine,
 317           or, update the existing floppy to match the new settings.</para>
 318         </listitem>
 319       </orderedlist>
 320
 321       <para>If the node ip address on the floppy does not mach the record at
 322       PLC, then the node will not boot until they do match. The intention here
 323       is to prevent a malicious user from taking the floppy disk, altering the
 324       network settings, and trying to bring up a new machine with the new
 325       settings.</para>
 326
 327       <para>On the other hand, if a non-primary network address needs to be
 328       updated, then simply updating the records at PLC will suffice. The boot
 329       manager, at next restart, will reconfigure the machine to match the PLC
 330       records.</para>
 331     </section>
 332
 333     <section>
 334       <title>Removing Nodes</title>
 335
 336       <para>Nodes are removed from the system by:</para>
 337
 338       <orderedlist>
 339         <listitem>
 340           <para>Deleting the record of the node at PLC</para>
 341         </listitem>
 342
 343         <listitem>
 344           <para>Shutting down the machine.</para>
 345         </listitem>
 346       </orderedlist>
 347
 348       <para>Once this is done, even if the machine attempts to come back
 349       online, it cannot be authorized with PLC and will not boot.</para>
 350     </section>
 351   </section>
 352
 353   <section>
 354     <title>Common Scenarios</title>
 355
 356     <para>Below are common scenarios that the boot manager might encounter
 357     that would exist outside of the documented procedures for handling nodes.
 358     A full description of how they will be handled follows each.</para>
 359
 360     <itemizedlist>
 361       <listitem>
 362         <para>A configuration file from previously installed and functioning
 363         node is copied or moved to another machine, and the networks settings
 364         are updated on it (but the key is left the same).</para>
 365
 366         <para>Since the authentication for a node consists of matching not
 367         only the node id, but the primary node ip, this step will fail, and
 368         the node will not allow the boot manager to be run. Instead, the new
 369         node must be created at PLC first, and a network configuration file
 370         for it must be generated, with its own node key.</para>
 371       </listitem>
 372
 373       <listitem>
 374         <para>After a node is installed and running, the administrators
 375         mistakenly remove the cd and disk.</para>
 376
 377         <para>The node installer clears all boot records from the disk, so the
 378         node will not boot. Typically, the bios will report no operating
 379         system.</para>
 380       </listitem>
 381     </itemizedlist>
 382   </section>
 383
 384   <bibliography>
 385     <biblioentry>
 386       <abbrev>1</abbrev>
 387
 388       <title>The PlanetLab Boot Manager</title>
 389
 390       <date>January 14, 2005</date>
 391
 392       <author>
 393         <firstname>Aaron</firstname>
 394
 395         <surname>Klingaman</surname>
 396       </author>
 397     </biblioentry>
 398   </bibliography>
 399 </article>