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 10, 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 PlanetLab Design Note. These consist of:</para>
  41
  42     <para><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>A set of API calls and an appropriate user interface allowing
  53           administrators to create node configuration files</para>
  54         </listitem>
  55       </itemizedlist></para>
  56   </section>
  57
  58   <section>
  59     <title>API Calls</title>
  60
  61     <section>
  62       <title>Authentication</title>
  63
  64       <para>The Boot PLC API calls handle authentication in a different manner
  65       that other API calls, which typically require a username and password,
  66       and are called by users of the system, not nodes.</para>
  67
  68       <para>The authentication structure consists of two named fields:</para>
  69
  70       <para><itemizedlist>
  71           <listitem>
  72             <para>method</para>
  73
  74             <para>The authentication method, only hmac is currently
  75             supported</para>
  76           </listitem>
  77
  78           <listitem>
  79             <para>node_id</para>
  80
  81             <para>The node id, contained on the configuration file.</para>
  82           </listitem>
  83
  84           <listitem>
  85             <para>value</para>
  86
  87             <para>An hmac hash for the call, made from the parameters of the
  88             call the key contained on the configuration file.</para>
  89           </listitem>
  90         </itemizedlist></para>
  91     </section>
  92
  93     <section>
  94       <title>PLC API Calls</title>
  95
  96       <para>For full documentation of these functions can be found in the
  97       PlanetLab API documentation.</para>
  98
  99       <para><itemizedlist>
 100           <listitem>
 101             <para>BootUpdateNode( authentication, update_values )</para>
 102
 103             <para>Update a node record, currenly only allowing the boot state
 104             to change.</para>
 105           </listitem>
 106
 107           <listitem>
 108             <para>BootCheckAuthentication( authentication )</para>
 109
 110             <para>Simply check to see if the node is recognized by the system
 111             and is authorized</para>
 112           </listitem>
 113
 114           <listitem>
 115             <para>BootGetNodeDetails( authentication )</para>
 116
 117             <para>Return details about a node, including its state, what
 118             networks the PLC database has configured for the node.</para>
 119           </listitem>
 120
 121           <listitem>
 122             <para>BootNotifyOwners( authentication, message, include_pi,
 123             include_tech, include_support )</para>
 124
 125             <para>Notify someone about an event that happened on the machine,
 126             and optionally include the site PIs, technical contacts, and
 127             PlanetLab Support</para>
 128           </listitem>
 129         </itemizedlist></para>
 130     </section>
 131   </section>
 132
 133   <section>
 134     <title>Core Package</title>
 135
 136     <para>The Boot Manager core package, which is run on the nodes and
 137     contacts the Boot API as necessary, is responsible for the follow major
 138     functional units:<itemizedlist>
 139         <listitem>
 140           <para>Installing nodes with alpina, the PlanetLab installer</para>
 141         </listitem>
 142
 143         <listitem>
 144           <para>Putting a node into a debug state</para>
 145         </listitem>
 146
 147         <listitem>
 148           <para>Reconfiguring an already installed node to reflect new
 149           hardware, or changed network settings</para>
 150         </listitem>
 151
 152         <listitem>
 153           <para>Booting an already installed node</para>
 154         </listitem>
 155       </itemizedlist></para>
 156
 157     <para>Below is a high level flow chart of the boot manager, from the time
 158     it is executed to when it exits.</para>
 159
 160     <para><figure>
 161         <title>Boot Manager Flow Chart</title>
 162
 163         <mediaobject>
 164           <imageobject>
 165             <imagedata align="center" fileref="boot-manager-flow.png"
 166                        scalefit="1" />
 167           </imageobject>
 168         </mediaobject>
 169       </figure></para>
 170   </section>
 171
 172   <section>
 173     <title>User Interface Items</title>
 174
 175     <para>Nodes are now added to the system by administrators of the site, and
 176     technical contacts.</para>
 177   </section>
 178
 179   <section>
 180     <title>Node Management</title>
 181
 182     <section>
 183       <title>Adding Nodes</title>
 184
 185       <para>New nodes are added to the system explicitly by either a PI or a
 186       tech contact, either directly through the API calls, or by using the
 187       appropriate interfaces on the website. As nodes are added, only their
 188       hostname and ip address are required to be entered. When the node is
 189       brought online, the records at PLC will be updated with the remaining
 190       information.</para>
 191
 192       <para>After a node is added, the user has the option of creating a
 193       configuration file for that node. This is done automatically, and the
 194       user is prompted to download and save the file. This file contains only
 195       the primary network interface information (necessary to contact PLC),
 196       and the per-node key.</para>
 197
 198       <para>The default boot state of a new node is 'new', which requires the
 199       user to confirm the installation at the node, by typing yes on the
 200       console. If this is not desired, as is the case with nodes in a
 201       colocation site, or for a large number of nodes being setup at the same
 202       time, the administrator can change the node state, after the entry is in
 203       the PLC records, from 'new' to 'reinstall'. This will bypass the
 204       confirmation screen, and proceed directly to reinstall the machine (even
 205       if it already had a node installation on it).</para>
 206     </section>
 207
 208     <section>
 209       <title>Updating Node Network Settings</title>
 210
 211       <para>If the primary node network address must be updated, if the node
 212       is moved to a new network for example, then two steps must be performed
 213       to successfully complete the move:</para>
 214
 215       <para><orderedlist>
 216           <listitem>
 217             <para>The node network will need to be updated at PLC, either
 218             through the API directly or via the website.</para>
 219           </listitem>
 220
 221           <listitem>
 222             <para>Either the floppy file regenerated and put into the machine,
 223             or, update the existing floppy to match the new settings.</para>
 224           </listitem>
 225         </orderedlist>If the node ip address on the floppy does not mach the
 226       record at PLC, then the node will not boot until they do match. The
 227       intention here is to prevent a malicious user from taking the floppy
 228       disk, altering the network settings, and trying to bring up a new
 229       machine with the new settings.</para>
 230
 231       <para>On the other hand, if a non-primary network address needs to be
 232       updated, then simply updating the records at PLC will suffice. The boot
 233       manager, at next restart, will reconfigure the machine to match the PLC
 234       records.</para>
 235     </section>
 236
 237     <section>
 238       <title>Removing Nodes</title>
 239
 240       <para>Nodes are removed from the system by:</para>
 241
 242       <para><orderedlist>
 243           <listitem>
 244             <para>Deleting the record of the node at PLC</para>
 245           </listitem>
 246
 247           <listitem>
 248             <para>Shutting down the machine.</para>
 249           </listitem>
 250         </orderedlist>Once this is done, even if the machine attempts to come
 251       back online, it cannot be authorized with PLC and will not boot.</para>
 252     </section>
 253   </section>
 254
 255   <section>
 256     <title></title>
 257
 258     <para></para>
 259   </section>
 260 </article>