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 (typically 64K for hard disk drives and 16K for
834 solid-state drives). For filestore with filestore_punch_hole = false, the
835 recommended setting is image object size (typically 4M).
837 * crush_location=x - Specify the location of the client in terms of CRUSH
838 hierarchy (since 5.8). This is a set of key-value pairs separated from
839 each other by '|', with keys separated from values by ':'. Note that '|'
840 may need to be quoted or escaped to avoid it being interpreted as a pipe
841 by the shell. The key is the bucket type name (e.g. rack, datacenter or
842 region with default bucket types) and the value is the bucket name. For
843 example, to indicate that the client is local to rack "myrack", data center
844 "mydc" and region "myregion"::
846 crush_location=rack:myrack|datacenter:mydc|region:myregion
848 Each key-value pair stands on its own: "myrack" doesn't need to reside in
849 "mydc", which in turn doesn't need to reside in "myregion". The location
850 is not a path to the root of the hierarchy but rather a set of nodes that
851 are matched independently, owning to the fact that bucket names are unique
852 within a CRUSH map. "Multipath" locations are supported, so it is possible
853 to indicate locality for multiple parallel hierarchies::
855 crush_location=rack:myrack1|rack:myrack2|datacenter:mydc
857 * read_from_replica=no - Disable replica reads, always pick the primary OSD
858 (since 5.8, default).
860 * read_from_replica=balance - When issued a read on a replicated pool, pick
861 a random OSD for serving it (since 5.8).
863 This mode is safe for general use only since Octopus (i.e. after "ceph osd
864 require-osd-release octopus"). Otherwise it should be limited to read-only
865 workloads such as images mapped read-only everywhere or snapshots.
867 * read_from_replica=localize - When issued a read on a replicated pool, pick
868 the most local OSD for serving it (since 5.8). The locality metric is
869 calculated against the location of the client given with crush_location;
870 a match with the lowest-valued bucket type wins. For example, with default
871 bucket types, an OSD in a matching rack is closer than an OSD in a matching
872 data center, which in turn is closer than an OSD in a matching region.
874 This mode is safe for general use only since Octopus (i.e. after "ceph osd
875 require-osd-release octopus"). Otherwise it should be limited to read-only
876 workloads such as images mapped read-only everywhere or snapshots.
878 * compression_hint=none - Don't set compression hints (since 5.8, default).
880 * compression_hint=compressible - Hint to the underlying OSD object store
881 backend that the data is compressible, enabling compression in passive mode
884 * compression_hint=incompressible - Hint to the underlying OSD object store
885 backend that the data is incompressible, disabling compression in aggressive
888 * ms_mode=legacy - Use msgr1 on-the-wire protocol (since 5.11, default).
890 * ms_mode=crc - Use msgr2.1 on-the-wire protocol, select 'crc' mode, also
891 referred to as plain mode (since 5.11). If the daemon denies 'crc' mode,
894 * ms_mode=secure - Use msgr2.1 on-the-wire protocol, select 'secure' mode
895 (since 5.11). 'secure' mode provides full in-transit encryption ensuring
896 both confidentiality and authenticity. If the daemon denies 'secure' mode,
899 * ms_mode=prefer-crc - Use msgr2.1 on-the-wire protocol, select 'crc'
900 mode (since 5.11). If the daemon denies 'crc' mode in favor of 'secure'
901 mode, agree to 'secure' mode.
903 * ms_mode=prefer-secure - Use msgr2.1 on-the-wire protocol, select 'secure'
904 mode (since 5.11). If the daemon denies 'secure' mode in favor of 'crc'
905 mode, agree to 'crc' mode.
907 * rxbounce - Use a bounce buffer when receiving data (since 5.17). The default
908 behaviour is to read directly into the destination buffer. A bounce buffer
909 is needed if the destination buffer isn't guaranteed to be stable (i.e. remain
910 unchanged while it is being read to). In particular this is the case for
911 Windows where a system-wide "dummy" (throwaway) page may be mapped into the
912 destination buffer in order to generate a single large I/O. Otherwise,
913 "libceph: ... bad crc/signature" or "libceph: ... integrity error, bad crc"
914 errors and associated performance degradation are expected.
916 * udev - Wait for udev device manager to finish executing all matching
917 "add" rules and release the device before exiting (default). This option
918 is not passed to the kernel.
920 * noudev - Don't wait for udev device manager. When enabled, the device may
921 not be fully usable immediately on exit.
923 `rbd device unmap` options:
925 * force - Force the unmapping of a block device that is open (since 4.9). The
926 driver will wait for running requests to complete and then unmap; requests
927 sent to the driver after initiating the unmap will be failed.
929 * udev - Wait for udev device manager to finish executing all matching
930 "remove" rules and clean up after the device before exiting (default).
931 This option is not passed to the kernel.
933 * noudev - Don't wait for udev device manager.
939 To create a new rbd image that is 100 GB::
941 rbd create mypool/myimage --size 102400
943 To use a non-default object size (8 MB)::
945 rbd create mypool/myimage --size 102400 --object-size 8M
947 To delete an rbd image (be careful!)::
949 rbd rm mypool/myimage
951 To create a new snapshot::
953 rbd snap create mypool/myimage@mysnap
955 To create a copy-on-write clone of a protected snapshot::
957 rbd clone mypool/myimage@mysnap otherpool/cloneimage
959 To see which clones of a snapshot exist::
961 rbd children mypool/myimage@mysnap
963 To delete a snapshot::
965 rbd snap rm mypool/myimage@mysnap
967 To map an image via the kernel with cephx enabled::
969 rbd device map mypool/myimage --id admin --keyfile secretfile
971 To map an image via the kernel with different cluster name other than default *ceph*::
973 rbd device map mypool/myimage --cluster cluster-name
977 rbd device unmap /dev/rbd0
979 To create an image and a clone from it::
981 rbd import --image-format 2 image mypool/parent
982 rbd snap create mypool/parent@snap
983 rbd snap protect mypool/parent@snap
984 rbd clone mypool/parent@snap otherpool/child
986 To create an image with a smaller stripe_unit (to better distribute small writes in some workloads)::
988 rbd create mypool/myimage --size 102400 --stripe-unit 65536B --stripe-count 16
990 To change an image from one image format to another, export it and then
991 import it as the desired image format::
993 rbd export mypool/myimage@snap /tmp/img
994 rbd import --image-format 2 /tmp/img mypool/myimage2
996 To lock an image for exclusive use::
998 rbd lock add mypool/myimage mylockid
1002 rbd lock remove mypool/myimage mylockid client.2485
1004 To list images from trash::
1008 To defer delete an image (use *--expires-at* to set expiration time, default is now)::
1010 rbd trash mv mypool/myimage --expires-at "tomorrow"
1012 To delete an image from trash (be careful!)::
1014 rbd trash rm mypool/myimage-id
1016 To force delete an image from trash (be careful!)::
1018 rbd trash rm mypool/myimage-id --force
1020 To restore an image from trash::
1022 rbd trash restore mypool/myimage-id
1024 To restore an image from trash and rename it::
1026 rbd trash restore mypool/myimage-id --image mynewimage
1032 **rbd** is part of Ceph, a massively scalable, open-source, distributed storage system. Please refer to
1033 the Ceph documentation at https://docs.ceph.com for more information.
1039 :doc:`ceph <ceph>`\(8),
1040 :doc:`rados <rados>`\(8)