diff options
Diffstat (limited to 'doc/man/8/rbdmap.rst')
| -rw-r--r-- | doc/man/8/rbdmap.rst | 128 |
1 files changed, 128 insertions, 0 deletions
diff --git a/doc/man/8/rbdmap.rst b/doc/man/8/rbdmap.rst new file mode 100644 index 000000000..1a9096a99 --- /dev/null +++ b/doc/man/8/rbdmap.rst @@ -0,0 +1,128 @@ +:orphan: + +========================================= + rbdmap -- map RBD devices at boot time +========================================= + +.. program:: rbdmap + +Synopsis +======== + +| **rbdmap map** +| **rbdmap unmap** + + +Description +=========== + +**rbdmap** is a shell script that automates ``rbd map`` and ``rbd unmap`` +operations on one or more RBD (RADOS Block Device) images. While the script can be +run manually by the system administrator at any time, the principal use case is +automatic mapping/mounting of RBD images at boot time (and unmounting/unmapping +at shutdown), as triggered by the init system (a systemd unit file, +``rbdmap.service`` is included with the ceph-common package for this purpose). + +The script takes a single argument, which can be either "map" or "unmap". +In either case, the script parses a configuration file (defaults to ``/etc/ceph/rbdmap``, +but can be overridden via an environment variable ``RBDMAPFILE``). Each line +of the configuration file corresponds to an RBD image which is to be mapped, or +unmapped. + +The configuration file format is:: + + IMAGESPEC RBDOPTS + +where ``IMAGESPEC`` should be specified as ``POOLNAME/IMAGENAME`` (the pool +name, a forward slash, and the image name), or merely ``IMAGENAME``, in which +case the ``POOLNAME`` defaults to "rbd". ``RBDOPTS`` is an optional list of +parameters to be passed to the underlying ``rbd map`` command. These parameters +and their values should be specified as a comma-separated string:: + + PARAM1=VAL1,PARAM2=VAL2,...,PARAMN=VALN + +This will cause the script to issue an ``rbd map`` command like the following:: + + rbd map POOLNAME/IMAGENAME --PARAM1 VAL1 --PARAM2 VAL2 + +(See the ``rbd`` manpage for a full list of possible options.) +For parameters and values which contain commas or equality signs, a simple +apostrophe can be used to prevent replacing them. + +When run as ``rbdmap map``, the script parses the configuration file, and for +each RBD image specified attempts to first map the image (using the ``rbd map`` +command) and, second, to mount the image. + +When run as ``rbdmap unmap``, images listed in the configuration file will +be unmounted and unmapped. + +``rbdmap unmap-all`` attempts to unmount and subsequently unmap all currently +mapped RBD images, regardless of whether or not they are listed in the +configuration file. + +If successful, the ``rbd map`` operation maps the image to a ``/dev/rbdX`` +device, at which point a udev rule is triggered to create a friendly device +name symlink, ``/dev/rbd/POOLNAME/IMAGENAME``, pointing to the real mapped +device. + +In order for mounting/unmounting to succeed, the friendly device name must +have a corresponding entry in ``/etc/fstab``. + +When writing ``/etc/fstab`` entries for RBD images, it's a good idea to specify +the "noauto" (or "nofail") mount option. This prevents the init system from +trying to mount the device too early - before the device in question even +exists. (Since ``rbdmap.service`` +executes a shell script, it is typically triggered quite late in the boot +sequence.) + + +Examples +======== + +Example ``/etc/ceph/rbdmap`` for three RBD images called "bar1", "bar2" and "bar3", +which are in pool "foopool":: + + foopool/bar1 id=admin,keyring=/etc/ceph/ceph.client.admin.keyring + foopool/bar2 id=admin,keyring=/etc/ceph/ceph.client.admin.keyring + foopool/bar3 id=admin,keyring=/etc/ceph/ceph.client.admin.keyring,options='lock_on_read,queue_depth=1024' + +Each line in the file contains two strings: the image spec and the options to +be passed to ``rbd map``. These two lines get transformed into the following +commands:: + + rbd map foopool/bar1 --id admin --keyring /etc/ceph/ceph.client.admin.keyring + rbd map foopool/bar2 --id admin --keyring /etc/ceph/ceph.client.admin.keyring + rbd map foopool/bar2 --id admin --keyring /etc/ceph/ceph.client.admin.keyring --options lock_on_read,queue_depth=1024 + +If the images had XFS file systems on them, the corresponding ``/etc/fstab`` +entries might look like this:: + + /dev/rbd/foopool/bar1 /mnt/bar1 xfs noauto 0 0 + /dev/rbd/foopool/bar2 /mnt/bar2 xfs noauto 0 0 + /dev/rbd/foopool/bar3 /mnt/bar3 xfs noauto 0 0 + +After creating the images and populating the ``/etc/ceph/rbdmap`` file, making +the images get automatically mapped and mounted at boot is just a matter of +enabling that unit:: + + systemctl enable rbdmap.service + + +Options +======= + +None + + +Availability +============ + +**rbdmap** is part of Ceph, a massively scalable, open-source, distributed +storage system. Please refer to the Ceph documentation at +https://docs.ceph.com for more information. + + +See also +======== + +:doc:`rbd <rbd>`\(8), |