[Cluster-devel] [PATCH] Updated fence_manual docs for HEAD

[Lon Hohberger]

As described.  The documentation surrounding the disappearance and
subsequent replacement of fence_manual was nonexistent; this patch
addresses that problem.

-- 
Lon Hohberger - Software Engineer - Red Hat, Inc.
-------------- next part --------------
Index: agents/manual/fence_ack_manual.sh
===================================================================
RCS file: /cvs/cluster/cluster/fence/agents/manual/fence_ack_manual.sh,v
retrieving revision 1.2
diff -u -r1.2 fence_ack_manual.sh
--- agents/manual/fence_ack_manual.sh	14 May 2007 16:33:53 -0000	1.2
+++ agents/manual/fence_ack_manual.sh	25 Sep 2007 19:06:51 -0000
@@ -1,14 +1,25 @@
 #!/bin/bash
 #
-# Dummy fence_ack_manual which uses the fenced manual override
-# socket to communicate.
+###############################################################################
+###############################################################################
+##
+##  COPYRIGHT (C) 2007 RED HAT, INC.
+##  
+##  THIS COPYRIGHTED MATERIAL IS MADE AVAILABLE TO ANYONE WISHING TO USE,
+##  MODIFY, COPY, OR REDISTRIBUTE IT SUBJECT TO THE TERMS AND CONDITIONS
+##  OF THE GNU GENERAL PUBLIC LICENSE V.2.
+##
+###############################################################################
+###############################################################################
+#
+# Manual override after fencing has failed.
 #
 
 if [ "$1" = "-n" ]; then
 	shift
 fi
 
-if [ -z "$1" ]; then
+if [ -z "$1" ] || [ "$1" = "-h" ]; then
 	echo "usage:"
         echo " 	$0 <nodename>"
         echo " 	$0 -n <nodename>"
Index: man/fence_ack_manual.8
===================================================================
RCS file: /cvs/cluster/cluster/fence/man/fence_ack_manual.8,v
retrieving revision 1.4
diff -u -r1.4 fence_ack_manual.8
--- man/fence_ack_manual.8	15 Feb 2007 17:57:43 -0000	1.4
+++ man/fence_ack_manual.8	25 Sep 2007 19:06:51 -0000
@@ -8,7 +8,8 @@
 .TH fence_ack_manual 8
 
 .SH NAME
-fence_ack_manual - program run by an operator as a part of manual I/O Fencing
+fence_ack_manual - program run by an operator to allow the cluster to
+recover after fencing has failed
 
 .SH SYNOPSIS
 .B
@@ -16,28 +17,28 @@
 [\fIOPTION\fR]...
 
 .SH DESCRIPTION
-fence_ack_manual is run by an operator on the same node that fence_manual(8) 
-was run after the operator has reset a node which required fencing.  A message 
-in the system log indicates to the operator that they must reset a machine and 
-then run fence_ack_manual.  Running fence_ack_manual allows the cluster to 
-continue with recovery of the fenced machine.  The victim may be disconnected 
-from storage rather than resetting it.
+fence_ack_manual may be run by an operator at any point after fencing has
+failed.  It must be run on the same node which is handling fencing
+(indications of failed fencing should appear in the system logs), and the
+operator must manually reset the affected node(s) prior to running
+fence_ack_manual.
+
+This allows the cluster to recover in a situation where fencing has failed
+for some reason.
+
+.SH NOTES
+It is also permissable for the affected node(s) to be disconnected from
+shared storage rather than reset.
+
+No configuration is necessary in order to use fence_ack_manual after a
+fencing failure.
 
 .SH OPTIONS
 .TP
 \fB-h\fP
 Print out a help message describing available options, then exit.
 .TP
-\fB-O\fP
-Run without prompting for user confirmation.
-.TP
 \fB-n\fP \fInodename\fP
 Name of node that has been reset or disconnected from storage.
-.TP
-\fB-s\fP \fIIPaddress\fP
-IP address of the machine which has been reset or disconnected from storage.  (Deprecated; use -n instead.)
-.TP
-\fB-V\fP
-Print out a version message, then exit.
 .SH SEE ALSO
-fence(8), fence_node(8)
+fence(8), fence_node(8), fenced(8)
Index: man/fence_manual.8
===================================================================
RCS file: /cvs/cluster/cluster/fence/man/fence_manual.8,v
retrieving revision 1.5
diff -u -r1.5 fence_manual.8
--- man/fence_manual.8	15 Feb 2007 17:57:43 -0000	1.5
+++ man/fence_manual.8	25 Sep 2007 19:06:51 -0000
@@ -8,49 +8,19 @@
 .TH fence_manual 8
 
 .SH NAME
-fence_manual - program run by fenced as a part of manual I/O Fencing
-
-.SH SYNOPSIS
-.B
-fence_manual
-[\fIOPTION\fR]...
+fence_manual - Obsolete manual fencing agent
 
 .SH DESCRIPTION
-fence_manual is run by fenced.  It creates a fifo and waits for 
-its counter-part fence_ack_manual(8) to acknowledge that a failed node
-has been reset.  fence_ack_manual(8) should only be run after the operator
-has reset the faulty node.  While waiting for the manual acknowledgement,
-fence_manual also watches for the faulty node to rejoin the cluster;
-if it does, it's taken as an acknowledgement and completes.
-
-Note:  fence_manual is provided for use during testing and evaluation
-only.  Sites should not use fence_manual as the primary fencing method
-on a production cluster.
-
-.SH OPTIONS
-.TP
-\fB-h\fP
-Print out a help message describing available options, then exit.
-.TP
-\fB-q\fP
-quiet mode, no output.
-.TP
-\fB-n\fP \fInodename\fP
-The node name (usually hostname) of the machine that needs to be reset or disconnected from shared storage.
-.TP
-\fB-V\fP
-Print out a version message, then exit.
-
-.SH STDIN PARAMETERS
-.TP
-\fIagent = < param >\fR
-This option is used by fence_node(8) and is ignored by fence_manual.
-.TP
-\fInodename = < param >\fR
-The node name (usually hostname) of the machine that needs to be reset or disconnected from storage.
-.TP
-\fIipaddr = < param >\fR
-IP address or hostname of the machine that needs to be reset or disconnected from storage.  (Deprecated; use nodename instead.)
+fence_manual used to implement a manual fencing agent.  It has been
+supplanted by the manual fence override.  See the section fenced(8)
+entitled 'Fencing override', as well as fence_ack_manual(8) for more
+details.
+
+.P
+In order to configure a cluster which utilizes manual fencing, simply
+configure no fencing at all.  This will cause fencing to immediately
+fail, thereby opening the window to use the manual override using
+fence_ack_manual.
 
 .SH SEE ALSO
 fence(8), fence_node(8), fence_ack_manual(8)