Provided by: powerman_2.3.5-1build1_amd64 bug

NAME

       powerman.dev - PowerMan device specification files

DESCRIPTION

       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.

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.

SEE ALSO

       powerman(1),   powermand(8),   httppower(8),   plmpower(8),   vpcd(8),   powerman.conf(5),
       powerman.dev(5), powerman-devices(7).

       http://sourceforge.net/projects/powerman