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 The default value can be changed with the configuration option
72 rbd_default_order, which takes a power of two (default object
73 size is 2 ^ rbd_default_order).
74 --stripe-unit size-in-B/K/M
76 Specifies the stripe unit size in B/K/M. If no suffix is given,
77 unit B is assumed. See striping section (below) for more de‐
78 tails.
79 --stripe-count num
81 Specifies the number of objects to stripe over before looping
82 back to the first object. See striping section (below) for more
83 details.
84 --snap snap
86 Specifies the snapshot name for the specific operation.
87 --id username
89 Specifies the username (without the client. prefix) to use with
90 the map command.
91 --keyring filename
93 Specifies a keyring file containing a secret for the specified
94 user to use with the map command. If not specified, the default
95 keyring locations will be searched.
96 --keyfile filename
98 Specifies a file containing the secret key of --id user to use
99 with the map command. This option is overridden by --keyring if
100 the latter is also specified.
101 --shared lock-tag
103 Option for lock add that allows multiple clients to lock the
104 same image if they use the same tag. The tag is an arbitrary
105 string. This is useful for situations where an image must be
106 open from more than one client at once, like during live migra‐
107 tion of a virtual machine, or for use underneath a clustered
108 file system.
109 --format format
111 Specifies output formatting (default: plain, json, xml)
112 --pretty-format
114 Make json or xml formatted output more human-readable.
115 -o krbd-options, --options krbd-options
117 Specifies which options to use when mapping or unmapping an im‐
118 age via the rbd kernel driver. krbd-options is a comma-sepa‐
119 rated list of options (similar to mount(8) mount options). See
120 kernel rbd (krbd) options section below for more details.
121 --read-only
123 Map the image read-only. Equivalent to -o ro.
124 --image-feature feature-name
126 Specifies which RBD format 2 feature should be enabled when cre‐
127 ating an image. Multiple features can be enabled by repeating
128 this option multiple times. The following features are sup‐
129 ported:
130 • layering: layering support
132 • striping: striping v2 support
134 • exclusive-lock: exclusive locking support
136 • object-map: object map support (requires exclusive-lock)
138 • fast-diff: fast diff calculations (requires object-map)
140 • deep-flatten: snapshot flatten support
142 • journaling: journaled IO support (requires exclusive-lock)
144 • data-pool: erasure coded pool support
146 --image-shared
148 Specifies that the image will be used concurrently by multiple
149 clients. This will disable features that are dependent upon ex‐
150 clusive ownership of the image.
151 --whole-object
153 Specifies that the diff should be limited to the extents of a
154 full object instead of showing intra-object deltas. When the ob‐
155 ject map feature is enabled on an image, limiting the diff to
156 the object extents will dramatically improve performance since
157 the differences can be computed by examining the in-memory ob‐
158 ject map instead of querying RADOS for each object within the
159 image.
160 --limit
162 Specifies the limit for the number of snapshots permitted.
163
165 bench --io-type <read | write | readwrite | rw> [--io-size
166 size-in-B/K/M/G/T] [--io-threads num-ios-in-flight] [--io-total
167 size-in-B/K/M/G/T] [--io-pattern seq | rand] [--rw-mix-read read pro‐
168 portion in readwrite] image-spec
169 Generate a series of IOs to the image and measure the IO
170 throughput and latency. If no suffix is given, unit B is as‐
171 sumed for both --io-size and --io-total. Defaults are:
172 --io-size 4096, --io-threads 16, --io-total 1G, --io-pattern
173 seq, --rw-mix-read 50.
174 children snap-spec
176 List the clones of the image at the given snapshot. This checks
177 every pool, and outputs the resulting poolname/imagename.
178 This requires image format 2.
180 clone [--object-size size-in-B/K/M] [--stripe-unit size-in-B/K/M
182 --stripe-count num] [--image-feature feature-name] [--image-shared]
183 parent-snap-spec child-image-spec
184 Will create a clone (copy-on-write child) of the parent snap‐
185 shot. Object size will be identical to that of the parent image
186 unless specified. Size will be the same as the parent snapshot.
187 The --stripe-unit and --stripe-count arguments are optional, but
188 must be used together.
189 The parent snapshot must be protected (see rbd snap protect).
191 This requires image format 2.
192 config global get config-entity key
194 Get a global-level configuration override.
195 config global list [--format plain | json | xml] [--pretty-format] con‐
197 fig-entity
198 List global-level configuration overrides.
199 config global set config-entity key value
201 Set a global-level configuration override.
202 config global remove config-entity key
204 Remove a global-level configuration override.
205 config image get image-spec key
207 Get an image-level configuration override.
208 config image list [--format plain | json | xml] [--pretty-format] im‐
210 age-spec
211 List image-level configuration overrides.
212 config image set image-spec key value
214 Set an image-level configuration override.
215 config image remove image-spec key
217 Remove an image-level configuration override.
218 config pool get pool-name key
220 Get a pool-level configuration override.
221 config pool list [--format plain | json | xml] [--pretty-format]
223 pool-name
224 List pool-level configuration overrides.
225 config pool set pool-name key value
227 Set a pool-level configuration override.
228 config pool remove pool-name key
230 Remove a pool-level configuration override.
231 cp (src-image-spec | src-snap-spec) dest-image-spec
233 Copy the content of a src-image into the newly created dest-im‐
234 age. dest-image will have the same size, object size, and image
235 format as src-image. Note: snapshots are not copied, use deep
236 cp command to include snapshots.
237 create (-s | --size size-in-M/G/T) [--image-format format-id] [--ob‐
239 ject-size size-in-B/K/M] [--stripe-unit size-in-B/K/M --stripe-count
240 num] [--thick-provision] [--no-progress] [--image-feature fea‐
241 ture-name]... [--image-shared] image-spec
242 Will create a new rbd image. You must also specify the size via
243 --size. The --stripe-unit and --stripe-count arguments are op‐
244 tional, but must be used together. If the --thick-provision is
245 enabled, it will fully allocate storage for the image at cre‐
246 ation time. It will take a long time to do. Note: thick provi‐
247 sioning requires zeroing the contents of the entire image.
248 deep cp (src-image-spec | src-snap-spec) dest-image-spec
250 Deep copy the content of a src-image into the newly created
251 dest-image. Dest-image will have the same size, object size,
252 image format, and snapshots as src-image.
253 device list [-t | --device-type device-type] [--format plain | json |
255 xml] --pretty-format
256 Show the rbd images that are mapped via the rbd kernel module
257 (default) or other supported device.
258 device map [-t | --device-type device-type] [--cookie device-cookie]
260 [--show-cookie] [--snap-id snap-id] [--read-only] [--exclusive] [-o |
261 --options device-options] image-spec | snap-spec
262 Map the specified image to a block device via the rbd kernel
263 module (default) or other supported device (nbd on Linux or
264 ggate on FreeBSD).
265 The --options argument is a comma separated list of device type
267 specific options (opt1,opt2=val,...).
268 device unmap [-t | --device-type device-type] [-o | --options de‐
270 vice-options] [--snap-id snap-id] image-spec | snap-spec | device-path
271 Unmap the block device that was mapped via the rbd kernel module
272 (default) or other supported device.
273 The --options argument is a comma separated list of device type
275 specific options (opt1,opt2=val,...).
276 device attach [-t | --device-type device-type] --device device-path
278 [--cookie device-cookie] [--show-cookie] [--snap-id snap-id]
279 [--read-only] [--exclusive] [--force] [-o | --options device-options]
280 image-spec | snap-spec
281 Attach the specified image to the specified block device (cur‐
282 rently only nbd on Linux). This operation is unsafe and should
283 not be normally used. In particular, specifying the wrong image
284 or the wrong block device may lead to data corruption as no val‐
285 idation is performed by nbd kernel driver.
286 The --options argument is a comma separated list of device type
288 specific options (opt1,opt2=val,...).
289 device detach [-t | --device-type device-type] [-o | --options de‐
291 vice-options] [--snap-id snap-id] image-spec | snap-spec | device-path
292 Detach the block device that was mapped or attached (currently
293 only nbd on Linux). This operation is unsafe and should not be
294 normally used.
295 The --options argument is a comma separated list of device type
297 specific options (opt1,opt2=val,...).
298 diff [--from-snap snap-name] [--whole-object] image-spec | snap-spec
300 Dump a list of byte extents in the image that have changed since
301 the specified start snapshot, or since the image was created.
302 Each output line includes the starting offset (in bytes), the
303 length of the region (in bytes), and either 'zero' or 'data' to
304 indicate whether the region is known to be zeros or may contain
305 other data.
306 du [-p | --pool pool-name] [image-spec | snap-spec] [--merge-snapshots]
308 Will calculate the provisioned and actual disk usage of all im‐
309 ages and associated snapshots within the specified pool. It can
310 also be used against individual images and snapshots.
311 If the RBD fast-diff feature is not enabled on images, this op‐
313 eration will require querying the OSDs for every potential ob‐
314 ject within the image.
315 The --merge-snapshots will merge snapshots used space into their
317 parent images.
318 encryption format image-spec format passphrase-file [--cipher-alg alg]
320 Formats image to an encrypted format. All data previously writ‐
321 ten to the image will become unreadable. A cloned image cannot
322 be formatted, although encrypted images can be cloned. Sup‐
323 ported formats: luks1, luks2. Supported cipher algorithms:
324 aes-128, aes-256 (default).
325 export [--export-format format (1 or 2)] (image-spec | snap-spec)
327 [dest-path]
328 Export image to dest path (use - for stdout). The --export-for‐
329 mat accepts '1' or '2' currently. Format 2 allow us to export
330 not only the content of image, but also the snapshots and other
331 properties, such as image_order, features.
332 export-diff [--from-snap snap-name] [--whole-object] (image-spec |
334 snap-spec) dest-path
335 Export an incremental diff for an image to dest path (use - for
336 stdout). If an initial snapshot is specified, only changes
337 since that snapshot are included; otherwise, any regions of the
338 image that contain data are included. The end snapshot is spec‐
339 ified using the standard --snap option or @snap syntax (see be‐
340 low). The image diff format includes metadata about image size
341 changes, and the start and end snapshots. It efficiently repre‐
342 sents discarded or 'zero' regions of the image.
343 feature disable image-spec feature-name...
345 Disable the specified feature on the specified image. Multiple
346 features can be specified.
347 feature enable image-spec feature-name...
349 Enable the specified feature on the specified image. Multiple
350 features can be specified.
351 flatten image-spec
353 If image is a clone, copy all shared blocks from the parent
354 snapshot and make the child independent of the parent, severing
355 the link between parent snap and child. The parent snapshot can
356 be unprotected and deleted if it has no further dependent
357 clones.
358 This requires image format 2.
360 group create group-spec
362 Create a group.
363 group image add group-spec image-spec
365 Add an image to a group.
366 group image list group-spec
368 List images in a group.
369 group image remove group-spec image-spec
371 Remove an image from a group.
372 group ls [-p | --pool pool-name]
374 List rbd groups.
375 group rename src-group-spec dest-group-spec
377 Rename a group. Note: rename across pools is not supported.
378 group rm group-spec
380 Delete a group.
381 group snap create group-snap-spec
383 Make a snapshot of a group.
384 group snap list group-spec
386 List snapshots of a group.
387 group snap rm group-snap-spec
389 Remove a snapshot from a group.
390 group snap rename group-snap-spec snap-name
392 Rename group's snapshot.
393 group snap rollback group-snap-spec
395 Rollback group to snapshot.
396 image-meta get image-spec key
398 Get metadata value with the key.
399 image-meta list image-spec
401 Show metadata held on the image. The first column is the key and
402 the second column is the value.
403 image-meta remove image-spec key
405 Remove metadata key with the value.
406 image-meta set image-spec key value
408 Set metadata key with the value. They will displayed in im‐
409 age-meta list.
410 import [--export-format format (1 or 2)] [--image-format format-id]
412 [--object-size size-in-B/K/M] [--stripe-unit size-in-B/K/M
413 --stripe-count num] [--image-feature feature-name]... [--image-shared]
414 src-path [image-spec]
415 Create a new image and imports its data from path (use - for
416 stdin). The import operation will try to create sparse rbd im‐
417 ages if possible. For import from stdin, the sparsification
418 unit is the data block size of the destination image (object
419 size).
420 The --stripe-unit and --stripe-count arguments are optional, but
422 must be used together.
423 The --export-format accepts '1' or '2' currently. Format 2 allow
425 us to import not only the content of image, but also the snap‐
426 shots and other properties, such as image_order, features.
427 import-diff src-path image-spec
429 Import an incremental diff of an image and applies it to the
430 current image. If the diff was generated relative to a start
431 snapshot, we verify that snapshot already exists before continu‐
432 ing. If there was an end snapshot we verify it does not already
433 exist before applying the changes, and create the snapshot when
434 we are done.
435 info image-spec | snap-spec
437 Will dump information (such as size and object size) about a
438 specific rbd image. If image is a clone, information about its
439 parent is also displayed. If a snapshot is specified, whether
440 it is protected is shown as well.
441 journal client disconnect journal-spec
443 Flag image journal client as disconnected.
444 journal export [--verbose] [--no-error] src-journal-spec path-name
446 Export image journal to path (use - for stdout). It can be make
447 a backup of the image journal especially before attempting dan‐
448 gerous operations.
449 Note that this command may not always work if the journal is
451 badly corrupted.
452 journal import [--verbose] [--no-error] path-name dest-journal-spec
454 Import image journal from path (use - for stdin).
455 journal info journal-spec
457 Show information about image journal.
458 journal inspect [--verbose] journal-spec
460 Inspect and report image journal for structural errors.
461 journal reset journal-spec
463 Reset image journal.
464 journal status journal-spec
466 Show status of image journal.
467 lock add [--shared lock-tag] image-spec lock-id
469 Lock an image. The lock-id is an arbitrary name for the user's
470 convenience. By default, this is an exclusive lock, meaning it
471 will fail if the image is already locked. The --shared option
472 changes this behavior. Note that locking does not affect any op‐
473 eration other than adding a lock. It does not protect an image
474 from being deleted.
475 lock ls image-spec
477 Show locks held on the image. The first column is the locker to
478 use with the lock remove command.
479 lock rm image-spec lock-id locker
481 Release a lock on an image. The lock id and locker are as output
482 by lock ls.
483 ls [-l | --long] [pool-name]
485 Will list all rbd images listed in the rbd_directory object.
486 With -l, also show snapshots, and use longer-format output in‐
487 cluding size, parent (if clone), format, etc.
488 merge-diff first-diff-path second-diff-path merged-diff-path
490 Merge two continuous incremental diffs of an image into one sin‐
491 gle diff. The first diff's end snapshot must be equal with the
492 second diff's start snapshot. The first diff could be - for
493 stdin, and merged diff could be - for stdout, which enables mul‐
494 tiple diff files to be merged using something like 'rbd
495 merge-diff first second - | rbd merge-diff - third result'. Note
496 this command currently only support the source incremental diff
497 with stripe_count == 1
498 migration abort image-spec
500 Cancel image migration. This step may be run after successful or
501 failed migration prepare or migration execute steps and returns
502 the image to its initial (before migration) state. All modifica‐
503 tions to the destination image are lost.
504 migration commit image-spec
506 Commit image migration. This step is run after a successful mi‐
507 gration prepare and migration execute steps and removes the
508 source image data.
509 migration execute image-spec
511 Execute image migration. This step is run after a successful mi‐
512 gration prepare step and copies image data to the destination.
513 migration prepare [--order order] [--object-size object-size] [--im‐
515 age-feature image-feature] [--image-shared] [--stripe-unit stripe-unit]
516 [--stripe-count stripe-count] [--data-pool data-pool] [--import-only]
517 [--source-spec json] [--source-spec-path path] src-image-spec [dest-im‐
518 age-spec]
519 Prepare image migration. This is the first step when migrating
520 an image, i.e. changing the image location, format or other pa‐
521 rameters that can't be changed dynamically. The destination can
522 match the source, and in this case dest-image-spec can be omit‐
523 ted. After this step the source image is set as a parent of the
524 destination image, and the image is accessible in copy-on-write
525 mode by its destination spec.
526 An image can also be migrated from a read-only import source by
528 adding the --import-only optional and providing a JSON-encoded
529 --source-spec or a path to a JSON-encoded source-spec file using
530 the --source-spec-path optionals.
531 mirror image demote image-spec
533 Demote a primary image to non-primary for RBD mirroring.
534 mirror image disable [--force] image-spec
536 Disable RBD mirroring for an image. If the mirroring is config‐
537 ured in image mode for the image's pool, then it can be explic‐
538 itly disabled mirroring for each image within the pool.
539 mirror image enable image-spec mode
541 Enable RBD mirroring for an image. If the mirroring is config‐
542 ured in image mode for the image's pool, then it can be explic‐
543 itly enabled mirroring for each image within the pool.
544 The mirror image mode can either be journal (default) or snap‐
546 shot. The journal mode requires the RBD journaling feature.
547 mirror image promote [--force] image-spec
549 Promote a non-primary image to primary for RBD mirroring.
550 mirror image resync image-spec
552 Force resync to primary image for RBD mirroring.
553 mirror image status image-spec
555 Show RBD mirroring status for an image.
556 mirror pool demote [pool-name]
558 Demote all primary images within a pool to non-primary. Every
559 mirroring enabled image will demoted in the pool.
560 mirror pool disable [pool-name]
562 Disable RBD mirroring by default within a pool. When mirroring
563 is disabled on a pool in this way, mirroring will also be dis‐
564 abled on any images (within the pool) for which mirroring was
565 enabled explicitly.
566 mirror pool enable [pool-name] mode
568 Enable RBD mirroring by default within a pool. The mirroring
569 mode can either be pool or image. If configured in pool mode,
570 all images in the pool with the journaling feature enabled are
571 mirrored. If configured in image mode, mirroring needs to be
572 explicitly enabled (by mirror image enable command) on each im‐
573 age.
574 mirror pool info [pool-name]
576 Show information about the pool mirroring configuration. It in‐
577 cludes mirroring mode, peer UUID, remote cluster name, and re‐
578 mote client name.
579 mirror pool peer add [pool-name] remote-cluster-spec
581 Add a mirroring peer to a pool. remote-cluster-spec is [remote
582 client name@]remote cluster name.
583 The default for remote client name is "client.admin".
585 This requires mirroring mode is enabled.
587 mirror pool peer remove [pool-name] uuid
589 Remove a mirroring peer from a pool. The peer uuid is available
590 from mirror pool info command.
591 mirror pool peer set [pool-name] uuid key value
593 Update mirroring peer settings. The key can be either client or
594 cluster, and the value is corresponding to remote client name or
595 remote cluster name.
596 mirror pool promote [--force] [pool-name]
598 Promote all non-primary images within a pool to primary. Every
599 mirroring enabled image will promoted in the pool.
600 mirror pool status [--verbose] [pool-name]
602 Show status for all mirrored images in the pool. With --ver‐
603 bose, also show additionally output status details for every
604 mirroring image in the pool.
605 mirror snapshot schedule add [-p | --pool pool] [--namespace namespace]
607 [--image image] interval [start-time]
608 Add mirror snapshot schedule.
609 mirror snapshot schedule list [-R | --recursive] [--format format]
611 [--pretty-format] [-p | --pool pool] [--namespace namespace] [--image
612 image]
613 List mirror snapshot schedule.
614 mirror snapshot schedule remove [-p | --pool pool] [--namespace name‐
616 space] [--image image] interval [start-time]
617 Remove mirror snapshot schedule.
618 mirror snapshot schedule status [-p | --pool pool] [--format format]
620 [--pretty-format] [--namespace namespace] [--image image]
621 Show mirror snapshot schedule status.
622 mv src-image-spec dest-image-spec
624 Rename an image. Note: rename across pools is not supported.
625 namespace create pool-name/namespace-name
627 Create a new image namespace within the pool.
628 namespace list pool-name
630 List image namespaces defined within the pool.
631 namespace remove pool-name/namespace-name
633 Remove an empty image namespace from the pool.
634 object-map check image-spec | snap-spec
636 Verify the object map is correct.
637 object-map rebuild image-spec | snap-spec
639 Rebuild an invalid object map for the specified image. An image
640 snapshot can be specified to rebuild an invalid object map for a
641 snapshot.
642 pool init [pool-name] [--force]
644 Initialize pool for use by RBD. Newly created pools must ini‐
645 tialized prior to use.
646 resize (-s | --size size-in-M/G/T) [--allow-shrink] image-spec
648 Resize rbd image. The size parameter also needs to be specified.
649 The --allow-shrink option lets the size be reduced.
650 rm image-spec
652 Delete an rbd image (including all data blocks). If the image
653 has snapshots, this fails and nothing is deleted.
654 snap create snap-spec
656 Create a new snapshot. Requires the snapshot name parameter
657 specified.
658 snap limit clear image-spec
660 Remove any previously set limit on the number of snapshots al‐
661 lowed on an image.
662 snap limit set [--limit] limit image-spec
664 Set a limit for the number of snapshots allowed on an image.
665 snap ls image-spec
667 Dump the list of snapshots inside a specific image.
668 snap protect snap-spec
670 Protect a snapshot from deletion, so that clones can be made of
671 it (see rbd clone). Snapshots must be protected before clones
672 are made; protection implies that there exist dependent cloned
673 children that refer to this snapshot. rbd clone will fail on a
674 nonprotected snapshot.
675 This requires image format 2.
677 snap purge image-spec
679 Remove all unprotected snapshots from an image.
680 snap rename src-snap-spec dest-snap-spec
682 Rename a snapshot. Note: rename across pools and images is not
683 supported.
684 snap rm [--force] snap-spec
686 Remove the specified snapshot.
687 snap rollback snap-spec
689 Rollback image content to snapshot. This will iterate through
690 the entire blocks array and update the data head content to the
691 snapshotted version.
692 snap unprotect snap-spec
694 Unprotect a snapshot from deletion (undo snap protect). If
695 cloned children remain, snap unprotect fails. (Note that clones
696 may exist in different pools than the parent snapshot.)
697 This requires image format 2.
699 sparsify [--sparse-size sparse-size] image-spec
701 Reclaim space for zeroed image extents. The default sparse size
702 is 4096 bytes and can be changed via --sparse-size option with
703 the following restrictions: it should be power of two, not less
704 than 4096, and not larger than image object size.
705 status image-spec
707 Show the status of the image, including which clients have it
708 open.
709 trash ls [pool-name]
711 List all entries from trash.
712 trash mv image-spec
714 Move an image to the trash. Images, even ones actively in-use by
715 clones, can be moved to the trash and deleted at a later time.
716 trash purge [pool-name]
718 Remove all expired images from trash.
719 trash restore image-id
721 Restore an image from trash.
722 trash rm image-id
724 Delete an image from trash. If image deferment time has not ex‐
725 pired you can not removed it unless use force. But an actively
726 in-use by clones or has snapshots can not be removed.
727 trash purge schedule add [-p | --pool pool] [--namespace namespace] in‐
729 terval [start-time]
730 Add trash purge schedule.
731 trash purge schedule list [-R | --recursive] [--format format]
733 [--pretty-format] [-p | --pool pool] [--namespace namespace]
734 List trash purge schedule.
735 trash purge schedule remove [-p | --pool pool] [--namespace namespace]
737 interval [start-time]
738 Remove trash purge schedule.
739 trash purge schedule status [-p | --pool pool] [--format format]
741 [--pretty-format] [--namespace namespace]
742 Show trash purge schedule status.
743 watch image-spec
745 Watch events on image.
746
748 image-spec is [pool-name/[namespace-name/]]image-name
749 snap-spec is [pool-name/[namespace-name/]]image-name@snap-name
750 group-spec is [pool-name/[namespace-name/]]group-name
751 group-snap-spec is [pool-name/[namespace-name/]]group-name@snap-name
752 journal-spec is [pool-name/[namespace-name/]]journal-name
753 The default for pool-name is "rbd" and namespace-name is "". If an im‐
756 age name contains a slash character ('/'), pool-name is required.
757 The journal-name is image-id.
759 You may specify each name individually, using --pool, --namespace,
761 --image, and --snap options, but this is discouraged in favor of the
762 above spec syntax.
763
765 RBD images are striped over many objects, which are then stored by the
766 Ceph distributed object store (RADOS). As a result, read and write re‐
767 quests for the image are distributed across many nodes in the cluster,
768 generally preventing any single node from becoming a bottleneck when
769 individual images get large or busy.
770 The striping is controlled by three parameters:
772 object-size
774 The size of objects we stripe over is a power of two. It will be
775 rounded up the nearest power of two. The default object size is
776 4 MB, smallest is 4K and maximum is 32M.
777 stripe_unit
779 Each [stripe_unit] contiguous bytes are stored adjacently in the
780 same object, before we move on to the next object.
781 stripe_count
783 After we write [stripe_unit] bytes to [stripe_count] objects, we
784 loop back to the initial object and write another stripe, until
785 the object reaches its maximum size. At that point, we move on
786 to the next [stripe_count] objects.
787 By default, [stripe_unit] is the same as the object size and
789 [stripe_count] is 1. Specifying a different [stripe_unit] and/or
790 [stripe_count] is often referred to as using "fancy" striping and re‐
791 quires format 2.
792
794 Most of these options are useful mainly for debugging and benchmarking.
795 The default values are set in the kernel and may therefore depend on
796 the version of the running kernel.
797 Per client instance rbd device map options:
799 • fsid=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee - FSID that should be as‐
801 sumed by the client.
802 • ip=a.b.c.d[:p] - IP and, optionally, port the client should use.
804 • share - Enable sharing of client instances with other mappings (de‐
806 fault).
807 • noshare - Disable sharing of client instances with other mappings.
809 • crc - Enable CRC32C checksumming for msgr1 on-the-wire protocol (de‐
811 fault). For msgr2.1 protocol this option is ignored: full checksum‐
812 ming is always on in 'crc' mode and always off in 'secure' mode.
813 • nocrc - Disable CRC32C checksumming for msgr1 on-the-wire protocol.
815 Note that only payload checksumming is disabled, header checksumming
816 is always on. For msgr2.1 protocol this option is ignored.
817 • cephx_require_signatures - Require msgr1 message signing feature
819 (since 3.19, default). This option is deprecated and will be removed
820 in the future as the feature has been supported since the Bobtail re‐
821 lease.
822 • nocephx_require_signatures - Don't require msgr1 message signing fea‐
824 ture (since 3.19). This option is deprecated and will be removed in
825 the future.
826 • tcp_nodelay - Disable Nagle's algorithm on client sockets (since 4.0,
828 default).
829 • notcp_nodelay - Enable Nagle's algorithm on client sockets (since
831 4.0).
832 • cephx_sign_messages - Enable message signing for msgr1 on-the-wire
834 protocol (since 4.4, default). For msgr2.1 protocol this option is
835 ignored: message signing is built into 'secure' mode and not offered
836 in 'crc' mode.
837 • nocephx_sign_messages - Disable message signing for msgr1 on-the-wire
839 protocol (since 4.4). For msgr2.1 protocol this option is ignored.
840 • mount_timeout=x - A timeout on various steps in rbd device map and
842 rbd device unmap sequences (default is 60 seconds). In particular,
843 since 4.2 this can be used to ensure that rbd device unmap eventually
844 times out when there is no network connection to a cluster.
845 • osdkeepalive=x - OSD keepalive timeout (default is 5 seconds).
847 • osd_idle_ttl=x - OSD idle TTL (default is 60 seconds).
849 Per mapping (block device) rbd device map options:
851 • rw - Map the image read-write (default). Overridden by --read-only.
853 • ro - Map the image read-only. Equivalent to --read-only.
855 • queue_depth=x - queue depth (since 4.2, default is 128 requests).
857 • lock_on_read - Acquire exclusive lock on reads, in addition to writes
859 and discards (since 4.9).
860 • exclusive - Disable automatic exclusive lock transitions (since
862 4.12). Equivalent to --exclusive.
863 • lock_timeout=x - A timeout on waiting for the acquisition of exclu‐
865 sive lock (since 4.17, default is 0 seconds, meaning no timeout).
866 • notrim - Turn off discard and write zeroes offload support to avoid
868 deprovisioning a fully provisioned image (since 4.17). When enabled,
869 discard requests will fail with -EOPNOTSUPP, write zeroes requests
870 will fall back to manually zeroing.
871 • abort_on_full - Fail write requests with -ENOSPC when the cluster is
873 full or the data pool reaches its quota (since 5.0). The default be‐
874 haviour is to block until the full condition is cleared.
875 • alloc_size - Minimum allocation unit of the underlying OSD object
877 store backend (since 5.1, default is 64K bytes). This is used to
878 round off and drop discards that are too small. For bluestore, the
879 recommended setting is bluestore_min_alloc_size (currently set to 4K
880 for all types of drives, previously used to be set to 64K for hard
881 disk drives and 16K for solid-state drives). For filestore with
882 filestore_punch_hole = false, the recommended setting is image object
883 size (typically 4M).
884 • crush_location=x - Specify the location of the client in terms of
886 CRUSH hierarchy (since 5.8). This is a set of key-value pairs sepa‐
887 rated from each other by '|', with keys separated from values by ':'.
888 Note that '|' may need to be quoted or escaped to avoid it being in‐
889 terpreted as a pipe by the shell. The key is the bucket type name
890 (e.g. rack, datacenter or region with default bucket types) and the
891 value is the bucket name. For example, to indicate that the client
892 is local to rack "myrack", data center "mydc" and region "myregion":
893 crush_location=rack:myrack|datacenter:mydc|region:myregion
895 Each key-value pair stands on its own: "myrack" doesn't need to re‐
897 side in "mydc", which in turn doesn't need to reside in "myregion".
898 The location is not a path to the root of the hierarchy but rather a
899 set of nodes that are matched independently, owning to the fact that
900 bucket names are unique within a CRUSH map. "Multipath" locations
901 are supported, so it is possible to indicate locality for multiple
902 parallel hierarchies:
903 crush_location=rack:myrack1|rack:myrack2|datacenter:mydc
905 • read_from_replica=no - Disable replica reads, always pick the primary
907 OSD (since 5.8, default).
908 • read_from_replica=balance - When issued a read on a replicated pool,
910 pick a random OSD for serving it (since 5.8).
911 This mode is safe for general use only since Octopus (i.e. after
913 "ceph osd require-osd-release octopus"). Otherwise it should be lim‐
914 ited to read-only workloads such as images mapped read-only every‐
915 where or snapshots.
916 • read_from_replica=localize - When issued a read on a replicated pool,
918 pick the most local OSD for serving it (since 5.8). The locality
919 metric is calculated against the location of the client given with
920 crush_location; a match with the lowest-valued bucket type wins. For
921 example, with default bucket types, an OSD in a matching rack is
922 closer than an OSD in a matching data center, which in turn is closer
923 than an OSD in a matching region.
924 This mode is safe for general use only since Octopus (i.e. after
926 "ceph osd require-osd-release octopus"). Otherwise it should be lim‐
927 ited to read-only workloads such as images mapped read-only every‐
928 where or snapshots.
929 • compression_hint=none - Don't set compression hints (since 5.8, de‐
931 fault).
932 • compression_hint=compressible - Hint to the underlying OSD object
934 store backend that the data is compressible, enabling compression in
935 passive mode (since 5.8).
936 • compression_hint=incompressible - Hint to the underlying OSD object
938 store backend that the data is incompressible, disabling compression
939 in aggressive mode (since 5.8).
940 • ms_mode=legacy - Use msgr1 on-the-wire protocol (since 5.11, de‐
942 fault).
943 • ms_mode=crc - Use msgr2.1 on-the-wire protocol, select 'crc' mode,
945 also referred to as plain mode (since 5.11). If the daemon denies
946 'crc' mode, fail the connection.
947 • ms_mode=secure - Use msgr2.1 on-the-wire protocol, select 'secure'
949 mode (since 5.11). 'secure' mode provides full in-transit encryption
950 ensuring both confidentiality and authenticity. If the daemon denies
951 'secure' mode, fail the connection.
952 • ms_mode=prefer-crc - Use msgr2.1 on-the-wire protocol, select 'crc'
954 mode (since 5.11). If the daemon denies 'crc' mode in favor of 'se‐
955 cure' mode, agree to 'secure' mode.
956 • ms_mode=prefer-secure - Use msgr2.1 on-the-wire protocol, select 'se‐
958 cure' mode (since 5.11). If the daemon denies 'secure' mode in favor
959 of 'crc' mode, agree to 'crc' mode.
960 • rxbounce - Use a bounce buffer when receiving data (since 5.17). The
962 default behaviour is to read directly into the destination buffer. A
963 bounce buffer is needed if the destination buffer isn't guaranteed to
964 be stable (i.e. remain unchanged while it is being read to). In par‐
965 ticular this is the case for Windows where a system-wide "dummy"
966 (throwaway) page may be mapped into the destination buffer in order
967 to generate a single large I/O. Otherwise, "libceph: ... bad
968 crc/signature" or "libceph: ... integrity error, bad crc" errors and
969 associated performance degradation are expected.
970 • udev - Wait for udev device manager to finish executing all matching
972 "add" rules and release the device before exiting (default). This
973 option is not passed to the kernel.
974 • noudev - Don't wait for udev device manager. When enabled, the de‐
976 vice may not be fully usable immediately on exit.
977 rbd device unmap options:
979 • force - Force the unmapping of a block device that is open (since
981 4.9). The driver will wait for running requests to complete and then
982 unmap; requests sent to the driver after initiating the unmap will be
983 failed.
984 • udev - Wait for udev device manager to finish executing all matching
986 "remove" rules and clean up after the device before exiting (de‐
987 fault). This option is not passed to the kernel.
988 • noudev - Don't wait for udev device manager.
990
992 To create a new rbd image that is 100 GB:
993 rbd create mypool/myimage --size 102400
995 To use a non-default object size (8 MB):
997 rbd create mypool/myimage --size 102400 --object-size 8M
999 To delete an rbd image (be careful!):
1001 rbd rm mypool/myimage
1003 To create a new snapshot:
1005 rbd snap create mypool/myimage@mysnap
1007 To create a copy-on-write clone of a protected snapshot:
1009 rbd clone mypool/myimage@mysnap otherpool/cloneimage
1011 To see which clones of a snapshot exist:
1013 rbd children mypool/myimage@mysnap
1015 To delete a snapshot:
1017 rbd snap rm mypool/myimage@mysnap
1019 To map an image via the kernel with cephx enabled:
1021 rbd device map mypool/myimage --id admin --keyfile secretfile
1023 To map an image via the kernel with different cluster name other than
1025 default ceph:
1026 rbd device map mypool/myimage --cluster cluster-name
1028 To unmap an image:
1030 rbd device unmap /dev/rbd0
1032 To create an image and a clone from it:
1034 rbd import --image-format 2 image mypool/parent
1036 rbd snap create mypool/parent@snap
1037 rbd snap protect mypool/parent@snap
1038 rbd clone mypool/parent@snap otherpool/child
1039 To create an image with a smaller stripe_unit (to better distribute
1041 small writes in some workloads):
1042 rbd create mypool/myimage --size 102400 --stripe-unit 65536B --stripe-count 16
1044 To change an image from one image format to another, export it and then
1046 import it as the desired image format:
1047 rbd export mypool/myimage@snap /tmp/img
1049 rbd import --image-format 2 /tmp/img mypool/myimage2
1050 To lock an image for exclusive use:
1052 rbd lock add mypool/myimage mylockid
1054 To release a lock:
1056 rbd lock remove mypool/myimage mylockid client.2485
1058 To list images from trash:
1060 rbd trash ls mypool
1062 To defer delete an image (use --expires-at to set expiration time, de‐
1064 fault is now):
1065 rbd trash mv mypool/myimage --expires-at "tomorrow"
1067 To delete an image from trash (be careful!):
1069 rbd trash rm mypool/myimage-id
1071 To force delete an image from trash (be careful!):
1073 rbd trash rm mypool/myimage-id --force
1075 To restore an image from trash:
1077 rbd trash restore mypool/myimage-id
1079 To restore an image from trash and rename it:
1081 rbd trash restore mypool/myimage-id --image mynewimage
1083
1085 rbd is part of Ceph, a massively scalable, open-source, distributed
1086 storage system. Please refer to the Ceph documentation at
1087 https://docs.ceph.com for more information.
1088
1090 ceph(8), rados(8)
1091
1093 2010-2023, Inktank Storage, Inc. and contributors. Licensed under Cre‐
1094 ative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)
1095dev Nov 02, 2023 RBD(8)