[ceph.git] / ceph / doc / man / 8 / rbdmap.rst

: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.)

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 two RBD images called "bar1" and "bar2", both
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

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

If the images had XFS filesystems 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

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
http://ceph.com/docs for more information.


See also
========

:doc:`rbd <rbd>`\(8),
Commit	Line	Data
7c673cae FG	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
c07f9fc5	58	mapped RBD images, regardless of whether or not they are listed in the
7c673cae FG	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),