From b4d2829e5372808ce95f705ffe4534108d737284 Mon Sep 17 00:00:00 2001 From: Aaron Klingaman Date: Wed, 16 Nov 2005 19:13:43 +0000 Subject: [PATCH] update to include where the source is, and misc. updates to match the implementation --- documentation/boot-manager-tech-doc.xml | 132 +++++++++++++++--------- 1 file changed, 84 insertions(+), 48 deletions(-) diff --git a/documentation/boot-manager-tech-doc.xml b/documentation/boot-manager-tech-doc.xml index 592184a..c1a3380 100644 --- a/documentation/boot-manager-tech-doc.xml +++ b/documentation/boot-manager-tech-doc.xml @@ -41,6 +41,19 @@ Updated post implementation and deployment. + + + 1.2 + + November 16, 2005 + + AK + + + Add section on where source code is, and other updates to make + it consistent with implementation. + + @@ -57,12 +70,18 @@ - A package to be run in the boot cd environment on nodes + An API authentication mechanism used exclusively by the + BootManager, for the above API calls - An appropriate user interface allowing administrators to add - nodes and create node configuration files + A package to be run in the boot cd environment on nodes + containing core logic + + + + A user interface allowing authorized users to add and manage + nodes and create node/BootManager configuration files @@ -72,12 +91,22 @@ state. Only the necessary script for the current state would be downloaded, and 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. All state based logic for - the node boot, install, debug, and reconfigure operations are contained in - one place; there is no longer any boot state specific logic at PLC. + intention with the new BootManager system is to send the same script back + for all nodes (consisting of the core BootManager code), 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. All state based logic for the node boot, install, debug, and + reconfigure operations are contained in one place; there is no longer any + boot state specific logic at PLC. + + +
+ Soure Code + + All BootManager source code is located in the repository + 'bootmanager' on the PlanetLab CVS system. For information on how to + access CVS, consult the PlanetLab website. Unless otherwise noted, all + file references refer to this repository.
@@ -93,7 +122,7 @@ Authentication As is done with other PLC API calls, the first parameter to all - Boot Manager related calls will be an authentication structure, + BootManager related calls will be an authentication structure, consisting of these named fields: @@ -122,8 +151,8 @@ The authentication string, depending on method. For the 'hmac' method, a hash for the call using the HMAC algorithm, made from the - parameters of the call the key contained on the configuration - file. + parameters of the call the key contained on the configuration file. + For specifics on how this is created, see below. @@ -157,10 +186,16 @@ - Prepend the string with the method name. + Prepend the string with the method name and [, and append + ]. + The implementation of this algorithm is in the function + serialize_params in the file source/BootAPI.py. The same algorithm is + located in the 'plc_api' repository, in the function serialize_params in + the file PLC/Auth.py. + The resultant string is fed into the HMAC algorithm with the node key, and the resultant hash value is used in the authentication structure. @@ -179,17 +214,21 @@ could be sent directly to PLC, assuming the connection is made to an HTTPS server with a third party signed SSL certificate. - - + + Athough calls are done over SSL, they use the Python class + libary xmlrpclib, which does not do SSL certificate + verification. + +
PLC API Calls Full, up to date technical documentation of these functions can be - found in the PlanetLab API documentation. They are listed here for - completeness. + found in the PlanetLab Central API documentation. They are listed here + for completeness. @@ -222,13 +261,6 @@ and optionally include the site PIs, technical contacts, and PlanetLab Support. - - - BootUpdateNodeHardware( authentication, pci_entries ) - - Send the set of hardware this node has and update the record - at PLC. -
@@ -242,7 +274,8 @@ - Installing the node operating system + Configuring node hardware and installing the PlanetLab operating + system @@ -256,7 +289,8 @@ - Booting an already installed node + Booting an already installed node into the PlanetLab operating + system @@ -308,7 +342,8 @@ Flow Chart Below is a high level flow chart of the boot manager, from the - time it is executed to when it exits. + time it is executed to when it exits. This core state machine is located + in source/BootManager.py.
Boot Manager Flow Chart @@ -333,6 +368,10 @@ 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. + + See the PlanetLab BootCD Documentation for more information about + the current, 3.x boot cds, how they are build, and what they provide to + the BootManager.
@@ -404,8 +443,9 @@ NODE_ID="121" However, the Boot Manager will also need to identify the location of and read in the file, so it can get the extra fields not initially - used to bring the network online (node_key and node_id). Below is the - search order that the boot manager will use to locate a file. + used to bring the network online (primarily node_key and node_id). Below + is the search order that the BootManager will use to locate a + file. Configuration file location search order: @@ -448,8 +488,6 @@ NODE_ID="121" - -
@@ -540,7 +578,7 @@ NODE_ID="121" BootManager Configuration All run time configuration options for the BootManager exist in a - single file named 'configuration'. These values are described + single file located at source/configuration. These values are described below. @@ -551,13 +589,6 @@ NODE_ID="121" /etc/planetlab/install_version - - BOOT_API_SERVER - - The full url of the Boot API server to contact and make API - calls against. - - TEMP_PATH @@ -572,20 +603,24 @@ NODE_ID="121" step that requires access to the disks. + + CACERT_PATH + + Variable not used anymore. + + NONCE_FILE - The location of the nonce value that is sent to PLC when the - initial script to run is requested. Used only as a replace for - node_key when one does not exist (see Backward Compatibiltiy for more - information). + Variable not used anymore. PLCONF_DIR The path that PlanetLab node configuration files will be created - in during install + in during install. This should not be changed from /etc/planetlab, as + this path is assumed in other PlanetLab components. @@ -666,7 +701,7 @@ NODE_ID="121" hardware the machine has that is applicable to a running node, and configure the node properly so it can boot properly post-install. The general procedure for doing so is outline in this section. It is - implemented in the systeminfo.py file. + implemented in the source/systeminfo.py file. The process for identifying which kernel module needs to be load is: @@ -800,9 +835,10 @@ NODE_ID="121"
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. + Below are common scenarios that the BootManager might encounter that + would exist outside of the documented procedures for handling nodes. A + full description of how they will be handled by the BootManager follows + each. -- 2.43.0