rbd: unified way to map images using different drivers

Instead of "rbd map|unmap|showmapped", "rbd ndb map|unmap|list",
"rbd ggate map|unmap|list" commands, provide:

 rbd device -t krbd|nbd|ggate|... map|unmap|list

which gives interface consistent between drivers.

Signed-off-by: Mykola Golub <mgolub@suse.com>

doc/man/8/rbd.rst

@@ -205,6 +205,25 @@ Commands
   Deep copy the content of a src-image into the newly created dest-image.
   Dest-image will have the same size, object size, image format, and snapshots as src-image.
 
+:command:`device list` [-t | --device-type *device-type*] [--format plain | json | xml] --pretty-format
+  Show the rbd images that are mapped via the rbd kernel module
+  (default) or other supported device.
+
+:command:`device map` [-t | --device-type *device-type*] [--read-only] [--exclusive] [-o | --options *device-options*] *image-spec* | *snap-spec*
+  Map the specified image to a block device via the rbd kernel module
+  (default) or other supported device (*nbd* on Linux or *ggate* on
+  FreeBSD).
+
+  The --options argument is a comma separated list of device type
+  specific options (opt1,opt2=val,...).
+
+:command:`device unmap` [-t | --device-type *device-type*] [-o | --options *device-options*] *image-spec* | *snap-spec* | *device-path*
+  Unmap the block device that was mapped via the rbd kernel module
+  (default) or other supported device.
+
+  The --options argument is a comma separated list of device type
+  specific options (opt1,opt2=val,...).
+
 :command:`diff` [--from-snap *snap-name*] [--whole-object] *image-spec* | *snap-spec*
   Dump a list of byte extents in the image that have changed since the specified start
   snapshot, or since the image was created.  Each output line includes the starting offset
@@ -347,9 +366,6 @@ Commands
   -l, also show snapshots, and use longer-format output including
   size, parent (if clone), format, etc.
 
-:command:`map` [-o | --options *krbd-options* ] [--read-only] *image-spec* | *snap-spec*
-  Map the specified image to a block device via the rbd kernel module.
-
 :command:`merge-diff` *first-diff-path* *second-diff-path* *merged-diff-path*
   Merge two continuous incremental diffs of an image into one single diff. The
   first diff's end snapshot must be equal with the second diff's start snapshot.
@@ -437,15 +453,6 @@ Commands
 :command:`mv` *src-image-spec* *dest-image-spec*
   Rename an image.  Note: rename across pools is not supported.
 
-:command:`nbd ls`
-  Show the list of used nbd devices via the rbd-nbd tool.
-
-:command:`nbd map` [--device *device-path*] [--read-only] *image-spec* | *snap-spec*
-  Map the specified image to a block device via the rbd-nbd tool.
-
-:command:`nbd unmap` *device-path*
-  Unmap the block device that was mapped via the rbd-nbd tool.
-
 :command:`object-map check` *image-spec* | *snap-spec*
   Verify the object map is correct.
 
@@ -465,9 +472,6 @@ Commands
   Delete an rbd image (including all data blocks). If the image has
   snapshots, this fails and nothing is deleted.
 
-:command:`showmapped`
-  Show the rbd images that are mapped via the rbd kernel module.
-
 :command:`snap create` *snap-spec*
   Create a new snapshot. Requires the snapshot name parameter specified.
 
@@ -528,9 +532,6 @@ Commands
   you can not removed it unless use force. But an actively in-use by clones 
   or has snapshots can not be removed.
 
-:command:`unmap` [-o | --options *krbd-options* ] *image-spec* | *snap-spec* | *device-path*
-  Unmap the block device that was mapped via the rbd kernel module.
-
 :command:`watch` *image-spec*
   Watch events on image.
 
@@ -589,7 +590,7 @@ Most of these options are useful mainly for debugging and benchmarking.  The
 default values are set in the kernel and may therefore depend on the version of
 the running kernel.
 
-Per client instance `rbd map` options:
+Per client instance `rbd device map` options:
 
 * fsid=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee - FSID that should be assumed by
   the client.
@@ -619,16 +620,16 @@ Per client instance `rbd map` options:
 
 * nocephx_sign_messages - Disable message signing (since 4.4).
 
