1RBD(8) Ceph RBD(8)
2
6 rbd - manage rados block device (RBD) images
7
9 rbd [ -c ceph.conf ] [ -m monaddr ] [--cluster cluster-name]
10 [ -p | --pool pool ] [ command ... ]
11
14 rbd is a utility for manipulating rados block device (RBD) images, used
15 by the Linux rbd driver and the rbd storage driver for QEMU/KVM. RBD
16 images are simple block devices that are striped over objects and
17 stored in a RADOS object store. The size of the objects the image is
18 striped over must be a power of two.
19
21 -c ceph.conf, --conf ceph.conf
22 Use ceph.conf configuration file instead of the default
23 /etc/ceph/ceph.conf to determine monitor addresses during
24 startup.
25 -m monaddress[:port]
27 Connect to specified monitor (instead of looking through
28 ceph.conf).
29 --cluster cluster-name
31 Use different cluster name as compared to default cluster name
32 ceph.
33 -p pool-name, --pool pool-name
35 Interact with the given pool. Required by most commands.
36 --namespace namespace-name
38 Use a pre-defined image namespace within a pool
39 --no-progress
41 Do not output progress information (goes to standard error by
42 default for some commands).
43
45 --image-format format-id
46 Specifies which object layout to use. The default is 2.
47 • format 1 - (deprecated) Use the original format for a new rbd
49 image. This format is understood by all versions of librbd and
50 the kernel rbd module, but does not support newer features
51 like cloning.
52 • format 2 - Use the second rbd format, which is supported by
54 librbd since the Bobtail release and the kernel rbd module
55 since kernel 3.10 (except for "fancy" striping, which is sup‐
56 ported since kernel 4.17). This adds support for cloning and
57 is more easily extensible to allow more features in the fu‐
58 ture.
59 -s size-in-M/G/T, --size size-in-M/G/T
61 Specifies the size of the new rbd image or the new size of the
62 existing rbd image in M/G/T. If no suffix is given, unit M is
63 assumed.
64 --object-size size-in-B/K/M
66 Specifies the object size in B/K/M. Object size will be rounded
67 up the nearest power of two; if no suffix is given, unit B is
68 assumed. The default object size is 4M, smallest is 4K and max‐
69 imum is 32M.
70 --stripe-unit size-in-B/K/M
72 Specifies the stripe unit size in B/K/M. If no suffix is given,
73 unit B is assumed. See striping section (below) for more de‐
74 tails.
75 --stripe-count num
77 Specifies the number of objects to stripe over before looping
78 back to the first object. See striping section (below) for more
79 details.
80 --snap snap
82 Specifies the snapshot name for the specific operation.
83 --id username
85 Specifies the username (without the client. prefix) to use with
86 the map command.
87 --keyring filename
89 Specifies a keyring file containing a secret for the specified
90 user to use with the map command. If not specified, the default
91 keyring locations will be searched.
92 --keyfile filename
94 Specifies a file containing the secret key of --id user to use
95 with the map command. This option is overridden by --keyring if
96 the latter is also specified.
97 --shared lock-tag
99 Option for lock add that allows multiple clients to lock the
100 same image if they use the same tag. The tag is an arbitrary
101 string. This is useful for situations where an image must be
102 open from more than one client at once, like during live migra‐
103 tion of a virtual machine, or for use underneath a clustered
104 file system.
105 --format format
107 Specifies output formatting (default: plain, json, xml)
108 --pretty-format
110 Make json or xml formatted output more human-readable.
111 -o krbd-options, --options krbd-options
113 Specifies which options to use when mapping or unmapping an im‐
114 age via the rbd kernel driver. krbd-options is a comma-sepa‐
115 rated list of options (similar to mount(8) mount options). See
116 kernel rbd (krbd) options section below for more details.
117 --read-only
119 Map the image read-only. Equivalent to -o ro.
120 --image-feature feature-name
122 Specifies which RBD format 2 feature should be enabled when cre‐
123 ating an image. Multiple features can be enabled by repeating
124 this option multiple times. The following features are sup‐
125 ported:
126 • layering: layering support
128 • striping: striping v2 support
130 • exclusive-lock: exclusive locking support
132 • object-map: object map support (requires exclusive-lock)
134 • fast-diff: fast diff calculations (requires object-map)
136 • deep-flatten: snapshot flatten support
138 • journaling: journaled IO support (requires exclusive-lock)
140 • data-pool: erasure coded pool support
142 --image-shared
144 Specifies that the image will be used concurrently by multiple
145 clients. This will disable features that are dependent upon ex‐
146 clusive ownership of the image.
147 --whole-object
149 Specifies that the diff should be limited to the extents of a
150 full object instead of showing intra-object deltas. When the ob‐
151 ject map feature is enabled on an image, limiting the diff to
152 the object extents will dramatically improve performance since
153 the differences can be computed by examining the in-memory ob‐
154 ject map instead of querying RADOS for each object within the
155 image.
156 --limit
158 Specifies the limit for the number of snapshots permitted.
159
161 bench --io-type <read | write | readwrite | rw> [--io-size
162 size-in-B/K/M/G/T] [--io-threads num-ios-in-flight] [--io-total
163 size-in-B/K/M/G/T] [--io-pattern seq | rand] [--rw-mix-read read pro‐
164 portion in readwrite] image-spec
165 Generate a series of IOs to the image and measure the IO
166 throughput and latency. If no suffix is given, unit B is as‐
167 sumed for both --io-size and --io-total. Defaults are:
168 --io-size 4096, --io-threads 16, --io-total 1G, --io-pattern
169 seq, --rw-mix-read 50.
170 children snap-spec
172 List the clones of the image at the given snapshot. This checks
173 every pool, and outputs the resulting poolname/imagename.
174 This requires image format 2.
176 clone [--object-size size-in-B/K/M] [--stripe-unit size-in-B/K/M
178 --stripe-count num] [--image-feature feature-name] [--image-shared]
179 parent-snap-spec child-image-spec
180 Will create a clone (copy-on-write child) of the parent snap‐
181 shot. Object size will be identical to that of the parent image
182 unless specified. Size will be the same as the parent snapshot.
183 The --stripe-unit and --stripe-count arguments are optional, but
184 must be used together.
185 The parent snapshot must be protected (see rbd snap protect).
187 This requires image format 2.
188 config global get config-entity key
190 Get a global-level configuration override.
191 config global list [--format plain | json | xml] [--pretty-format] con‐
193 fig-entity
194 List global-level configuration overrides.
195 config global set config-entity key value
197 Set a global-level configuration override.
198 config global remove config-entity key
200 Remove a global-level configuration override.
201 config image get image-spec key
203 Get an image-level configuration override.
204 config image list [--format plain | json | xml] [--pretty-format] im‐
206 age-spec
207 List image-level configuration overrides.
208 config image set image-spec key value
210 Set an image-level configuration override.
211 config image remove image-spec key
213 Remove an image-level configuration override.
214 config pool get pool-name key
216 Get a pool-level configuration override.
217 config pool list [--format plain | json | xml] [--pretty-format]
219 pool-name
220 List pool-level configuration overrides.
221 config pool set pool-name key value
223 Set a pool-level configuration override.
224 config pool remove pool-name key
226 Remove a pool-level configuration override.
227 cp (src-image-spec | src-snap-spec) dest-image-spec
229 Copy the content of a src-image into the newly created dest-im‐
230 age. dest-image will have the same size, object size, and image
231 format as src-image.
232 create (-s | --size size-in-M/G/T) [--image-format format-id] [--ob‐
234 ject-size size-in-B/K/M] [--stripe-unit size-in-B/K/M --stripe-count
235 num] [--thick-provision] [--no-progress] [--image-feature fea‐
236 ture-name]... [--image-shared] image-spec
237 Will create a new rbd image. You must also specify the size via
238 --size. The --stripe-unit and --stripe-count arguments are op‐
239 tional, but must be used together. If the --thick-provision is
240 enabled, it will fully allocate storage for the image at cre‐
241 ation time. It will take a long time to do. Note: thick provi‐
242 sioning requires zeroing the contents of the entire image.
243 deep cp (src-image-spec | src-snap-spec) dest-image-spec
245 Deep copy the content of a src-image into the newly created
246 dest-image. Dest-image will have the same size, object size,
247 image format, and snapshots as src-image.
248 device list [-t | --device-type device-type] [--format plain | json |
250 xml] --pretty-format
251 Show the rbd images that are mapped via the rbd kernel module
252 (default) or other supported device.
253 device map [-t | --device-type device-type] [--cookie device-cookie]
255 [--show-cookie] [--read-only] [--exclusive] [-o | --options device-op‐
256 tions] image-spec | snap-spec
257 Map the specified image to a block device via the rbd kernel
258 module (default) or other supported device (nbd on Linux or
259 ggate on FreeBSD).
260 The --options argument is a comma separated list of device type
262 specific options (opt1,opt2=val,...).
263 device unmap [-t | --device-type device-type] [-o | --options de‐
265 vice-options] image-spec | snap-spec | device-path
266 Unmap the block device that was mapped via the rbd kernel module
267 (default) or other supported device.
268 The --options argument is a comma separated list of device type
270 specific options (opt1,opt2=val,...).
271 device attach [-t | --device-type device-type] --device device-path
273 [--cookie device-cookie] [--show-cookie] [--read-only] [--exclusive]
274 [--force] [-o | --options device-options] image-spec | snap-spec
275 Attach the specified image to the specified block device (cur‐
276 rently only nbd on Linux). This operation is unsafe and should
277 not be normally used. In particular, specifying the wrong image
278 or the wrong block device may lead to data corruption as no val‐
279 idation is performed by nbd kernel driver.
280 The --options argument is a comma separated list of device type
282 specific options (opt1,opt2=val,...).
283 device detach [-t | --device-type device-type] [-o | --options de‐
285 vice-options] image-spec | snap-spec | device-path
286 Detach the block device that was mapped or attached (currently
287 only nbd on Linux). This operation is unsafe and should not be
288 normally used.
289 The --options argument is a comma separated list of device type
291 specific options (opt1,opt2=val,...).
292 diff [--from-snap snap-name] [--whole-object] image-spec | snap-spec
294 Dump a list of byte extents in the image that have changed since
295 the specified start snapshot, or since the image was created.
296 Each output line includes the starting offset (in bytes), the
297 length of the region (in bytes), and either 'zero' or 'data' to
298 indicate whether the region is known to be zeros or may contain
299 other data.
300 du [-p | --pool pool-name] [image-spec | snap-spec] [--merge-snapshots]
302 Will calculate the provisioned and actual disk usage of all im‐
303 ages and associated snapshots within the specified pool. It can
304 also be used against individual images and snapshots.
305 If the RBD fast-diff feature is not enabled on images, this op‐
307 eration will require querying the OSDs for every potential ob‐
308 ject within the image.
309 The --merge-snapshots will merge snapshots used space into their
311 parent images.
312 encryption format image-spec format passphrase-file [--cipher-alg alg]
314 Formats image to an encrypted format. All data previously writ‐
315 ten to the image will become unreadable. A cloned image cannot
316 be formatted, although encrypted images can be cloned. Sup‐
317 ported formats: luks1, luks2. Supported cipher algorithms:
318 aes-128, aes-256 (default).
319 export [--export-format format (1 or 2)] (image-spec | snap-spec)
321 [dest-path]
322 Export image to dest path (use - for stdout). The --export-for‐
323 mat accepts '1' or '2' currently. Format 2 allow us to export
324 not only the content of image, but also the snapshots and other
325 properties, such as image_order, features.
326 export-diff [--from-snap snap-name] [--whole-object] (image-spec |
328 snap-spec) dest-path
329 Export an incremental diff for an image to dest path (use - for
330 stdout). If an initial snapshot is specified, only changes
331 since that snapshot are included; otherwise, any regions of the
332 image that contain data are included. The end snapshot is spec‐
333 ified using the standard --snap option or @snap syntax (see be‐
334 low). The image diff format includes metadata about image size
335 changes, and the start and end snapshots. It efficiently repre‐
336 sents discarded or 'zero' regions of the image.
337 feature disable image-spec feature-name...
339 Disable the specified feature on the specified image. Multiple
340 features can be specified.
341 feature enable image-spec feature-name...
343 Enable the specified feature on the specified image. Multiple
344 features can be specified.
345 flatten image-spec
347 If image is a clone, copy all shared blocks from the parent
348 snapshot and make the child independent of the parent, severing
349 the link between parent snap and child. The parent snapshot can
350 be unprotected and deleted if it has no further dependent
351 clones.
352 This requires image format 2.
354 group create group-spec
356 Create a group.
357 group image add group-spec image-spec
359 Add an image to a group.
360 group image list group-spec
362 List images in a group.
363 group image remove group-spec image-spec
365 Remove an image from a group.
366 group ls [-p | --pool pool-name]
368 List rbd groups.
369 group rename src-group-spec dest-group-spec
371 Rename a group. Note: rename across pools is not supported.
372 group rm group-spec
374 Delete a group.
375 group snap create group-snap-spec
377 Make a snapshot of a group.
378 group snap list group-spec
380 List snapshots of a group.
381 group snap rm group-snap-spec
383 Remove a snapshot from a group.
384 group snap rename group-snap-spec snap-name
386 Rename group's snapshot.
387 group snap rollback group-snap-spec
389 Rollback group to snapshot.
390 image-meta get image-spec key
392 Get metadata value with the key.
393 image-meta list image-spec
395 Show metadata held on the image. The first column is the key and
396 the second column is the value.
397 image-meta remove image-spec key
399 Remove metadata key with the value.
400 image-meta set image-spec key value
402 Set metadata key with the value. They will displayed in im‐
403 age-meta list.
404 import [--export-format format (1 or 2)] [--image-format format-id]
406 [--object-size size-in-B/K/M] [--stripe-unit size-in-B/K/M
407 --stripe-count num] [--image-feature feature-name]... [--image-shared]
408 src-path [image-spec]
409 Create a new image and imports its data from path (use - for
410 stdin). The import operation will try to create sparse rbd im‐
411 ages if possible. For import from stdin, the sparsification
412 unit is the data block size of the destination image (object
413 size).
414 The --stripe-unit and --stripe-count arguments are optional, but
416 must be used together.
417 The --export-format accepts '1' or '2' currently. Format 2 allow
419 us to import not only the content of image, but also the snap‐
420 shots and other properties, such as image_order, features.
421 import-diff src-path image-spec
423 Import an incremental diff of an image and applies it to the
424 current image. If the diff was generated relative to a start
425 snapshot, we verify that snapshot already exists before continu‐
426 ing. If there was an end snapshot we verify it does not already
427 exist before applying the changes, and create the snapshot when
428 we are done.
429 info image-spec | snap-spec
431 Will dump information (such as size and object size) about a
432 specific rbd image. If image is a clone, information about its
433 parent is also displayed. If a snapshot is specified, whether
434 it is protected is shown as well.
435 journal client disconnect journal-spec
437 Flag image journal client as disconnected.
438 journal export [--verbose] [--no-error] src-journal-spec path-name
440 Export image journal to path (use - for stdout). It can be make
441 a backup of the image journal especially before attempting dan‐
442 gerous operations.
443 Note that this command may not always work if the journal is
445 badly corrupted.
446 journal import [--verbose] [--no-error] path-name dest-journal-spec
448 Import image journal from path (use - for stdin).
449 journal info journal-spec
451 Show information about image journal.
452 journal inspect [--verbose] journal-spec
454 Inspect and report image journal for structural errors.
455 journal reset journal-spec
457 Reset image journal.
458 journal status journal-spec
460 Show status of image journal.
461 lock add [--shared lock-tag] image-spec lock-id
463 Lock an image. The lock-id is an arbitrary name for the user's
464 convenience. By default, this is an exclusive lock, meaning it
465 will fail if the image is already locked. The --shared option
466 changes this behavior. Note that locking does not affect any op‐
467 eration other than adding a lock. It does not protect an image
468 from being deleted.
469 lock ls image-spec
471 Show locks held on the image. The first column is the locker to
472 use with the lock remove command.
473 lock rm image-spec lock-id locker
475 Release a lock on an image. The lock id and locker are as output
476 by lock ls.
477 ls [-l | --long] [pool-name]
479 Will list all rbd images listed in the rbd_directory object.
480 With -l, also show snapshots, and use longer-format output in‐
481 cluding size, parent (if clone), format, etc.
482 merge-diff first-diff-path second-diff-path merged-diff-path
484 Merge two continuous incremental diffs of an image into one sin‐
485 gle diff. The first diff's end snapshot must be equal with the
486 second diff's start snapshot. The first diff could be - for
487 stdin, and merged diff could be - for stdout, which enables mul‐
488 tiple diff files to be merged using something like 'rbd
489 merge-diff first second - | rbd merge-diff - third result'. Note
490 this command currently only support the source incremental diff
491 with stripe_count == 1
492 migration abort image-spec
494 Cancel image migration. This step may be run after successful or
495 failed migration prepare or migration execute steps and returns
496 the image to its initial (before migration) state. All modifica‐
497 tions to the destination image are lost.
498 migration commit image-spec
500 Commit image migration. This step is run after a successful mi‐
501 gration prepare and migration execute steps and removes the
502 source image data.
503 migration execute image-spec
505 Execute image migration. This step is run after a successful mi‐
506 gration prepare step and copies image data to the destination.
507 migration prepare [--order order] [--object-size object-size] [--im‐
509 age-feature image-feature] [--image-shared] [--stripe-unit stripe-unit]
510 [--stripe-count stripe-count] [--data-pool data-pool] [--import-only]
511 [--source-spec json] [--source-spec-path path] src-image-spec [dest-im‐
512 age-spec]
513 Prepare image migration. This is the first step when migrating
514 an image, i.e. changing the image location, format or other pa‐
515 rameters that can't be changed dynamically. The destination can
516 match the source, and in this case dest-image-spec can be omit‐
517 ted. After this step the source image is set as a parent of the
518 destination image, and the image is accessible in copy-on-write
519 mode by its destination spec.
520 An image can also be migrated from a read-only import source by
522 adding the --import-only optional and providing a JSON-encoded
523 --source-spec or a path to a JSON-encoded source-spec file using
524 the --source-spec-path optionals.
525 mirror image demote image-spec
527 Demote a primary image to non-primary for RBD mirroring.
528 mirror image disable [--force] image-spec
530 Disable RBD mirroring for an image. If the mirroring is config‐
531 ured in image mode for the image's pool, then it can be explic‐
532 itly disabled mirroring for each image within the pool.
533 mirror image enable image-spec mode
535 Enable RBD mirroring for an image. If the mirroring is config‐
536 ured in image mode for the image's pool, then it can be explic‐
537 itly enabled mirroring for each image within the pool.
538 The mirror image mode can either be journal (default) or snap‐
540 shot. The journal mode requires the RBD journaling feature.
541 mirror image promote [--force] image-spec
543 Promote a non-primary image to primary for RBD mirroring.
544 mirror image resync image-spec
546 Force resync to primary image for RBD mirroring.
547 mirror image status image-spec
549 Show RBD mirroring status for an image.
550 mirror pool demote [pool-name]
552 Demote all primary images within a pool to non-primary. Every
553 mirroring enabled image will demoted in the pool.
554 mirror pool disable [pool-name]
556 Disable RBD mirroring by default within a pool. When mirroring
557 is disabled on a pool in this way, mirroring will also be dis‐
558 abled on any images (within the pool) for which mirroring was
559 enabled explicitly.
560 mirror pool enable [pool-name] mode
562 Enable RBD mirroring by default within a pool. The mirroring
563 mode can either be pool or image. If configured in pool mode,
564 all images in the pool with the journaling feature enabled are
565 mirrored. If configured in image mode, mirroring needs to be
566 explicitly enabled (by mirror image enable command) on each im‐
567 age.
568 mirror pool info [pool-name]
570 Show information about the pool mirroring configuration. It in‐
571 cludes mirroring mode, peer UUID, remote cluster name, and re‐
572 mote client name.
573 mirror pool peer add [pool-name] remote-cluster-spec
575 Add a mirroring peer to a pool. remote-cluster-spec is [remote
576 client name@]remote cluster name.
577 The default for remote client name is "client.admin".
579 This requires mirroring mode is enabled.
581 mirror pool peer remove [pool-name] uuid
583 Remove a mirroring peer from a pool. The peer uuid is available
584 from mirror pool info command.
585 mirror pool peer set [pool-name] uuid key value
587 Update mirroring peer settings. The key can be either client or
588 cluster, and the value is corresponding to remote client name or
589 remote cluster name.
590 mirror pool promote [--force] [pool-name]
592 Promote all non-primary images within a pool to primary. Every
593 mirroring enabled image will promoted in the pool.
594 mirror pool status [--verbose] [pool-name]
596 Show status for all mirrored images in the pool. With --ver‐
597 bose, also show additionally output status details for every
598 mirroring image in the pool.
599 mirror snapshot schedule add [-p | --pool pool] [--namespace namespace]
601 [--image image] interval [start-time]
602 Add mirror snapshot schedule.
603 mirror snapshot schedule list [-R | --recursive] [--format format]
605 [--pretty-format] [-p | --pool pool] [--namespace namespace] [--image
606 image]
607 List mirror snapshot schedule.
608 mirror snapshot schedule remove [-p | --pool pool] [--namespace name‐
610 space] [--image image] interval [start-time]
611 Remove mirror snapshot schedule.
612 mirror snapshot schedule status [-p | --pool pool] [--format format]
614 [--pretty-format] [--namespace namespace] [--image image]
615 Show mirror snapshot schedule status.
616 mv src-image-spec dest-image-spec
618 Rename an image. Note: rename across pools is not supported.
619 namespace create pool-name/namespace-name
621 Create a new image namespace within the pool.
622 namespace list pool-name
624 List image namespaces defined within the pool.
625 namespace remove pool-name/namespace-name
627 Remove an empty image namespace from the pool.
628 object-map check image-spec | snap-spec
630 Verify the object map is correct.
631 object-map rebuild image-spec | snap-spec
633 Rebuild an invalid object map for the specified image. An image
634 snapshot can be specified to rebuild an invalid object map for a
635 snapshot.
636 pool init [pool-name] [--force]
638 Initialize pool for use by RBD. Newly created pools must ini‐
639 tialized prior to use.
640 resize (-s | --size size-in-M/G/T) [--allow-shrink] image-spec
642 Resize rbd image. The size parameter also needs to be specified.
643 The --allow-shrink option lets the size be reduced.
644 rm image-spec
646 Delete an rbd image (including all data blocks). If the image
647 has snapshots, this fails and nothing is deleted.
648 snap create snap-spec
650 Create a new snapshot. Requires the snapshot name parameter
651 specified.
652 snap limit clear image-spec
654 Remove any previously set limit on the number of snapshots al‐
655 lowed on an image.
656 snap limit set [--limit] limit image-spec
658 Set a limit for the number of snapshots allowed on an image.
659 snap ls image-spec
661 Dump the list of snapshots inside a specific image.
662 snap protect snap-spec
664 Protect a snapshot from deletion, so that clones can be made of
665 it (see rbd clone). Snapshots must be protected before clones
666 are made; protection implies that there exist dependent cloned
667 children that refer to this snapshot. rbd clone will fail on a
668 nonprotected snapshot.
669 This requires image format 2.
671 snap purge image-spec
673 Remove all unprotected snapshots from an image.
674 snap rename src-snap-spec dest-snap-spec
676 Rename a snapshot. Note: rename across pools and images is not
677 supported.
678 snap rm [--force] snap-spec
680 Remove the specified snapshot.
681 snap rollback snap-spec
683 Rollback image content to snapshot. This will iterate through
684 the entire blocks array and update the data head content to the
685 snapshotted version.
686 snap unprotect snap-spec
688 Unprotect a snapshot from deletion (undo snap protect). If
689 cloned children remain, snap unprotect fails. (Note that clones
690 may exist in different pools than the parent snapshot.)
691 This requires image format 2.
693 sparsify [--sparse-size sparse-size] image-spec
695 Reclaim space for zeroed image extents. The default sparse size
696 is 4096 bytes and can be changed via --sparse-size option with
697 the following restrictions: it should be power of two, not less
698 than 4096, and not larger than image object size.
699 status image-spec
701 Show the status of the image, including which clients have it
702 open.
703 trash ls [pool-name]
705 List all entries from trash.
706 trash mv image-spec
708 Move an image to the trash. Images, even ones actively in-use by
709 clones, can be moved to the trash and deleted at a later time.
710 trash purge [pool-name]
712 Remove all expired images from trash.
713 trash restore image-id
715 Restore an image from trash.
716 trash rm image-id
718 Delete an image from trash. If image deferment time has not ex‐
719 pired you can not removed it unless use force. But an actively
720 in-use by clones or has snapshots can not be removed.
721 trash purge schedule add [-p | --pool pool] [--namespace namespace] in‐
723 terval [start-time]
724 Add trash purge schedule.
725 trash purge schedule list [-R | --recursive] [--format format]
727 [--pretty-format] [-p | --pool pool] [--namespace namespace]
728 List trash purge schedule.
729 trash purge schedule remove [-p | --pool pool] [--namespace namespace]
731 interval [start-time]
732 Remove trash purge schedule.
733 trash purge schedule status [-p | --pool pool] [--format format]
735 [--pretty-format] [--namespace namespace]
736 Show trash purge schedule status.
737 watch image-spec
739 Watch events on image.
740
742 image-spec is [pool-name/[namespace-name/]]image-name
743 snap-spec is [pool-name/[namespace-name/]]image-name@snap-name
744 group-spec is [pool-name/[namespace-name/]]group-name
745 group-snap-spec is [pool-name/[namespace-name/]]group-name@snap-name
746 journal-spec is [pool-name/[namespace-name/]]journal-name
747 The default for pool-name is "rbd" and namespace-name is "". If an im‐
750 age name contains a slash character ('/'), pool-name is required.
751 The journal-name is image-id.
753 You may specify each name individually, using --pool, --namespace,
755 --image, and --snap options, but this is discouraged in favor of the
756 above spec syntax.
757
759 RBD images are striped over many objects, which are then stored by the
760 Ceph distributed object store (RADOS). As a result, read and write re‐
761 quests for the image are distributed across many nodes in the cluster,
762 generally preventing any single node from becoming a bottleneck when
763 individual images get large or busy.
764 The striping is controlled by three parameters:
766 object-size
768 The size of objects we stripe over is a power of two. It will be
769 rounded up the nearest power of two. The default object size is
770 4 MB, smallest is 4K and maximum is 32M.
771 stripe_unit
773 Each [stripe_unit] contiguous bytes are stored adjacently in the
774 same object, before we move on to the next object.
775 stripe_count
777 After we write [stripe_unit] bytes to [stripe_count] objects, we
778 loop back to the initial object and write another stripe, until
779 the object reaches its maximum size. At that point, we move on
780 to the next [stripe_count] objects.
781 By default, [stripe_unit] is the same as the object size and
783 [stripe_count] is 1. Specifying a different [stripe_unit] and/or
784 [stripe_count] is often referred to as using "fancy" striping and re‐
785 quires format 2.
786
788 Most of these options are useful mainly for debugging and benchmarking.
789 The default values are set in the kernel and may therefore depend on
790 the version of the running kernel.
791 Per client instance rbd device map options:
793 • fsid=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee - FSID that should be as‐
795 sumed by the client.
796 • ip=a.b.c.d[:p] - IP and, optionally, port the client should use.
798 • share - Enable sharing of client instances with other mappings (de‐
800 fault).
801 • noshare - Disable sharing of client instances with other mappings.
803 • crc - Enable CRC32C checksumming for msgr1 on-the-wire protocol (de‐
805 fault). For msgr2.1 protocol this option is ignored: full checksum‐
806 ming is always on in 'crc' mode and always off in 'secure' mode.
807 • nocrc - Disable CRC32C checksumming for msgr1 on-the-wire protocol.
809 Note that only payload checksumming is disabled, header checksumming
810 is always on. For msgr2.1 protocol this option is ignored.
811 • cephx_require_signatures - Require msgr1 message signing feature
813 (since 3.19, default). This option is deprecated and will be removed
814 in the future as the feature has been supported since the Bobtail re‐
815 lease.
816 • nocephx_require_signatures - Don't require msgr1 message signing fea‐
818 ture (since 3.19). This option is deprecated and will be removed in
819 the future.
820 • tcp_nodelay - Disable Nagle's algorithm on client sockets (since 4.0,
822 default).
823 • notcp_nodelay - Enable Nagle's algorithm on client sockets (since
825 4.0).
826 • cephx_sign_messages - Enable message signing for msgr1 on-the-wire
828 protocol (since 4.4, default). For msgr2.1 protocol this option is
829 ignored: message signing is built into 'secure' mode and not offered
830 in 'crc' mode.
831 • nocephx_sign_messages - Disable message signing for msgr1 on-the-wire
833 protocol (since 4.4). For msgr2.1 protocol this option is ignored.
834 • mount_timeout=x - A timeout on various steps in rbd device map and
836 rbd device unmap sequences (default is 60 seconds). In particular,
837 since 4.2 this can be used to ensure that rbd device unmap eventually
838 times out when there is no network connection to a cluster.
839 • osdkeepalive=x - OSD keepalive timeout (default is 5 seconds).
841 • osd_idle_ttl=x - OSD idle TTL (default is 60 seconds).
843 Per mapping (block device) rbd device map options:
845 • rw - Map the image read-write (default). Overridden by --read-only.
847 • ro - Map the image read-only. Equivalent to --read-only.
849 • queue_depth=x - queue depth (since 4.2, default is 128 requests).
851 • lock_on_read - Acquire exclusive lock on reads, in addition to writes
853 and discards (since 4.9).
854 • exclusive - Disable automatic exclusive lock transitions (since
856 4.12). Equivalent to --exclusive.
857 • lock_timeout=x - A timeout on waiting for the acquisition of exclu‐
859 sive lock (since 4.17, default is 0 seconds, meaning no timeout).
860 • notrim - Turn off discard and write zeroes offload support to avoid
862 deprovisioning a fully provisioned image (since 4.17). When enabled,
863 discard requests will fail with -EOPNOTSUPP, write zeroes requests
864 will fall back to manually zeroing.
865 • abort_on_full - Fail write requests with -ENOSPC when the cluster is
867 full or the data pool reaches its quota (since 5.0). The default be‐
868 haviour is to block until the full condition is cleared.
869 • alloc_size - Minimum allocation unit of the underlying OSD object
871 store backend (since 5.1, default is 64K bytes). This is used to
872 round off and drop discards that are too small. For bluestore, the
873 recommended setting is bluestore_min_alloc_size (typically 64K for
874 hard disk drives and 16K for solid-state drives). For filestore with
875 filestore_punch_hole = false, the recommended setting is image object
876 size (typically 4M).
877 • crush_location=x - Specify the location of the client in terms of
879 CRUSH hierarchy (since 5.8). This is a set of key-value pairs sepa‐
880 rated from each other by '|', with keys separated from values by ':'.
881 Note that '|' may need to be quoted or escaped to avoid it being in‐
882 terpreted as a pipe by the shell. The key is the bucket type name
883 (e.g. rack, datacenter or region with default bucket types) and the
884 value is the bucket name. For example, to indicate that the client
885 is local to rack "myrack", data center "mydc" and region "myregion":
886 crush_location=rack:myrack|datacenter:mydc|region:myregion
888 Each key-value pair stands on its own: "myrack" doesn't need to re‐
890 side in "mydc", which in turn doesn't need to reside in "myregion".
891 The location is not a path to the root of the hierarchy but rather a
892 set of nodes that are matched independently, owning to the fact that
893 bucket names are unique within a CRUSH map. "Multipath" locations
894 are supported, so it is possible to indicate locality for multiple
895 parallel hierarchies:
896 crush_location=rack:myrack1|rack:myrack2|datacenter:mydc
898 • read_from_replica=no - Disable replica reads, always pick the primary
900 OSD (since 5.8, default).
901 • read_from_replica=balance - When issued a read on a replicated pool,
903 pick a random OSD for serving it (since 5.8).
904 This mode is safe for general use only since Octopus (i.e. after
906 "ceph osd require-osd-release octopus"). Otherwise it should be lim‐
907 ited to read-only workloads such as images mapped read-only every‐
908 where or snapshots.
909 • read_from_replica=localize - When issued a read on a replicated pool,
911 pick the most local OSD for serving it (since 5.8). The locality
912 metric is calculated against the location of the client given with
913 crush_location; a match with the lowest-valued bucket type wins. For
914 example, with default bucket types, an OSD in a matching rack is
915 closer than an OSD in a matching data center, which in turn is closer
916 than an OSD in a matching region.
917 This mode is safe for general use only since Octopus (i.e. after
919 "ceph osd require-osd-release octopus"). Otherwise it should be lim‐
920 ited to read-only workloads such as images mapped read-only every‐
921 where or snapshots.
922 • compression_hint=none - Don't set compression hints (since 5.8, de‐
924 fault).
925 • compression_hint=compressible - Hint to the underlying OSD object
927 store backend that the data is compressible, enabling compression in
928 passive mode (since 5.8).
929 • compression_hint=incompressible - Hint to the underlying OSD object
931 store backend that the data is incompressible, disabling compression
932 in aggressive mode (since 5.8).
933 • ms_mode=legacy - Use msgr1 on-the-wire protocol (since 5.11, de‐
935 fault).
936 • ms_mode=crc - Use msgr2.1 on-the-wire protocol, select 'crc' mode,
938 also referred to as plain mode (since 5.11). If the daemon denies
939 'crc' mode, fail the connection.
940 • ms_mode=secure - Use msgr2.1 on-the-wire protocol, select 'secure'
942 mode (since 5.11). 'secure' mode provides full in-transit encryption
943 ensuring both confidentiality and authenticity. If the daemon denies
944 'secure' mode, fail the connection.
945 • ms_mode=prefer-crc - Use msgr2.1 on-the-wire protocol, select 'crc'
947 mode (since 5.11). If the daemon denies 'crc' mode in favor of 'se‐
948 cure' mode, agree to 'secure' mode.
949 • ms_mode=prefer-secure - Use msgr2.1 on-the-wire protocol, select 'se‐
951 cure' mode (since 5.11). If the daemon denies 'secure' mode in favor
952 of 'crc' mode, agree to 'crc' mode.
953 • rxbounce - Use a bounce buffer when receiving data (since 5.17). The
955 default behaviour is to read directly into the destination buffer. A
956 bounce buffer is needed if the destination buffer isn't guaranteed to
957 be stable (i.e. remain unchanged while it is being read to). In par‐
958 ticular this is the case for Windows where a system-wide "dummy"
959 (throwaway) page may be mapped into the destination buffer in order
960 to generate a single large I/O. Otherwise, "libceph: ... bad
961 crc/signature" or "libceph: ... integrity error, bad crc" errors and
962 associated performance degradation are expected.
963 • udev - Wait for udev device manager to finish executing all matching
965 "add" rules and release the device before exiting (default). This
966 option is not passed to the kernel.
967 • noudev - Don't wait for udev device manager. When enabled, the de‐
969 vice may not be fully usable immediately on exit.
970 rbd device unmap options:
972 • force - Force the unmapping of a block device that is open (since
974 4.9). The driver will wait for running requests to complete and then
975 unmap; requests sent to the driver after initiating the unmap will be
976 failed.
977 • udev - Wait for udev device manager to finish executing all matching
979 "remove" rules and clean up after the device before exiting (de‐
980 fault). This option is not passed to the kernel.
981 • noudev - Don't wait for udev device manager.
983
985 To create a new rbd image that is 100 GB:
986 rbd create mypool/myimage --size 102400
988 To use a non-default object size (8 MB):
990 rbd create mypool/myimage --size 102400 --object-size 8M
992 To delete an rbd image (be careful!):
994 rbd rm mypool/myimage
996 To create a new snapshot:
998 rbd snap create mypool/myimage@mysnap
1000 To create a copy-on-write clone of a protected snapshot:
1002 rbd clone mypool/myimage@mysnap otherpool/cloneimage
1004 To see which clones of a snapshot exist:
1006 rbd children mypool/myimage@mysnap
1008 To delete a snapshot:
1010 rbd snap rm mypool/myimage@mysnap
1012 To map an image via the kernel with cephx enabled:
1014 rbd device map mypool/myimage --id admin --keyfile secretfile
1016 To map an image via the kernel with different cluster name other than
1018 default ceph:
1019 rbd device map mypool/myimage --cluster cluster-name
1021 To unmap an image:
1023 rbd device unmap /dev/rbd0
1025 To create an image and a clone from it:
1027 rbd import --image-format 2 image mypool/parent
1029 rbd snap create mypool/parent@snap
1030 rbd snap protect mypool/parent@snap
1031 rbd clone mypool/parent@snap otherpool/child
1032 To create an image with a smaller stripe_unit (to better distribute
1034 small writes in some workloads):
1035 rbd create mypool/myimage --size 102400 --stripe-unit 65536B --stripe-count 16
1037 To change an image from one image format to another, export it and then
1039 import it as the desired image format:
1040 rbd export mypool/myimage@snap /tmp/img
1042 rbd import --image-format 2 /tmp/img mypool/myimage2
1043 To lock an image for exclusive use:
1045 rbd lock add mypool/myimage mylockid
1047 To release a lock:
1049 rbd lock remove mypool/myimage mylockid client.2485
1051 To list images from trash:
1053 rbd trash ls mypool
1055 To defer delete an image (use --expires-at to set expiration time, de‐
1057 fault is now):
1058 rbd trash mv mypool/myimage --expires-at "tomorrow"
1060 To delete an image from trash (be careful!):
1062 rbd trash rm mypool/myimage-id
1064 To force delete an image from trash (be careful!):
1066 rbd trash rm mypool/myimage-id --force
1068 To restore an image from trash:
1070 rbd trash restore mypool/myimage-id
1072 To restore an image from trash and rename it:
1074 rbd trash restore mypool/myimage-id --image mynewimage
1076
1078 rbd is part of Ceph, a massively scalable, open-source, distributed
1079 storage system. Please refer to the Ceph documentation at
1080 http://ceph.com/docs for more information.
1081
1083 ceph(8), rados(8)
1084
1086 2010-2022, Inktank Storage, Inc. and contributors. Licensed under Cre‐
1087 ative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)
1088dev Jun 22, 2022 RBD(8)