[Cluster-devel] cluster/fence/man fence_scsi.8

[rohara@sourceware.org <rohara@sourceware.org>]

CVSROOT:	/cvs/cluster
Module name:	cluster
Changes by:	rohara at sourceware.org	2006-07-10 22:38:53

Added files:
	fence/man      : fence_scsi.8 

Log message:
	Initial version of the fence_scsi man page.

Patches:
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/fence/man/fence_scsi.8.diff?cvsroot=cluster&r1=NONE&r2=1.1

/cvs/cluster/cluster/fence/man/fence_scsi.8,v  -->  standard output
revision 1.1
--- cluster/fence/man/fence_scsi.8
+++ -	2006-07-10 22:38:53.507621000 +0000
@@ -0,0 +1,110 @@
+.\"  Copyright (C) Sistina Software, Inc.  1997-2003  All rights reserved.
+.\"  Copyright (C) 2004 Red Hat, Inc.  All rights reserved.
+.\"  
+.\"  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.
+
+.TH fence_apc 8
+
+.SH NAME
+fence_scsi - I/O fencing agent for SCSI persistent reservations
+
+.SH SYNOPSIS
+.B 
+fence_scsi
+[\fIOPTION\fR]...
+
+.SH DESCRIPTION
+fence_scsi is an I/O fencing agent which can be used with the SCSI
+devices that support persistent reservations (SPC-2 or greater).
+
+SCSI persistent reservations work by having each node in the cluster
+register with the SCSI device. Registration is done using a unique key
+(based on the node's IP address). Each node that will perform I/O
+operations to the shared storage must register with the device. This
+is done at system startup with the scsi_reserve init script. This
+script will discover all clustered volumes as well as the underlying
+SCSI device(s). Device discovery is done via the lvs command (see
+lvs(8)) and is subject to any filtering rules defined in the lvm.conf
+file.
+
+After generating the node's unique key, the script will register the
+node with the SCSI device(s) that were discovered. Once the node is
+registered, the script will attempt to create a reservation. Unlike
+registrations, of which there are multiple registrants (one for each
+node in the cluster), there is only one reservation holder. If a
+reservation does not already exist for a device, the script will
+create a reservation using the node's unique key.
+
+It is important to distinguish between registrations and
+reservations. As mentioned above, each node that will perform I/O
+operations to the SCSI device must register. As a result, there will
+be multiple registrations for a given SCSI device. In contrast, there
+can only be one reservation per SCSI device. It is not important which
+node holds the reservation. The reservation simply tells the device
+how the registrants are allowed to access the device. For our
+purposes, the reservation type is "write exclusive, registrants only".
+With this reservation type, only registered nodes will be able to
+write to the device.
+
+When the cluster must fence a node, it simply revokes a node's
+registration, or "unregisters" the node. This operation also uses the
+node's unique key. By deriving the unique key based on the errant
+node's IP address, the cluster can "unregister" the key. As a
+result, the errant node will no longer be able to write to the SCSI
+device.
+
+Note that the node that holds the reservation for a device must also
+be registered with that device. When the situation arises where the
+node that is being fenced is also the reservation holder, the
+reservation must be moved. This is handled by using the
+"preempt-and-abort command" which will transfer the reservation from
+the node that is being fenced to the node that is performing the
+fencing. This operation will maintain the reservation while
+"unregistering" the node being fenced.
+
+At system shutdown, the scsi_reserve script will attempt to
+"unregister" the node from all devices. The exception is when the
+node happens to be the reservation holder. In this case, the script
+does nothing, due to the fact that there may be other nodes using the
+device and the reservation must remain intact.
+
+fence_scsi accepts options on the command line as well as from stdin.
+fenced sends parameters through stdin when it execs the agent.  fence_scsi
+can be run by itself with command line options.  This is useful for testing 
+and for turning outlets on or off from scripts.
+
+.SH OPTIONS
+.TP
+\fB-n\fP \fInode\fR
+Name of the node to be fenced.
+.TP
+\fB-h\fP
+Print out a help message describing available options, then exit.
+.TP
+\fB-s\fP \fIself\fR
+Name of the node that will perform the fencing operation.
+.TP
+\fB-v\fP
+Verbose output.
+.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_scsi.
+.TP
+\fInodename = < hostname | ip >\fR
+Name of the node to be fenced.
+.TP
+\fIself = < nodename >\fR
+Name of the node that will perform the fencing operation.
+.TP
+\fIverbose = < param >\fR
+Verbose output.
+
+.SH SEE ALSO
+fence(8), fence_node(8), sg_persist(8), lvs(8), lvm.conf(5)