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 .. option:: --stripe-unit size-in-B/K/M
86 Specifies the stripe unit size in B/K/M. If no suffix is given, unit B is
87 assumed. See striping section (below) for more details.
89 .. option:: --stripe-count num
91 Specifies the number of objects to stripe over before looping back
92 to the first object. See striping section (below) for more details.
94 .. option:: --snap snap
96 Specifies the snapshot name for the specific operation.
98 .. option:: --id username
100 Specifies the username (without the ``client.`` prefix) to use with the map command.
102 .. option:: --keyring filename
104 Specifies a keyring file containing a secret for the specified user
105 to use with the map command. If not specified, the default keyring
106 locations will be searched.
108 .. option:: --keyfile filename
110 Specifies a file containing the secret key of ``--id user`` to use with the map command.
111 This option is overridden by ``--keyring`` if the latter is also specified.
113 .. option:: --shared lock-tag
115 Option for `lock add` that allows multiple clients to lock the
116 same image if they use the same tag. The tag is an arbitrary
117 string. This is useful for situations where an image must
118 be open from more than one client at once, like during
119 live migration of a virtual machine, or for use underneath
120 a clustered file system.
122 .. option:: --format format
124 Specifies output formatting (default: plain, json, xml)
126 .. option:: --pretty-format
128 Make json or xml formatted output more human-readable.
130 .. option:: -o krbd-options, --options krbd-options
132 Specifies which options to use when mapping or unmapping an image via the
133 rbd kernel driver. krbd-options is a comma-separated list of options
134 (similar to mount(8) mount options). See kernel rbd (krbd) options section
135 below for more details.
137 .. option:: --read-only
139 Map the image read-only. Equivalent to -o ro.
141 .. option:: --image-feature feature-name
143 Specifies which RBD format 2 feature should be enabled when creating
144 an image. Multiple features can be enabled by repeating this option
145 multiple times. The following features are supported:
147 * layering: layering support
148 * striping: striping v2 support
149 * exclusive-lock: exclusive locking support
150 * object-map: object map support (requires exclusive-lock)
151 * fast-diff: fast diff calculations (requires object-map)
152 * deep-flatten: snapshot flatten support
153 * journaling: journaled IO support (requires exclusive-lock)
154 * data-pool: erasure coded pool support
156 .. option:: --image-shared
158 Specifies that the image will be used concurrently by multiple clients.
159 This will disable features that are dependent upon exclusive ownership
162 .. option:: --whole-object
164 Specifies that the diff should be limited to the extents of a full object
165 instead of showing intra-object deltas. When the object map feature is
166 enabled on an image, limiting the diff to the object extents will
167 dramatically improve performance since the differences can be computed
168 by examining the in-memory object map instead of querying RADOS for each
169 object within the image.
173 Specifies the limit for the number of snapshots permitted.
178 .. TODO rst "option" directive seems to require --foo style options, parsing breaks on subcommands.. the args show up as bold too
180 :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*
181 Generate a series of IOs to the image and measure the IO throughput and
182 latency. If no suffix is given, unit B is assumed for both --io-size and
183 --io-total. Defaults are: --io-size 4096, --io-threads 16, --io-total 1G,
184 --io-pattern seq, --rw-mix-read 50.
186 :command:`children` *snap-spec*
187 List the clones of the image at the given snapshot. This checks
188 every pool, and outputs the resulting poolname/imagename.
190 This requires image format 2.
192 :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*
193 Will create a clone (copy-on-write child) of the parent snapshot.
194 Object size will be identical to that of the parent image unless
195 specified. Size will be the same as the parent snapshot. The --stripe-unit
196 and --stripe-count arguments are optional, but must be used together.
198 The parent snapshot must be protected (see `rbd snap protect`).
199 This requires image format 2.
201 :command:`config global get` *config-entity* *key*
202 Get a global-level configuration override.
204 :command:`config global list` [--format plain | json | xml] [--pretty-format] *config-entity*
205 List global-level configuration overrides.
207 :command:`config global set` *config-entity* *key* *value*
208 Set a global-level configuration override.
210 :command:`config global remove` *config-entity* *key*
211 Remove a global-level configuration override.
213 :command:`config image get` *image-spec* *key*
214 Get an image-level configuration override.
216 :command:`config image list` [--format plain | json | xml] [--pretty-format] *image-spec*
217 List image-level configuration overrides.
219 :command:`config image set` *image-spec* *key* *value*
220 Set an image-level configuration override.
222 :command:`config image remove` *image-spec* *key*
223 Remove an image-level configuration override.
225 :command:`config pool get` *pool-name* *key*
226 Get a pool-level configuration override.
228 :command:`config pool list` [--format plain | json | xml] [--pretty-format] *pool-name*
229 List pool-level configuration overrides.
231 :command:`config pool set` *pool-name* *key* *value*
232 Set a pool-level configuration override.
234 :command:`config pool remove` *pool-name* *key*
235 Remove a pool-level configuration override.
237 :command:`cp` (*src-image-spec* | *src-snap-spec*) *dest-image-spec*
238 Copy the content of a src-image into the newly created dest-image.
239 dest-image will have the same size, object size, and image format as src-image.
241 :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*
242 Will create a new rbd image. You must also specify the size via --size. The
243 --stripe-unit and --stripe-count arguments are optional, but must be used together.
244 If the --thick-provision is enabled, it will fully allocate storage for
245 the image at creation time. It will take a long time to do.
246 Note: thick provisioning requires zeroing the contents of the entire image.
248 :command:`deep cp` (*src-image-spec* | *src-snap-spec*) *dest-image-spec*
249 Deep copy the content of a src-image into the newly created dest-image.
250 Dest-image will have the same size, object size, image format, and snapshots as src-image.
252 :command:`device list` [-t | --device-type *device-type*] [--format plain | json | xml] --pretty-format
253 Show the rbd images that are mapped via the rbd kernel module
254 (default) or other supported device.
256 :command:`device map` [-t | --device-type *device-type*] [--read-only] [--exclusive] [-o | --options *device-options*] *image-spec* | *snap-spec*
257 Map the specified image to a block device via the rbd kernel module
258 (default) or other supported device (*nbd* on Linux or *ggate* on
261 The --options argument is a comma separated list of device type
262 specific options (opt1,opt2=val,...).
264 :command:`device unmap` [-t | --device-type *device-type*] [-o | --options *device-options*] *image-spec* | *snap-spec* | *device-path*
265 Unmap the block device that was mapped via the rbd kernel module
266 (default) or other supported device.
268 The --options argument is a comma separated list of device type
269 specific options (opt1,opt2=val,...).
271 :command:`diff` [--from-snap *snap-name*] [--whole-object] *image-spec* | *snap-spec*
272 Dump a list of byte extents in the image that have changed since the specified start
273 snapshot, or since the image was created. Each output line includes the starting offset
274 (in bytes), the length of the region (in bytes), and either 'zero' or 'data' to indicate
275 whether the region is known to be zeros or may contain other data.
277 :command:`du` [-p | --pool *pool-name*] [*image-spec* | *snap-spec*] [--merge-snapshots]
278 Will calculate the provisioned and actual disk usage of all images and
279 associated snapshots within the specified pool. It can also be used against
280 individual images and snapshots.
282 If the RBD fast-diff feature is not enabled on images, this operation will
283 require querying the OSDs for every potential object within the image.
285 The --merge-snapshots will merge snapshots used space into their parent images.
287 :command:`encryption format` *image-spec* *format* *passphrase-file* [--cipher-alg *alg*]
288 Formats image to an encrypted format.
289 All data previously written to the image will become unreadable.
290 A cloned image cannot be formatted, although encrypted images can be cloned.
291 Supported formats: *luks1*, *luks2*.
292 Supported cipher algorithms: *aes-128*, *aes-256* (default).
294 :command:`export` [--export-format *format (1 or 2)*] (*image-spec* | *snap-spec*) [*dest-path*]
295 Export image to dest path (use - for stdout).
296 The --export-format accepts '1' or '2' currently. Format 2 allow us to export not only the content
297 of image, but also the snapshots and other properties, such as image_order, features.
299 :command:`export-diff` [--from-snap *snap-name*] [--whole-object] (*image-spec* | *snap-spec*) *dest-path*
300 Export an incremental diff for an image to dest path (use - for stdout). If
301 an initial snapshot is specified, only changes since that snapshot are included; otherwise,
302 any regions of the image that contain data are included. The end snapshot is specified
303 using the standard --snap option or @snap syntax (see below). The image diff format includes
304 metadata about image size changes, and the start and end snapshots. It efficiently represents
305 discarded or 'zero' regions of the image.
307 :command:`feature disable` *image-spec* *feature-name*...
308 Disable the specified feature on the specified image. Multiple features can
311 :command:`feature enable` *image-spec* *feature-name*...
312 Enable the specified feature on the specified image. Multiple features can
315 :command:`flatten` *image-spec*
316 If image is a clone, copy all shared blocks from the parent snapshot and
317 make the child independent of the parent, severing the link between
318 parent snap and child. The parent snapshot can be unprotected and
319 deleted if it has no further dependent clones.
321 This requires image format 2.
323 :command:`group create` *group-spec*
326 :command:`group image add` *group-spec* *image-spec*
327 Add an image to a group.
329 :command:`group image list` *group-spec*
330 List images in a group.
332 :command:`group image remove` *group-spec* *image-spec*
333 Remove an image from a group.
335 :command:`group ls` [-p | --pool *pool-name*]
338 :command:`group rename` *src-group-spec* *dest-group-spec*
339 Rename a group. Note: rename across pools is not supported.
341 :command:`group rm` *group-spec*
344 :command:`group snap create` *group-snap-spec*
345 Make a snapshot of a group.
347 :command:`group snap list` *group-spec*
348 List snapshots of a group.
350 :command:`group snap rm` *group-snap-spec*
351 Remove a snapshot from a group.
353 :command:`group snap rename` *group-snap-spec* *snap-name*
354 Rename group's snapshot.
356 :command:`group snap rollback` *group-snap-spec*
357 Rollback group to snapshot.
359 :command:`image-meta get` *image-spec* *key*
360 Get metadata value with the key.
362 :command:`image-meta list` *image-spec*
363 Show metadata held on the image. The first column is the key
364 and the second column is the value.
366 :command:`image-meta remove` *image-spec* *key*
367 Remove metadata key with the value.
369 :command:`image-meta set` *image-spec* *key* *value*
370 Set metadata key with the value. They will displayed in `image-meta list`.
372 :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*]
373 Create a new image and imports its data from path (use - for
374 stdin). The import operation will try to create sparse rbd images
375 if possible. For import from stdin, the sparsification unit is
376 the data block size of the destination image (object size).
378 The --stripe-unit and --stripe-count arguments are optional, but must be
381 The --export-format accepts '1' or '2' currently. Format 2 allow us to import not only the content
382 of image, but also the snapshots and other properties, such as image_order, features.
384 :command:`import-diff` *src-path* *image-spec*
385 Import an incremental diff of an image and applies it to the current image. If the diff
386 was generated relative to a start snapshot, we verify that snapshot already exists before
387 continuing. If there was an end snapshot we verify it does not already exist before
388 applying the changes, and create the snapshot when we are done.
390 :command:`info` *image-spec* | *snap-spec*
391 Will dump information (such as size and object size) about a specific rbd image.
392 If image is a clone, information about its parent is also displayed.
393 If a snapshot is specified, whether it is protected is shown as well.
395 :command:`journal client disconnect` *journal-spec*
396 Flag image journal client as disconnected.
398 :command:`journal export` [--verbose] [--no-error] *src-journal-spec* *path-name*
399 Export image journal to path (use - for stdout). It can be make a backup
400 of the image journal especially before attempting dangerous operations.
402 Note that this command may not always work if the journal is badly corrupted.
404 :command:`journal import` [--verbose] [--no-error] *path-name* *dest-journal-spec*
405 Import image journal from path (use - for stdin).
407 :command:`journal info` *journal-spec*
408 Show information about image journal.
410 :command:`journal inspect` [--verbose] *journal-spec*
411 Inspect and report image journal for structural errors.
413 :command:`journal reset` *journal-spec*
416 :command:`journal status` *journal-spec*
417 Show status of image journal.
419 :command:`lock add` [--shared *lock-tag*] *image-spec* *lock-id*
420 Lock an image. The lock-id is an arbitrary name for the user's
421 convenience. By default, this is an exclusive lock, meaning it
422 will fail if the image is already locked. The --shared option
423 changes this behavior. Note that locking does not affect
424 any operation other than adding a lock. It does not
425 protect an image from being deleted.
427 :command:`lock ls` *image-spec*
428 Show locks held on the image. The first column is the locker
429 to use with the `lock remove` command.
431 :command:`lock rm` *image-spec* *lock-id* *locker*
432 Release a lock on an image. The lock id and locker are
433 as output by lock ls.
435 :command:`ls` [-l | --long] [*pool-name*]
436 Will list all rbd images listed in the rbd_directory object. With
437 -l, also show snapshots, and use longer-format output including
438 size, parent (if clone), format, etc.
440 :command:`merge-diff` *first-diff-path* *second-diff-path* *merged-diff-path*
441 Merge two continuous incremental diffs of an image into one single diff. The
442 first diff's end snapshot must be equal with the second diff's start snapshot.
443 The first diff could be - for stdin, and merged diff could be - for stdout, which
444 enables multiple diff files to be merged using something like
445 'rbd merge-diff first second - | rbd merge-diff - third result'. Note this command
446 currently only support the source incremental diff with stripe_count == 1
448 :command:`migration abort` *image-spec*
449 Cancel image migration. This step may be run after successful or
450 failed migration prepare or migration execute steps and returns the
451 image to its initial (before migration) state. All modifications to
452 the destination image are lost.
454 :command:`migration commit` *image-spec*
455 Commit image migration. This step is run after a successful migration
456 prepare and migration execute steps and removes the source image data.
458 :command:`migration execute` *image-spec*
459 Execute image migration. This step is run after a successful migration
460 prepare step and copies image data to the destination.
462 :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*]
463 Prepare image migration. This is the first step when migrating an
464 image, i.e. changing the image location, format or other
465 parameters that can't be changed dynamically. The destination can
466 match the source, and in this case *dest-image-spec* can be omitted.
467 After this step the source image is set as a parent of the
468 destination image, and the image is accessible in copy-on-write mode
469 by its destination spec.
471 An image can also be migrated from a read-only import source by adding the
472 *--import-only* optional and providing a JSON-encoded *--source-spec* or a
473 path to a JSON-encoded source-spec file using the *--source-spec-path*
476 :command:`mirror image demote` *image-spec*
477 Demote a primary image to non-primary for RBD mirroring.
479 :command:`mirror image disable` [--force] *image-spec*
480 Disable RBD mirroring for an image. If the mirroring is
481 configured in ``image`` mode for the image's pool, then it
482 can be explicitly disabled mirroring for each image within
485 :command:`mirror image enable` *image-spec* *mode*
486 Enable RBD mirroring for an image. If the mirroring is
487 configured in ``image`` mode for the image's pool, then it
488 can be explicitly enabled mirroring for each image within
491 The mirror image mode can either be ``journal`` (default) or
492 ``snapshot``. The ``journal`` mode requires the RBD journaling
495 :command:`mirror image promote` [--force] *image-spec*
496 Promote a non-primary image to primary for RBD mirroring.
498 :command:`mirror image resync` *image-spec*
499 Force resync to primary image for RBD mirroring.
501 :command:`mirror image status` *image-spec*
502 Show RBD mirroring status for an image.
504 :command:`mirror pool demote` [*pool-name*]
505 Demote all primary images within a pool to non-primary.
506 Every mirroring enabled image will demoted in the pool.
508 :command:`mirror pool disable` [*pool-name*]
509 Disable RBD mirroring by default within a pool. When mirroring
510 is disabled on a pool in this way, mirroring will also be
511 disabled on any images (within the pool) for which mirroring
512 was enabled explicitly.
514 :command:`mirror pool enable` [*pool-name*] *mode*
515 Enable RBD mirroring by default within a pool.
516 The mirroring mode can either be ``pool`` or ``image``.
517 If configured in ``pool`` mode, all images in the pool
518 with the journaling feature enabled are mirrored.
519 If configured in ``image`` mode, mirroring needs to be
520 explicitly enabled (by ``mirror image enable`` command)
523 :command:`mirror pool info` [*pool-name*]
524 Show information about the pool mirroring configuration.
525 It includes mirroring mode, peer UUID, remote cluster name,
526 and remote client name.
528 :command:`mirror pool peer add` [*pool-name*] *remote-cluster-spec*
529 Add a mirroring peer to a pool.
530 *remote-cluster-spec* is [*remote client name*\ @\ ]\ *remote cluster name*.
532 The default for *remote client name* is "client.admin".
534 This requires mirroring mode is enabled.
536 :command:`mirror pool peer remove` [*pool-name*] *uuid*
537 Remove a mirroring peer from a pool. The peer uuid is available
538 from ``mirror pool info`` command.
540 :command:`mirror pool peer set` [*pool-name*] *uuid* *key* *value*
541 Update mirroring peer settings.
542 The key can be either ``client`` or ``cluster``, and the value
543 is corresponding to remote client name or remote cluster name.
545 :command:`mirror pool promote` [--force] [*pool-name*]
546 Promote all non-primary images within a pool to primary.
547 Every mirroring enabled image will promoted in the pool.
549 :command:`mirror pool status` [--verbose] [*pool-name*]
550 Show status for all mirrored images in the pool.
551 With --verbose, also show additionally output status
552 details for every mirroring image in the pool.
554 :command:`mirror snapshot schedule add` [-p | --pool *pool*] [--namespace *namespace*] [--image *image*] *interval* [*start-time*]
555 Add mirror snapshot schedule.
557 :command:`mirror snapshot schedule list` [-R | --recursive] [--format *format*] [--pretty-format] [-p | --pool *pool*] [--namespace *namespace*] [--image *image*]
558 List mirror snapshot schedule.
560 :command:`mirror snapshot schedule remove` [-p | --pool *pool*] [--namespace *namespace*] [--image *image*] *interval* [*start-time*]
561 Remove mirror snapshot schedule.
563 :command:`mirror snapshot schedule status` [-p | --pool *pool*] [--format *format*] [--pretty-format] [--namespace *namespace*] [--image *image*]
564 Show mirror snapshot schedule status.
566 :command:`mv` *src-image-spec* *dest-image-spec*
567 Rename an image. Note: rename across pools is not supported.
569 :command:`namespace create` *pool-name*/*namespace-name*
570 Create a new image namespace within the pool.
572 :command:`namespace list` *pool-name*
573 List image namespaces defined within the pool.
575 :command:`namespace remove` *pool-name*/*namespace-name*
576 Remove an empty image namespace from the pool.
578 :command:`object-map check` *image-spec* | *snap-spec*
579 Verify the object map is correct.
581 :command:`object-map rebuild` *image-spec* | *snap-spec*
582 Rebuild an invalid object map for the specified image. An image snapshot can be
583 specified to rebuild an invalid object map for a snapshot.
585 :command:`pool init` [*pool-name*] [--force]
586 Initialize pool for use by RBD. Newly created pools must initialized
589 :command:`resize` (-s | --size *size-in-M/G/T*) [--allow-shrink] *image-spec*
590 Resize rbd image. The size parameter also needs to be specified.
591 The --allow-shrink option lets the size be reduced.
593 :command:`rm` *image-spec*
594 Delete an rbd image (including all data blocks). If the image has
595 snapshots, this fails and nothing is deleted.
597 :command:`snap create` *snap-spec*
598 Create a new snapshot. Requires the snapshot name parameter specified.
600 :command:`snap limit clear` *image-spec*
601 Remove any previously set limit on the number of snapshots allowed on
604 :command:`snap limit set` [--limit] *limit* *image-spec*
605 Set a limit for the number of snapshots allowed on an image.
607 :command:`snap ls` *image-spec*
608 Dump the list of snapshots inside a specific image.
610 :command:`snap protect` *snap-spec*
611 Protect a snapshot from deletion, so that clones can be made of it
612 (see `rbd clone`). Snapshots must be protected before clones are made;
613 protection implies that there exist dependent cloned children that
614 refer to this snapshot. `rbd clone` will fail on a nonprotected
617 This requires image format 2.
619 :command:`snap purge` *image-spec*
620 Remove all unprotected snapshots from an image.
622 :command:`snap rename` *src-snap-spec* *dest-snap-spec*
623 Rename a snapshot. Note: rename across pools and images is not supported.
625 :command:`snap rm` [--force] *snap-spec*
626 Remove the specified snapshot.
628 :command:`snap rollback` *snap-spec*
629 Rollback image content to snapshot. This will iterate through the entire blocks
630 array and update the data head content to the snapshotted version.
632 :command:`snap unprotect` *snap-spec*
633 Unprotect a snapshot from deletion (undo `snap protect`). If cloned
634 children remain, `snap unprotect` fails. (Note that clones may exist
635 in different pools than the parent snapshot.)
637 This requires image format 2.
639 :command:`sparsify` [--sparse-size *sparse-size*] *image-spec*
640 Reclaim space for zeroed image extents. The default sparse size is
641 4096 bytes and can be changed via --sparse-size option with the
642 following restrictions: it should be power of two, not less than
643 4096, and not larger than image object size.
645 :command:`status` *image-spec*
646 Show the status of the image, including which clients have it open.
648 :command:`trash ls` [*pool-name*]
649 List all entries from trash.
651 :command:`trash mv` *image-spec*
652 Move an image to the trash. Images, even ones actively in-use by
653 clones, can be moved to the trash and deleted at a later time.
655 :command:`trash purge` [*pool-name*]
656 Remove all expired images from trash.
658 :command:`trash restore` *image-id*
659 Restore an image from trash.
661 :command:`trash rm` *image-id*
662 Delete an image from trash. If image deferment time has not expired
663 you can not removed it unless use force. But an actively in-use by clones
664 or has snapshots can not be removed.
666 :command:`trash purge schedule add` [-p | --pool *pool*] [--namespace *namespace*] *interval* [*start-time*]
667 Add trash purge schedule.
669 :command:`trash purge schedule list` [-R | --recursive] [--format *format*] [--pretty-format] [-p | --pool *pool*] [--namespace *namespace*]
670 List trash purge schedule.
672 :command:`trash purge schedule remove` [-p | --pool *pool*] [--namespace *namespace*] *interval* [*start-time*]
673 Remove trash purge schedule.
675 :command:`trash purge schedule status` [-p | --pool *pool*] [--format *format*] [--pretty-format] [--namespace *namespace*]
676 Show trash purge schedule status.
678 :command:`watch` *image-spec*
679 Watch events on image.
681 Image, snap, group and journal specs
682 ====================================
684 | *image-spec* is [*pool-name*/[*namespace-name*/]]\ *image-name*
685 | *snap-spec* is [*pool-name*/[*namespace-name*/]]\ *image-name*\ @\ *snap-name*
686 | *group-spec* is [*pool-name*/[*namespace-name*/]]\ *group-name*
687 | *group-snap-spec* is [*pool-name*/[*namespace-name*/]]\ *group-name*\ @\ *snap-name*
688 | *journal-spec* is [*pool-name*/[*namespace-name*/]]\ *journal-name*
690 The default for *pool-name* is "rbd" and *namespace-name* is "". If an image
691 name contains a slash character ('/'), *pool-name* is required.
693 The *journal-name* is *image-id*.
695 You may specify each name individually, using --pool, --namespace, --image, and
696 --snap options, but this is discouraged in favor of the above spec syntax.
701 RBD images are striped over many objects, which are then stored by the
702 Ceph distributed object store (RADOS). As a result, read and write
703 requests for the image are distributed across many nodes in the
704 cluster, generally preventing any single node from becoming a
705 bottleneck when individual images get large or busy.
707 The striping is controlled by three parameters:
709 .. option:: object-size
711 The size of objects we stripe over is a power of two. It will be rounded up the nearest power of two.
712 The default object size is 4 MB, smallest is 4K and maximum is 32M.
714 .. option:: stripe_unit
716 Each [*stripe_unit*] contiguous bytes are stored adjacently in the same object, before we move on
719 .. option:: stripe_count
721 After we write [*stripe_unit*] bytes to [*stripe_count*] objects, we loop back to the initial object
722 and write another stripe, until the object reaches its maximum size. At that point,
723 we move on to the next [*stripe_count*] objects.
725 By default, [*stripe_unit*] is the same as the object size and [*stripe_count*] is 1. Specifying a different
726 [*stripe_unit*] and/or [*stripe_count*] is often referred to as using "fancy" striping and requires format 2.
729 Kernel rbd (krbd) options
730 =========================
732 Most of these options are useful mainly for debugging and benchmarking. The
733 default values are set in the kernel and may therefore depend on the version of
736 Per client instance `rbd device map` options:
738 * fsid=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee - FSID that should be assumed by
741 * ip=a.b.c.d[:p] - IP and, optionally, port the client should use.
743 * share - Enable sharing of client instances with other mappings (default).
745 * noshare - Disable sharing of client instances with other mappings.
747 * crc - Enable CRC32C checksumming for msgr1 on-the-wire protocol (default).
748 For msgr2.1 protocol this option is ignored: full checksumming is always on
749 in 'crc' mode and always off in 'secure' mode.
751 * nocrc - Disable CRC32C checksumming for msgr1 on-the-wire protocol. Note
752 that only payload checksumming is disabled, header checksumming is always on.
753 For msgr2.1 protocol this option is ignored.
755 * cephx_require_signatures - Require msgr1 message signing feature (since 3.19,
756 default). This option is deprecated and will be removed in the future as the
757 feature has been supported since the Bobtail release.
759 * nocephx_require_signatures - Don't require msgr1 message signing feature
760 (since 3.19). This option is deprecated and will be removed in the future.
762 * tcp_nodelay - Disable Nagle's algorithm on client sockets (since 4.0,
765 * notcp_nodelay - Enable Nagle's algorithm on client sockets (since 4.0).
767 * cephx_sign_messages - Enable message signing for msgr1 on-the-wire protocol
768 (since 4.4, default). For msgr2.1 protocol this option is ignored: message
769 signing is built into 'secure' mode and not offered in 'crc' mode.
771 * nocephx_sign_messages - Disable message signing for msgr1 on-the-wire protocol
772 (since 4.4). For msgr2.1 protocol this option is ignored.
774 * mount_timeout=x - A timeout on various steps in `rbd device map` and
775 `rbd device unmap` sequences (default is 60 seconds). In particular,
776 since 4.2 this can be used to ensure that `rbd device unmap` eventually
777 times out when there is no network connection to a cluster.
779 * osdkeepalive=x - OSD keepalive timeout (default is 5 seconds).
781 * osd_idle_ttl=x - OSD idle TTL (default is 60 seconds).
783 Per mapping (block device) `rbd device map` options:
785 * rw - Map the image read-write (default). Overridden by --read-only.
787 * ro - Map the image read-only. Equivalent to --read-only.
789 * queue_depth=x - queue depth (since 4.2, default is 128 requests).
791 * lock_on_read - Acquire exclusive lock on reads, in addition to writes and
792 discards (since 4.9).
794 * exclusive - Disable automatic exclusive lock transitions (since 4.12).
795 Equivalent to --exclusive.
797 * lock_timeout=x - A timeout on waiting for the acquisition of exclusive lock
798 (since 4.17, default is 0 seconds, meaning no timeout).
800 * notrim - Turn off discard and write zeroes offload support to avoid
801 deprovisioning a fully provisioned image (since 4.17). When enabled, discard
802 requests will fail with -EOPNOTSUPP, write zeroes requests will fall back to
805 * abort_on_full - Fail write requests with -ENOSPC when the cluster is full or
806 the data pool reaches its quota (since 5.0). The default behaviour is to
807 block until the full condition is cleared.
809 * alloc_size - Minimum allocation unit of the underlying OSD object store
810 backend (since 5.1, default is 64K bytes). This is used to round off and
811 drop discards that are too small. For bluestore, the recommended setting is
812 bluestore_min_alloc_size (typically 64K for hard disk drives and 16K for
813 solid-state drives). For filestore with filestore_punch_hole = false, the
814 recommended setting is image object size (typically 4M).
816 * crush_location=x - Specify the location of the client in terms of CRUSH
817 hierarchy (since 5.8). This is a set of key-value pairs separated from
818 each other by '|', with keys separated from values by ':'. Note that '|'
819 may need to be quoted or escaped to avoid it being interpreted as a pipe
820 by the shell. The key is the bucket type name (e.g. rack, datacenter or
821 region with default bucket types) and the value is the bucket name. For
822 example, to indicate that the client is local to rack "myrack", data center
823 "mydc" and region "myregion"::
825 crush_location=rack:myrack|datacenter:mydc|region:myregion
827 Each key-value pair stands on its own: "myrack" doesn't need to reside in
828 "mydc", which in turn doesn't need to reside in "myregion". The location
829 is not a path to the root of the hierarchy but rather a set of nodes that
830 are matched independently, owning to the fact that bucket names are unique
831 within a CRUSH map. "Multipath" locations are supported, so it is possible
832 to indicate locality for multiple parallel hierarchies::
834 crush_location=rack:myrack1|rack:myrack2|datacenter:mydc
836 * read_from_replica=no - Disable replica reads, always pick the primary OSD
837 (since 5.8, default).
839 * read_from_replica=balance - When issued a read on a replicated pool, pick
840 a random OSD for serving it (since 5.8).
842 This mode is safe for general use only since Octopus (i.e. after "ceph osd
843 require-osd-release octopus"). Otherwise it should be limited to read-only
844 workloads such as images mapped read-only everywhere or snapshots.
846 * read_from_replica=localize - When issued a read on a replicated pool, pick
847 the most local OSD for serving it (since 5.8). The locality metric is
848 calculated against the location of the client given with crush_location;
849 a match with the lowest-valued bucket type wins. For example, with default
850 bucket types, an OSD in a matching rack is closer than an OSD in a matching
851 data center, which in turn is closer than an OSD in a matching region.
853 This mode is safe for general use only since Octopus (i.e. after "ceph osd
854 require-osd-release octopus"). Otherwise it should be limited to read-only
855 workloads such as images mapped read-only everywhere or snapshots.
857 * compression_hint=none - Don't set compression hints (since 5.8, default).
859 * compression_hint=compressible - Hint to the underlying OSD object store
860 backend that the data is compressible, enabling compression in passive mode
863 * compression_hint=incompressible - Hint to the underlying OSD object store
864 backend that the data is incompressible, disabling compression in aggressive
867 * ms_mode=legacy - Use msgr1 on-the-wire protocol (since 5.11, default).
869 * ms_mode=crc - Use msgr2.1 on-the-wire protocol, select 'crc' mode, also
870 referred to as plain mode (since 5.11). If the daemon denies 'crc' mode,
873 * ms_mode=secure - Use msgr2.1 on-the-wire protocol, select 'secure' mode
874 (since 5.11). 'secure' mode provides full in-transit encryption ensuring
875 both confidentiality and authenticity. If the daemon denies 'secure' mode,
878 * ms_mode=prefer-crc - Use msgr2.1 on-the-wire protocol, select 'crc'
879 mode (since 5.11). If the daemon denies 'crc' mode in favor of 'secure'
880 mode, agree to 'secure' mode.
882 * ms_mode=prefer-secure - Use msgr2.1 on-the-wire protocol, select 'secure'
883 mode (since 5.11). If the daemon denies 'secure' mode in favor of 'crc'
884 mode, agree to 'crc' mode.
886 * udev - Wait for udev device manager to finish executing all matching
887 "add" rules and release the device before exiting (default). This option
888 is not passed to the kernel.
890 * noudev - Don't wait for udev device manager. When enabled, the device may
891 not be fully usable immediately on exit.
893 `rbd device unmap` options:
895 * force - Force the unmapping of a block device that is open (since 4.9). The
896 driver will wait for running requests to complete and then unmap; requests
897 sent to the driver after initiating the unmap will be failed.
899 * udev - Wait for udev device manager to finish executing all matching
900 "remove" rules and clean up after the device before exiting (default).
901 This option is not passed to the kernel.
903 * noudev - Don't wait for udev device manager.
909 To create a new rbd image that is 100 GB::
911 rbd create mypool/myimage --size 102400
913 To use a non-default object size (8 MB)::
915 rbd create mypool/myimage --size 102400 --object-size 8M
917 To delete an rbd image (be careful!)::
919 rbd rm mypool/myimage
921 To create a new snapshot::
923 rbd snap create mypool/myimage@mysnap
925 To create a copy-on-write clone of a protected snapshot::
927 rbd clone mypool/myimage@mysnap otherpool/cloneimage
929 To see which clones of a snapshot exist::
931 rbd children mypool/myimage@mysnap
933 To delete a snapshot::
935 rbd snap rm mypool/myimage@mysnap
937 To map an image via the kernel with cephx enabled::
939 rbd device map mypool/myimage --id admin --keyfile secretfile
941 To map an image via the kernel with different cluster name other than default *ceph*::
943 rbd device map mypool/myimage --cluster cluster-name
947 rbd device unmap /dev/rbd0
949 To create an image and a clone from it::
951 rbd import --image-format 2 image mypool/parent
952 rbd snap create mypool/parent@snap
953 rbd snap protect mypool/parent@snap
954 rbd clone mypool/parent@snap otherpool/child
956 To create an image with a smaller stripe_unit (to better distribute small writes in some workloads)::
958 rbd create mypool/myimage --size 102400 --stripe-unit 65536B --stripe-count 16
960 To change an image from one image format to another, export it and then
961 import it as the desired image format::
963 rbd export mypool/myimage@snap /tmp/img
964 rbd import --image-format 2 /tmp/img mypool/myimage2
966 To lock an image for exclusive use::
968 rbd lock add mypool/myimage mylockid
972 rbd lock remove mypool/myimage mylockid client.2485
974 To list images from trash::
978 To defer delete an image (use *--expires-at* to set expiration time, default is now)::
980 rbd trash mv mypool/myimage --expires-at "tomorrow"
982 To delete an image from trash (be careful!)::
984 rbd trash rm mypool/myimage-id
986 To force delete an image from trash (be careful!)::
988 rbd trash rm mypool/myimage-id --force
990 To restore an image from trash::
992 rbd trash restore mypool/myimage-id
994 To restore an image from trash and rename it::
996 rbd trash restore mypool/myimage-id --image mynewimage
1002 **rbd** is part of Ceph, a massively scalable, open-source, distributed storage system. Please refer to
1003 the Ceph documentation at http://ceph.com/docs for more information.
1009 :doc:`ceph <ceph>`\(8),
1010 :doc:`rados <rados>`\(8)