Ubuntu Manpage: powerman.dev - PowerMan device specification files

name
description
files
origin
see also

NAME

       powerman.dev - PowerMan device specification files

DESCRIPTION

PowerMan device specifications are rather weird. 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. In most cases, only one script needs
to be specified. In some hardware where unpopulated plugs may be problematic, it may be
beneficial to specify both. If both scripts are specified, the status_all script will be called
only when all plug are requested.

on_all, on_ranged[%s], on[%s]
Power on all plugs, a range of plugs, or the specified plug.

off_all, off_ranged[%s], off[%s]
Power off all plugs, a range of plugs, or the specified plug.

cycle_all, cycle_ranged[%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. In most cases, only one script needs to be
specified. In some hardware where unpopulated plugs may be problematic, it may be beneficial to
specify both. If both scripts are specified, the status_all script will be called only when all
plug are requested.

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. In most cases, only one script needs to be specified. In some hardware where
unpopulated plugs may be problematic, it may be beneficial to specify both. If both scripts are
specified, the status_all script will be called only when all plugs are requested.

beacon_on[%s]
Flash beacon on the specified plug.

beacon_off[%s]
Clear beacon on the specified plug.

reset_all, reset_ranged[%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.

setresult <regmatch> <regmatch> success=<string>
Set the result state. The first argument, a <regmatch> from the previous expect which contains
the plug name. The success string is a compiled regex, which if it matches the second argument,
results in the power operation being successful for this plug.

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.

FILES

       /etc/powerman/*.dev

ORIGIN

       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.

NAME

DESCRIPTION

FILES

ORIGIN

SEE ALSO