3 ===============================================
4 rbd -- manage rados block device (RBD) images
5 ===============================================
12 | **rbd** [ -c *ceph.conf* ] [ -m *monaddr* ] [--cluster *cluster-name*]
13 [ -p | --pool *pool* ] [ *command* ... ]
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.
29 .. option:: -c ceph.conf, --conf ceph.conf
31 Use ceph.conf configuration file instead of the default /etc/ceph/ceph.conf to
32 determine monitor addresses during startup.
34 .. option:: -m monaddress[:port]
36 Connect to specified monitor (instead of looking through ceph.conf).
38 .. option:: --cluster cluster-name
40 Use different cluster name as compared to default cluster name *ceph*.
42 .. option:: -p pool-name, --pool pool-name
44 Interact with the given pool. Required by most commands.
46 .. option:: --namespace namespace-name
48 Use a pre-defined image namespace within a pool
50 .. option:: --no-progress
52 Do not output progress information (goes to standard error by
53 default for some commands).
59 .. option:: --image-format format-id
61 Specifies which object layout to use. The default is 2.
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.
67 * format 2 - Use the second rbd format, which is supported by librbd since
68 the Bobtail release and the kernel rbd module since kernel 3.10 (except
69 for "fancy" striping, which is supported since kernel 4.17). This adds
70 support for cloning and is more easily extensible to allow more
71 features in the future.
73 .. option:: -s size-in-M/G/T, --size size-in-M/G/T
75 Specifies the size of the new rbd image or the new size of the existing rbd
76 image in M/G/T. If no suffix is given, unit M is assumed.
78 .. option:: --object-size size-in-B/K/M
80 Specifies the object size in B/K/M. Object size will be rounded up the
81 nearest power of two; if no suffix is given, unit B is assumed. The default
82 object size is 4M, smallest is 4K and maximum is 32M.
84 The default value can be changed with the configuration option ``rbd_default_order``,
85 which takes a power of two (default object size is ``2 ^ rbd_default_order``).
87 .. option:: --stripe-unit size-in-B/K/M
89 Specifies the stripe unit size in B/K/M. If no suffix is given, unit B is
90 assumed. See striping section (below) for more details.
92 .. option:: --stripe-count num
94 Specifies the number of objects to stripe over before looping back
95 to the first object. See striping section (below) for more details.
97 .. option:: --snap snap
99 Specifies the snapshot name for the specific operation.
101 .. option:: --id username
103 Specifies the username (without the ``client.`` prefix) to use with the map command.
105 .. option:: --keyring filename
107 Specifies a keyring file containing a secret for the specified user
108 to use with the map command. If not specified, the default keyring
109 locations will be searched.
111 .. option:: --keyfile filename
113 Specifies a file containing the secret key of ``--id user`` to use with the map command.
114 This option is overridden by ``--keyring`` if the latter is also specified.
116 .. option:: --shared lock-tag
118 Option for `lock add` that allows multiple clients to lock the
119 same image if they use the same tag. The tag is an arbitrary
120 string. This is useful for situations where an image must
121 be open from more than one client at once, like during
122 live migration of a virtual machine, or for use underneath
123 a clustered file system.
125 .. option:: --format format
127 Specifies output formatting (default: plain, json, xml)
129 .. option:: --pretty-format
131 Make json or xml formatted output more human-readable.
133 .. option:: -o krbd-options, --options krbd-options
135 Specifies which options to use when mapping or unmapping an image via the
136 rbd kernel driver. krbd-options is a comma-separated list of options
137 (similar to mount(8) mount options). See kernel rbd (krbd) options section
138 below for more details.
140 .. option:: --read-only
142 Map the image read-only. Equivalent to -o ro.
144 .. option:: --image-feature feature-name
146 Specifies which RBD format 2 feature should be enabled when creating
147 an image. Multiple features can be enabled by repeating this option
148 multiple times. The following features are supported:
150 * layering: layering support
151 * striping: striping v2 support
152 * exclusive-lock: exclusive locking support
153 * object-map: object map support (requires exclusive-lock)
154 * fast-diff: fast diff calculations (requires object-map)
155 * deep-flatten: snapshot flatten support
156 * journaling: journaled IO support (requires exclusive-lock)
157 * data-pool: erasure coded pool support
159 .. option:: --image-shared
161 Specifies that the image will be used concurrently by multiple clients.
162 This will disable features that are dependent upon exclusive ownership
165 .. option:: --whole-object
167 Specifies that the diff should be limited to the extents of a full object
168 instead of showing intra-object deltas. When the object map feature is
169 enabled on an image, limiting the diff to the object extents will
170 dramatically improve performance since the differences can be computed
171 by examining the in-memory object map instead of querying RADOS for each
172 object within the image.
176 Specifies the limit for the number of snapshots permitted.
181 .. TODO rst "option" directive seems to require --foo style options, parsing breaks on subcommands.. the args show up as bold too
183 :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*
184 Generate a series of IOs to the image and measure the IO throughput and
185 latency. If no suffix is given, unit B is assumed for both --io-size and
186 --io-total. Defaults are: --io-size 4096, --io-threads 16, --io-total 1G,
187 --io-pattern seq, --rw-mix-read 50.
189 :command:`children` *snap-spec*
190 List the clones of the image at the given snapshot. This checks
191 every pool, and outputs the resulting poolname/imagename.
193 This requires image format 2.
195 :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*
196 Will create a clone (copy-on-write child) of the parent snapshot.
197 Object size will be identical to that of the parent image unless
198 specified. Size will be the same as the parent snapshot. The --stripe-unit
199 and --stripe-count arguments are optional, but must be used together.
201 The parent snapshot must be protected (see `rbd snap protect`).
202 This requires image format 2.
204 :command:`config global get` *config-entity* *key*
205 Get a global-level configuration override.
207 :command:`config global list` [--format plain | json | xml] [--pretty-format] *config-entity*
208 List global-level configuration overrides.
210 :command:`config global set` *config-entity* *key* *value*
211 Set a global-level configuration override.
213 :command:`config global remove` *config-entity* *key*
214 Remove a global-level configuration override.
216 :command:`config image get` *image-spec* *key*
217 Get an image-level configuration override.
219 :command:`config image list` [--format plain | json | xml] [--pretty-format] *image-spec*
220 List image-level configuration overrides.
222 :command:`config image set` *image-spec* *key* *value*
223 Set an image-level configuration override.
225 :command:`config image remove` *image-spec* *key*
226 Remove an image-level configuration override.
228 :command:`config pool get` *pool-name* *key*
229 Get a pool-level configuration override.
231 :command:`config pool list` [--format plain | json | xml] [--pretty-format] *pool-name*
232 List pool-level configuration overrides.
234 :command:`config pool set` *pool-name* *key* *value*
235 Set a pool-level configuration override.
237 :command:`config pool remove` *pool-name* *key*
238 Remove a pool-level configuration override.
240 :command:`cp` (*src-image-spec* | *src-snap-spec*) *dest-image-spec*
241 Copy the content of a src-image into the newly created dest-image.
242 dest-image will have the same size, object size, and image format as src-image.
243 Note: snapshots are not copied, use `deep cp` command to include
246 :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*
247 Will create a new rbd image. You must also specify the size via --size. The
248 --stripe-unit and --stripe-count arguments are optional, but must be used together.
249 If the --thick-provision is enabled, it will fully allocate storage for
250 the image at creation time. It will take a long time to do.
251 Note: thick provisioning requires zeroing the contents of the entire image.
253 :command:`deep cp` (*src-image-spec* | *src-snap-spec*) *dest-image-spec*
254 Deep copy the content of a src-image into the newly created dest-image.
255 Dest-image will have the same size, object size, image format, and snapshots as src-image.
257 :command:`device list` [-t | --device-type *device-type*] [--format plain | json | xml] --pretty-format
258 Show the rbd images that are mapped via the rbd kernel module
259 (default) or other supported device.
261 :command:`device map` [-t | --device-type *device-type*] [--cookie *device-cookie*] [--show-cookie] [--read-only] [--exclusive] [-o | --options *device-options*] *image-spec* | *snap-spec*
262 Map the specified image to a block device via the rbd kernel module
263 (default) or other supported device (*nbd* on Linux or *ggate* on
266 The --options argument is a comma separated list of device type
267 specific options (opt1,opt2=val,...).
269 :command:`device unmap` [-t | --device-type *device-type*] [-o | --options *device-options*] *image-spec* | *snap-spec* | *device-path*
270 Unmap the block device that was mapped via the rbd kernel module
271 (default) or other supported device.
273 The --options argument is a comma separated list of device type
274 specific options (opt1,opt2=val,...).
276 :command:`device attach` [-t | --device-type *device-type*] --device *device-path* [--cookie *device-cookie*] [--show-cookie] [--read-only] [--exclusive] [--force] [-o | --options *device-options*] *image-spec* | *snap-spec*
277 Attach the specified image to the specified block device (currently only
278 `nbd` on Linux). This operation is unsafe and should not be normally used.
279 In particular, specifying the wrong image or the wrong block device may
280 lead to data corruption as no validation is performed by `nbd` kernel driver.
282 The --options argument is a comma separated list of device type
283 specific options (opt1,opt2=val,...).
285 :command:`device detach` [-t | --device-type *device-type*] [-o | --options *device-options*] *image-spec* | *snap-spec* | *device-path*
286 Detach the block device that was mapped or attached (currently only `nbd`
287 on Linux). This operation is unsafe and should not be normally used.
289 The --options argument is a comma separated list of device type
290 specific options (opt1,opt2=val,...).
292 :command:`diff` [--from-snap *snap-name*] [--whole-object] *image-spec* | *snap-spec*
293 Dump a list of byte extents in the image that have changed since the specified start
294 snapshot, or since the image was created. Each output line includes the starting offset
295 (in bytes), the length of the region (in bytes), and either 'zero' or 'data' to indicate
296 whether the region is known to be zeros or may contain other data.
298 :command:`du` [-p | --pool *pool-name*] [*image-spec* | *snap-spec*] [--merge-snapshots]
299 Will calculate the provisioned and actual disk usage of all images and
300 associated snapshots within the specified pool. It can also be used against
301 individual images and snapshots.
303 If the RBD fast-diff feature is not enabled on images, this operation will
304 require querying the OSDs for every potential object within the image.
306 The --merge-snapshots will merge snapshots used space into their parent images.
308 :command:`encryption format` *image-spec* *format* *passphrase-file* [--cipher-alg *alg*]
309 Formats image to an encrypted format.
310 All data previously written to the image will become unreadable.
311 A cloned image cannot be formatted, although encrypted images can be cloned.
312 Supported formats: *luks1*, *luks2*.
313 Supported cipher algorithms: *aes-128*, *aes-256* (default).
315 :command:`export` [--export-format *format (1 or 2)*] (*image-spec* | *snap-spec*) [*dest-path*]
316 Export image to dest path (use - for stdout).
317 The --export-format accepts '1' or '2' currently. Format 2 allow us to export not only the content
318 of image, but also the snapshots and other properties, such as image_order, features.
320 :command:`export-diff` [--from-snap *snap-name*] [--whole-object] (*image-spec* | *snap-spec*) *dest-path*
321 Export an incremental diff for an image to dest path (use - for stdout). If
322 an initial snapshot is specified, only changes since that snapshot are included; otherwise,
323 any regions of the image that contain data are included. The end snapshot is specified
324 using the standard --snap option or @snap syntax (see below). The image diff format includes
325 metadata about image size changes, and the start and end snapshots. It efficiently represents
326 discarded or 'zero' regions of the image.
328 :command:`feature disable` *image-spec* *feature-name*...
329 Disable the specified feature on the specified image. Multiple features can
332 :command:`feature enable` *image-spec* *feature-name*...
333 Enable the specified feature on the specified image. Multiple features can
336 :command:`flatten` *image-spec*
337 If image is a clone, copy all shared blocks from the parent snapshot and
338 make the child independent of the parent, severing the link between
339 parent snap and child. The parent snapshot can be unprotected and
340 deleted if it has no further dependent clones.
342 This requires image format 2.
344 :command:`group create` *group-spec*
347 :command:`group image add` *group-spec* *image-spec*
348 Add an image to a group.
350 :command:`group image list` *group-spec*
351 List images in a group.
353 :command:`group image remove` *group-spec* *image-spec*
354 Remove an image from a group.
356 :command:`group ls` [-p | --pool *pool-name*]
359 :command:`group rename` *src-group-spec* *dest-group-spec*
360 Rename a group. Note: rename across pools is not supported.
362 :command:`group rm` *group-spec*
365 :command:`group snap create` *group-snap-spec*
366 Make a snapshot of a group.
368 :command:`group snap list` *group-spec*
369 List snapshots of a group.
371 :command:`group snap rm` *group-snap-spec*
372 Remove a snapshot from a group.
374 :command:`group snap rename` *group-snap-spec* *snap-name*
375 Rename group's snapshot.
377 :command:`group snap rollback` *group-snap-spec*
378 Rollback group to snapshot.
380 :command:`image-meta get` *image-spec* *key*
381 Get metadata value with the key.
383 :command:`image-meta list` *image-spec*
384 Show metadata held on the image. The first column is the key
385 and the second column is the value.
387 :command:`image-meta remove` *image-spec* *key*
388 Remove metadata key with the value.
390 :command:`image-meta set` *image-spec* *key* *value*
391 Set metadata key with the value. They will displayed in `image-meta list`.
393 :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*]
394 Create a new image and imports its data from path (use - for
395 stdin). The import operation will try to create sparse rbd images
396 if possible. For import from stdin, the sparsification unit is
397 the data block size of the destination image (object size).
399 The --stripe-unit and --stripe-count arguments are optional, but must be
402 The --export-format accepts '1' or '2' currently. Format 2 allow us to import not only the content
403 of image, but also the snapshots and other properties, such as image_order, features.
405 :command:`import-diff` *src-path* *image-spec*
406 Import an incremental diff of an image and applies it to the current image. If the diff
407 was generated relative to a start snapshot, we verify that snapshot already exists before
408 continuing. If there was an end snapshot we verify it does not already exist before
409 applying the changes, and create the snapshot when we are done.
411 :command:`info` *image-spec* | *snap-spec*
412 Will dump information (such as size and object size) about a specific rbd image.
413 If image is a clone, information about its parent is also displayed.
414 If a snapshot is specified, whether it is protected is shown as well.
416 :command:`journal client disconnect` *journal-spec*
417 Flag image journal client as disconnected.
419 :command:`journal export` [--verbose] [--no-error] *src-journal-spec* *path-name*
420 Export image journal to path (use - for stdout). It can be make a backup
421 of the image journal especially before attempting dangerous operations.
423 Note that this command may not always work if the journal is badly corrupted.
425 :command:`journal import` [--verbose] [--no-error] *path-name* *dest-journal-spec*
426 Import image journal from path (use - for stdin).
428 :command:`journal info` *journal-spec*
429 Show information about image journal.
431 :command:`journal inspect` [--verbose] *journal-spec*
432 Inspect and report image journal for structural errors.
434 :command:`journal reset` *journal-spec*
437 :command:`journal status` *journal-spec*
438 Show status of image journal.
440 :command:`lock add` [--shared *lock-tag*] *image-spec* *lock-id*
441 Lock an image. The lock-id is an arbitrary name for the user's
442 convenience. By default, this is an exclusive lock, meaning it
443 will fail if the image is already locked. The --shared option
444 changes this behavior. Note that locking does not affect
445 any operation other than adding a lock. It does not
446 protect an image from being deleted.
448 :command:`lock ls` *image-spec*
449 Show locks held on the image. The first column is the locker
450 to use with the `lock remove` command.
452 :command:`lock rm` *image-spec* *lock-id* *locker*
453 Release a lock on an image. The lock id and locker are
454 as output by lock ls.
456 :command:`ls` [-l | --long] [*pool-name*]
457 Will list all rbd images listed in the rbd_directory object. With
458 -l, also show snapshots, and use longer-format output including
459 size, parent (if clone), format, etc.
461 :command:`merge-diff` *first-diff-path* *second-diff-path* *merged-diff-path*
462 Merge two continuous incremental diffs of an image into one single diff. The
463 first diff's end snapshot must be equal with the second diff's start snapshot.
464 The first diff could be - for stdin, and merged diff could be - for stdout, which
465 enables multiple diff files to be merged using something like
466 'rbd merge-diff first second - | rbd merge-diff - third result'. Note this command
467 currently only support the source incremental diff with stripe_count == 1
469 :command:`migration abort` *image-spec*
470 Cancel image migration. This step may be run after successful or
471 failed migration prepare or migration execute steps and returns the
472 image to its initial (before migration) state. All modifications to
473 the destination image are lost.
475 :command:`migration commit` *image-spec*
476 Commit image migration. This step is run after a successful migration
477 prepare and migration execute steps and removes the source image data.
479 :command:`migration execute` *image-spec*
480 Execute image migration. This step is run after a successful migration
481 prepare step and copies image data to the destination.
483 :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*] [--import-only] [--source-spec *json*] [--source-spec-path *path*] *src-image-spec* [*dest-image-spec*]
484 Prepare image migration. This is the first step when migrating an
485 image, i.e. changing the image location, format or other
486 parameters that can't be changed dynamically. The destination can
487 match the source, and in this case *dest-image-spec* can be omitted.
488 After this step the source image is set as a parent of the
489 destination image, and the image is accessible in copy-on-write mode
490 by its destination spec.
492 An image can also be migrated from a read-only import source by adding the
493 *--import-only* optional and providing a JSON-encoded *--source-spec* or a
494 path to a JSON-encoded source-spec file using the *--source-spec-path*
497 :command:`mirror image demote` *image-spec*
498 Demote a primary image to non-primary for RBD mirroring.
500 :command:`mirror image disable` [--force] *image-spec*
501 Disable RBD mirroring for an image. If the mirroring is
502 configured in ``image`` mode for the image's pool, then it
503 can be explicitly disabled mirroring for each image within
506 :command:`mirror image enable` *image-spec* *mode*
507 Enable RBD mirroring for an image. If the mirroring is
508 configured in ``image`` mode for the image's pool, then it
509 can be explicitly enabled mirroring for each image within
512 The mirror image mode can either be ``journal`` (default) or
513 ``snapshot``. The ``journal`` mode requires the RBD journaling
516 :command:`mirror image promote` [--force] *image-spec*
517 Promote a non-primary image to primary for RBD mirroring.
519 :command:`mirror image resync` *image-spec*
520 Force resync to primary image for RBD mirroring.
522 :command:`mirror image status` *image-spec*
523 Show RBD mirroring status for an image.
525 :command:`mirror pool demote` [*pool-name*]
526 Demote all primary images within a pool to non-primary.
527 Every mirroring enabled image will demoted in the pool.
529 :command:`mirror pool disable` [*pool-name*]
530 Disable RBD mirroring by default within a pool. When mirroring
531 is disabled on a pool in this way, mirroring will also be
532 disabled on any images (within the pool) for which mirroring
533 was enabled explicitly.
535 :command:`mirror pool enable` [*pool-name*] *mode*
536 Enable RBD mirroring by default within a pool.
537 The mirroring mode can either be ``pool`` or ``image``.
538 If configured in ``pool`` mode, all images in the pool
539 with the journaling feature enabled are mirrored.
540 If configured in ``image`` mode, mirroring needs to be
541 explicitly enabled (by ``mirror image enable`` command)
544 :command:`mirror pool info` [*pool-name*]
545 Show information about the pool mirroring configuration.
546 It includes mirroring mode, peer UUID, remote cluster name,
547 and remote client name.
549 :command:`mirror pool peer add` [*pool-name*] *remote-cluster-spec*
550 Add a mirroring peer to a pool.
551 *remote-cluster-spec* is [*remote client name*\ @\ ]\ *remote cluster name*.
553 The default for *remote client name* is "client.admin".
555 This requires mirroring mode is enabled.
557 :command:`mirror pool peer remove` [*pool-name*] *uuid*
558 Remove a mirroring peer from a pool. The peer uuid is available
559 from ``mirror pool info`` command.
561 :command:`mirror pool peer set` [*pool-name*] *uuid* *key* *value*
562 Update mirroring peer settings.
563 The key can be either ``client`` or ``cluster``, and the value
564 is corresponding to remote client name or remote cluster name.
566 :command:`mirror pool promote` [--force] [*pool-name*]
567 Promote all non-primary images within a pool to primary.
568 Every mirroring enabled image will promoted in the pool.
570 :command:`mirror pool status` [--verbose] [*pool-name*]
571 Show status for all mirrored images in the pool.
572 With --verbose, also show additionally output status
573 details for every mirroring image in the pool.
575 :command:`mirror snapshot schedule add` [-p | --pool *pool*] [--namespace *namespace*] [--image *image*] *interval* [*start-time*]
576 Add mirror snapshot schedule.
578 :command:`mirror snapshot schedule list` [-R | --recursive] [--format *format*] [--pretty-format] [-p | --pool *pool*] [--namespace *namespace*] [--image *image*]
579 List mirror snapshot schedule.
581 :command:`mirror snapshot schedule remove` [-p | --pool *pool*] [--namespace *namespace*] [--image *image*] *interval* [*start-time*]
582 Remove mirror snapshot schedule.
584 :command:`mirror snapshot schedule status` [-p | --pool *pool*] [--format *format*] [--pretty-format] [--namespace *namespace*] [--image *image*]
585 Show mirror snapshot schedule status.
587 :command:`mv` *src-image-spec* *dest-image-spec*
588 Rename an image. Note: rename across pools is not supported.
590 :command:`namespace create` *pool-name*/*namespace-name*
591 Create a new image namespace within the pool.
593 :command:`namespace list` *pool-name*
594 List image namespaces defined within the pool.
596 :command:`namespace remove` *pool-name*/*namespace-name*
597 Remove an empty image namespace from the pool.
599 :command:`object-map check` *image-spec* | *snap-spec*
600 Verify the object map is correct.
602 :command:`object-map rebuild` *image-spec* | *snap-spec*
603 Rebuild an invalid object map for the specified image. An image snapshot can be
604 specified to rebuild an invalid object map for a snapshot.
606 :command:`pool init` [*pool-name*] [--force]
607 Initialize pool for use by RBD. Newly created pools must initialized
610 :command:`resize` (-s | --size *size-in-M/G/T*) [--allow-shrink] *image-spec*
611 Resize rbd image. The size parameter also needs to be specified.
612 The --allow-shrink option lets the size be reduced.
614 :command:`rm` *image-spec*
615 Delete an rbd image (including all data blocks). If the image has
616 snapshots, this fails and nothing is deleted.
618 :command:`snap create` *snap-spec*
619 Create a new snapshot. Requires the snapshot name parameter specified.
621 :command:`snap limit clear` *image-spec*
622 Remove any previously set limit on the number of snapshots allowed on
625 :command:`snap limit set` [--limit] *limit* *image-spec*
626 Set a limit for the number of snapshots allowed on an image.
628 :command:`snap ls` *image-spec*
629 Dump the list of snapshots inside a specific image.
631 :command:`snap protect` *snap-spec*
632 Protect a snapshot from deletion, so that clones can be made of it
633 (see `rbd clone`). Snapshots must be protected before clones are made;
634 protection implies that there exist dependent cloned children that
635 refer to this snapshot. `rbd clone` will fail on a nonprotected
638 This requires image format 2.
640 :command:`snap purge` *image-spec*
641 Remove all unprotected snapshots from an image.
643 :command:`snap rename` *src-snap-spec* *dest-snap-spec*
644 Rename a snapshot. Note: rename across pools and images is not supported.
646 :command:`snap rm` [--force] *snap-spec*
647 Remove the specified snapshot.
649 :command:`snap rollback` *snap-spec*
650 Rollback image content to snapshot. This will iterate through the entire blocks
651 array and update the data head content to the snapshotted version.
653 :command:`snap unprotect` *snap-spec*
654 Unprotect a snapshot from deletion (undo `snap protect`). If cloned
655 children remain, `snap unprotect` fails. (Note that clones may exist
656 in different pools than the parent snapshot.)
658 This requires image format 2.
660 :command:`sparsify` [--sparse-size *sparse-size*] *image-spec*
661 Reclaim space for zeroed image extents. The default sparse size is
662 4096 bytes and can be changed via --sparse-size option with the
663 following restrictions: it should be power of two, not less than
664 4096, and not larger than image object size.
666 :command:`status` *image-spec*
667 Show the status of the image, including which clients have it open.
669 :command:`trash ls` [*pool-name*]
670 List all entries from trash.
672 :command:`trash mv` *image-spec*
673 Move an image to the trash. Images, even ones actively in-use by
674 clones, can be moved to the trash and deleted at a later time.
676 :command:`trash purge` [*pool-name*]
677 Remove all expired images from trash.
679 :command:`trash restore` *image-id*
680 Restore an image from trash.
682 :command:`trash rm` *image-id*
683 Delete an image from trash. If image deferment time has not expired
684 you can not removed it unless use force. But an actively in-use by clones
685 or has snapshots can not be removed.
687 :command:`trash purge schedule add` [-p | --pool *pool*] [--namespace *namespace*] *interval* [*start-time*]
688 Add trash purge schedule.
690 :command:`trash purge schedule list` [-R | --recursive] [--format *format*] [--pretty-format] [-p | --pool *pool*] [--namespace *namespace*]
691 List trash purge schedule.
693 :command:`trash purge schedule remove` [-p | --pool *pool*] [--namespace *namespace*] *interval* [*start-time*]
694 Remove trash purge schedule.
696 :command:`trash purge schedule status` [-p | --pool *pool*] [--format *format*] [--pretty-format] [--namespace *namespace*]
697 Show trash purge schedule status.
699 :command:`watch` *image-spec*
700 Watch events on image.
702 Image, snap, group and journal specs
703 ====================================
705 | *image-spec* is [*pool-name*/[*namespace-name*/]]\ *image-name*
706 | *snap-spec* is [*pool-name*/[*namespace-name*/]]\ *image-name*\ @\ *snap-name*
707 | *group-spec* is [*pool-name*/[*namespace-name*/]]\ *group-name*
708 | *group-snap-spec* is [*pool-name*/[*namespace-name*/]]\ *group-name*\ @\ *snap-name*
709 | *journal-spec* is [*pool-name*/[*namespace-name*/]]\ *journal-name*
711 The default for *pool-name* is "rbd" and *namespace-name* is "". If an image
712 name contains a slash character ('/'), *pool-name* is required.
714 The *journal-name* is *image-id*.
716 You may specify each name individually, using --pool, --namespace, --image, and
717 --snap options, but this is discouraged in favor of the above spec syntax.
722 RBD images are striped over many objects, which are then stored by the
723 Ceph distributed object store (RADOS). As a result, read and write
724 requests for the image are distributed across many nodes in the
725 cluster, generally preventing any single node from becoming a
726 bottleneck when individual images get large or busy.
728 The striping is controlled by three parameters:
730 .. option:: object-size
732 The size of objects we stripe over is a power of two. It will be rounded up the nearest power of two.
733 The default object size is 4 MB, smallest is 4K and maximum is 32M.
735 .. option:: stripe_unit
737 Each [*stripe_unit*] contiguous bytes are stored adjacently in the same object, before we move on
740 .. option:: stripe_count
742 After we write [*stripe_unit*] bytes to [*stripe_count*] objects, we loop back to the initial object
743 and write another stripe, until the object reaches its maximum size. At that point,
744 we move on to the next [*stripe_count*] objects.
746 By default, [*stripe_unit*] is the same as the object size and [*stripe_count*] is 1. Specifying a different
747 [*stripe_unit*] and/or [*stripe_count*] is often referred to as using "fancy" striping and requires format 2.
750 Kernel rbd (krbd) options
751 =========================
753 Most of these options are useful mainly for debugging and benchmarking. The
754 default values are set in the kernel and may therefore depend on the version of
757 Per client instance `rbd device map` options:
759 * fsid=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee - FSID that should be assumed by
762 * ip=a.b.c.d[:p] - IP and, optionally, port the client should use.
764 * share - Enable sharing of client instances with other mappings (default).
766 * noshare - Disable sharing of client instances with other mappings.
768 * crc - Enable CRC32C checksumming for msgr1 on-the-wire protocol (default).
769 For msgr2.1 protocol this option is ignored: full checksumming is always on
770 in 'crc' mode and always off in 'secure' mode.
772 * nocrc - Disable CRC32C checksumming for msgr1 on-the-wire protocol. Note
773 that only payload checksumming is disabled, header checksumming is always on.
774 For msgr2.1 protocol this option is ignored.
776 * cephx_require_signatures - Require msgr1 message signing feature (since 3.19,
777 default). This option is deprecated and will be removed in the future as the
778 feature has been supported since the Bobtail release.
780 * nocephx_require_signatures - Don't require msgr1 message signing feature
781 (since 3.19). This option is deprecated and will be removed in the future.
783 * tcp_nodelay - Disable Nagle's algorithm on client sockets (since 4.0,
786 * notcp_nodelay - Enable Nagle's algorithm on client sockets (since 4.0).
788 * cephx_sign_messages - Enable message signing for msgr1 on-the-wire protocol
789 (since 4.4, default). For msgr2.1 protocol this option is ignored: message
790 signing is built into 'secure' mode and not offered in 'crc' mode.
792 * nocephx_sign_messages - Disable message signing for msgr1 on-the-wire protocol
793 (since 4.4). For msgr2.1 protocol this option is ignored.
795 * mount_timeout=x - A timeout on various steps in `rbd device map` and
796 `rbd device unmap` sequences (default is 60 seconds). In particular,
797 since 4.2 this can be used to ensure that `rbd device unmap` eventually
798 times out when there is no network connection to a cluster.
800 * osdkeepalive=x - OSD keepalive timeout (default is 5 seconds).
802 * osd_idle_ttl=x - OSD idle TTL (default is 60 seconds).
804 Per mapping (block device) `rbd device map` options:
806 * rw - Map the image read-write (default). Overridden by --read-only.
808 * ro - Map the image read-only. Equivalent to --read-only.
810 * queue_depth=x - queue depth (since 4.2, default is 128 requests).
812 * lock_on_read - Acquire exclusive lock on reads, in addition to writes and
813 discards (since 4.9).
815 * exclusive - Disable automatic exclusive lock transitions (since 4.12).
816 Equivalent to --exclusive.
818 * lock_timeout=x - A timeout on waiting for the acquisition of exclusive lock
819 (since 4.17, default is 0 seconds, meaning no timeout).
821 * notrim - Turn off discard and write zeroes offload support to avoid
822 deprovisioning a fully provisioned image (since 4.17). When enabled, discard
823 requests will fail with -EOPNOTSUPP, write zeroes requests will fall back to
826 * abort_on_full - Fail write requests with -ENOSPC when the cluster is full or
827 the data pool reaches its quota (since 5.0). The default behaviour is to
828 block until the full condition is cleared.
830 * alloc_size - Minimum allocation unit of the underlying OSD object store
831 backend (since 5.1, default is 64K bytes). This is used to round off and
832 drop discards that are too small. For bluestore, the recommended setting is
833 bluestore_min_alloc_size (currently set to 4K for all types of drives,
834 previously used to be set to 64K for hard disk drives and 16K for
835 solid-state drives). For filestore with filestore_punch_hole = false, the
836 recommended setting is image object size (typically 4M).
838 * crush_location=x - Specify the location of the client in terms of CRUSH
839 hierarchy (since 5.8). This is a set of key-value pairs separated from
840 each other by '|', with keys separated from values by ':'. Note that '|'
841 may need to be quoted or escaped to avoid it being interpreted as a pipe
842 by the shell. The key is the bucket type name (e.g. rack, datacenter or
843 region with default bucket types) and the value is the bucket name. For
844 example, to indicate that the client is local to rack "myrack", data center
845 "mydc" and region "myregion"::
847 crush_location=rack:myrack|datacenter:mydc|region:myregion
849 Each key-value pair stands on its own: "myrack" doesn't need to reside in
850 "mydc", which in turn doesn't need to reside in "myregion". The location
851 is not a path to the root of the hierarchy but rather a set of nodes that
852 are matched independently, owning to the fact that bucket names are unique
853 within a CRUSH map. "Multipath" locations are supported, so it is possible
854 to indicate locality for multiple parallel hierarchies::
856 crush_location=rack:myrack1|rack:myrack2|datacenter:mydc
858 * read_from_replica=no - Disable replica reads, always pick the primary OSD
859 (since 5.8, default).
861 * read_from_replica=balance - When issued a read on a replicated pool, pick
862 a random OSD for serving it (since 5.8).
864 This mode is safe for general use only since Octopus (i.e. after "ceph osd
865 require-osd-release octopus"). Otherwise it should be limited to read-only
866 workloads such as images mapped read-only everywhere or snapshots.
868 * read_from_replica=localize - When issued a read on a replicated pool, pick
869 the most local OSD for serving it (since 5.8). The locality metric is
870 calculated against the location of the client given with crush_location;
871 a match with the lowest-valued bucket type wins. For example, with default
872 bucket types, an OSD in a matching rack is closer than an OSD in a matching
873 data center, which in turn is closer than an OSD in a matching region.
875 This mode is safe for general use only since Octopus (i.e. after "ceph osd
876 require-osd-release octopus"). Otherwise it should be limited to read-only
877 workloads such as images mapped read-only everywhere or snapshots.
879 * compression_hint=none - Don't set compression hints (since 5.8, default).
881 * compression_hint=compressible - Hint to the underlying OSD object store
882 backend that the data is compressible, enabling compression in passive mode
885 * compression_hint=incompressible - Hint to the underlying OSD object store
886 backend that the data is incompressible, disabling compression in aggressive
889 * ms_mode=legacy - Use msgr1 on-the-wire protocol (since 5.11, default).
891 * ms_mode=crc - Use msgr2.1 on-the-wire protocol, select 'crc' mode, also
892 referred to as plain mode (since 5.11). If the daemon denies 'crc' mode,
895 * ms_mode=secure - Use msgr2.1 on-the-wire protocol, select 'secure' mode
896 (since 5.11). 'secure' mode provides full in-transit encryption ensuring
897 both confidentiality and authenticity. If the daemon denies 'secure' mode,
900 * ms_mode=prefer-crc - Use msgr2.1 on-the-wire protocol, select 'crc'
901 mode (since 5.11). If the daemon denies 'crc' mode in favor of 'secure'
902 mode, agree to 'secure' mode.
904 * ms_mode=prefer-secure - Use msgr2.1 on-the-wire protocol, select 'secure'
905 mode (since 5.11). If the daemon denies 'secure' mode in favor of 'crc'
906 mode, agree to 'crc' mode.
908 * rxbounce - Use a bounce buffer when receiving data (since 5.17). The default
909 behaviour is to read directly into the destination buffer. A bounce buffer
910 is needed if the destination buffer isn't guaranteed to be stable (i.e. remain
911 unchanged while it is being read to). In particular this is the case for
912 Windows where a system-wide "dummy" (throwaway) page may be mapped into the
913 destination buffer in order to generate a single large I/O. Otherwise,
914 "libceph: ... bad crc/signature" or "libceph: ... integrity error, bad crc"
915 errors and associated performance degradation are expected.
917 * udev - Wait for udev device manager to finish executing all matching
918 "add" rules and release the device before exiting (default). This option
919 is not passed to the kernel.
921 * noudev - Don't wait for udev device manager. When enabled, the device may
922 not be fully usable immediately on exit.
924 `rbd device unmap` options:
926 * force - Force the unmapping of a block device that is open (since 4.9). The
927 driver will wait for running requests to complete and then unmap; requests
928 sent to the driver after initiating the unmap will be failed.
930 * udev - Wait for udev device manager to finish executing all matching
931 "remove" rules and clean up after the device before exiting (default).
932 This option is not passed to the kernel.
934 * noudev - Don't wait for udev device manager.
940 To create a new rbd image that is 100 GB::
942 rbd create mypool/myimage --size 102400
944 To use a non-default object size (8 MB)::
946 rbd create mypool/myimage --size 102400 --object-size 8M
948 To delete an rbd image (be careful!)::
950 rbd rm mypool/myimage
952 To create a new snapshot::
954 rbd snap create mypool/myimage@mysnap
956 To create a copy-on-write clone of a protected snapshot::
958 rbd clone mypool/myimage@mysnap otherpool/cloneimage
960 To see which clones of a snapshot exist::
962 rbd children mypool/myimage@mysnap
964 To delete a snapshot::
966 rbd snap rm mypool/myimage@mysnap
968 To map an image via the kernel with cephx enabled::
970 rbd device map mypool/myimage --id admin --keyfile secretfile
972 To map an image via the kernel with different cluster name other than default *ceph*::
974 rbd device map mypool/myimage --cluster cluster-name
978 rbd device unmap /dev/rbd0
980 To create an image and a clone from it::
982 rbd import --image-format 2 image mypool/parent
983 rbd snap create mypool/parent@snap
984 rbd snap protect mypool/parent@snap
985 rbd clone mypool/parent@snap otherpool/child
987 To create an image with a smaller stripe_unit (to better distribute small writes in some workloads)::
989 rbd create mypool/myimage --size 102400 --stripe-unit 65536B --stripe-count 16
991 To change an image from one image format to another, export it and then
992 import it as the desired image format::
994 rbd export mypool/myimage@snap /tmp/img
995 rbd import --image-format 2 /tmp/img mypool/myimage2
997 To lock an image for exclusive use::
999 rbd lock add mypool/myimage mylockid
1003 rbd lock remove mypool/myimage mylockid client.2485
1005 To list images from trash::
1009 To defer delete an image (use *--expires-at* to set expiration time, default is now)::
1011 rbd trash mv mypool/myimage --expires-at "tomorrow"
1013 To delete an image from trash (be careful!)::
1015 rbd trash rm mypool/myimage-id
1017 To force delete an image from trash (be careful!)::
1019 rbd trash rm mypool/myimage-id --force
1021 To restore an image from trash::
1023 rbd trash restore mypool/myimage-id
1025 To restore an image from trash and rename it::
1027 rbd trash restore mypool/myimage-id --image mynewimage
1033 **rbd** is part of Ceph, a massively scalable, open-source, distributed storage system. Please refer to
1034 the Ceph documentation at https://docs.ceph.com for more information.
1040 :doc:`ceph <ceph>`\(8),
1041 :doc:`rados <rados>`\(8)