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: ceph#2556 Signed-off-by: Josh Durgin <[email protected]>
sahid · Sep 8, 2012 · eeaa92c · eeaa92c
1 parent fd1c634
commit eeaa92c
Show file tree

Hide file tree

Showing 6 changed files with 480 additions and 18 deletions.
diff --git a/doc/man/8/rbd.rst b/doc/man/8/rbd.rst
@@ -82,6 +82,15 @@ Parameters
    to use with the map command.  If not specified, the default keyring
    locations will be searched.
 
+.. option:: --shared tag
+
+   Option for `lock add` 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.
+
 
 Commands
 ========
@@ -182,6 +191,22 @@ Commands
 :command:`showmapped`
   Show the rbd images that are mapped via the rbd kernel module.
 
+:command:`lock` list [*image-name*]
+  Show locks held on the image. The first column is the locker
+  to use with the `lock remove` command.
+
+:command:`lock` add [*image-name*] [*lock-id*]
+  Lock an image. The lock-id is an arbitrary name for the user's
+  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.
+
+:command:`lock` remove [*image-name*] [*lock-id*] [*locker*]
+  Release a lock on an image. The lock id and locker are
+  as output by lock ls.
+
 Image name
 ==========
 
@@ -250,6 +275,14 @@ import it as the desired format::
        rbd export mypool/myimage@snap /tmp/img
        rbd import --format 2 /tmp/img mypool/myimage2
 
+To lock an image for exclusive use::
+
+       rbd lock add mypool/myimage mylockid
+
+To release a lock::
+
+       rbd lock remove mypool/myimage mylockid client.2485
+
 
 Availability
 ============

diff --git 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

diff --git a/qa/workunits/rbd/copy.sh b/qa/workunits/rbd/copy.sh
@@ -148,12 +148,40 @@ test_remove() {
     rbd ls | wc -l | grep "^0$"
 }
 
+test_locking() {
+    echo "testing locking..."
+    remove_images
+
+    rbd create -s 1 test1
+    rbd lock list test1 | wc -l | grep '^0$'
+    rbd lock add test1 id
+    rbd lock list test1 | grep ' 1 '
+    LOCKER=$(rbd lock list test1 | tail -n 1 | cut -f 1)
+    rbd lock remove test1 id $LOCKER
+    rbd lock list test1 | wc -l | grep '^0$'
+
+    rbd lock add test1 id --shared tag
+    rbd lock list test1 | grep ' 1 '
+    rbd lock add test1 id --shared tag
+    rbd lock list test1 | grep ' 2 '
+    rbd lock add test1 id2 --shared tag
+    rbd lock list test1 | grep ' 3 '
+    LOCKER=$(rbd lock list test1 | tail -n 1 | cut -f 1)
+    ID=$(rbd lock list test1 | tail -n 1 | cut -f 2)
+    rbd lock remove test1 $ID $LOCKER
+    # locks don't prevent you from removing an image,
+    # just from taking a lock
+    rbd rm test1
+}
+
 test_rename
 test_ls
 test_remove
 RBD_CREATE_ARGS=""
 test_others
+test_locking
 RBD_CREATE_ARGS="--format 2"
 test_others
+test_locking
 
 echo OK