power: Document Power* host properties and power methods

Signed-off-by: Ian Jackson <ian.jackson@eu.citrix.com>

diff --git a/README b/README
index bb9dc18e4e3d14bdf6d51c99e31ed2a35ded0e68..9179379547a5e7166951a4d4c3a8c7082db0f438 100644 (file)
--- a/README
+++ b/README
@@ -631,6 +631,83 @@ Username
     User name on this host.  Defaults to the output of `whoami'.
     Should not normally be changed.
 
+HostProp_<host>_PowerPDU
+HostProp_<host>_PowerILOM
+    How to power cycle this host.  Each item is a ;-separated
+    list of method specifications.  When power is to be removed
+    or applied, the methods in the list are operated in order
+    (when powering on) or reverse order (when powering off).
+
+    If both PDU and ILOM are supplied, osstest tries first to just use
+    ILOM.  If that is not successful, it tries again using PDU and
+    ILOM together.  In this case: they are done in the appropriate
+    order (PDU first, on power on); it is if `pause' were specified in
+    between PDU and ILOM; and it is as if try_off were specified
+    before each ILOM.
+
+    A method specification has a keyword at the front, and 
+    is in one of these forms:
+
+        Any of the Osstest::PDU::* modules in Osstest/PDU/*.pm.  See
+        the individual modules.  We document here, particularly:
+
+        manual          Asks the user on the controlling terminal
+        unsupported     Fails whenever a power operation is needed
+
+        msw [--apc6] <pdu> <port-name-regexp|port-num>
+             Control and APC masterswitch via SNMP.  The SNMP
+             community is `private'.  See the `pdu-msw' script.
+
+        ipmi <mgmt> [<user> [<pass> [<ipmitool options...>]]]
+             Use IPMI by (by running ipmitool).  <mgmt> is the name or
+             address of the management port.  <user> and <pass>
+             default to the IpmiUser and IpmiPassword host properties.
+
+        ipmiextra on|off|both <mgmt> <user> <pass> [<ipmitool options...>]
+             Does nothing if `on|off|both' is inapplicable, and has
+             less error checking and less defaulting than ipmi.
+
+        Supported specially are:
+
+        <delay>
+        <ondelay>/<offdelay>
+        pause <delay>
+        pause <ondelay> <offdelay>
+             Pause for the specified time(s) (in seconds).
+
+        pause
+             Pause for <ondelay> (defaulting to the PowerOnTime host
+             property) on power on, and for 10 seconds on power off.
+             Normally it is not necessary to specify this explicitly,
+             as it is implied by providing both PowerPDU and
+             PowerILOM.
+
+        try_off [<attempts>] <method...>
+             Use <method>.  However, on powering off: make <attempts>
+             attempts (default=3), and if that fails, only warn rather
+             than failing.
+
+HostProp_<host>_PowerOnTime
+    Length of time it takes this host to wake up from cold power on,
+    until the ILOM is working.  (Used if both PowerPDU and PowerILOM
+    are set, or if `pause' appears in a power method pspecification.)
+    Default is 120 seconds.
+
+HostProp_<host>_PowerCycleTime
+    Length of time this host must be powered off to ensure that it
+    reboots properly.  (This should be the longer value of the values
+    for PDU and ILOM, if applicable.)  Default is 5 seconds.
+
+HostProp_<host>_PowerMethod
+    Older specification for how to power cycle this host.  Only used
+    if neither PowerPDU or PowerILOM is provided.
+
+    Syntax and semantics are the same as those, except that the order
+    of operation is forwards through the list for both power on and
+    power off, unless the first `method' is the pseudo-method `nest'.
+
+    This host property is honoured for backward compatibility.
+
 ========================================
 
 Host-specific config settigs

diff --git a/README.dev b/README.dev
index eff82350c7cc6018688c473f358a307b6e62224b..e32889b7067796223a37a3935f177b6732e0a92e 100644 (file)
--- a/README.dev
+++ b/README.dev
@@ -38,8 +38,8 @@ Firstly, arrange that it is hooked up to network, serial, and pdu.
 (In the Xen Project Massachusetts test lab, make sure that ansible
 playbook hosts/ has the wiring information; running `make install'
 will then arrange for /root/osstest-hosts-config to contain the Ether,
-Serial and PowerMethod configuration, and also configure the DNS and
-the DHCP server.)
+Serial and PowerILOM/PowerHard/PowerCycleTime configuration, and also
+configure the DNS and the DHCP server.)
 
 Go through the BIOS set up, using the serial console.  Check that:
  - After AC power loss, machine is set to turn on