NAME

       rbdmap - map RBD devices at boot time

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

       rbd(8),

COPYRIGHT

       2010-2024, Inktank Storage, Inc. and contributors. Licensed  under  Creative  Commons  Attribution  Share
       Alike 3.0 (CC-BY-SA-3.0)

dev                                               Dec 18, 2024                                         RBDMAP(8)