Author: richter Date: Wed Apr 27 07:41:23 2011 New Revision: 2561 Log: add a help action to the testbed environment and basic documentation run 'pisa-testbed help' for help Added: trunk/tools/testbed/doc/pisa-testbed.1 trunk/tools/testbed/doc/pisa-testbed_config.5 trunk/tools/testbed/doc/pisa-testbed_plugins.1 trunk/tools/testbed/plugins/actions/help/ trunk/tools/testbed/plugins/actions/help/pisa-testbed.1 (contents, props changed) trunk/tools/testbed/plugins/actions/help/pisa-testbed_config.5 (contents, props changed) trunk/tools/testbed/plugins/actions/help/pisa-testbed_plugins.1 (contents, props changed) trunk/tools/testbed/plugins/actions/help/pre_hook Added: trunk/tools/testbed/doc/pisa-testbed.1 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ trunk/tools/testbed/doc/pisa-testbed.1 Wed Apr 27 07:41:23 2011 (r2561) @@ -0,0 +1,43 @@ +.TH pisa-testbed 1 "April 23, 2011" "version 0.1" "USER COMMANDS" +.SH NAME +pisa-testbed \- build and maintain a test network +.SH SYNOPSIS +.B pisa-testbed +NODES ACTION [ACTION_ARGUMENTS] +.SH DESCRIPTION +This program must be run from a valid testbed folder. Such a folder must contain +a config file and a plugins folder. +The config file specifies a set of nodes that make up the network, each node can +have different classes, that are used to decide what to do on a specific action. +This is done with shell code snippets in the plugins folder (run 'pisa-testbed +help config' or 'pisa-testbed help plugins' for more information). +.PP +NODES is a list of the nodes the action is applied on. A class stands for all +nodes containing this class. Preceding the node or class with '-' removes the +corresponding nodes from the list. 'all' selects all nodes. The first word that +is a valid action ends the NODES section, thus neither nodes nor classes may +have the same names as actions. +.PP +ACTION is an action from plugins/actions/. Run 'pisa-testbed help commands' +to list all available actions and 'pisa-testbed help ACTION' to get help for +a specific action. +.SH EXAMPLES +.TP +The create action builds and starts the testbed from scratch: +.B pisa-testbed +all create +.PP +.TP +Update all routers of an existing testbed: +.B pisa-testbed +router update +.PP +.TP +Update all but routers: +.B pisa-testbed +all \-router update +.PP +.TP +The debug action starts an interactive console: +.B pisa-testbed +all debug create Added: trunk/tools/testbed/doc/pisa-testbed_config.5 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ trunk/tools/testbed/doc/pisa-testbed_config.5 Wed Apr 27 07:41:23 2011 (r2561) @@ -0,0 +1,60 @@ +.TH pisa-testbed_config 5 "April 23, 2011" "version 0.1" +.SH NAME +pisa-testbed_config \- test network configuration file +.SH SYNOPSIS +.B $TESTBED_PATH/config +.SH DESCRIPTION +.B $TESBED_PATH/config +specifies a set of nodes that make up the network. Each node can have different +classes that are used to decide what to do on a specific action. +.PP +Configuration is done by setting various variables in shell command language +syntax. The names of the variables may contain uppercase letters and '_'. +.PP +The testbed name can be set with the variable TESTBED_NAME, by default +the name of the folder containing the testbed is used. +.PP +The variable NODES is mandatory, it is a list of the names of all testbed nodes. +These names may contain all alphanumeric letters, '-' and '_'. +.PP +Every node can have several classes, that are assigned by setting a variable, +which name is the name of the node converted to uppercase letters and '-' +to '_'. +.PP +An example testbed shall consist of a client, a server and a router. The client +and the server shall run debian systems, the router openwrt and all nodes shall +run on virtualbox. The following config variables would set up this testbed: +.PP +.PD 0 +NODES="client server router" +.PP +CLIENT="debian vbox" +.PP +SERVER="debian vbox" +.PP +ROUTER="openwrt vbox" +.PD +.PP +Classes are inherited, which means the following is equivalent: +.PP +.PD 0 +NODES="client server router" +.PP +CLIENT="debian" +.PP +SERVER="debian" +.PP +DEBIAN="vbox" +.PP +ROUTER="openwrt vbox" +.PD +.PP +At last various variables can be set, that are used to configure the plugins. +For a description of all relevant variables of a specific testbed +run 'pisa-testbed help variables' inside the testbed folder. +.PP +Variables can be set differently for the nodes through a simple scoping +mechanism. When running an action on a node, any variable which name contains +the name of the node, gets reassigned to a variable which name has the node +removed. For example SERVER_SSH_HOST overrides SSH_HOST when the current node +is 'server'. Added: trunk/tools/testbed/doc/pisa-testbed_plugins.1 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ trunk/tools/testbed/doc/pisa-testbed_plugins.1 Wed Apr 27 07:41:23 2011 (r2561) @@ -0,0 +1,24 @@ +.TH pisa-testbed_plugins 5 "April 23, 2011" "version 0.1" +.SH NAME +pisa-testbed_plugins \- contains code snippets for actions and classes +.SH SYNOPSIS +.B $TESTBED_PATH/plugins/actions/ +.PP +.B $TESTBED_PATH/plugins/classes/ +.SH DESCRIPTION +There are two basic types of plugins: actions are called from commandline, they +define the user interface of the testbed; classes are assigned to nodes in the +testbed config, they define what to do for a specific node on a specific action. +.PP +.B Actions +can execute a pre_hook, a node_hook and a post_hook. If a file pre_hook exists +in the folder of the action it is executed once for all nodes. The node_hook is +then executed once for every node, with the variables NODE and NODE_PATH +pointing to the name and the temporary buildpath of the node. At the end the +post_hook is executed, again once for all nodes. +.PP +.B Classes +often run their own code for an action. Therefore the action looks whether a +file with the name of the action exists in the folder of the class and executes +it in its node_hook. For the pre_hook and post_hook the filename may be +succeded with pre_hook and post_hook. Added: trunk/tools/testbed/plugins/actions/help/pisa-testbed.1 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ trunk/tools/testbed/plugins/actions/help/pisa-testbed.1 Wed Apr 27 07:41:23 2011 (r2561) @@ -0,0 +1 @@ +link ../../../doc/pisa-testbed.1 \ No newline at end of file Added: trunk/tools/testbed/plugins/actions/help/pisa-testbed_config.5 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ trunk/tools/testbed/plugins/actions/help/pisa-testbed_config.5 Wed Apr 27 07:41:23 2011 (r2561) @@ -0,0 +1 @@ +link ../../../doc/pisa-testbed_config.5 \ No newline at end of file Added: trunk/tools/testbed/plugins/actions/help/pisa-testbed_plugins.1 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ trunk/tools/testbed/plugins/actions/help/pisa-testbed_plugins.1 Wed Apr 27 07:41:23 2011 (r2561) @@ -0,0 +1 @@ +link ../../../doc/pisa-testbed_plugins.1 \ No newline at end of file Added: trunk/tools/testbed/plugins/actions/help/pre_hook ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ trunk/tools/testbed/plugins/actions/help/pre_hook Wed Apr 27 07:41:23 2011 (r2561) @@ -0,0 +1,22 @@ +#!/bin/sh + +if [ "$1" ]; then + case $1 in + + commands) echo "Available actions are:\n$(ls "$PLUGIN_PATH/actions")";; + + variables) echo "Available variables are:\nnot yet implemented";; #TODO + + config) man "$PLUGIN_PATH/actions/help/pisa-testbed_config.5";; + + plugins) man "$PLUGIN_PATH/actions/help/pisa-testbed_plugins.1";; + + *) if [ -f "$PLUGIN_PATH/actions/$1" ]; then + man "$PLUGIN_PATH/actions/$1/pisa-testbed_$1.1" + else + echo "No documentation found for '$1'." + fi;; + esac +else + man "$PLUGIN_PATH/actions/help/pisa-testbed.1" +fi -- This is the pisa developer mailing list. Please also subscribe to the main pisa list at: //www.freelists.org/list/pisa