[pisa-src] r2561 - in trunk/tools/testbed: doc/pisa-testbed.1 doc/pisa-testbed_config.5 doc/pisa-testbed_plugins.1 plugins/actions/help plugins/actions/help/pisa-testbed.1 plugins/actions/help/pisa-testbed_co...
- From: Samuel Richter <samuel.richter@xxxxxxxxxxxxxx>
- To: pisa-src@xxxxxxxxxxxxx
- Date: Wed, 27 Apr 2011 07:41:23 +0200
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
Other related posts:
- » [pisa-src] r2561 - in trunk/tools/testbed: doc/pisa-testbed.1 doc/pisa-testbed_config.5 doc/pisa-testbed_plugins.1 plugins/actions/help plugins/actions/help/pisa-testbed.1 plugins/actions/help/pisa-testbed_co... - Samuel Richter
