From mboxrd@z Thu Jan 1 00:00:00 1970 From: rohara@sourceware.org Date: 15 Jan 2007 20:05:00 -0000 Subject: [Cluster-devel] cluster/fence/man fence_scsi.8 Message-ID: <20070115200500.11414.qmail@sourceware.org> List-Id: To: cluster-devel.redhat.com MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit CVSROOT: /cvs/cluster Module name: cluster Branch: RHEL4 Changes by: rohara at sourceware.org 2007-01-15 20:04:59 Added files: fence/man : fence_scsi.8 Log message: fence_scsi man page Patches: http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/fence/man/fence_scsi.8.diff?cvsroot=cluster&only_with_tag=RHEL4&r1=NONE&r2=1.2.6.1 /cvs/cluster/cluster/fence/man/fence_scsi.8,v --> standard output revision 1.2.6.1 --- cluster/fence/man/fence_scsi.8 +++ - 2007-01-15 20:05:00.028388000 +0000 @@ -0,0 +1,109 @@ +.\" Copyright (C) 2006 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_scsi 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)