1RBDMAP(8)                            Ceph                            RBDMAP(8)
2
3
4

NAME

6       rbdmap - map RBD devices at boot time
7

SYNOPSIS

9       rbdmap map
10       rbdmap unmap
11
12

DESCRIPTION

14       rbdmap  is  a  shell script that automates rbd map and rbd unmap opera‐
15       tions on one or more RBD (RADOS Block Device) images. While the  script
16       can  be run manually by the system administrator at any time, the prin‐
17       cipal use case is automatic mapping/mounting of RBD images at boot time
18       (and unmounting/unmapping at shutdown), as triggered by the init system
19       (a systemd unit file, rbdmap.service is included with  the  ceph-common
20       package for this purpose).
21
22       The  script  takes a single argument, which can be either "map" or "un‐
23       map".  In either case, the script parses a configuration file (defaults
24       to  /etc/ceph/rbdmap, but can be overridden via an environment variable
25       RBDMAPFILE). Each line of the configuration file corresponds to an  RBD
26       image which is to be mapped, or unmapped.
27
28       The configuration file format is:
29
30          IMAGESPEC RBDOPTS
31
32       where  IMAGESPEC  should  be  specified as POOLNAME/IMAGENAME (the pool
33       name, a forward slash, and the image name),  or  merely  IMAGENAME,  in
34       which  case the POOLNAME defaults to "rbd". RBDOPTS is an optional list
35       of parameters to be passed to the underlying rbd map command. These pa‐
36       rameters  and  their  values  should  be specified as a comma-separated
37       string:
38
39          PARAM1=VAL1,PARAM2=VAL2,...,PARAMN=VALN
40
41       This will cause the script to issue an rbd map command like the follow‐
42       ing:
43
44          rbd map POOLNAME/IMAGENAME --PARAM1 VAL1 --PARAM2 VAL2
45
46       (See the rbd manpage for a full list of possible options.)  For parame‐
47       ters and values which contain commas or equality signs, a simple  apos‐
48       trophe can be used to prevent replacing them.
49
50       When  run  as rbdmap map, the script parses the configuration file, and
51       for each RBD image specified attempts to first map the image (using the
52       rbd map 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  cur‐
58       rently  mapped RBD images, regardless of whether or not they are listed
59       in the configuration file.
60
61       If successful, the rbd map operation maps the image to a /dev/rbdX  de‐
62       vice,  at which point a udev rule is triggered to create a friendly de‐
63       vice name symlink, /dev/rbd/POOLNAME/IMAGENAME, pointing  to  the  real
64       mapped device.
65
66       In  order  for mounting/unmounting to succeed, the friendly device name
67       must have a corresponding entry in /etc/fstab.
68
69       When writing /etc/fstab entries for RBD images, it's  a  good  idea  to
70       specify the "noauto" (or "nofail") mount option. This prevents the init
71       system from trying to mount the device too early - before the device in
72       question even exists. (Since rbdmap.service executes a shell script, it
73       is typically triggered quite late in the boot sequence.)
74

EXAMPLES

76       Example /etc/ceph/rbdmap for three RBD images called "bar1", "bar2" and
77       "bar3", which are in pool "foopool":
78
79          foopool/bar1    id=admin,keyring=/etc/ceph/ceph.client.admin.keyring
80          foopool/bar2    id=admin,keyring=/etc/ceph/ceph.client.admin.keyring
81          foopool/bar3    id=admin,keyring=/etc/ceph/ceph.client.admin.keyring,options='lock_on_read,queue_depth=1024'
82
83       Each  line in the file contains two strings: the image spec and the op‐
84       tions to be passed to rbd map. These two lines get transformed into the
85       following commands:
86
87          rbd map foopool/bar1 --id admin --keyring /etc/ceph/ceph.client.admin.keyring
88          rbd map foopool/bar2 --id admin --keyring /etc/ceph/ceph.client.admin.keyring
89          rbd map foopool/bar2 --id admin --keyring /etc/ceph/ceph.client.admin.keyring --options lock_on_read,queue_depth=1024
90
91       If  the  images  had  XFS  file  systems  on  them,  the  corresponding
92       /etc/fstab entries might look like this:
93
94          /dev/rbd/foopool/bar1 /mnt/bar1 xfs noauto 0 0
95          /dev/rbd/foopool/bar2 /mnt/bar2 xfs noauto 0 0
96          /dev/rbd/foopool/bar3 /mnt/bar3 xfs noauto 0 0
97
98       After creating the images and  populating  the  /etc/ceph/rbdmap  file,
99       making  the images get automatically mapped and mounted at boot is just
100       a matter of enabling that unit:
101
102          systemctl enable rbdmap.service
103

OPTIONS

105       None
106

AVAILABILITY

108       rbdmap is part of Ceph, a massively scalable, open-source,  distributed
109       storage   system.   Please   refer   to   the   Ceph  documentation  at
110       https://docs.ceph.com for more information.
111

SEE ALSO

113       rbd(8),
114

116       2010-2023, Inktank Storage, Inc. and contributors. Licensed under  Cre‐
117       ative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)
118
119
120
121
122dev                              Nov 02, 2023                        RBDMAP(8)
Impressum