powerman.dev - PowerMan device specification files
PowerMan device specifications are rather wierd. For this reason,
we suggest that you leave the writing of these scripts to the PowerMan
authors. However, if you insist, here is how they work.
Note: the authors do not guarantee that the PowerMan specification
language will not change, however we are open to taking on maintenance of
scripts submitted by PowerMan users. We can't guarantee that we'll be able
to test new releases against all devices but we'll do our best not to break
anything. NOTE: the best way to help us in this endeavor is to provide a
``simulator'' for your power controller and associated tests in the
test subdirectory of the powerman source code. See the examples in
that directory.
By convention, device scripts are one device per file and are
included as needed from a powerman.conf file, like this:
-
include "/etc/powerman/icebox3.dev"
A device script is surrounded by an outer block:
-
specification "my_device_name" {
# configuration settings
# script blocks
}
The possible configuration settings are:
- timeout
<float>
- (optional) device script timeout in seconds - applies to each script, the
whole thing, not just a particular "expect".
- plug name { <string
list> }
- (optional) if plug names are static, they should be defined. Any reference
to a plug name in the powerman.conf must match one of the defined plug
names.
- pingperiod
<float>
- (optional) if a ping script is defined, and pingperiod is nonzero, the
ping script will be executed periodically, every <float>
seconds.
Script blocks have the form:
-
script <script_name> {
# statements
}
Script blocks should all be grouped together with no config lines
in between. Scripts are for performing particular operations such as power
on, get power status, etc. The various script names are listed below. Those
marked with [%s] are called with a plug name "argument", which can
be included in a send statements by including a %s (printf style). Warning:
all the send strings are processed with printf and you can cause powermand
to segfault if you include any printf tokens other than the appropriate zero
or one %s.
- login
- Executed immediately on (re-)connect. If you need to login to the box, do
it here. This is also a good place to descend through a first layer of
menus. Caveat: % occurring in passwords must be escaped as %%. Caveat:
occurs outside of client session so cannot be debugged with -T. A trick
when debugging is to move this code into the status script temporarily so
you can see what is going on.
- logout
- Executed prior to disconnect. Get device in a state so login script will
work (though hopefully disconnecting will do that too).
- status_all,
status[%s]
- Obtain plug state for all plugs or only the specified plug. When all plugs
of a device are involved in a plug status query, the status_all script, if
defined, will be called in preference to the status script; otherwise the
status script is called for each plug.
- on_all, on_range[%s],
on[%s]
- Power on all plugs, a range of plugs, or the specified plug.
- off_all,
off_range[%s], off[%s]
- Power off all plugs, a range of plugs, or the specified plug.
- cycle_all,
cycle_range[%s], cycle[%s]
- Power cycle all plugs, a range of plugs, or the specified plug. The intent
of this command was to map to the RPC's cycle command; however, device
script are increasingly implementing this in terms of a power
off/delay/power so the off time can be controlled by the script.
- status_soft_all,
status_soft[%s]
- Obtain soft power state for all plugs or only the specified plug. Soft
Power refers to the "standby state" of the node. On means the
node is powered up. Off means either the node is powered off at the plug
or is powered on at the plug and in standby mode. This is really only
useful on devices that include both a plug relay and a probe into the node
attached to a non-standby power source.
- status_temp_all,
status_temp[%s]
- Obtain temperature reading for all plugs or only the specified plug.
Temperature is obtained by sampling a thermocouple in the node. Results
are reported as a text string - not interpreted by Powerman beyond any
regex chopping done by the script.
- status_beacon_all,
status_beacon[%s]
- Obtain beacon state for all plugs or only the specified plug. Some RPC's
include a way to flash a light on a node.
- beacon_on[%s]
- Flash beacon on the specified plug.
- beacon_off[%s]
- Clear beacon on the specified plug.
- reset_all,
reset_range[%s], reset[%s]
- Reset all plugs, a range of plugs, or only the specified plug. Reset
refers to signaling a motherboard reset butten header, not a plug
cycle.
Within a script, the following statements can be used:
- send
<string>
- Send <string> to the device.
- delay
<float>
- Pause script for <float> seconds.
- expect
<string>
- <string> is compiled as a regular expression with regcomp(3). The
regular expression is matched against device input. The script blocks
until the regex is matched or the device timeout occurs (in which case the
script is aborted). Upon matching, any parenthesized expressiones are
assigned to variables: $1 for the first match, $2 for the second match,
and so on. Warning: some implementations of regex(3) silently fail if the
regular expression exceeds available static storage.
- setplugstate
[<string>|<regmatch>] <regmatch> [off=<string>]
[on=<string>]
- Set the plug state. The first argument, if present, is the literal plug
name or a <regmatch> from the previous expect which contains the
plug name. If omitted, the plug name is presumed to be the script
argument. The off and on strings are compiled regexes, which if matched by
the second argument, result in the plug state being set to off or on. Yes
we are applying regexes to regmatches! If no off or on strings are
provided, state will be unknown.
- ifoff,
ifon
- Script statements enclosed in an ifon/ifoff block are conditional executed
based on the state of the plug passed in as an argument. Ifon/ifoff blocks
can only be used in single plug scripts that take an argument.
- foreachplug
- Script statements enclosed in a foreachplug block are executed iteratively
with a %s argument defined for each target plug. Foreachplug blocks can
only be used in all plug scripts that take no argument.
Script terminals are defined as follows:
- <float>
- decimal number - exponent forms not supported
- <string>
- Text surrounded by double quotes. May contain C style backslash-escaped
characters, including three digit octal values, and most common
backslash-escaped single character values.
- <string list>
- Multiple <string> values separated by white space.
- <script_name>
- Name of script (see above).
- <regmatch>
- Results of a parenthesized regular expression match are assigned to $1,
$2, ... $N.
PowerMan was originally developed by Andrew Uselton on LLNL's
Linux clusters. This software is open source and distributed under the terms
of the GNU GPL.