rbd: add locking commands

The locker (entity_name_t) will be different each time the rbd
command line tool is run, so 'lock remove' is always breaking a lock.

Fixes: #2556
Signed-off-by: Josh Durgin <josh.durgin@inktank.com>

1 files changed, 43 insertions, 1 deletions

diff --git a/man/rbd.8 b/man/rbd.8
index f2a6640b058..995fa3f4ff3 100644
--- a/man/rbd.8
+++ b/man/rbd.8
@@ -1,4 +1,4 @@
-.TH "RBD" "8" "August 29, 2012" "dev" "Ceph"
+.TH "RBD" "8" "September 07, 2012" "dev" "Ceph"
 .SH NAME
 rbd \- manage rados block device (RBD) images
 .
@@ -111,6 +111,16 @@ Specifies a keyring file containing a secret for the specified user
 to use with the map command.  If not specified, the default keyring
 locations will be searched.
 .UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-shared tag
+Option for \fIlock add\fP that allows multiple clients to lock the
+same image if they use the same tag. The tag is an arbitrary
+string. This is useful for situations where an image must
+be open from more than one client at once, like during
+live migration of a virtual machine, or for use underneath
+a clustered filesystem.
+.UNINDENT
 .SH COMMANDS
 .INDENT 0.0
 .TP
@@ -207,6 +217,22 @@ Unmaps the block device that was mapped via the rbd kernel module.
 .TP
 .B \fBshowmapped\fP
 Show the rbd images that are mapped via the rbd kernel module.
+.TP
+.B \fBlock\fP list [\fIimage\-name\fP]
+Show locks held on the image. The first column is the locker
+to use with the \fIlock remove\fP command.
+.TP
+.B \fBlock\fP add [\fIimage\-name\fP] [\fIlock\-id\fP]
+Lock an image. The lock\-id is an arbitrary name for the user\(aqs
+convenience. By default, this is an exclusive lock, meaning it
+will fail if the image is already locked. The \-\-shared option
+changes this behavior. Note that locking does not affect
+any operation other than adding a lock. It does not
+protect an image from being deleted.
+.TP
+.B \fBlock\fP remove [\fIimage\-name\fP] [\fIlock\-id\fP] [\fIlocker\fP]
+Release a lock on an image. The lock id and locker are
+as output by lock ls.
 .UNINDENT
 .SH IMAGE NAME
 .sp
@@ -323,6 +349,22 @@ rbd export mypool/myimage@snap /tmp/img
 rbd import \-\-format 2 /tmp/img mypool/myimage2
 .ft P
 .fi
+.sp
+To lock an image for exclusive use:
+.sp
+.nf
+.ft C
+rbd lock add mypool/myimage mylockid
+.ft P
+.fi
+.sp
+To release a lock:
+.sp
+.nf
+.ft C
+rbd lock remove mypool/myimage mylockid client.2485
+.ft P
+.fi
 .SH AVAILABILITY
 .sp
 \fBrbd\fP is part of the Ceph distributed file system. Please refer to