-* mount_timeout=x - A timeout on various steps in `rbd map` and `rbd unmap`
-  sequences (default is 60 seconds).  In particular, since 4.2 this can be used
-  to ensure that `rbd unmap` eventually times out when there is no network
-  connection to a cluster.
+* mount_timeout=x - A timeout on various steps in `rbd device map` and
+  `rbd device unmap` sequences (default is 60 seconds).  In particular,
+  since 4.2 this can be used to ensure that `rbd device unmap` eventually
+  times out when there is no network connection to a cluster.
 
 * osdkeepalive=x - OSD keepalive timeout (default is 5 seconds).
 
 * osd_idle_ttl=x - OSD idle TTL (default is 60 seconds).
 
-Per mapping (block device) `rbd map` options:
+Per mapping (block device) `rbd device map` options:
 
 * rw - Map the image read-write (default).
 
@@ -641,7 +642,7 @@ Per mapping (block device) `rbd map` options:
 
 * exclusive - Disable automatic exclusive lock transitions (since 4.12).
 
-`rbd unmap` options:
+`rbd device unmap` options:
 
 * force - Force the unmapping of a block device that is open (since 4.9).  The
   driver will wait for running requests to complete and then unmap; requests
@@ -681,15 +682,15 @@ To delete a snapshot::
 
 To map an image via the kernel with cephx enabled::
 
-       rbd map mypool/myimage --id admin --keyfile secretfile
+       rbd device map mypool/myimage --id admin --keyfile secretfile
 
 To map an image via the kernel with different cluster name other than default *ceph*::
 
-       rbd map mypool/myimage --cluster cluster-name
+       rbd device map mypool/myimage --cluster cluster-name
 
 To unmap an image::
 
-       rbd unmap /dev/rbd0
+       rbd device unmap /dev/rbd0
 
 To create an image and a clone from it::
 

doc/rbd/rbd-ko.rst

@@ -20,40 +20,40 @@ Use ``rbd`` to map an image name to a kernel module. You must specify the
 image name, the pool name, and the user name. ``rbd`` will load RBD kernel
 module on your behalf if it's not already loaded. ::
 
-  sudo rbd map {pool-name}/{image-name} --id {user-name}
+  sudo rbd device map {pool-name}/{image-name} --id {user-name}
 
 For example:: 
 
-  sudo rbd map rbd/myimage --id admin
+  sudo rbd device map rbd/myimage --id admin
 
 If you use `cephx`_ authentication, you must also specify a secret.  It may come
 from a keyring or a file containing the secret. ::
 
-  sudo rbd map rbd/myimage --id admin --keyring /path/to/keyring
-  sudo rbd map rbd/myimage --id admin --keyfile /path/to/file
+  sudo rbd device map rbd/myimage --id admin --keyring /path/to/keyring
+  sudo rbd device map rbd/myimage --id admin --keyfile /path/to/file
 
 
 Show Mapped Block Devices
 =========================
 
-To show block device images mapped to kernel modules with the ``rbd`` command,
-specify the ``showmapped`` option. ::
+To show block device images mapped to kernel modules with the ``rbd``,
+specify ``device list`` arguments. ::
 
-	rbd showmapped
+	rbd device list
 
 
 Unmapping a Block Device
-========================	
+========================
 
-To unmap a block device image with the ``rbd`` command, specify the ``unmap``
-option  and the device name (i.e., by convention the same as the block device
-image name). :: 
+To unmap a block device image with the ``rbd`` command, specify the
+``device unmap`` arguments and the device name (i.e., by convention the
+same as the block device image name). :: 
+
+	sudo rbd device unmap /dev/rbd/{poolname}/{imagename}
 
-	sudo rbd unmap /dev/rbd/{poolname}/{imagename}
-
 For example::
 
-	sudo rbd unmap /dev/rbd/rbd/foo
+	sudo rbd device unmap /dev/rbd/rbd/foo
 
 
 .. _cephx: ../../rados/operations/user-management/

qa/tasks/rbd_fio.py

@@ -78,7 +78,8 @@ def get_ioengine_package_name(ioengine, remote):
 def run_rbd_map(remote, image, iodepth):
     iodepth = max(iodepth, 128)  # RBD_QUEUE_DEPTH_DEFAULT
     out = StringIO.StringIO()
