powerman.dev(5) 						     powerman							   powerman.dev(5)

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> sec-
	      onds.

       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  "argu-
       ment",  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 parenthe-
	      sized expressiones are assigned to variables: $1 for the first match, $2 for the second match, and so on.  Warning: some implementa-
	      tions 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 con-
	      tains 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 reg-
	      matches!	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.  Fore-
	      achplug 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

powerman-2.3.5							    2009-02-09							   powerman.dev(5)