1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
|
===============================================
rbd -- manage rados block device (RBD) images
===============================================
.. program:: rbd
Synopsis
========
| **rbd** [ -c *ceph.conf* ] [ -m *monaddr* ] [ -p | --pool *pool* ] [
--size *size* ] [ --order *bits* ] [ *command* ... ]
Description
===========
**rbd** is a utility for manipulating rados block device (RBD) images,
used by the Linux rbd driver and the rbd storage driver for Qemu/KVM.
RBD images are simple block devices that are striped over objects and
stored in a RADOS object store. The size of the objects the image is
striped over must be a power of two.
Options
=======
.. option:: -c ceph.conf, --conf ceph.conf
Use ceph.conf configuration file instead of the default /etc/ceph/ceph.conf to
determine monitor addresses during startup.
.. option:: -m monaddress[:port]
Connect to specified monitor (instead of looking through ceph.conf).
.. option:: -p pool, --pool pool
Interact with the given pool. Required by most commands.
Parameters
==========
.. option:: --format format
Specifies which object layout to use. The default is 1.
* format 1 - Use the original format for a new rbd image. This format is
understood by all versions of librbd and the kernel rbd module, but
does not support newer features like cloning.
* format 2 - Use the second rbd format, which is supported by
librbd (but not the kernel rbd module) at this time. This adds
support for cloning and is more easily extensible to allow more
features in the future.
.. option:: --size size-in-mb
Specifies the size (in megabytes) of the new rbd image.
.. option:: --order bits
Specifies the object size expressed as a number of bits, such that
the object size is ``1 << order``. The default is 22 (4 MB).
.. option:: --snap snap
Specifies the snapshot name for the specific operation.
.. option:: --id username
Specifies the username (without the ``client.'' prefix) to use with the map command.
.. option:: --keyfile filename
Specifies a file containing the secret to use with the map command.
If not specified, ``client.admin'' will be used by default.
.. option:: --keyring filename
Specifies a keyring file containing a secret for the specified user
to use with the map command. If not specified, the default keyring
locations will be searched.
Commands
========
.. TODO rst "option" directive seems to require --foo style options, parsing breaks on subcommands.. the args show up as bold too
:command:`ls` [*pool-name*]
Will list all rbd images listed in the rbd_directory object.
:command:`info` [*image-name*]
Will dump information (such as size and order) about a specific rbd image.
If image is a clone, information about its parent is also displayed.
:command:`create` [*image-name*]
Will create a new rbd image. You must also specify the size via --size.
:command:`clone` [*parent-snapname*] [*image-name*]
Will create a clone (copy-on-write child) of the parent snapshot.
Size and object order will be identical to parent image unless specified.
The parent snapshot must be protected (see `rbd snap protect`).
:command:`flatten` [*image-name*]
If image is a clone, copy all shared blocks from the parent snapshot and
make the child independent of the parent, severing the link between
parent snap and child. The parent snapshot can be unprotected and
deleted if it has no further dependent clones.
:command:`children` [*image-name*]
List the clones of the image at the given snapshot. This checks
every pool, and outputs the resulting poolname/imagename.
:command:`resize` [*image-name*]
Resizes rbd image. The size parameter also needs to be specified.
:command:`rm` [*image-name*]
Deletes an rbd image (including all data blocks). If the image has
snapshots, this fails and nothing is deleted.
:command:`export` [*image-name*] [*dest-path*]
Exports image to dest path.
:command:`import` [*path*] [*dest-image*]
Creates a new image and imports its data from path.
:command:`cp` [*src-image*] [*dest-image*]
Copies the content of a src-image into the newly created dest-image.
:command:`mv` [*src-image*] [*dest-image*]
Renames an image. Note: rename across pools is not supported.
:command:`snap` ls [*image-name*]
Dumps the list of snapshots inside a specific image.
:command:`snap` create [*image-name*]
Creates a new snapshot. Requires the snapshot name parameter specified.
:command:`snap` rollback [*image-name*]
Rollback image content to snapshot. This will iterate through the entire blocks
array and update the data head content to the snapshotted version.
:command:`snap` rm [*image-name*]
Removes the specified snapshot.
:command:`snap` purge [*image-name*]
Removes all snapshots from an image.
:command:`snap` protect [*image-name*]
Protect a snapshot from deletion, so that clones can be made of it
(see `rbd clone`). Snapshots must be protected before clones are made;
protection implies that there exist dependent cloned children that
refer to this snapshot. `rbd clone` will fail on a nonprotected snapshot.
:command:`snap` unprotect [*image-name*]
Unprotect a snapshot from deletion (undo `snap protect`). If cloned
children remain, `snap unprotect` fails. (Note that clones may exist
in different pools than the parent snapshot.)
:command:`map` [*image-name*]
Maps the specified image to a block device via the rbd kernel module.
:command:`unmap` [*device-path*]
Unmaps the block device that was mapped via the rbd kernel module.
:command:`showmapped`
Show the rbd images that are mapped via the rbd kernel module.
Image name
==========
In addition to using the --pool and the --snap options, the image name can include both
the pool name and the snapshot name. The image name format is as follows::
[pool/]image-name[@snap]
Thus an image name that contains a slash character ('/') requires specifying the pool
name explicitly.
Examples
========
To create a new rbd image that is 100 GB::
rbd -p mypool create myimage --size 102400
or alternatively::
rbd create mypool/myimage --size 102400
To use a non-default object size (8 MB)::
rbd create mypool/myimage --size 102400 --order 23
To delete an rbd image (be careful!)::
rbd rm mypool/myimage
To create a new snapshot::
rbd snap create mypool/myimage@mysnap
To create a copy-on-write clone of a snapshot::
rbd clone myimage@mysnap cloneimage
To delete a snapshot::
rbd snap rm mypool/myimage@mysnap
To map an image via the kernel with cephx enabled::
rbd map myimage --id admin --keyfile secretfile
To unmap an image::
rbd unmap /dev/rbd0
Availability
============
**rbd** is part of the Ceph distributed file system. Please refer to
the Ceph documentation at http://ceph.com/docs for more information.
See also
========
:doc:`ceph <ceph>`\(8),
:doc:`rados <rados>`\(8)
|