-    remote.run(args=['sudo', 'rbd', 'map', '-o', 'queue_depth={}'.format(iodepth), image], stdout=out)
+    remote.run(args=['sudo', 'rbd', 'device', 'map', '-o',
+                     'queue_depth={}'.format(iodepth), image], stdout=out)
     dev = out.getvalue().rstrip('\n')
     teuthology.sudo_write_file(
         remote,
@@ -214,12 +215,13 @@ def run_fio(remote, config, rbd_test_dir):
         remote.run(args=['ceph', '-s'])
     finally:
         out=StringIO.StringIO()
-        remote.run(args=['rbd','showmapped', '--format=json'], stdout=out)
+        remote.run(args=['rbd', 'device', 'list', '--format=json'], stdout=out)
         mapped_images = json.loads(out.getvalue())
         if mapped_images:
             log.info("Unmapping rbd images on {sn}".format(sn=sn))
             for image in mapped_images:
-                remote.run(args=['sudo', 'rbd', 'unmap', str(image['device'])])
+                remote.run(args=['sudo', 'rbd', 'device', 'unmap',
+                                 str(image['device'])])
         log.info("Cleaning up fio install")
         remote.run(args=['rm','-rf', run.Raw(rbd_test_dir)])
         if ioengine_pkg:

qa/workunits/rbd/kernel.sh

@@ -14,14 +14,15 @@ function get_device_dir {
 	local POOL=$1
 	local IMAGE=$2
 	local SNAP=$3
-	rbd showmapped | tail -n +2 | egrep "\s+$POOL\s+$IMAGE\s+$SNAP\s+" | awk '{print $1;}'
+	rbd device list | tail -n +2 | egrep "\s+$POOL\s+$IMAGE\s+$SNAP\s+" |
+	    awk '{print $1;}'
 }
 
 function clean_up {
 	[ -e /dev/rbd/rbd/testimg1@snap1 ] &&
-		sudo rbd unmap /dev/rbd/rbd/testimg1@snap1
+		sudo rbd device unmap /dev/rbd/rbd/testimg1@snap1
 	if [ -e /dev/rbd/rbd/testimg1 ]; then
-		sudo rbd unmap /dev/rbd/rbd/testimg1
+		sudo rbd device unmap /dev/rbd/rbd/testimg1
 		rbd snap purge testimg1 || true
 	fi
 	rbd ls | grep testimg1 > /dev/null && rbd rm testimg1 || true
@@ -42,7 +43,7 @@ dd if=/dev/zero of=/tmp/img1 count=0 seek=150000
 
 # import
 rbd import /tmp/img1 testimg1
-sudo rbd map testimg1 --user $CEPH_ID $SECRET_ARGS
+sudo rbd device map testimg1 --user $CEPH_ID $SECRET_ARGS
 
 DEV_ID1=$(get_device_dir rbd testimg1 -)
 echo "dev_id1 = $DEV_ID1"
@@ -54,7 +55,7 @@ cmp /tmp/img1 /tmp/img1.export
 
 # snapshot
 rbd snap create testimg1 --snap=snap1
-sudo rbd map --snap=snap1 testimg1 --user $CEPH_ID $SECRET_ARGS
+sudo rbd device map --snap=snap1 testimg1 --user $CEPH_ID $SECRET_ARGS
 
 DEV_ID2=$(get_device_dir rbd testimg1 snap1)
 cat /sys/bus/rbd/devices/$DEV_ID2/size | grep 76800000

src/init-rbdmap

@@ -29,11 +29,11 @@ fi
 
 case "$1" in
   start)
-	rbdmap map
+	rbdmap device map
 	;;
 
   stop)
-	rbdmap unmap
+	rbdmap device unmap
 	;;
 
   restart|force-reload)
@@ -42,11 +42,11 @@ case "$1" in
 	;;
 
   reload)
-	rbdmap map
+	rbdmap device map
 	;;
 
   status)
-	rbd showmapped
+	rbd device list
 	;;
 
   *)

src/ocf/rbd.in

@@ -123,22 +123,22 @@ do_rbd() {
     ocf_run rbd $rbd_options $@
 }
 
