From 829072c022ba9f6180dfddae59df8871d7d37e06 Mon Sep 17 00:00:00 2001 From: Aaron Klingaman Date: Mon, 14 Mar 2005 22:57:19 +0000 Subject: [PATCH] add reference to pdn, describe boot states, expand upon authentication --- documentation/boot-manager-tech-doc.xml | 369 ++++++++++++++++-------- 1 file changed, 254 insertions(+), 115 deletions(-) diff --git a/documentation/boot-manager-tech-doc.xml b/documentation/boot-manager-tech-doc.xml index 554ce8f..c4495a3 100644 --- a/documentation/boot-manager-tech-doc.xml +++ b/documentation/boot-manager-tech-doc.xml @@ -21,7 +21,7 @@ 1.0 - March 10, 2005 + March 14, 2005 AK @@ -37,96 +37,135 @@ The entire Boot Manager system consists of several components that are designed to work together to provide the functionality outline in the - Boot Manager PlanetLab Design Note. These consist of: - - - - A set of API calls available at PlanetLab Central - - - - A package to be run in the boot cd environment on nodes - - - - A set of API calls and an appropriate user interface allowing - administrators to create node configuration files - - + Boot Manager PDN 1. These consist of: + + + + A set of API calls available at PlanetLab Central + + + + A package to be run in the boot cd environment on nodes + + + + An appropriate user interface allowing administrators to create + node configuration files + + + + The previous implementation of the software responsible for + installing and booting nodes consisted of a set of boot scripts that the + boot cd would run, depending on the node's current boot state. The logic + behind which script the node was sent to the node existed on the boot + server in the form of PHP scripts. However, the intention with the new + Boot Manager system is to send the same boot manager back for all nodes, + in all boot states, each time the node starts. Then, the boot manager will + run and detiremine which operations to perform on the node, based on the + current boot state. There is no longer any boot state specific logic at + PLC.
API Calls + Most of the API calls available as part of the PlanetLab Central API + are intended to be run by users, and thus authentication for these calls + is done with the user's email address and password. However, the API calls + described below will be run by the nodes themselves, so a new + authentication mechanism is required. +
Authentication - The Boot PLC API calls handle authentication in a different manner - that other API calls, which typically require a username and password, - and are called by users of the system, not nodes. + As is done with other PLC API calls, the first parameter to all + Boot Manager related calls will be an authentication structure, + consisting of these named fields: + + + + method + + The authentication method, only 'hmac' is currently + supported + + + + node_id - The authentication structure consists of two named fields: + The node id, contained on the configuration file. + - - - method + + node_ip - The authentication method, only hmac is currently - supported - + The node's primary IP address. This will be checked with the + node_id against PLC records. + - - node_id + + value - The node id, contained on the configuration file. - + The authentication string, depending on method. For the 'hmac' + method, a hash for the call, made from the parameters of the call + the key contained on the configuration file. + + - - value + Authentication is succesful if PLC is able to create the same hash + from the values usings its own copy of the node key. If the hash values + to not match, then either the keys do not match or the values of the + call were modified in transmision and the node cannot be + authenticated. - An hmac hash for the call, made from the parameters of the - call the key contained on the configuration file. - - + TODO: add specifics on how the hash value is produced from the + parameters in the API call.
PLC API Calls - For full documentation of these functions can be found in the - PlanetLab API documentation. + Full technical documentation of these functions can be found in + the PlanetLab API documentation. - - - BootUpdateNode( authentication, update_values ) + + + BootUpdateNode( authentication, update_values ) - Update a node record, currenly only allowing the boot state - to change. - + Update a node record, currenly only allowing the boot state to + change. + - - BootCheckAuthentication( authentication ) + + BootCheckAuthentication( authentication ) - Simply check to see if the node is recognized by the system - and is authorized - + Simply check to see if the node is recognized by the system + and is authorized + - - BootGetNodeDetails( authentication ) + + BootGetNodeDetails( authentication ) - Return details about a node, including its state, what - networks the PLC database has configured for the node. - + Return details about a node, including its state, what + networks the PLC database has configured for the node. + + + + BootNotifyOwners( authentication, message, include_pi, + include_tech, include_support ) + + Notify someone about an event that happened on the machine, + and optionally include the site PIs, technical contacts, and + PlanetLab Support + - - BootNotifyOwners( authentication, message, include_pi, - include_tech, include_support ) + + BootUpdateNodeHardware( authentication, pci_entries ) - Notify someone about an event that happened on the machine, - and optionally include the site PIs, technical contacts, and - PlanetLab Support - - + Send the set of hardware this node has and update the record + at PLC. + +
@@ -134,50 +173,105 @@ Core Package The Boot Manager core package, which is run on the nodes and - contacts the Boot API as necessary, is responsible for the follow major - functional units: + contacts the Boot API as necessary, is responsible for the following major + functional units: + + + + Installing nodes with alpina, the PlanetLab installer + + + + Putting a node into a debug state so administrators can track + down problems + + + + Reconfiguring an already installed node to reflect new hardware, + or changed network settings + + + + Booting an already installed node + + + +
+ Boot States + + Each node always has one of four possible boot states. + + - Installing nodes with alpina, the PlanetLab installer + 'new' + + The boot state cooresponds to a new node that has not yet been + installed, but record of it does exist. When the boot manager + starts, and the node is in this state, the user is prompted to + continue with the installation. The intention here is to prevent a + non-PlanetLab machine (like a user's desktop machine) from becoming + inadvertantly wiped and installed with the PlanetLab node + software. - Putting a node into a debug state + 'reinstall' + + In this state, a node will reinstall the node software, + erasing anything that might have been on the disk before. - Reconfiguring an already installed node to reflect new - hardware, or changed network settings + 'boot' + + This state cooresponds with nodes that have sucessfully + installed, and can be chain booted to the runtime node + kernel. - Booting an already installed node + 'debug' + + Regardless of whether or not a machine has been installed, + this state sets up a node to be debugged by administrators. - + +
- Below is a high level flow chart of the boot manager, from the time - it is executed to when it exits. +
+ Flow Chart -
- Boot Manager Flow Chart + Below is a high level flow chart of the boot manager, from the + time it is executed to when it exits. - - - - - -
-
+
+ Boot Manager Flow Chart -
- User Interface Items + + + + + +
+ - Nodes are now added to the system by administrators of the site, and - technical contacts. +
+ Boot CD Environment + + The boot manager needs to be able to operate under all currently + supported boot cds. The new 3.0 cd contains software the current 2.x cds + do not contain, including the Logical Volume Mangaer (LVM) client tools, + RPM, and YUM, among other packages. Given this requirement, the boot cd + will need to download as necessary the extra support files it needs to + run. Depending on the size of these files, they may only be downloaded + by specific steps in the flow chart in figure 1, and thus are not + mentioned. +
- Node Management + User Interface for Node Management
Adding Nodes @@ -212,21 +306,23 @@ is moved to a new network for example, then two steps must be performed to successfully complete the move: - - - The node network will need to be updated at PLC, either - through the API directly or via the website. - - - - Either the floppy file regenerated and put into the machine, - or, update the existing floppy to match the new settings. - - If the node ip address on the floppy does not mach the - record at PLC, then the node will not boot until they do match. The - intention here is to prevent a malicious user from taking the floppy - disk, altering the network settings, and trying to bring up a new - machine with the new settings. + + + The node network will need to be updated at PLC, either + through the API directly or via the website. + + + + Either the floppy file regenerated and put into the machine, + or, update the existing floppy to match the new settings. + + + + If the node ip address on the floppy does not mach the record at + PLC, then the node will not boot until they do match. The intention here + is to prevent a malicious user from taking the floppy disk, altering the + network settings, and trying to bring up a new machine with the new + settings. On the other hand, if a non-primary network address needs to be updated, then simply updating the records at PLC will suffice. The boot @@ -239,22 +335,65 @@ Nodes are removed from the system by: - - - Deleting the record of the node at PLC - + + + Deleting the record of the node at PLC + - - Shutting down the machine. - - Once this is done, even if the machine attempts to come - back online, it cannot be authorized with PLC and will not boot. + + Shutting down the machine. + + + + Once this is done, even if the machine attempts to come back + online, it cannot be authorized with PLC and will not boot.
- - - + Common Scenarios + + Below are common scenarios that the boot manager might encounter + that would exist outside of the documented procedures for handling nodes. + A full description of how they will be handled follows each. + + + + A configuration file from previously installed and functioning + node is copied or moved to another machine, and the networks settings + are updated on it (but the key is left the same). + + Since the authentication for a node consists of matching not + only the node id, but the primary node ip, this step will fail, and + the node will not allow the boot manager to be run. Instead, the new + node must be created at PLC first, and a network configuration file + for it must be generated, with its own node key. + + + + After a node is installed and running, the administrators + mistakenly remove the cd and disk. + + The node installer clears all boot records from the disk, so the + node will not boot. Typically, the bios will report no operating + system. + +
+ + + + 1 + + The PlanetLab Boot Manager + + January 14, 2005 + + + Aaron + + Klingaman + + + \ No newline at end of file -- 2.43.0