man: add redfishpower modification info

Problem: Due to the nature of redfishpower being a REST interface,
many users are copying and pasting the redfishpower device files
and slightly tweaking them for their systems.  Users could use
more information on how to do this.  In addition, there are potential
pitfalls on other systems that users need to be aware of.

Add a section on modifications to redfishpower(8).  Add pointers to
this section in all redfishpower device files.

Fixes #67

etc/devices/redfishpower-cray-r272z30.dev

@@ -10,11 +10,9 @@
 #
 # - This device specification was tested on a Cray with Gigabyte R272-Z30.
 #
-# - If using a slightly different model or BMC firmware version, its
-#   possible the URI paths will be different.  A good starting point
-#   is to run the following command to discover the correct paths:
-#
-#   curl -s -u USER:PASS -k -X GET https://pnode1/redfish/v1/Systems
+# - CAUTION: If you intend to use this file as the basis for a different
+#   Redfish system, read the section "UPDATING REDFISHPOWER DEVICE FILES"
+#   in redfishpower(8).
 #
 specification "redfishpower-cray-r272z30" {
 	timeout 	60

etc/devices/redfishpower-cray-windom.dev

@@ -18,11 +18,9 @@
 #   attached to a blade's service processor.  Some experimentation may
 #   be needed to determine which node is attached to which suffix.
 #
-# - If using a slightly different model or BMC firmware version, its
-#   possible the URI paths will be different.  A good starting point
-#   is to run the following command to discover the correct paths:
-#
-#   curl -s -u USER:PASS -k -X GET https://pnode1/redfish/v1/Systems
+# - CAUTION: If you intend to use this file as the basis for a different
+#   Redfish system, read the section "UPDATING REDFISHPOWER DEVICE FILES"
+#   in redfishpower(8).
 #
 specification "redfishpower-cray-windom-node0" {
 	timeout 	60

etc/devices/redfishpower-supermicro.dev

@@ -10,11 +10,9 @@
 #
 # - This device specification was tested on a Supermicro H12DSG-O-CPU.
 #
-# - If using a slightly different model or BMC firmware version, its
-#   possible the URI paths will be different.  A good starting point
-#   is to run the following command to discover the correct paths:
-#
-#   curl -s -u USER:PASS -k -X GET https://pnode1/redfish/v1/Systems/1
+# - CAUTION: If you intend to use this file as the basis for a different
+#   Redfish system, read the section "UPDATING REDFISHPOWER DEVICE FILES"
+#   in redfishpower(8).
 #
 specification "redfishpower-supermicro" {
 	timeout 	60

man/redfishpower.8.in

@@ -90,6 +90,65 @@ Turn off all nodes or specified subset of nodes.  Will return "ok" after confirm
 .I "cycle [nodes]"
 Turn off all nodes or specified subset of nodes.
 
+.SH "UPDATING REDFISHPOWER DEVICE FILES"
+.LP
+Users may often need to modify
+.B redfishpower
+device files for other systems, as URI paths may be slightly different.
+.LP
+To find the URI paths on your system, a good starting point is to
+use
+.B curl(1)
+to discover the correct paths at the following standard location.
+Note that the output can be easier to read if piped to
+.B jq(1),
+but that is optional.
+.PP
+.B # curl -s -u USER:PASS -k -X GET https://<node>/redfish/v1/Systems | jq
+.LP
+Information in the response will point you on how to dig further.
+Several paths the authors have seen include:
+.PP
+.B # curl -s -u USER:PASS -k -X GET https://<node>/redfish/v1/Systems/1
+.PP
+.B # curl -s -u USER:PASS -k -X GET https://<node>/redfish/v1/Systems/Node0
+.PP
+.B # curl -s -u USER:PASS -k -X GET https://<node>/redfish/v1/Systems/Self
+.LP
+To discover if \fIcycle\fR is supported, a path similar to the following might
+be found:
+.PP
+.B # curl -s -u USER:PASS -k -X GET https://<node>/redfish/v1/Systems/Node0/ResetActionInfo
+.LP
+If \fIcycle\fR (i.e. \fIForceRestart\fR) is not available, the
+\fIcycle_ranged\fR script could be replaced with.
+.PP
+.nf
+      script cycle_ranged {
+              send "off %s\\n"
+              expect "redfishpower> "
+              send "on %s\\n"
+              expect "redfishpower> "
+      }
+.fi
+.LP
+Internally within
+.B redfishpower,
+an \fIon\fR or \fIoff\fR command will not return until the
+\fIon\fR/\fIoff\fR is confirmed to complete.  i.e. \fIstat\fR returns
+the expected status.
+.LP
+This can sometimes take awhile and on some systems may push the
+timeout limit specified in the device file (typically 60 seconds).  If
+necessary, it should be increased at the top of the specification file
+(via \fItimeout\fR) and the login section of device file (via
+\fIsettimeout\fR).
+.LP
+Note that if \fIcycle_ranged\fR is scripted as an \fIoff\fR followed by an
+\fIon\fR, the
+.B powerman
+timeout should account for the combined time of both.
+
 .SH "FILES"
 @X_SBINDIR@/redfishpower
 .br