1 =======================
3 =======================
5 .. index:: Ceph Block Device; image management
7 The ``rbd`` command enables you to create, list, introspect and remove block
8 device images. You can also use it to clone images, create snapshots,
9 rollback an image to a snapshot, view a snapshot, etc. For details on using
10 the ``rbd`` command, see `RBD – Manage RADOS Block Device (RBD) Images`_ for
13 .. important:: To use Ceph Block Device commands, you must have access to
14 a running Ceph cluster.
16 Create a Block Device Pool
17 ==========================
19 #. On the admin node, use the ``ceph`` tool to `create a pool`_.
21 #. On the admin node, use the ``rbd`` tool to initialize the pool for use by RBD::
23 rbd pool init <pool-name>
25 .. note:: The ``rbd`` tool assumes a default pool name of 'rbd' when not
28 Create a Block Device User
29 ==========================
31 Unless specified, the ``rbd`` command will access the Ceph cluster using the ID
32 ``admin``. This ID allows full administrative access to the cluster. It is
33 recommended that you utilize a more restricted user wherever possible.
35 To `create a Ceph user`_, with ``ceph`` specify the ``auth get-or-create``
36 command, user name, monitor caps, and OSD caps::
38 ceph auth get-or-create client.{ID} mon 'profile rbd' osd 'profile {profile name} [pool={pool-name}][, profile ...]'
40 For example, to create a user ID named ``qemu`` with read-write access to the
41 pool ``vms`` and read-only access to the pool ``images``, execute the
44 ceph auth get-or-create client.qemu mon 'profile rbd' osd 'profile rbd pool=vms, profile rbd-read-only pool=images'
46 The output from the ``ceph auth get-or-create`` command will be the keyring for
47 the specified user, which can be written to ``/etc/ceph/ceph.client.{ID}.keyring``.
49 .. note:: The user ID can be specified when using the ``rbd`` command by
50 providing the ``--id {id}`` optional argument.
52 Creating a Block Device Image
53 =============================
55 Before you can add a block device to a node, you must create an image for it in
56 the :term:`Ceph Storage Cluster` first. To create a block device image, execute
59 rbd create --size {megabytes} {pool-name}/{image-name}
61 For example, to create a 1GB image named ``bar`` that stores information in a
62 pool named ``swimmingpool``, execute the following::
64 rbd create --size 1024 swimmingpool/bar
66 If you don't specify pool when creating an image, it will be stored in the
67 default pool ``rbd``. For example, to create a 1GB image named ``foo`` stored in
68 the default pool ``rbd``, execute the following::
70 rbd create --size 1024 foo
72 .. note:: You must create a pool first before you can specify it as a
73 source. See `Storage Pools`_ for details.
75 Listing Block Device Images
76 ===========================
78 To list block devices in the ``rbd`` pool, execute the following
79 (i.e., ``rbd`` is the default pool name)::
83 To list block devices in a particular pool, execute the following,
84 but replace ``{poolname}`` with the name of the pool::
92 To list deferred delete block devices in the ``rbd`` pool, execute the
97 To list deferred delete block devices in a particular pool, execute the
98 following, but replace ``{poolname}`` with the name of the pool::
100 rbd trash ls {poolname}
104 rbd trash ls swimmingpool
106 Retrieving Image Information
107 ============================
109 To retrieve information from a particular image, execute the following,
110 but replace ``{image-name}`` with the name for the image::
112 rbd info {image-name}
118 To retrieve information from an image within a pool, execute the following,
119 but replace ``{image-name}`` with the name of the image and replace ``{pool-name}``
120 with the name of the pool::
122 rbd info {pool-name}/{image-name}
126 rbd info swimmingpool/bar
128 Resizing a Block Device Image
129 =============================
131 :term:`Ceph Block Device` images are thin provisioned. They don't actually use
132 any physical storage until you begin saving data to them. However, they do have
133 a maximum capacity that you set with the ``--size`` option. If you want to
134 increase (or decrease) the maximum size of a Ceph Block Device image, execute
137 rbd resize --size 2048 foo (to increase)
138 rbd resize --size 2048 foo --allow-shrink (to decrease)
141 Removing a Block Device Image
142 =============================
144 To remove a block device, execute the following, but replace ``{image-name}``
145 with the name of the image you want to remove::
153 To remove a block device from a pool, execute the following, but replace
154 ``{image-name}`` with the name of the image to remove and replace
155 ``{pool-name}`` with the name of the pool::
157 rbd rm {pool-name}/{image-name}
161 rbd rm swimmingpool/bar
163 To defer delete a block device from a pool, execute the following, but
164 replace ``{image-name}`` with the name of the image to move and replace
165 ``{pool-name}`` with the name of the pool::
167 rbd trash mv {pool-name}/{image-name}
171 rbd trash mv swimmingpool/bar
173 To remove a deferred block device from a pool, execute the following, but
174 replace ``{image-id}`` with the id of the image to remove and replace
175 ``{pool-name}`` with the name of the pool::
177 rbd trash rm {pool-name}/{image-id}
181 rbd trash rm swimmingpool/2bf4474b0dc51
185 * You can move an image to the trash even it has shapshot(s) or actively
186 in-use by clones, but can not be removed from trash.
188 * You can use *--delay* to set the defer time (default is 0), and if its
189 deferment time has not expired, it can not be removed unless you use
192 Restoring a Block Device Image
193 ==============================
195 To restore a deferred delete block device in the rbd pool, execute the
196 following, but replace ``{image-id}`` with the id of the image::
198 rbd trash restore {image-d}
202 rbd trash restore 2bf4474b0dc51
204 To restore a deferred delete block device in a particular pool, execute
205 the following, but replace ``{image-id}`` with the id of the image and
206 replace ``{pool-name}`` with the name of the pool::
208 rbd trash restore {pool-name}/{image-id}
212 rbd trash restore swimmingpool/2bf4474b0dc51
214 Also you can use *--image* to rename the iamge when restore it, for
217 rbd trash restore swimmingpool/2bf4474b0dc51 --image new-name
220 .. _create a pool: ../../rados/operations/pools/#create-a-pool
221 .. _Storage Pools: ../../rados/operations/pools
222 .. _RBD – Manage RADOS Block Device (RBD) Images: ../../man/8/rbd/
223 .. _create a Ceph user: ../../rados/operations/user-management#add-a-user