ceph/doc/man/8/rbdmap.rst

   1 :orphan:
   2
   3 =========================================
   4  rbdmap -- map RBD devices at boot time
   5 =========================================
   6
   7 .. program:: rbdmap
   8
   9 Synopsis
  10 ========
  11
  12 | **rbdmap map**
  13 | **rbdmap unmap**
  14
  15
  16 Description
  17 ===========
  18
  19 **rbdmap** is a shell script that automates ``rbd map`` and ``rbd unmap``
  20 operations on one or more RBD (RADOS Block Device) images. While the script can be
  21 run manually by the system administrator at any time, the principal use case is
  22 automatic mapping/mounting of RBD images at boot time (and unmounting/unmapping
  23 at shutdown), as triggered by the init system (a systemd unit file,
  24 ``rbdmap.service`` is included with the ceph-common package for this purpose).
  25
  26 The script takes a single argument, which can be either "map" or "unmap".
  27 In either case, the script parses a configuration file (defaults to ``/etc/ceph/rbdmap``,
  28 but can be overridden via an environment variable ``RBDMAPFILE``). Each line
  29 of the configuration file corresponds to an RBD image which is to be mapped, or
  30 unmapped.
  31
  32 The configuration file format is::
  33
  34     IMAGESPEC RBDOPTS
  35
  36 where ``IMAGESPEC`` should be specified as ``POOLNAME/IMAGENAME`` (the pool
  37 name, a forward slash, and the image name), or merely ``IMAGENAME``, in which
  38 case the ``POOLNAME`` defaults to "rbd". ``RBDOPTS`` is an optional list of
  39 parameters to be passed to the underlying ``rbd map`` command. These parameters
  40 and their values should be specified as a comma-separated string::
  41
  42     PARAM1=VAL1,PARAM2=VAL2,...,PARAMN=VALN
  43
  44 This will cause the script to issue an ``rbd map`` command like the following::
  45
  46     rbd map POOLNAME/IMAGENAME --PARAM1 VAL1 --PARAM2 VAL2
  47
  48 (See the ``rbd`` manpage for a full list of possible options.)
  49 For parameters and values which contain commas or equality signs, a simple
  50 apostrophe can be used to prevent replacing them.
  51
  52 When run as ``rbdmap map``, the script parses the configuration file, and for
  53 each RBD image specified attempts to first map the image (using the ``rbd map``
  54 command) and, second, to mount the image.
  55
  56 When run as ``rbdmap unmap``, images listed in the configuration file will
  57 be unmounted and unmapped.
  58
  59 ``rbdmap unmap-all`` attempts to unmount and subsequently unmap all currently
  60 mapped RBD images, regardless of whether or not they are listed in the
  61 configuration file.
  62
  63 If successful, the ``rbd map`` operation maps the image to a ``/dev/rbdX``
  64 device, at which point a udev rule is triggered to create a friendly device
  65 name symlink, ``/dev/rbd/POOLNAME/IMAGENAME``, pointing to the real mapped
  66 device.
  67
  68 In order for mounting/unmounting to succeed, the friendly device name must
  69 have a corresponding entry in ``/etc/fstab``.
  70
  71 When writing ``/etc/fstab`` entries for RBD images, it's a good idea to specify
  72 the "noauto" (or "nofail") mount option. This prevents the init system from
  73 trying to mount the device too early - before the device in question even
  74 exists. (Since ``rbdmap.service``
  75 executes a shell script, it is typically triggered quite late in the boot
  76 sequence.)
  77
  78
  79 Examples
  80 ========
  81
  82 Example ``/etc/ceph/rbdmap`` for three RBD images called "bar1", "bar2" and "bar3",
  83 which are in pool "foopool"::
  84
  85     foopool/bar1    id=admin,keyring=/etc/ceph/ceph.client.admin.keyring
  86     foopool/bar2    id=admin,keyring=/etc/ceph/ceph.client.admin.keyring
  87     foopool/bar3    id=admin,keyring=/etc/ceph/ceph.client.admin.keyring,options='lock_on_read,queue_depth=1024'
  88
  89 Each line in the file contains two strings: the image spec and the options to
  90 be passed to ``rbd map``. These two lines get transformed into the following
  91 commands::
  92
  93     rbd map foopool/bar1 --id admin --keyring /etc/ceph/ceph.client.admin.keyring
  94     rbd map foopool/bar2 --id admin --keyring /etc/ceph/ceph.client.admin.keyring
  95     rbd map foopool/bar2 --id admin --keyring /etc/ceph/ceph.client.admin.keyring --options lock_on_read,queue_depth=1024
  96
  97 If the images had XFS file systems on them, the corresponding ``/etc/fstab``
  98 entries might look like this::
  99
 100     /dev/rbd/foopool/bar1 /mnt/bar1 xfs noauto 0 0
 101     /dev/rbd/foopool/bar2 /mnt/bar2 xfs noauto 0 0
 102     /dev/rbd/foopool/bar3 /mnt/bar3 xfs noauto 0 0
 103
 104 After creating the images and populating the ``/etc/ceph/rbdmap`` file, making
 105 the images get automatically mapped and mounted at boot is just a matter of
 106 enabling that unit::
 107
 108     systemctl enable rbdmap.service
 109
 110
 111 Options
 112 =======
 113
 114 None
 115
 116
 117 Availability
 118 ============
 119
 120 **rbdmap** is part of Ceph, a massively scalable, open-source, distributed
 121 storage system. Please refer to the Ceph documentation at
 122 https://docs.ceph.com for more information.
 123
 124
 125 See also
 126 ========
 127
 128 :doc:`rbd <rbd>`\(8),