src/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
  50 When run as ``rbdmap map``, the script parses the configuration file, and for
  51 each RBD image specified attempts to first map the image (using the ``rbd map``
  52 command) and, second, to mount the image.
  53
  54 When run as ``rbdmap unmap``, images listed in the configuration file will
  55 be unmounted and unmapped.
  56
  57 ``rbdmap unmap-all`` attempts to unmount and subsequently unmap all currently
  58 mapped RBD images, regardless of whether or not they are listed in the
  59 configuration file.
  60
  61 If successful, the ``rbd map`` operation maps the image to a ``/dev/rbdX``
  62 device, at which point a udev rule is triggered to create a friendly device
  63 name symlink, ``/dev/rbd/POOLNAME/IMAGENAME``, pointing to the real mapped
  64 device.
  65
  66 In order for mounting/unmounting to succeed, the friendly device name must
  67 have a corresponding entry in ``/etc/fstab``.
  68
  69 When writing ``/etc/fstab`` entries for RBD images, it's a good idea to specify
  70 the "noauto" (or "nofail") mount option. This prevents the init system from
  71 trying to mount the device too early - before the device in question even
  72 exists. (Since ``rbdmap.service``
  73 executes a shell script, it is typically triggered quite late in the boot
  74 sequence.)
  75
  76
  77 Examples
  78 ========
  79
  80 Example ``/etc/ceph/rbdmap`` for two RBD images called "bar1" and "bar2", both
  81 in pool "foopool"::
  82
  83     foopool/bar1    id=admin,keyring=/etc/ceph/ceph.client.admin.keyring
  84     foopool/bar2    id=admin,keyring=/etc/ceph/ceph.client.admin.keyring
  85
  86 Each line in the file contains two strings: the image spec and the options to
  87 be passed to ``rbd map``. These two lines get transformed into the following
  88 commands::
  89
  90     rbd map foopool/bar1 --id admin --keyring /etc/ceph/ceph.client.admin.keyring
  91     rbd map foopool/bar2 --id admin --keyring /etc/ceph/ceph.client.admin.keyring
  92
  93 If the images had XFS filesystems on them, the corresponding ``/etc/fstab``
  94 entries might look like this::
  95
  96     /dev/rbd/foopool/bar1 /mnt/bar1 xfs noauto 0 0
  97     /dev/rbd/foopool/bar2 /mnt/bar2 xfs noauto 0 0
  98
  99 After creating the images and populating the ``/etc/ceph/rbdmap`` file, making
 100 the images get automatically mapped and mounted at boot is just a matter of
 101 enabling that unit::
 102
 103     systemctl enable rbdmap.service
 104
 105
 106 Options
 107 =======
 108
 109 None
 110
 111
 112 Availability
 113 ============
 114
 115 **rbdmap** is part of Ceph, a massively scalable, open-source, distributed
 116 storage system. Please refer to the Ceph documentation at
 117 http://ceph.com/docs for more information.
 118
 119
 120 See also
 121 ========
 122
 123 :doc:`rbd <rbd>`\(8),