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:`export` [--export-format *format (1 or 2)*] (*image-spec* | *snap-spec*) [*dest-path*]
288 Export image to dest path (use - for stdout).
289 The --export-format accepts '1' or '2' currently. Format 2 allow us to export not only the content
290 of image, but also the snapshots and other properties, such as image_order, features.
292 :command:`export-diff` [--from-snap *snap-name*] [--whole-object] (*image-spec* | *snap-spec*) *dest-path*
293 Export an incremental diff for an image to dest path (use - for stdout). If
294 an initial snapshot is specified, only changes since that snapshot are included; otherwise,
295 any regions of the image that contain data are included. The end snapshot is specified
296 using the standard --snap option or @snap syntax (see below). The image diff format includes
297 metadata about image size changes, and the start and end snapshots. It efficiently represents
298 discarded or 'zero' regions of the image.
300 :command:`feature disable` *image-spec* *feature-name*...
301 Disable the specified feature on the specified image. Multiple features can
304 :command:`feature enable` *image-spec* *feature-name*...
305 Enable the specified feature on the specified image. Multiple features can
308 :command:`flatten` *image-spec*
309 If image is a clone, copy all shared blocks from the parent snapshot and
310 make the child independent of the parent, severing the link between
311 parent snap and child. The parent snapshot can be unprotected and
312 deleted if it has no further dependent clones.
314 This requires image format 2.
316 :command:`group create` *group-spec*
319 :command:`group image add` *group-spec* *image-spec*
320 Add an image to a group.
322 :command:`group image list` *group-spec*
323 List images in a group.
325 :command:`group image remove` *group-spec* *image-spec*
326 Remove an image from a group.
328 :command:`group ls` [-p | --pool *pool-name*]
331 :command:`group rename` *src-group-spec* *dest-group-spec*
332 Rename a group. Note: rename across pools is not supported.
334 :command:`group rm` *group-spec*
337 :command:`group snap create` *group-snap-spec*
338 Make a snapshot of a group.
340 :command:`group snap list` *group-spec*
341 List snapshots of a group.
343 :command:`group snap rm` *group-snap-spec*
344 Remove a snapshot from a group.
346 :command:`group snap rename` *group-snap-spec* *snap-name*
347 Rename group's snapshot.
349 :command:`group snap rollback` *group-snap-spec*
350 Rollback group to snapshot.
352 :command:`image-meta get` *image-spec* *key*
353 Get metadata value with the key.
355 :command:`image-meta list` *image-spec*
356 Show metadata held on the image. The first column is the key
357 and the second column is the value.
359 :command:`image-meta remove` *image-spec* *key*
360 Remove metadata key with the value.
362 :command:`image-meta set` *image-spec* *key* *value*
363 Set metadata key with the value. They will displayed in `image-meta list`.
365 :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*]
366 Create a new image and imports its data from path (use - for
367 stdin). The import operation will try to create sparse rbd images
368 if possible. For import from stdin, the sparsification unit is
369 the data block size of the destination image (object size).
371 The --stripe-unit and --stripe-count arguments are optional, but must be
374 The --export-format accepts '1' or '2' currently. Format 2 allow us to import not only the content
375 of image, but also the snapshots and other properties, such as image_order, features.
377 :command:`import-diff` *src-path* *image-spec*
378 Import an incremental diff of an image and applies it to the current image. If the diff
379 was generated relative to a start snapshot, we verify that snapshot already exists before
380 continuing. If there was an end snapshot we verify it does not already exist before
381 applying the changes, and create the snapshot when we are done.
383 :command:`info` *image-spec* | *snap-spec*
384 Will dump information (such as size and object size) about a specific rbd image.
385 If image is a clone, information about its parent is also displayed.
386 If a snapshot is specified, whether it is protected is shown as well.
388 :command:`journal client disconnect` *journal-spec*
389 Flag image journal client as disconnected.
391 :command:`journal export` [--verbose] [--no-error] *src-journal-spec* *path-name*
392 Export image journal to path (use - for stdout). It can be make a backup
393 of the image journal especially before attempting dangerous operations.
395 Note that this command may not always work if the journal is badly corrupted.
397 :command:`journal import` [--verbose] [--no-error] *path-name* *dest-journal-spec*
398 Import image journal from path (use - for stdin).
400 :command:`journal info` *journal-spec*
401 Show information about image journal.
403 :command:`journal inspect` [--verbose] *journal-spec*
404 Inspect and report image journal for structural errors.
406 :command:`journal reset` *journal-spec*
409 :command:`journal status` *journal-spec*
410 Show status of image journal.
412 :command:`lock add` [--shared *lock-tag*] *image-spec* *lock-id*
413 Lock an image. The lock-id is an arbitrary name for the user's
414 convenience. By default, this is an exclusive lock, meaning it
415 will fail if the image is already locked. The --shared option
416 changes this behavior. Note that locking does not affect
417 any operation other than adding a lock. It does not
418 protect an image from being deleted.
420 :command:`lock ls` *image-spec*
421 Show locks held on the image. The first column is the locker
422 to use with the `lock remove` command.
424 :command:`lock rm` *image-spec* *lock-id* *locker*
425 Release a lock on an image. The lock id and locker are
426 as output by lock ls.
428 :command:`ls` [-l | --long] [*pool-name*]
429 Will list all rbd images listed in the rbd_directory object. With
430 -l, also show snapshots, and use longer-format output including
431 size, parent (if clone), format, etc.
433 :command:`merge-diff` *first-diff-path* *second-diff-path* *merged-diff-path*
434 Merge two continuous incremental diffs of an image into one single diff. The
435 first diff's end snapshot must be equal with the second diff's start snapshot.
436 The first diff could be - for stdin, and merged diff could be - for stdout, which
437 enables multiple diff files to be merged using something like
438 'rbd merge-diff first second - | rbd merge-diff - third result'. Note this command
439 currently only support the source incremental diff with stripe_count == 1
441 :command:`migration abort` *image-spec*
442 Cancel image migration. This step may be run after successful or
443 failed migration prepare or migration execute steps and returns the
444 image to its initial (before migration) state. All modifications to
445 the destination image are lost.
447 :command:`migration commit` *image-spec*
448 Commit image migration. This step is run after a successful migration
449 prepare and migration execute steps and removes the source image data.
451 :command:`migration execute` *image-spec*
452 Execute image migration. This step is run after a successful migration
453 prepare step and copies image data to the destination.
455 :command:`migration prepare` [--order *order*] [--object-size *object-size*] [--image-feature *image-feature*] [--image-shared] [--stripe-unit *stripe-unit*] [--stripe-count *stripe-count*] [--data-pool *data-pool*] *src-image-spec* [*dest-image-spec*]
456 Prepare image migration. This is the first step when migrating an
457 image, i.e. changing the image location, format or other
458 parameters that can't be changed dynamically. The destination can
459 match the source, and in this case *dest-image-spec* can be omitted.
460 After this step the source image is set as a parent of the
461 destination image, and the image is accessible in copy-on-write mode
462 by its destination spec.
464 :command:`mirror image demote` *image-spec*
465 Demote a primary image to non-primary for RBD mirroring.
467 :command:`mirror image disable` [--force] *image-spec*
468 Disable RBD mirroring for an image. If the mirroring is
469 configured in ``image`` mode for the image's pool, then it
470 can be explicitly disabled mirroring for each image within
473 :command:`mirror image enable` *image-spec* *mode*
474 Enable RBD mirroring for an image. If the mirroring is
475 configured in ``image`` mode for the image's pool, then it
476 can be explicitly enabled mirroring for each image within
479 The mirror image mode can either be ``journal`` (default) or
480 ``snapshot``. The ``journal`` mode requires the RBD journaling
483 :command:`mirror image promote` [--force] *image-spec*
484 Promote a non-primary image to primary for RBD mirroring.
486 :command:`mirror image resync` *image-spec*
487 Force resync to primary image for RBD mirroring.
489 :command:`mirror image status` *image-spec*
490 Show RBD mirroring status for an image.
492 :command:`mirror pool demote` [*pool-name*]
493 Demote all primary images within a pool to non-primary.
494 Every mirroring enabled image will demoted in the pool.
496 :command:`mirror pool disable` [*pool-name*]
497 Disable RBD mirroring by default within a pool. When mirroring
498 is disabled on a pool in this way, mirroring will also be
499 disabled on any images (within the pool) for which mirroring
500 was enabled explicitly.
502 :command:`mirror pool enable` [*pool-name*] *mode*
503 Enable RBD mirroring by default within a pool.
504 The mirroring mode can either be ``pool`` or ``image``.
505 If configured in ``pool`` mode, all images in the pool
506 with the journaling feature enabled are mirrored.
507 If configured in ``image`` mode, mirroring needs to be
508 explicitly enabled (by ``mirror image enable`` command)
511 :command:`mirror pool info` [*pool-name*]
512 Show information about the pool mirroring configuration.
513 It includes mirroring mode, peer UUID, remote cluster name,
514 and remote client name.
516 :command:`mirror pool peer add` [*pool-name*] *remote-cluster-spec*
517 Add a mirroring peer to a pool.
518 *remote-cluster-spec* is [*remote client name*\ @\ ]\ *remote cluster name*.
520 The default for *remote client name* is "client.admin".
522 This requires mirroring mode is enabled.
524 :command:`mirror pool peer remove` [*pool-name*] *uuid*
525 Remove a mirroring peer from a pool. The peer uuid is available
526 from ``mirror pool info`` command.
528 :command:`mirror pool peer set` [*pool-name*] *uuid* *key* *value*
529 Update mirroring peer settings.
530 The key can be either ``client`` or ``cluster``, and the value
531 is corresponding to remote client name or remote cluster name.
533 :command:`mirror pool promote` [--force] [*pool-name*]
534 Promote all non-primary images within a pool to primary.
535 Every mirroring enabled image will promoted in the pool.
537 :command:`mirror pool status` [--verbose] [*pool-name*]
538 Show status for all mirrored images in the pool.
539 With --verbose, also show additionally output status
540 details for every mirroring image in the pool.
542 :command:`mirror snapshot schedule add` [-p | --pool *pool*] [--namespace *namespace*] [--image *image*] *interval* [*start-time*]
543 Add mirror snapshot schedule.
545 :command:`mirror snapshot schedule list` [-R | --recursive] [--format *format*] [--pretty-format] [-p | --pool *pool*] [--namespace *namespace*] [--image *image*]
546 List mirror snapshot schedule.
548 :command:`mirror snapshot schedule remove` [-p | --pool *pool*] [--namespace *namespace*] [--image *image*] *interval* [*start-time*]
549 Remove mirror snapshot schedule.
551 :command:`mirror snapshot schedule status` [-p | --pool *pool*] [--format *format*] [--pretty-format] [--namespace *namespace*] [--image *image*]
552 Show mirror snapshot schedule status.
554 :command:`mv` *src-image-spec* *dest-image-spec*
555 Rename an image. Note: rename across pools is not supported.
557 :command:`namespace create` *pool-name*/*namespace-name*
558 Create a new image namespace within the pool.
560 :command:`namespace list` *pool-name*
561 List image namespaces defined within the pool.
563 :command:`namespace remove` *pool-name*/*namespace-name*
564 Remove an empty image namespace from the pool.
566 :command:`object-map check` *image-spec* | *snap-spec*
567 Verify the object map is correct.
569 :command:`object-map rebuild` *image-spec* | *snap-spec*
570 Rebuild an invalid object map for the specified image. An image snapshot can be
571 specified to rebuild an invalid object map for a snapshot.
573 :command:`pool init` [*pool-name*] [--force]
574 Initialize pool for use by RBD. Newly created pools must initialized
577 :command:`resize` (-s | --size *size-in-M/G/T*) [--allow-shrink] *image-spec*
578 Resize rbd image. The size parameter also needs to be specified.
579 The --allow-shrink option lets the size be reduced.
581 :command:`rm` *image-spec*
582 Delete an rbd image (including all data blocks). If the image has
583 snapshots, this fails and nothing is deleted.
585 :command:`snap create` *snap-spec*
586 Create a new snapshot. Requires the snapshot name parameter specified.
588 :command:`snap limit clear` *image-spec*
589 Remove any previously set limit on the number of snapshots allowed on
592 :command:`snap limit set` [--limit] *limit* *image-spec*
593 Set a limit for the number of snapshots allowed on an image.
595 :command:`snap ls` *image-spec*
596 Dump the list of snapshots inside a specific image.
598 :command:`snap protect` *snap-spec*
599 Protect a snapshot from deletion, so that clones can be made of it
600 (see `rbd clone`). Snapshots must be protected before clones are made;
601 protection implies that there exist dependent cloned children that
602 refer to this snapshot. `rbd clone` will fail on a nonprotected
605 This requires image format 2.
607 :command:`snap purge` *image-spec*
608 Remove all unprotected snapshots from an image.
610 :command:`snap rename` *src-snap-spec* *dest-snap-spec*
611 Rename a snapshot. Note: rename across pools and images is not supported.
613 :command:`snap rm` [--force] *snap-spec*
614 Remove the specified snapshot.
616 :command:`snap rollback` *snap-spec*
617 Rollback image content to snapshot. This will iterate through the entire blocks
618 array and update the data head content to the snapshotted version.
620 :command:`snap unprotect` *snap-spec*
621 Unprotect a snapshot from deletion (undo `snap protect`). If cloned
622 children remain, `snap unprotect` fails. (Note that clones may exist
623 in different pools than the parent snapshot.)
625 This requires image format 2.
627 :command:`sparsify` [--sparse-size *sparse-size*] *image-spec*
628 Reclaim space for zeroed image extents. The default sparse size is
629 4096 bytes and can be changed via --sparse-size option with the
630 following restrictions: it should be power of two, not less than
631 4096, and not larger than image object size.
633 :command:`status` *image-spec*
634 Show the status of the image, including which clients have it open.
636 :command:`trash ls` [*pool-name*]
637 List all entries from trash.
639 :command:`trash mv` *image-spec*
640 Move an image to the trash. Images, even ones actively in-use by
641 clones, can be moved to the trash and deleted at a later time.
643 :command:`trash purge` [*pool-name*]
644 Remove all expired images from trash.
646 :command:`trash restore` *image-id*
647 Restore an image from trash.
649 :command:`trash rm` *image-id*
650 Delete an image from trash. If image deferment time has not expired
651 you can not removed it unless use force. But an actively in-use by clones
652 or has snapshots can not be removed.
654 :command:`trash purge schedule add` [-p | --pool *pool*] [--namespace *namespace*] *interval* [*start-time*]
655 Add trash purge schedule.
657 :command:`trash purge schedule list` [-R | --recursive] [--format *format*] [--pretty-format] [-p | --pool *pool*] [--namespace *namespace*]
658 List trash purge schedule.
660 :command:`trash purge schedule remove` [-p | --pool *pool*] [--namespace *namespace*] *interval* [*start-time*]
661 Remove trash purge schedule.
663 :command:`trash purge schedule status` [-p | --pool *pool*] [--format *format*] [--pretty-format] [--namespace *namespace*]
664 Show trash purge schedule status.
666 :command:`watch` *image-spec*
667 Watch events on image.
669 Image, snap, group and journal specs
670 ====================================
672 | *image-spec* is [*pool-name*/[*namespace-name*/]]\ *image-name*
673 | *snap-spec* is [*pool-name*/[*namespace-name*/]]\ *image-name*\ @\ *snap-name*
674 | *group-spec* is [*pool-name*/[*namespace-name*/]]\ *group-name*
675 | *group-snap-spec* is [*pool-name*/[*namespace-name*/]]\ *group-name*\ @\ *snap-name*
676 | *journal-spec* is [*pool-name*/[*namespace-name*/]]\ *journal-name*
678 The default for *pool-name* is "rbd" and *namespace-name* is "". If an image
679 name contains a slash character ('/'), *pool-name* is required.
681 The *journal-name* is *image-id*.
683 You may specify each name individually, using --pool, --namespace, --image, and
684 --snap options, but this is discouraged in favor of the above spec syntax.
689 RBD images are striped over many objects, which are then stored by the
690 Ceph distributed object store (RADOS). As a result, read and write
691 requests for the image are distributed across many nodes in the
692 cluster, generally preventing any single node from becoming a
693 bottleneck when individual images get large or busy.
695 The striping is controlled by three parameters:
697 .. option:: object-size
699 The size of objects we stripe over is a power of two. It will be rounded up the nearest power of two.
700 The default object size is 4 MB, smallest is 4K and maximum is 32M.
702 .. option:: stripe_unit
704 Each [*stripe_unit*] contiguous bytes are stored adjacently in the same object, before we move on
707 .. option:: stripe_count
709 After we write [*stripe_unit*] bytes to [*stripe_count*] objects, we loop back to the initial object
710 and write another stripe, until the object reaches its maximum size. At that point,
711 we move on to the next [*stripe_count*] objects.
713 By default, [*stripe_unit*] is the same as the object size and [*stripe_count*] is 1. Specifying a different
714 [*stripe_unit*] and/or [*stripe_count*] is often referred to as using "fancy" striping and requires format 2.
717 Kernel rbd (krbd) options
718 =========================
720 Most of these options are useful mainly for debugging and benchmarking. The
721 default values are set in the kernel and may therefore depend on the version of
724 Per client instance `rbd device map` options:
726 * fsid=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee - FSID that should be assumed by
729 * ip=a.b.c.d[:p] - IP and, optionally, port the client should use.
731 * share - Enable sharing of client instances with other mappings (default).
733 * noshare - Disable sharing of client instances with other mappings.
735 * crc - Enable CRC32C checksumming for data writes (default).
737 * nocrc - Disable CRC32C checksumming for data writes.
739 * cephx_require_signatures - Require cephx message signing (since 3.19,
742 * nocephx_require_signatures - Don't require cephx message signing (since
745 * tcp_nodelay - Disable Nagle's algorithm on client sockets (since 4.0,
748 * notcp_nodelay - Enable Nagle's algorithm on client sockets (since 4.0).
750 * cephx_sign_messages - Enable message signing (since 4.4, default).
752 * nocephx_sign_messages - Disable message signing (since 4.4).
754 * mount_timeout=x - A timeout on various steps in `rbd device map` and
755 `rbd device unmap` sequences (default is 60 seconds). In particular,
756 since 4.2 this can be used to ensure that `rbd device unmap` eventually
757 times out when there is no network connection to a cluster.
759 * osdkeepalive=x - OSD keepalive timeout (default is 5 seconds).
761 * osd_idle_ttl=x - OSD idle TTL (default is 60 seconds).
763 Per mapping (block device) `rbd device map` options:
765 * rw - Map the image read-write (default).
767 * ro - Map the image read-only. Equivalent to --read-only.
769 * queue_depth=x - queue depth (since 4.2, default is 128 requests).
771 * lock_on_read - Acquire exclusive lock on reads, in addition to writes and
772 discards (since 4.9).
774 * exclusive - Disable automatic exclusive lock transitions (since 4.12).
776 * lock_timeout=x - A timeout on waiting for the acquisition of exclusive lock
777 (since 4.17, default is 0 seconds, meaning no timeout).
779 * notrim - Turn off discard and write zeroes offload support to avoid
780 deprovisioning a fully provisioned image (since 4.17). When enabled, discard
781 requests will fail with -EOPNOTSUPP, write zeroes requests will fall back to
784 * abort_on_full - Fail write requests with -ENOSPC when the cluster is full or
785 the data pool reaches its quota (since 5.0). The default behaviour is to
786 block until the full condition is cleared.
788 * alloc_size - Minimum allocation unit of the underlying OSD object store
789 backend (since 5.1, default is 64K bytes). This is used to round off and
790 drop discards that are too small. For bluestore, the recommended setting is
791 bluestore_min_alloc_size (typically 64K for hard disk drives and 16K for
792 solid-state drives). For filestore with filestore_punch_hole = false, the
793 recommended setting is image object size (typically 4M).
795 `rbd device unmap` options:
797 * force - Force the unmapping of a block device that is open (since 4.9). The
798 driver will wait for running requests to complete and then unmap; requests
799 sent to the driver after initiating the unmap will be failed.
805 To create a new rbd image that is 100 GB::
807 rbd create mypool/myimage --size 102400
809 To use a non-default object size (8 MB)::
811 rbd create mypool/myimage --size 102400 --object-size 8M
813 To delete an rbd image (be careful!)::
815 rbd rm mypool/myimage
817 To create a new snapshot::
819 rbd snap create mypool/myimage@mysnap
821 To create a copy-on-write clone of a protected snapshot::
823 rbd clone mypool/myimage@mysnap otherpool/cloneimage
825 To see which clones of a snapshot exist::
827 rbd children mypool/myimage@mysnap
829 To delete a snapshot::
831 rbd snap rm mypool/myimage@mysnap
833 To map an image via the kernel with cephx enabled::
835 rbd device map mypool/myimage --id admin --keyfile secretfile
837 To map an image via the kernel with different cluster name other than default *ceph*::
839 rbd device map mypool/myimage --cluster cluster-name
843 rbd device unmap /dev/rbd0
845 To create an image and a clone from it::
847 rbd import --image-format 2 image mypool/parent
848 rbd snap create mypool/parent@snap
849 rbd snap protect mypool/parent@snap
850 rbd clone mypool/parent@snap otherpool/child
852 To create an image with a smaller stripe_unit (to better distribute small writes in some workloads)::
854 rbd create mypool/myimage --size 102400 --stripe-unit 65536B --stripe-count 16
856 To change an image from one image format to another, export it and then
857 import it as the desired image format::
859 rbd export mypool/myimage@snap /tmp/img
860 rbd import --image-format 2 /tmp/img mypool/myimage2
862 To lock an image for exclusive use::
864 rbd lock add mypool/myimage mylockid
868 rbd lock remove mypool/myimage mylockid client.2485
870 To list images from trash::
874 To defer delete an image (use *--expires-at* to set expiration time, default is now)::
876 rbd trash mv mypool/myimage --expires-at "tomorrow"
878 To delete an image from trash (be careful!)::
880 rbd trash rm mypool/myimage-id
882 To force delete an image from trash (be careful!)::
884 rbd trash rm mypool/myimage-id --force
886 To restore an image from trash::
888 rbd trash restore mypool/myimage-id
890 To restore an image from trash and rename it::
892 rbd trash restore mypool/myimage-id --image mynewimage
898 **rbd** is part of Ceph, a massively scalable, open-source, distributed storage system. Please refer to
899 the Ceph documentation at http://ceph.com/docs for more information.
905 :doc:`ceph <ceph>`\(8),
906 :doc:`rados <rados>`\(8)