src/sanlock.8 | 286 ++++++++++++++++++++++++++++++++++++++++++++--------------
1 file changed, 217 insertions(+), 69 deletions(-)
New commits:
commit 005583d6b7b5a7af8b9be30f3582337a9fee2203
Author: David Teigland <teigland(a)redhat.com>
Date: Thu Aug 4 17:33:38 2011 -0500
sanlock: man page update
diff --git a/src/sanlock.8 b/src/sanlock.8
index 7d7d2ed..43caaed 100644
--- a/src/sanlock.8
+++ b/src/sanlock.8
@@ -5,7 +5,7 @@ sanlock \- shared storage lock manager
.SH SYNOPSIS
.B sanlock
-[COMMAND] [ACTION] [OPTIONS]
+[COMMAND] [ACTION] ...
.SH DESCRIPTION
@@ -49,7 +49,7 @@ in the lockspace (for all possible hosts, max_hosts, which is 2000) is
1MB
(8MB for 4k sectors). (This is the same size as that required for a
single paxos lease.)
-.B example
+The following example illustrates these ideas.
1. Create storage pools and reserve and initialize host_id leases
.br
@@ -91,16 +91,16 @@ sanlock client add_lockspace -s
lockspace2:2:/dev/pool2/hostid_leases:0
4. Applications can now reserve/initialize space for resource leases, and
then acquire the leases as they need to access the resources.
-What resource leases are created and how they are used depends on the
-application. For example, say application foo, running on multiple hosts,
-needs to synchronize access to data it stores on /dev/pool1/foo_data. foo
+The resource leases that are created and how they are used depends on the
+application. For example, say application A, running on multiple hosts,
+needs to synchronize access to data it stores on /dev/pool1/Adata. A
could use a resource lease as follows:
-5. Reserve and initialize a single resource lease for foo_data
+5. Reserve and initialize a single resource lease for Adata
.br
-lvcreate -n foo_data -L 1MB pool1
+lvcreate -n Adata_lease -L 1MB pool1
.br
-sanlock direct init -r lockspace1:foo_data:/dev/pool1/foo_data:0
+sanlock direct init -r lockspace1:Adata:/dev/pool1/Adata_lease:0
.br
6. Acquire the lease from the app using libsanlock (see sanlock_register,
@@ -109,21 +109,43 @@ registered with the sanlock daemon, the lease can be added for it
manually.
.br
sanlock client acquire
- -p 1234 -r lockspace1:foo_data:/dev/pool1/foo_data:0
+ -p 1234 -r lockspace1:Adata:/dev/pool1/Adata_lease:0
.br
-.B client failure
+.B offsets
+
+offsets must be 1MB aligned for disks with 512 byte sectors, and
+8MB aligned for disks with 4096 byte sectors.
+
+offsets may be used to place leases on the same device rather than using
+separate devices and offset 0 as shown in examples above, e.g. these
+commands above:
+.br
+sanlock direct init -s lockspace1:0:/dev/pool1/hostid_leases:0
+.br
+sanlock direct init -r lockspace1:Adata:/dev/pool1/Adata_lease:0
+.br
+could be replaced by:
+.br
+.br
+sanlock direct init -s lockspace1:0:/dev/pool1/leases:0
+.br
+sanlock direct init -r lockspace1:Adata:/dev/pool1/leases:1048576
+
+.B failures
If a process holding resource leases fails or exits without releasing its
leases, sanlock will release the leases for it automatically.
-.B lockspace failure
-
If the sanlock daemon cannot renew a lockspace host_id for a specific
period of time (usually because storage access is lost), sanlock will kill
any process holding a resource lease within the lockspace.
-.B watchdog usage
+If the sanlock daemon crashes or gets stuck, it will no longer renew the
+expiry time of the host_id's in the wdmd daemon, and the watchdog device
+will reset the host.
+
+.B watchdog
The watchdog device is used to further protect shared resources in case
processes cannot be killed when a host_id fails to be renewed. The
@@ -132,12 +154,17 @@ the last successful host_id renewal. This known time is the length
of
time that sanlock on another host must wait before granting the resource
lease that was held by a process on the failed host.
+The sanlock daemon uses the wdmd daemon to multiplex petting the watchdog
+device for all host_id's that are held and being renewed. The watchdog is
+managed so it will reset the host if any host_id fails to be renewed for
+fixed period of time.
+
.B levels of protection
-sanlock leases are meant to guarantee that two different process on two
-different hosts are never allowed to hold the same resource lease at once.
-If they were, the resource being protected could be corrupted. There are
-three levels of protection built into sanlock itself:
+sanlock leases are meant to guarantee that two process on two hosts are
+never allowed to hold the same resource lease at once. If they were, the
+resource being protected could be corrupted. There are three levels of
+protection built into sanlock itself:
1. The paxos leases and delta leases themselves.
@@ -145,83 +172,204 @@ three levels of protection built into sanlock itself:
cannot be renewed), the sanlock daemon kills any pids using resource
leases in the lockspace.
-3. If the pids do not exit after being killed, the watchdog device resets
-the host.
+3. If the pids do not exit after being killed, or if the sanlock daemon
+fails, the watchdog device resets the host.
+
-.SH COMMANDS
+.SH OPTIONS
-sanlock is a multi purpose binary, with three top level commands:
+.P
+COMMAND can be one of three primary top level choices
+.P
+.BR "sanlock daemon" " start daemon"
+.br
+.BR "sanlock client" " send request to daemon (default command if none
given)"
+.br
+.BR "sanlock direct" " access storage directly (no coordination with
daemon)"
-.TP
-.B daemon
-start daemon
+.BR "sanlock daemon" " [options]"
-.TP
-.B client
-send request to daemon (default command if none given)
+.BR -D " "
+no fork and print all logging to stderr
-.TP
-.B direct
-access storage directly (no coordination with daemon)
+.BI -Q " num"
+quiet error messages for common lock contention
-.SH OPTIONS
+.BI -R " num"
+renewal debugging, log debug info for each renewal
-.TP
-.nf
-LOCKSPACE = <lockspace_name>:<host_id>:<path>:<offset>
-.fi
+.BI -L " num"
+write logging at level and up to logfile (-1 none)
-.TP
-.nf
-RESOURCE =
<lockspace_name>:<resource_name>:<path>:<offset>[:<lver>]
-.fi
+.BI -S " num"
+write logging at level and up to syslog (-1 none)
-.SS client actions
+.BI -U " num"
+uid
-.TP
-.B status
+.BI -G " num"
+gid
-.TP
-.B log_dump
+.BI -t " num"
+max worker threads
-.TP
-.B shutdown
+.BI -w " num"
+use watchdog through wdmd (1 yes, 0 no, default 1)
-.TP
-.B client add_lockspace -s LOCKSPACE
+.BI -h " num"
+use high priority features (1 yes, 0 no, default 1)
-.TP
-.B client rem_lockspace -s LOCKSPACE
+.BI \-a " num"
+use async i/o (1 yes, 0 no, default 1)
-.TP
-.B client command -r RESOURCE -c <path> <args>
+.BI -o " num"
+io timeout in seconds (default 10)
-.TP
-.B client acquire -p <pid> -r RESOURCE
+.B "sanlock client"
+.I action
+[options]
-.TP
-.B client release -p <pid> -r RESOURCE
+.B sanlock client status
-.TP
-.B client inquire -p <pid>
+Print processes, lockspaces, and resources being manged by the sanlock
+daemon.
-.SS direct actions
+.B sanlock client log_dump
-.TP
-.B direct init [-s LOCKSPACE] [-r RESOURCE]
+Print the sanlock daemon internal debug log.
-.TP
-.B direct dump <path>[:<offset>] [options]
+.B sanlock client shutdown
-.TP
-.B direct read_leader [-s LOCKSPACE] [-r RESOURCE]
+Tell the sanlock daemon to exit. Any registered processes will be killed,
+their resource leases released, and lockspaces removed.
-.TP
-.B direct acquire|release -i <num> -g <num> -r RESOURCE
+.BR "sanlock client add_lockspace -s" " LOCKSPACE"
-.TP
-.B direct acquire_id|renew_id|release_id|read_id|live_id -s LOCKSPACE
+Tell the sanlock daemon to acquire the specified host_id in the lockspace.
+This will allow resources to be acquired in the lockspace.
+
+.BR "sanlock client rem_lockspace -s" " LOCKSPACE"
+
+Tell the sanlock daemon to release the specified host_id in the lockspace.
+Any processes holding resource leases in this lockspace will be killed,
+and the leases released.
+
+.BR "sanlock client command -r" " RESOURCE " \
+\fB-c\fP " " \fIpath\fP " " \fIargs\fP
+
+Register with the sanlock daemon, acquire the specified resource lease,
+and exec the command at path with args. When the command exits, the
+sanlock daemon will release the lease. -c must be the final option.
+
+.BR "sanlock client acquire -r" " RESOURCE " \
+\fB-p\fP " " \fIpid\fP
+.br
+.BR "sanlock client release -r" " RESOURCE " \
+\fB-p\fP " " \fIpid\fP
+Tell the sanlock daemon to acquire or release the specified resource lease
+for the given pid. The pid must be registered with the sanlock daemon.
+acquire can optionally take a versioned RESOURCE string RESOURCE:lver,
+where lver is the version of the lease that must be acquired, or fail.
+
+.BI "sanlock client inquire -p" " pid"
+
+Print the resource leases held the given pid. The format is a versioned
+RESOURCE string "RESOURCE:lver" where lver is the version of the lease
+held.
+
+.B "sanlock direct"
+.I action
+[options]
+
+.BI \-a " num"
+use async i/o (1 yes, 0 no, default 1)
+
+.BI -o " num"
+io timeout in seconds (default 10)
+
+.BR "sanlock direct init -s" " LOCKSPACE"
+.br
+.BR "sanlock direct init -r" " RESOURCE"
+
+Initialize storage for 2000 host_id (delta) leases for the given
+lockspace, or initialize storage for one resource (paxos) lease. Both
+options require 1MB of space. The host_id in the LOCKSPACE string is not
+relevant to initialization, so the value is ignored. (The default of 2000
+host_ids can be changed for special cases using the -n num_hosts and -m
+max_hosts options.)
+
+.BR "sanlock direct read_leader -s" " LOCKSPACE"
+.br
+.BR "sanlock direct read_leader -r" " RESOURCE"
+
+Read a leader record from disk and print the fields. The leader record is
+the single sector of a delta lease, or the first sector of a paxos lease.
+
+.BR "sanlock direct read_id -s" " LOCKSPACE"
+.br
+.BR "sanlock direct live_id -s" " LOCKSPACE"
+
+read_id reads a host_id and prints the owner. live_id reads a host_id
+once a second until it the timestamp or owner change (prints live 1), or
+until host_dead_seconds (prints live 0). (host_dead_seconds is derived
+from the io_timeout option. The live 0|1 conclusion will not match the
+sanlock daemon's conclusion unless the configured timeouts match.)
+./" .P
+./" .BR "sanlock direct acquire_id -s" " LOCKSPACE"
+./" .br
+./" .BR "sanlock direct renew_id -s" " LOCKSPACE"
+./" .br
+./" .BR "sanlock direct release_id -s" " LOCKSPACE"
+./"
+./" Acquire, renew, or release a host_id directly to disk, independent from
+./" the sanlock daemon. Not for general use. This should only be used for
+./" testing or for manual recovery in an emergency.
+./"
+./" .P
+./" .BR "sanlock direct acquire -r" " RESOURCE " \
+./" \fB-i\fP " " \fInum\fP " " \fB-g\fP " " \fInum\fP
+./" .br
+./" .BR "sanlock direct release -r" " RESOURCE " \
+./" \fB-i\fP " " \fInum\fP " " \fB-g\fP " " \fInum\fP
+./"
+./" Not supported. Not for general use.
+./"
+
+.BI "sanlock direct dump" " path" \
+\fR[\fP\fB:\fP\fIoffset\fP\fR]\fP
+
+Read disk sectors and print leader records for delta or paxos leases.
+
+
+.SS
+LOCKSPACE option string
+
+.BR \-s " " \fIlockspace_name\fP:\fIhost_id\fP:\fIpath\fP:\fIoffset\fP
+.P
+.IR lockspace_name " name of the lockspace"
+.br
+.IR host_id " local host identifier in lockspace"
+.br
+.IR path " path to storage reserved for leases"
+.br
+.IR offset " offset on path (bytes)"
+.br
+
+.SS
+RESOURCE option string
+
+.BR \-r " " \fIlockspace_name\fP:\fIresource_name\fP:\fIpath\fP:\fIoffset\fP
+.P
+.IR lockspace_name " name of lockspace"
+.br
+.IR resource_name " name of resource"
+.br
+.IR path " path to storage reserved for leases"
+.br
+.IR offset " offset on path (bytes)"
+.br
+.IR lver " optional leader version"
.SH SEE ALSO
.BR wdmd (8)