[Cluster-devel] [PATCH] fence_scsi_test: document 'clear' action in man page.

[Ryan O'Hara]

This patch documents the 'clear' action. Also added comments
to man page that state the need to use at least two nodes to
use fence_scsi_test.

Signed-off-by: Ryan O'Hara <rohara at redhat.com>
---
 fence/man/fence_scsi_test.8 |   42 +++++++++++++++++++++++++++++++-----------
 1 files changed, 31 insertions(+), 11 deletions(-)

diff --git a/fence/man/fence_scsi_test.8 b/fence/man/fence_scsi_test.8
index 3252dca..57c3713 100644
--- a/fence/man/fence_scsi_test.8
+++ b/fence/man/fence_scsi_test.8
@@ -11,7 +11,7 @@ fence_scsi_test - Test for SCSI persistent reservation fencing
 
 .SH SYNOPSIS
 .B
-fence_scsi_test -o <on|off> -k <key>
+fence_scsi_test -o <action> [options]
 [\fIOPTIONS\fR]
 
 .SH DESCRIPTION
@@ -27,21 +27,39 @@ well as removing them. The "on" action is used to create reservations,
 just as you would do when a node comes online. The "off" action is
 used to remove registrations, which is equivalent to fencing. It is
 important to test both the "on" and "off" actions when testing for
-fence_scsi compatibility.
+fence_scsi compatibility. Note that at least two nodes will be
+required to test both the "on" and "off" actions.
 
 Because this script is capable of creating, modifying, and removing
 existing reservations and registrations, it should not be used on any
 systems that are actively using SCSI persistent reservations.
 
-.SH OPTIONS
+.SH ACTIONS
 .TP
-\fB-o, --action=[on|off]\fR
-The action to perform. This value can be "on" or "off". For "on", the
-script will attempt to register a key (see -k option) with the
-device(s) (see -d option) and create a reservation if none exists. The
-"off" action will attempt to remove a key from the device(s). This
-option is required.
+\fB-o, --action=[on|off|clear]\fR
+The action to perform. This value can be "on", "off" or "clear".
+
+For "on", the script will attempt to register a key (see -k option)
+with the device(s) (see -d option) and create a reservation if none
+exists. This action requires a key to be specified with the -k option.
+Since registrations are created via the "register-and-ignore"
+subcommand, any existing registrations for the local node will be
+overwritten.
+
+The "off" action will attempt to remove a key from the device(s). This
+action requires a key to be specified with the -k option. Since the
+registration key is removed via the "preempt-and-abort" subcommand,
+this action should not be used to remove a node's own key. The "off"
+action is intended to remove another node's key. Note that the node
+attempting to revoke a registration key from the device(s) must also
+be registered with the device(s).
 
+The "clear" action will remove all registrations and reservations from
+the device(s). The key (-k option) is ignored for this action, but the
+node attempting to clear the device(s) must be registered with the
+device(s). Do not use this action on a operational cluster.
+
+.SH OPTIONS
 .TP
 \fB-k, --key=VALUE\fR
 The key to use for the current action. The key must be a hexadecimal
@@ -54,7 +72,9 @@ removed from the device(s).
 \fB-d, --devices=LIST\fR
 List of devices to use for current action. This can be a single device
 or a comma-separated list of devices. Each device should be given as
-the full path (eg. /dev/sdc).
+the full path (eg. /dev/sdc). For all actions, if no devices are
+specified, fence_scsi_test will automatically use all devices found in
+cluster volumes.
 
 .TP
 \fB-h, --help\fR
@@ -65,4 +85,4 @@ Print out a help message describing available options, then exit.
 Verbose output.
 
 .SH SEE ALSO
-fence_scsi(8), fence(8), fence_node(8), sg_persist(8), lvs(8), lvm.conf(5)
+fence_scsi(8), fence(8), fence_node(8), sg_persist(8), vgs(8), lvm.conf(5)
-- 
1.7.2.3