]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | :orphan: |
2 | ||
3 | =============================================== | |
4 | rbd -- manage rados block device (RBD) images | |
5 | =============================================== | |
6 | ||
7 | .. program:: rbd | |
8 | ||
9 | Synopsis | |
10 | ======== | |
11 | ||
12 | | **rbd** [ -c *ceph.conf* ] [ -m *monaddr* ] [--cluster *cluster-name*] | |
13 | [ -p | --pool *pool* ] [ *command* ... ] | |
14 | ||
15 | ||
16 | Description | |
17 | =========== | |
18 | ||
19 | **rbd** is a utility for manipulating rados block device (RBD) images, | |
20 | used by the Linux rbd driver and the rbd storage driver for QEMU/KVM. | |
21 | RBD images are simple block devices that are striped over objects and | |
22 | stored in a RADOS object store. The size of the objects the image is | |
23 | striped over must be a power of two. | |
24 | ||
25 | ||
26 | Options | |
27 | ======= | |
28 | ||
29 | .. option:: -c ceph.conf, --conf ceph.conf | |
30 | ||
31 | Use ceph.conf configuration file instead of the default /etc/ceph/ceph.conf to | |
32 | determine monitor addresses during startup. | |
33 | ||
34 | .. option:: -m monaddress[:port] | |
35 | ||
36 | Connect to specified monitor (instead of looking through ceph.conf). | |
37 | ||
38 | .. option:: --cluster cluster-name | |
39 | ||
40 | Use different cluster name as compared to default cluster name *ceph*. | |
41 | ||
42 | .. option:: -p pool-name, --pool pool-name | |
43 | ||
44 | Interact with the given pool. Required by most commands. | |
45 | ||
11fdf7f2 TL |
46 | .. option:: --namespace namespace-name |
47 | ||
48 | Use a pre-defined image namespace within a pool | |
49 | ||
7c673cae FG |
50 | .. option:: --no-progress |
51 | ||
52 | Do not output progress information (goes to standard error by | |
53 | default for some commands). | |
54 | ||
55 | ||
56 | Parameters | |
57 | ========== | |
58 | ||
59 | .. option:: --image-format format-id | |
60 | ||
61 | Specifies which object layout to use. The default is 2. | |
62 | ||
63 | * format 1 - (deprecated) Use the original format for a new rbd image. This | |
64 | format is understood by all versions of librbd and the kernel rbd module, | |
65 | but does not support newer features like cloning. | |
66 | ||
67 | * format 2 - Use the second rbd format, which is supported by | |
68 | librbd and kernel since version 3.11 (except for striping). This adds | |
69 | support for cloning and is more easily extensible to allow more | |
70 | features in the future. | |
71 | ||
72 | .. option:: -s size-in-M/G/T, --size size-in-M/G/T | |
73 | ||
74 | Specifies the size of the new rbd image or the new size of the existing rbd | |
75 | image in M/G/T. If no suffix is given, unit M is assumed. | |
76 | ||
77 | .. option:: --object-size size-in-B/K/M | |
78 | ||
79 | Specifies the object size in B/K/M. Object size will be rounded up the | |
80 | nearest power of two; if no suffix is given, unit B is assumed. The default | |
81 | object size is 4M, smallest is 4K and maximum is 32M. | |
82 | ||
83 | .. option:: --stripe-unit size-in-B/K/M | |
84 | ||
85 | Specifies the stripe unit size in B/K/M. If no suffix is given, unit B is | |
86 | assumed. See striping section (below) for more details. | |
87 | ||
88 | .. option:: --stripe-count num | |
89 | ||
90 | Specifies the number of objects to stripe over before looping back | |
91 | to the first object. See striping section (below) for more details. | |
92 | ||
93 | .. option:: --snap snap | |
94 | ||
95 | Specifies the snapshot name for the specific operation. | |
96 | ||
97 | .. option:: --id username | |
98 | ||
99 | Specifies the username (without the ``client.`` prefix) to use with the map command. | |
100 | ||
101 | .. option:: --keyring filename | |
102 | ||
103 | Specifies a keyring file containing a secret for the specified user | |
104 | to use with the map command. If not specified, the default keyring | |
105 | locations will be searched. | |
106 | ||
107 | .. option:: --keyfile filename | |
108 | ||
109 | Specifies a file containing the secret key of ``--id user`` to use with the map command. | |
110 | This option is overridden by ``--keyring`` if the latter is also specified. | |
111 | ||
112 | .. option:: --shared lock-tag | |
113 | ||
114 | Option for `lock add` that allows multiple clients to lock the | |
115 | same image if they use the same tag. The tag is an arbitrary | |
116 | string. This is useful for situations where an image must | |
117 | be open from more than one client at once, like during | |
118 | live migration of a virtual machine, or for use underneath | |
119 | a clustered filesystem. | |
120 | ||
121 | .. option:: --format format | |
122 | ||
123 | Specifies output formatting (default: plain, json, xml) | |
124 | ||
125 | .. option:: --pretty-format | |
126 | ||
127 | Make json or xml formatted output more human-readable. | |
128 | ||
129 | .. option:: -o krbd-options, --options krbd-options | |
130 | ||
131 | Specifies which options to use when mapping or unmapping an image via the | |
132 | rbd kernel driver. krbd-options is a comma-separated list of options | |
133 | (similar to mount(8) mount options). See kernel rbd (krbd) options section | |
134 | below for more details. | |
135 | ||
136 | .. option:: --read-only | |
137 | ||
138 | Map the image read-only. Equivalent to -o ro. | |
139 | ||
140 | .. option:: --image-feature feature-name | |
141 | ||
142 | Specifies which RBD format 2 feature should be enabled when creating | |
143 | an image. Multiple features can be enabled by repeating this option | |
144 | multiple times. The following features are supported: | |
145 | ||
146 | * layering: layering support | |
147 | * striping: striping v2 support | |
148 | * exclusive-lock: exclusive locking support | |
149 | * object-map: object map support (requires exclusive-lock) | |
150 | * fast-diff: fast diff calculations (requires object-map) | |
151 | * deep-flatten: snapshot flatten support | |
152 | * journaling: journaled IO support (requires exclusive-lock) | |
11fdf7f2 | 153 | * data-pool: erasure coded pool support |
7c673cae FG |
154 | |
155 | .. option:: --image-shared | |
156 | ||
157 | Specifies that the image will be used concurrently by multiple clients. | |
158 | This will disable features that are dependent upon exclusive ownership | |
159 | of the image. | |
160 | ||
161 | .. option:: --whole-object | |
162 | ||
163 | Specifies that the diff should be limited to the extents of a full object | |
164 | instead of showing intra-object deltas. When the object map feature is | |
165 | enabled on an image, limiting the diff to the object extents will | |
166 | dramatically improve performance since the differences can be computed | |
167 | by examining the in-memory object map instead of querying RADOS for each | |
168 | object within the image. | |
169 | ||
170 | .. option:: --limit | |
171 | ||
172 | Specifies the limit for the number of snapshots permitted. | |
173 | ||
174 | Commands | |
175 | ======== | |
176 | ||
177 | .. TODO rst "option" directive seems to require --foo style options, parsing breaks on subcommands.. the args show up as bold too | |
178 | ||
11fdf7f2 TL |
179 | :command:`bench` --io-type <read | write | readwrite | rw> [--io-size *size-in-B/K/M/G/T*] [--io-threads *num-ios-in-flight*] [--io-total *size-in-B/K/M/G/T*] [--io-pattern seq | rand] [--rw-mix-read *read proportion in readwrite*] *image-spec* |
180 | Generate a series of IOs to the image and measure the IO throughput and | |
181 | latency. If no suffix is given, unit B is assumed for both --io-size and | |
182 | --io-total. Defaults are: --io-size 4096, --io-threads 16, --io-total 1G, | |
183 | --io-pattern seq, --rw-mix-read 50. | |
184 | ||
185 | :command:`children` *snap-spec* | |
186 | List the clones of the image at the given snapshot. This checks | |
187 | every pool, and outputs the resulting poolname/imagename. | |
188 | ||
189 | This requires image format 2. | |
190 | ||
191 | :command:`clone` [--object-size *size-in-B/K/M*] [--stripe-unit *size-in-B/K/M* --stripe-count *num*] [--image-feature *feature-name*] [--image-shared] *parent-snap-spec* *child-image-spec* | |
192 | Will create a clone (copy-on-write child) of the parent snapshot. | |
193 | Object size will be identical to that of the parent image unless | |
194 | specified. Size will be the same as the parent snapshot. The --stripe-unit | |
195 | and --stripe-count arguments are optional, but must be used together. | |
196 | ||
197 | The parent snapshot must be protected (see `rbd snap protect`). | |
198 | This requires image format 2. | |
199 | ||
200 | :command:`config global get` *config-entity* *key* | |
201 | Get a global-level configuration override. | |
202 | ||
203 | :command:`config global list` [--format plain | json | xml] [--pretty-format] *config-entity* | |
204 | List global-level configuration overrides. | |
205 | ||
206 | :command:`config global set` *config-entity* *key* *value* | |
207 | Set a global-level configuration override. | |
208 | ||
209 | :command:`config global remove` *config-entity* *key* | |
210 | Remove a global-level configuration override. | |
211 | ||
212 | :command:`config image get` *image-spec* *key* | |
213 | Get an image-level configuration override. | |
214 | ||
215 | :command:`config image list` [--format plain | json | xml] [--pretty-format] *image-spec* | |
216 | List image-level configuration overrides. | |
217 | ||
218 | :command:`config image set` *image-spec* *key* *value* | |
219 | Set an image-level configuration override. | |
220 | ||
221 | :command:`config image remove` *image-spec* *key* | |
222 | Remove an image-level configuration override. | |
223 | ||
224 | :command:`config pool get` *pool-name* *key* | |
225 | Get a pool-level configuration override. | |
226 | ||
227 | :command:`config pool list` [--format plain | json | xml] [--pretty-format] *pool-name* | |
228 | List pool-level configuration overrides. | |
229 | ||
230 | :command:`config pool set` *pool-name* *key* *value* | |
231 | Set a pool-level configuration override. | |
232 | ||
233 | :command:`config pool remove` *pool-name* *key* | |
234 | Remove a pool-level configuration override. | |
235 | ||
236 | :command:`cp` (*src-image-spec* | *src-snap-spec*) *dest-image-spec* | |
237 | Copy the content of a src-image into the newly created dest-image. | |
238 | dest-image will have the same size, object size, and image format as src-image. | |
239 | ||
240 | :command:`create` (-s | --size *size-in-M/G/T*) [--image-format *format-id*] [--object-size *size-in-B/K/M*] [--stripe-unit *size-in-B/K/M* --stripe-count *num*] [--thick-provision] [--no-progress] [--image-feature *feature-name*]... [--image-shared] *image-spec* | |
241 | Will create a new rbd image. You must also specify the size via --size. The | |
242 | --stripe-unit and --stripe-count arguments are optional, but must be used together. | |
243 | If the --thick-provision is enabled, it will fully allocate storage for | |
244 | the image at creation time. It will take a long time to do. | |
245 | Note: thick provisioning requires zeroing the contents of the entire image. | |
246 | ||
247 | :command:`deep cp` (*src-image-spec* | *src-snap-spec*) *dest-image-spec* | |
248 | Deep copy the content of a src-image into the newly created dest-image. | |
249 | Dest-image will have the same size, object size, image format, and snapshots as src-image. | |
250 | ||
251 | :command:`device list` [-t | --device-type *device-type*] [--format plain | json | xml] --pretty-format | |
252 | Show the rbd images that are mapped via the rbd kernel module | |
253 | (default) or other supported device. | |
254 | ||
255 | :command:`device map` [-t | --device-type *device-type*] [--read-only] [--exclusive] [-o | --options *device-options*] *image-spec* | *snap-spec* | |
256 | Map the specified image to a block device via the rbd kernel module | |
257 | (default) or other supported device (*nbd* on Linux or *ggate* on | |
258 | FreeBSD). | |
259 | ||
260 | The --options argument is a comma separated list of device type | |
261 | specific options (opt1,opt2=val,...). | |
262 | ||
263 | :command:`device unmap` [-t | --device-type *device-type*] [-o | --options *device-options*] *image-spec* | *snap-spec* | *device-path* | |
264 | Unmap the block device that was mapped via the rbd kernel module | |
265 | (default) or other supported device. | |
266 | ||
267 | The --options argument is a comma separated list of device type | |
268 | specific options (opt1,opt2=val,...). | |
269 | ||
270 | :command:`diff` [--from-snap *snap-name*] [--whole-object] *image-spec* | *snap-spec* | |
271 | Dump a list of byte extents in the image that have changed since the specified start | |
272 | snapshot, or since the image was created. Each output line includes the starting offset | |
273 | (in bytes), the length of the region (in bytes), and either 'zero' or 'data' to indicate | |
274 | whether the region is known to be zeros or may contain other data. | |
7c673cae FG |
275 | |
276 | :command:`du` [-p | --pool *pool-name*] [*image-spec* | *snap-spec*] | |
277 | Will calculate the provisioned and actual disk usage of all images and | |
278 | associated snapshots within the specified pool. It can also be used against | |
279 | individual images and snapshots. | |
280 | ||
c07f9fc5 | 281 | If the RBD fast-diff feature is not enabled on images, this operation will |
7c673cae FG |
282 | require querying the OSDs for every potential object within the image. |
283 | ||
11fdf7f2 TL |
284 | :command:`export` [--export-format *format (1 or 2)*] (*image-spec* | *snap-spec*) [*dest-path*] |
285 | Export image to dest path (use - for stdout). | |
286 | The --export-format accepts '1' or '2' currently. Format 2 allow us to export not only the content | |
287 | of image, but also the snapshots and other properties, such as image_order, features. | |
7c673cae | 288 | |
11fdf7f2 TL |
289 | :command:`export-diff` [--from-snap *snap-name*] [--whole-object] (*image-spec* | *snap-spec*) *dest-path* |
290 | Export an incremental diff for an image to dest path (use - for stdout). If | |
291 | an initial snapshot is specified, only changes since that snapshot are included; otherwise, | |
292 | any regions of the image that contain data are included. The end snapshot is specified | |
293 | using the standard --snap option or @snap syntax (see below). The image diff format includes | |
294 | metadata about image size changes, and the start and end snapshots. It efficiently represents | |
295 | discarded or 'zero' regions of the image. | |
7c673cae | 296 | |
11fdf7f2 TL |
297 | :command:`feature disable` *image-spec* *feature-name*... |
298 | Disable the specified feature on the specified image. Multiple features can | |
299 | be specified. | |
7c673cae | 300 | |
11fdf7f2 TL |
301 | :command:`feature enable` *image-spec* *feature-name*... |
302 | Enable the specified feature on the specified image. Multiple features can | |
303 | be specified. | |
7c673cae FG |
304 | |
305 | :command:`flatten` *image-spec* | |
306 | If image is a clone, copy all shared blocks from the parent snapshot and | |
307 | make the child independent of the parent, severing the link between | |
308 | parent snap and child. The parent snapshot can be unprotected and | |
309 | deleted if it has no further dependent clones. | |
310 | ||
311 | This requires image format 2. | |
312 | ||
11fdf7f2 TL |
313 | :command:`group create` *group-spec* |
314 | Create a group. | |
7c673cae | 315 | |
11fdf7f2 TL |
316 | :command:`group image add` *group-spec* *image-spec* |
317 | Add an image to a group. | |
7c673cae | 318 | |
11fdf7f2 TL |
319 | :command:`group image list` *group-spec* |
320 | List images in a group. | |
7c673cae | 321 | |
11fdf7f2 TL |
322 | :command:`group image remove` *group-spec* *image-spec* |
323 | Remove an image from a group. | |
7c673cae | 324 | |
11fdf7f2 TL |
325 | :command:`group ls` [-p | --pool *pool-name*] |
326 | List rbd groups. | |
327 | ||
328 | :command:`group rename` *src-group-spec* *dest-group-spec* | |
329 | Rename a group. Note: rename across pools is not supported. | |
330 | ||
331 | :command:`group rm` *group-spec* | |
332 | Delete a group. | |
333 | ||
334 | :command:`group snap create` *group-snap-spec* | |
335 | Make a snapshot of a group. | |
336 | ||
337 | :command:`group snap list` *group-spec* | |
338 | List snapshots of a group. | |
339 | ||
340 | :command:`group snap rm` *group-snap-spec* | |
341 | Remove a snapshot from a group. | |
342 | ||
343 | :command:`group snap rename` *group-snap-spec* *snap-name* | |
344 | Rename group's snapshot. | |
345 | ||
346 | :command:`group snap rollback` *group-snap-spec* | |
347 | Rollback group to snapshot. | |
348 | ||
349 | :command:`image-meta get` *image-spec* *key* | |
350 | Get metadata value with the key. | |
351 | ||
352 | :command:`image-meta list` *image-spec* | |
353 | Show metadata held on the image. The first column is the key | |
354 | and the second column is the value. | |
355 | ||
356 | :command:`image-meta remove` *image-spec* *key* | |
357 | Remove metadata key with the value. | |
358 | ||
359 | :command:`image-meta set` *image-spec* *key* *value* | |
360 | Set metadata key with the value. They will displayed in `image-meta list`. | |
7c673cae FG |
361 | |
362 | :command:`import` [--export-format *format (1 or 2)*] [--image-format *format-id*] [--object-size *size-in-B/K/M*] [--stripe-unit *size-in-B/K/M* --stripe-count *num*] [--image-feature *feature-name*]... [--image-shared] *src-path* [*image-spec*] | |
c07f9fc5 | 363 | Create a new image and imports its data from path (use - for |
7c673cae FG |
364 | stdin). The import operation will try to create sparse rbd images |
365 | if possible. For import from stdin, the sparsification unit is | |
366 | the data block size of the destination image (object size). | |
367 | ||
368 | The --stripe-unit and --stripe-count arguments are optional, but must be | |
369 | used together. | |
370 | ||
371 | The --export-format accepts '1' or '2' currently. Format 2 allow us to import not only the content | |
372 | of image, but also the snapshots and other properties, such as image_order, features. | |
373 | ||
11fdf7f2 TL |
374 | :command:`import-diff` *src-path* *image-spec* |
375 | Import an incremental diff of an image and applies it to the current image. If the diff | |
376 | was generated relative to a start snapshot, we verify that snapshot already exists before | |
377 | continuing. If there was an end snapshot we verify it does not already exist before | |
378 | applying the changes, and create the snapshot when we are done. | |
379 | ||
380 | :command:`info` *image-spec* | *snap-spec* | |
381 | Will dump information (such as size and object size) about a specific rbd image. | |
382 | If image is a clone, information about its parent is also displayed. | |
383 | If a snapshot is specified, whether it is protected is shown as well. | |
384 | ||
385 | :command:`journal client disconnect` *journal-spec* | |
386 | Flag image journal client as disconnected. | |
387 | ||
388 | :command:`journal export` [--verbose] [--no-error] *src-journal-spec* *path-name* | |
389 | Export image journal to path (use - for stdout). It can be make a backup | |
390 | of the image journal especially before attempting dangerous operations. | |
391 | ||
392 | Note that this command may not always work if the journal is badly corrupted. | |
393 | ||
394 | :command:`journal import` [--verbose] [--no-error] *path-name* *dest-journal-spec* | |
395 | Import image journal from path (use - for stdin). | |
396 | ||
397 | :command:`journal info` *journal-spec* | |
398 | Show information about image journal. | |
399 | ||
400 | :command:`journal inspect` [--verbose] *journal-spec* | |
401 | Inspect and report image journal for structural errors. | |
402 | ||
403 | :command:`journal reset` *journal-spec* | |
404 | Reset image journal. | |
405 | ||
406 | :command:`journal status` *journal-spec* | |
407 | Show status of image journal. | |
408 | ||
409 | :command:`lock add` [--shared *lock-tag*] *image-spec* *lock-id* | |
410 | Lock an image. The lock-id is an arbitrary name for the user's | |
411 | convenience. By default, this is an exclusive lock, meaning it | |
412 | will fail if the image is already locked. The --shared option | |
413 | changes this behavior. Note that locking does not affect | |
414 | any operation other than adding a lock. It does not | |
415 | protect an image from being deleted. | |
416 | ||
417 | :command:`lock ls` *image-spec* | |
418 | Show locks held on the image. The first column is the locker | |
419 | to use with the `lock remove` command. | |
420 | ||
421 | :command:`lock rm` *image-spec* *lock-id* *locker* | |
422 | Release a lock on an image. The lock id and locker are | |
423 | as output by lock ls. | |
424 | ||
425 | :command:`ls` [-l | --long] [*pool-name*] | |
426 | Will list all rbd images listed in the rbd_directory object. With | |
427 | -l, also show snapshots, and use longer-format output including | |
428 | size, parent (if clone), format, etc. | |
7c673cae FG |
429 | |
430 | :command:`merge-diff` *first-diff-path* *second-diff-path* *merged-diff-path* | |
431 | Merge two continuous incremental diffs of an image into one single diff. The | |
432 | first diff's end snapshot must be equal with the second diff's start snapshot. | |
433 | The first diff could be - for stdin, and merged diff could be - for stdout, which | |
434 | enables multiple diff files to be merged using something like | |
435 | 'rbd merge-diff first second - | rbd merge-diff - third result'. Note this command | |
436 | currently only support the source incremental diff with stripe_count == 1 | |
437 | ||
11fdf7f2 TL |
438 | :command:`migration abort` *image-spec* |
439 | Cancel image migration. This step may be run after successful or | |
440 | failed migration prepare or migration execute steps and returns the | |
441 | image to its initial (before migration) state. All modifications to | |
442 | the destination image are lost. | |
443 | ||
444 | :command:`migration commit` *image-spec* | |
445 | Commit image migration. This step is run after a successful migration | |
446 | prepare and migration execute steps and removes the source image data. | |
447 | ||
448 | :command:`migration execute` *image-spec* | |
449 | Execute image migration. This step is run after a successful migration | |
450 | prepare step and copies image data to the destination. | |
451 | ||
452 | :command:`migration prepare` [--order *order*] [--object-size *object-size*] [--image-feature *image-feature*] [--image-shared] [--stripe-unit *stripe-unit*] [--stripe-count *stripe-count*] [--data-pool *data-pool*] *src-image-spec* [*dest-image-spec*] | |
453 | Prepare image migration. This is the first step when migrating an | |
454 | image, i.e. changing the image location, format or other | |
455 | parameters that can't be changed dynamically. The destination can | |
456 | match the source, and in this case *dest-image-spec* can be omitted. | |
457 | After this step the source image is set as a parent of the | |
458 | destination image, and the image is accessible in copy-on-write mode | |
459 | by its destination spec. | |
460 | ||
461 | :command:`mirror image demote` *image-spec* | |
462 | Demote a primary image to non-primary for RBD mirroring. | |
463 | ||
464 | :command:`mirror image disable` [--force] *image-spec* | |
465 | Disable RBD mirroring for an image. If the mirroring is | |
466 | configured in ``image`` mode for the image's pool, then it | |
467 | can be explicitly disabled mirroring for each image within | |
468 | the pool. | |
469 | ||
470 | :command:`mirror image enable` *image-spec* | |
471 | Enable RBD mirroring for an image. If the mirroring is | |
472 | configured in ``image`` mode for the image's pool, then it | |
473 | can be explicitly enabled mirroring for each image within | |
474 | the pool. | |
475 | ||
476 | This requires the RBD journaling feature is enabled. | |
477 | ||
478 | :command:`mirror image promote` [--force] *image-spec* | |
479 | Promote a non-primary image to primary for RBD mirroring. | |
480 | ||
481 | :command:`mirror image resync` *image-spec* | |
482 | Force resync to primary image for RBD mirroring. | |
483 | ||
484 | :command:`mirror image status` *image-spec* | |
485 | Show RBD mirroring status for an image. | |
486 | ||
487 | :command:`mirror pool demote` [*pool-name*] | |
488 | Demote all primary images within a pool to non-primary. | |
489 | Every mirroring enabled image will demoted in the pool. | |
490 | ||
491 | :command:`mirror pool disable` [*pool-name*] | |
492 | Disable RBD mirroring by default within a pool. When mirroring | |
493 | is disabled on a pool in this way, mirroring will also be | |
494 | disabled on any images (within the pool) for which mirroring | |
495 | was enabled explicitly. | |
496 | ||
497 | :command:`mirror pool enable` [*pool-name*] *mode* | |
498 | Enable RBD mirroring by default within a pool. | |
499 | The mirroring mode can either be ``pool`` or ``image``. | |
500 | If configured in ``pool`` mode, all images in the pool | |
501 | with the journaling feature enabled are mirrored. | |
502 | If configured in ``image`` mode, mirroring needs to be | |
503 | explicitly enabled (by ``mirror image enable`` command) | |
504 | on each image. | |
505 | ||
506 | :command:`mirror pool info` [*pool-name*] | |
507 | Show information about the pool mirroring configuration. | |
508 | It includes mirroring mode, peer UUID, remote cluster name, | |
509 | and remote client name. | |
510 | ||
511 | :command:`mirror pool peer add` [*pool-name*] *remote-cluster-spec* | |
512 | Add a mirroring peer to a pool. | |
513 | *remote-cluster-spec* is [*remote client name*\ @\ ]\ *remote cluster name*. | |
514 | ||
515 | The default for *remote client name* is "client.admin". | |
516 | ||
517 | This requires mirroring mode is enabled. | |
518 | ||
519 | :command:`mirror pool peer remove` [*pool-name*] *uuid* | |
520 | Remove a mirroring peer from a pool. The peer uuid is available | |
521 | from ``mirror pool info`` command. | |
522 | ||
523 | :command:`mirror pool peer set` [*pool-name*] *uuid* *key* *value* | |
524 | Update mirroring peer settings. | |
525 | The key can be either ``client`` or ``cluster``, and the value | |
526 | is corresponding to remote client name or remote cluster name. | |
527 | ||
528 | :command:`mirror pool promote` [--force] [*pool-name*] | |
529 | Promote all non-primary images within a pool to primary. | |
530 | Every mirroring enabled image will promoted in the pool. | |
531 | ||
532 | :command:`mirror pool status` [--verbose] [*pool-name*] | |
533 | Show status for all mirrored images in the pool. | |
534 | With --verbose, also show additionally output status | |
535 | details for every mirroring image in the pool. | |
7c673cae FG |
536 | |
537 | :command:`mv` *src-image-spec* *dest-image-spec* | |
c07f9fc5 | 538 | Rename an image. Note: rename across pools is not supported. |
7c673cae | 539 | |
eafe8130 | 540 | :command:`namespace create` *pool-name*/*namespace-name* |
11fdf7f2 | 541 | Create a new image namespace within the pool. |
7c673cae | 542 | |
11fdf7f2 TL |
543 | :command:`namespace list` *pool-name* |
544 | List image namespaces defined within the pool. | |
7c673cae | 545 | |
eafe8130 | 546 | :command:`namespace remove` *pool-name*/*namespace-name* |
11fdf7f2 | 547 | Remove an empty image namespace from the pool. |
7c673cae | 548 | |
11fdf7f2 TL |
549 | :command:`object-map check` *image-spec* | *snap-spec* |
550 | Verify the object map is correct. | |
7c673cae FG |
551 | |
552 | :command:`object-map rebuild` *image-spec* | *snap-spec* | |
c07f9fc5 | 553 | Rebuild an invalid object map for the specified image. An image snapshot can be |
7c673cae FG |
554 | specified to rebuild an invalid object map for a snapshot. |
555 | ||
11fdf7f2 TL |
556 | :command:`pool init` [*pool-name*] [--force] |
557 | Initialize pool for use by RBD. Newly created pools must initialized | |
558 | prior to use. | |
559 | ||
560 | :command:`resize` (-s | --size *size-in-M/G/T*) [--allow-shrink] *image-spec* | |
561 | Resize rbd image. The size parameter also needs to be specified. | |
562 | The --allow-shrink option lets the size be reduced. | |
563 | ||
564 | :command:`rm` *image-spec* | |
565 | Delete an rbd image (including all data blocks). If the image has | |
566 | snapshots, this fails and nothing is deleted. | |
7c673cae FG |
567 | |
568 | :command:`snap create` *snap-spec* | |
c07f9fc5 | 569 | Create a new snapshot. Requires the snapshot name parameter specified. |
7c673cae | 570 | |
11fdf7f2 TL |
571 | :command:`snap limit clear` *image-spec* |
572 | Remove any previously set limit on the number of snapshots allowed on | |
573 | an image. | |
7c673cae | 574 | |
11fdf7f2 TL |
575 | :command:`snap limit set` [--limit] *limit* *image-spec* |
576 | Set a limit for the number of snapshots allowed on an image. | |
7c673cae | 577 | |
11fdf7f2 TL |
578 | :command:`snap ls` *image-spec* |
579 | Dump the list of snapshots inside a specific image. | |
7c673cae FG |
580 | |
581 | :command:`snap protect` *snap-spec* | |
582 | Protect a snapshot from deletion, so that clones can be made of it | |
583 | (see `rbd clone`). Snapshots must be protected before clones are made; | |
584 | protection implies that there exist dependent cloned children that | |
585 | refer to this snapshot. `rbd clone` will fail on a nonprotected | |
586 | snapshot. | |
587 | ||
588 | This requires image format 2. | |
589 | ||
11fdf7f2 TL |
590 | :command:`snap purge` *image-spec* |
591 | Remove all unprotected snapshots from an image. | |
592 | ||
593 | :command:`snap rename` *src-snap-spec* *dest-snap-spec* | |
594 | Rename a snapshot. Note: rename across pools and images is not supported. | |
595 | ||
596 | :command:`snap rm` [--force] *snap-spec* | |
597 | Remove the specified snapshot. | |
598 | ||
599 | :command:`snap rollback` *snap-spec* | |
600 | Rollback image content to snapshot. This will iterate through the entire blocks | |
601 | array and update the data head content to the snapshotted version. | |
602 | ||
7c673cae FG |
603 | :command:`snap unprotect` *snap-spec* |
604 | Unprotect a snapshot from deletion (undo `snap protect`). If cloned | |
605 | children remain, `snap unprotect` fails. (Note that clones may exist | |
606 | in different pools than the parent snapshot.) | |
607 | ||
608 | This requires image format 2. | |
609 | ||
11fdf7f2 TL |
610 | :command:`sparsify` [--sparse-size *sparse-size*] *image-spec* |
611 | Reclaim space for zeroed image extents. The default sparse size is | |
612 | 4096 bytes and can be changed via --sparse-size option with the | |
613 | following restrictions: it should be power of two, not less than | |
614 | 4096, and not larger image object size. | |
7c673cae FG |
615 | |
616 | :command:`status` *image-spec* | |
617 | Show the status of the image, including which clients have it open. | |
618 | ||
c07f9fc5 FG |
619 | :command:`trash ls` [*pool-name*] |
620 | List all entries from trash. | |
621 | ||
622 | :command:`trash mv` *image-spec* | |
623 | Move an image to the trash. Images, even ones actively in-use by | |
624 | clones, can be moved to the trash and deleted at a later time. | |
625 | ||
11fdf7f2 TL |
626 | :command:`trash purge` [*pool-name*] |
627 | Remove all expired images from trash. | |
628 | ||
629 | :command:`trash restore` *image-id* | |
630 | Restore an image from trash. | |
631 | ||
c07f9fc5 FG |
632 | :command:`trash rm` *image-id* |
633 | Delete an image from trash. If image deferment time has not expired | |
634 | you can not removed it unless use force. But an actively in-use by clones | |
635 | or has snapshots can not be removed. | |
636 | ||
11fdf7f2 TL |
637 | :command:`watch` *image-spec* |
638 | Watch events on image. | |
639 | ||
640 | Image, snap, group and journal specs | |
641 | ==================================== | |
c07f9fc5 | 642 | |
11fdf7f2 TL |
643 | | *image-spec* is [*pool-name*/[*namespace-name*/]]\ *image-name* |
644 | | *snap-spec* is [*pool-name*/[*namespace-name*/]]\ *image-name*\ @\ *snap-name* | |
645 | | *group-spec* is [*pool-name*/[*namespace-name*/]]\ *group-name* | |
646 | | *group-snap-spec* is [*pool-name*/[*namespace-name*/]]\ *group-name*\ @\ *snap-name* | |
647 | | *journal-spec* is [*pool-name*/[*namespace-name*/]]\ *journal-name* | |
7c673cae | 648 | |
11fdf7f2 TL |
649 | The default for *pool-name* is "rbd" and *namespace-name* is "". If an image |
650 | name contains a slash character ('/'), *pool-name* is required. | |
7c673cae | 651 | |
11fdf7f2 | 652 | The *journal-name* is *image-id*. |
7c673cae | 653 | |
11fdf7f2 TL |
654 | You may specify each name individually, using --pool, --namespace, --image, and |
655 | --snap options, but this is discouraged in favor of the above spec syntax. | |
7c673cae FG |
656 | |
657 | Striping | |
658 | ======== | |
659 | ||
660 | RBD images are striped over many objects, which are then stored by the | |
661 | Ceph distributed object store (RADOS). As a result, read and write | |
662 | requests for the image are distributed across many nodes in the | |
663 | cluster, generally preventing any single node from becoming a | |
664 | bottleneck when individual images get large or busy. | |
665 | ||
666 | The striping is controlled by three parameters: | |
667 | ||
668 | .. option:: object-size | |
669 | ||
670 | The size of objects we stripe over is a power of two. It will be rounded up the nearest power of two. | |
671 | The default object size is 4 MB, smallest is 4K and maximum is 32M. | |
672 | ||
673 | .. option:: stripe_unit | |
674 | ||
675 | Each [*stripe_unit*] contiguous bytes are stored adjacently in the same object, before we move on | |
676 | to the next object. | |
677 | ||
678 | .. option:: stripe_count | |
679 | ||
680 | After we write [*stripe_unit*] bytes to [*stripe_count*] objects, we loop back to the initial object | |
681 | and write another stripe, until the object reaches its maximum size. At that point, | |
682 | we move on to the next [*stripe_count*] objects. | |
683 | ||
684 | By default, [*stripe_unit*] is the same as the object size and [*stripe_count*] is 1. Specifying a different | |
685 | [*stripe_unit*] requires that the STRIPINGV2 feature be supported (added in Ceph v0.53) and format 2 images be | |
686 | used. | |
687 | ||
688 | ||
689 | Kernel rbd (krbd) options | |
690 | ========================= | |
691 | ||
692 | Most of these options are useful mainly for debugging and benchmarking. The | |
693 | default values are set in the kernel and may therefore depend on the version of | |
694 | the running kernel. | |
695 | ||
11fdf7f2 | 696 | Per client instance `rbd device map` options: |
7c673cae FG |
697 | |
698 | * fsid=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee - FSID that should be assumed by | |
699 | the client. | |
700 | ||
701 | * ip=a.b.c.d[:p] - IP and, optionally, port the client should use. | |
702 | ||
703 | * share - Enable sharing of client instances with other mappings (default). | |
704 | ||
705 | * noshare - Disable sharing of client instances with other mappings. | |
706 | ||
707 | * crc - Enable CRC32C checksumming for data writes (default). | |
708 | ||
709 | * nocrc - Disable CRC32C checksumming for data writes. | |
710 | ||
711 | * cephx_require_signatures - Require cephx message signing (since 3.19, | |
712 | default). | |
713 | ||
714 | * nocephx_require_signatures - Don't require cephx message signing (since | |
715 | 3.19). | |
716 | ||
717 | * tcp_nodelay - Disable Nagle's algorithm on client sockets (since 4.0, | |
718 | default). | |
719 | ||
720 | * notcp_nodelay - Enable Nagle's algorithm on client sockets (since 4.0). | |
721 | ||
722 | * cephx_sign_messages - Enable message signing (since 4.4, default). | |
723 | ||
724 | * nocephx_sign_messages - Disable message signing (since 4.4). | |
725 | ||
11fdf7f2 TL |
726 | * mount_timeout=x - A timeout on various steps in `rbd device map` and |
727 | `rbd device unmap` sequences (default is 60 seconds). In particular, | |
728 | since 4.2 this can be used to ensure that `rbd device unmap` eventually | |
729 | times out when there is no network connection to a cluster. | |
7c673cae FG |
730 | |
731 | * osdkeepalive=x - OSD keepalive timeout (default is 5 seconds). | |
732 | ||
733 | * osd_idle_ttl=x - OSD idle TTL (default is 60 seconds). | |
734 | ||
11fdf7f2 | 735 | Per mapping (block device) `rbd device map` options: |
7c673cae FG |
736 | |
737 | * rw - Map the image read-write (default). | |
738 | ||
739 | * ro - Map the image read-only. Equivalent to --read-only. | |
740 | ||
741 | * queue_depth=x - queue depth (since 4.2, default is 128 requests). | |
742 | ||
743 | * lock_on_read - Acquire exclusive lock on reads, in addition to writes and | |
744 | discards (since 4.9). | |
745 | ||
746 | * exclusive - Disable automatic exclusive lock transitions (since 4.12). | |
747 | ||
11fdf7f2 TL |
748 | * lock_timeout=x - A timeout on waiting for the acquisition of exclusive lock |
749 | (since 4.17, default is 0 seconds, meaning no timeout). | |
750 | ||
751 | * notrim - Turn off discard and write zeroes offload support to avoid | |
752 | deprovisioning a fully provisioned image (since 4.17). When enabled, discard | |
753 | requests will fail with -EOPNOTSUPP, write zeroes requests will fall back to | |
754 | manually zeroing. | |
755 | ||
756 | * abort_on_full - Fail write requests with -ENOSPC when the cluster is full or | |
757 | the data pool reaches its quota (since 5.0). The default behaviour is to | |
758 | block until the full condition is cleared. | |
759 | ||
760 | * alloc_size - Minimum allocation unit of the underlying OSD object store | |
761 | backend (since 5.1, default is 64K bytes). This is used to round off and | |
762 | drop discards that are too small. For bluestore, the recommended setting is | |
763 | bluestore_min_alloc_size (typically 64K for hard disk drives and 16K for | |
764 | solid-state drives). For filestore with filestore_punch_hole = false, the | |
765 | recommended setting is image object size (typically 4M). | |
766 | ||
767 | `rbd device unmap` options: | |
7c673cae FG |
768 | |
769 | * force - Force the unmapping of a block device that is open (since 4.9). The | |
770 | driver will wait for running requests to complete and then unmap; requests | |
771 | sent to the driver after initiating the unmap will be failed. | |
772 | ||
773 | ||
774 | Examples | |
775 | ======== | |
776 | ||
777 | To create a new rbd image that is 100 GB:: | |
778 | ||
779 | rbd create mypool/myimage --size 102400 | |
780 | ||
781 | To use a non-default object size (8 MB):: | |
782 | ||
783 | rbd create mypool/myimage --size 102400 --object-size 8M | |
784 | ||
785 | To delete an rbd image (be careful!):: | |
786 | ||
787 | rbd rm mypool/myimage | |
788 | ||
789 | To create a new snapshot:: | |
790 | ||
791 | rbd snap create mypool/myimage@mysnap | |
792 | ||
793 | To create a copy-on-write clone of a protected snapshot:: | |
794 | ||
795 | rbd clone mypool/myimage@mysnap otherpool/cloneimage | |
796 | ||
797 | To see which clones of a snapshot exist:: | |
798 | ||
799 | rbd children mypool/myimage@mysnap | |
800 | ||
801 | To delete a snapshot:: | |
802 | ||
803 | rbd snap rm mypool/myimage@mysnap | |
804 | ||
805 | To map an image via the kernel with cephx enabled:: | |
806 | ||
11fdf7f2 | 807 | rbd device map mypool/myimage --id admin --keyfile secretfile |
7c673cae FG |
808 | |
809 | To map an image via the kernel with different cluster name other than default *ceph*:: | |
810 | ||
11fdf7f2 | 811 | rbd device map mypool/myimage --cluster cluster-name |
7c673cae FG |
812 | |
813 | To unmap an image:: | |
814 | ||
11fdf7f2 | 815 | rbd device unmap /dev/rbd0 |
7c673cae FG |
816 | |
817 | To create an image and a clone from it:: | |
818 | ||
819 | rbd import --image-format 2 image mypool/parent | |
820 | rbd snap create mypool/parent@snap | |
821 | rbd snap protect mypool/parent@snap | |
822 | rbd clone mypool/parent@snap otherpool/child | |
823 | ||
824 | To create an image with a smaller stripe_unit (to better distribute small writes in some workloads):: | |
825 | ||
826 | rbd create mypool/myimage --size 102400 --stripe-unit 65536B --stripe-count 16 | |
827 | ||
828 | To change an image from one image format to another, export it and then | |
829 | import it as the desired image format:: | |
830 | ||
831 | rbd export mypool/myimage@snap /tmp/img | |
832 | rbd import --image-format 2 /tmp/img mypool/myimage2 | |
833 | ||
834 | To lock an image for exclusive use:: | |
835 | ||
836 | rbd lock add mypool/myimage mylockid | |
837 | ||
838 | To release a lock:: | |
839 | ||
840 | rbd lock remove mypool/myimage mylockid client.2485 | |
841 | ||
c07f9fc5 FG |
842 | To list images from trash:: |
843 | ||
844 | rbd trash ls mypool | |
845 | ||
11fdf7f2 | 846 | To defer delete an image (use *--expires-at* to set expiration time, default is now):: |
c07f9fc5 | 847 | |
11fdf7f2 | 848 | rbd trash mv mypool/myimage --expires-at "tomorrow" |
c07f9fc5 FG |
849 | |
850 | To delete an image from trash (be careful!):: | |
851 | ||
852 | rbd trash rm mypool/myimage-id | |
853 | ||
854 | To force delete an image from trash (be careful!):: | |
855 | ||
856 | rbd trash rm mypool/myimage-id --force | |
857 | ||
858 | To restore an image from trash:: | |
859 | ||
860 | rbd trash restore mypool/myimage-id | |
861 | ||
862 | To restore an image from trash and rename it:: | |
863 | ||
864 | rbd trash restore mypool/myimage-id --image mynewimage | |
865 | ||
7c673cae FG |
866 | |
867 | Availability | |
868 | ============ | |
869 | ||
870 | **rbd** is part of Ceph, a massively scalable, open-source, distributed storage system. Please refer to | |
871 | the Ceph documentation at http://ceph.com/docs for more information. | |
872 | ||
873 | ||
874 | See also | |
875 | ======== | |
876 | ||
877 | :doc:`ceph <ceph>`\(8), | |
878 | :doc:`rados <rados>`\(8) |