-# Convenience function that uses "rbd showmapped" to retrieve the
+# Convenience function that uses "rbd device list" to retrieve the
 # mapped device name from the pool, RBD name, and snapshot.
 find_rbd_dev() {
     local sedpat
 
-    # Example output from "rbd showmapped" (tab separated):
+    # Example output from "rbd device list" (tab separated):
     # id        pool    image   snap    device
     # 0         rbd     test    -       /dev/rbd0
 
     # Build the sed pattern, substituting "-" for the snapshot name if
     # it's unset
     sedpat="[0-9]\+[ \t]\+${OCF_RESKEY_pool}[ \t]\+${OCF_RESKEY_name}[ \t]\+${OCF_RESKEY_snap:--}[ \t]\+\(/dev/rbd[0-9]\+\).*"
 
-    # Run rbd showmapped, filter out the header line, then try to
+    # Run "rbd device list", filter out the header line, then try to
     # extract the device name
-    rbd showmapped | tail -n +2 | sed -n -e "s,$sedpat,\1,p"
+    rbd device list | tail -n +2 | sed -n -e "s,$sedpat,\1,p"
 }
 
 rbd_validate_all() {
@@ -211,7 +211,7 @@ rbd_start() {
         rbd_name="$rbd_name@${OCF_RESKEY_snap}"
     fi
 
-    do_rbd map $rbd_name $rbd_map_options || exit $OCF_ERR_GENERIC
+    do_rbd device map $rbd_name $rbd_map_options || exit $OCF_ERR_GENERIC
 
     # After the resource has been started, check whether it started up
     # correctly. If the resource starts asynchronously, the agent may
@@ -249,7 +249,7 @@ rbd_stop() {
     # exit with an $OCF_ERR_ error code if anything goes seriously
     # wrong)
     rbd_dev=`find_rbd_dev`
-    do_rbd unmap $rbd_dev || exit $OCF_ERR_GENERIC
+    do_rbd device unmap $rbd_dev || exit $OCF_ERR_GENERIC
 
     # After the resource has been stopped, check whether it shut down
     # correctly. If the resource stops asynchronously, the agent may

src/rbdmap

@@ -27,7 +27,7 @@ do_map() {
 		if [ -b /dev/rbd/$DEV ]; then
 			MAP_RV="$(readlink -f /dev/rbd/$DEV)"
 		else
-			MAP_RV="$(rbd map $DEV $CMDPARAMS 2>&1)"
+			MAP_RV="$(rbd device map $DEV $CMDPARAMS 2>&1)"
 			if [ $? -eq 0 ]; then
 			    newrbd="yes"
 			else
@@ -72,7 +72,7 @@ unmount_unmap() {
 	    fi
 	done
 	## Un-mapping.
-	rbd unmap $rbd_dev >>/dev/null 2>&1
+	rbd device unmap $rbd_dev >>/dev/null 2>&1
 	if [ $? -ne 0 ]; then
 	    logger -p "daemon.warning" -t rbdmap "Failed to unmap '${mnt}'"
 	    return 1

src/stop.sh

@@ -73,19 +73,19 @@ while [ $# -ge 1 ]; do
 done
 
 if [ $stop_all -eq 1 ]; then
-    if "${CEPH_BIN}"/rbd showmapped >/dev/null 2>&1; then
-        "${CEPH_BIN}"/rbd showmapped | tail -n +2 |
+    if "${CEPH_BIN}"/rbd device list >/dev/null 2>&1; then
+        "${CEPH_BIN}"/rbd device list | tail -n +2 |
         while read DEV; do
             # While it is currently possible to create an rbd image with
             # whitespace chars in its name, krbd will refuse mapping such
             # an image, so we can safely split on whitespace here.  (The
             # same goes for whitespace chars in names of the pools that
             # contain rbd images).
             DEV="$(echo "${DEV}" | tr -s '[:space:]' | awk '{ print $5 }')"
-            sudo "${CEPH_BIN}"/rbd unmap "${DEV}"
+            sudo "${CEPH_BIN}"/rbd device unmap "${DEV}"
         done
 
-        if [ -n "$("${CEPH_BIN}"/rbd showmapped)" ]; then
+        if [ -n "$("${CEPH_BIN}"/rbd device list)" ]; then
             echo "WARNING: Some rbd images are still mapped!" >&2
         fi
     fi