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 and kernel since version 3.11 (except for striping).
55 This adds support for cloning and is more easily extensible to
56 allow more features in the future.
57 -s size-in-M/G/T, --size size-in-M/G/T
59 Specifies the size of the new rbd image or the new size of the
60 existing rbd image in M/G/T. If no suffix is given, unit M is
61 assumed.
62 --object-size size-in-B/K/M
64 Specifies the object size in B/K/M. Object size will be rounded
65 up the nearest power of two; if no suffix is given, unit B is
66 assumed. The default object size is 4M, smallest is 4K and max‐
67 imum is 32M.
68 --stripe-unit size-in-B/K/M
70 Specifies the stripe unit size in B/K/M. If no suffix is given,
71 unit B is assumed. See striping section (below) for more
72 details.
73 --stripe-count num
75 Specifies the number of objects to stripe over before looping
76 back to the first object. See striping section (below) for more
77 details.
78 --snap snap
80 Specifies the snapshot name for the specific operation.
81 --id username
83 Specifies the username (without the client. prefix) to use with
84 the map command.
85 --keyring filename
87 Specifies a keyring file containing a secret for the specified
88 user to use with the map command. If not specified, the default
89 keyring locations will be searched.
90 --keyfile filename
92 Specifies a file containing the secret key of --id user to use
93 with the map command. This option is overridden by --keyring if
94 the latter is also specified.
95 --shared lock-tag
97 Option for lock add that allows multiple clients to lock the
98 same image if they use the same tag. The tag is an arbitrary
99 string. This is useful for situations where an image must be
100 open from more than one client at once, like during live migra‐
101 tion of a virtual machine, or for use underneath a clustered
102 filesystem.
103 --format format
105 Specifies output formatting (default: plain, json, xml)
106 --pretty-format
108 Make json or xml formatted output more human-readable.
109 -o krbd-options, --options krbd-options
111 Specifies which options to use when mapping or unmapping an
112 image via the rbd kernel driver. krbd-options is a comma-sepa‐
113 rated list of options (similar to mount(8) mount options). See
114 kernel rbd (krbd) options section below for more details.
115 --read-only
117 Map the image read-only. Equivalent to -o ro.
118 --image-feature feature-name
120 Specifies which RBD format 2 feature should be enabled when cre‐
121 ating an image. Multiple features can be enabled by repeating
122 this option multiple times. The following features are sup‐
123 ported:
124 · layering: layering support
126 · striping: striping v2 support
128 · exclusive-lock: exclusive locking support
130 · object-map: object map support (requires exclusive-lock)
132 · fast-diff: fast diff calculations (requires object-map)
134 · deep-flatten: snapshot flatten support
136 · journaling: journaled IO support (requires exclusive-lock)
138 · data-pool: erasure coded pool support
140 --image-shared
142 Specifies that the image will be used concurrently by multiple
143 clients. This will disable features that are dependent upon
144 exclusive ownership of the image.
145 --whole-object
147 Specifies that the diff should be limited to the extents of a
148 full object instead of showing intra-object deltas. When the
149 object map feature is enabled on an image, limiting the diff to
150 the object extents will dramatically improve performance since
151 the differences can be computed by examining the in-memory
152 object map instead of querying RADOS for each object within the
153 image.
154 --limit
156 Specifies the limit for the number of snapshots permitted.
157
159 bench --io-type <read | write | readwrite | rw> [--io-size
160 size-in-B/K/M/G/T] [--io-threads num-ios-in-flight] [--io-total
161 size-in-B/K/M/G/T] [--io-pattern seq | rand] [--rw-mix-read read pro‐
162 portion in readwrite] image-spec
163 Generate a series of IOs to the image and measure the IO
164 throughput and latency. If no suffix is given, unit B is
165 assumed for both --io-size and --io-total. Defaults are:
166 --io-size 4096, --io-threads 16, --io-total 1G, --io-pattern
167 seq, --rw-mix-read 50.
168 children snap-spec
170 List the clones of the image at the given snapshot. This checks
171 every pool, and outputs the resulting poolname/imagename.
172 This requires image format 2.
174 clone [--object-size size-in-B/K/M] [--stripe-unit size-in-B/K/M
176 --stripe-count num] [--image-feature feature-name] [--image-shared]
177 parent-snap-spec child-image-spec
178 Will create a clone (copy-on-write child) of the parent snap‐
179 shot. Object size will be identical to that of the parent image
180 unless specified. Size will be the same as the parent snapshot.
181 The --stripe-unit and --stripe-count arguments are optional, but
182 must be used together.
183 The parent snapshot must be protected (see rbd snap protect).
185 This requires image format 2.
186 config global get config-entity key
188 Get a global-level configuration override.
189 config global list [--format plain | json | xml] [--pretty-format] con‐
191 fig-entity
192 List global-level configuration overrides.
193 config global set config-entity key value
195 Set a global-level configuration override.
196 config global remove config-entity key
198 Remove a global-level configuration override.
199 config image get image-spec key
201 Get an image-level configuration override.
202 config image list [--format plain | json | xml] [--pretty-format]
204 image-spec
205 List image-level configuration overrides.
206 config image set image-spec key value
208 Set an image-level configuration override.
209 config image remove image-spec key
211 Remove an image-level configuration override.
212 config pool get pool-name key
214 Get a pool-level configuration override.
215 config pool list [--format plain | json | xml] [--pretty-format]
217 pool-name
218 List pool-level configuration overrides.
219 config pool set pool-name key value
221 Set a pool-level configuration override.
222 config pool remove pool-name key
224 Remove a pool-level configuration override.
225 cp (src-image-spec | src-snap-spec) dest-image-spec
227 Copy the content of a src-image into the newly created
228 dest-image. dest-image will have the same size, object size,
229 and image format as src-image.
230 create (-s | --size size-in-M/G/T) [--image-format format-id]
232 [--object-size size-in-B/K/M] [--stripe-unit size-in-B/K/M
233 --stripe-count num] [--thick-provision] [--no-progress] [--image-fea‐
234 ture feature-name]... [--image-shared] image-spec
235 Will create a new rbd image. You must also specify the size via
236 --size. The --stripe-unit and --stripe-count arguments are
237 optional, but must be used together. If the --thick-provision
238 is enabled, it will fully allocate storage for the image at cre‐
239 ation time. It will take a long time to do. Note: thick provi‐
240 sioning requires zeroing the contents of the entire image.
241 deep cp (src-image-spec | src-snap-spec) dest-image-spec
243 Deep copy the content of a src-image into the newly created
244 dest-image. Dest-image will have the same size, object size,
245 image format, and snapshots as src-image.
246 device list [-t | --device-type device-type] [--format plain | json |
248 xml] --pretty-format
249 Show the rbd images that are mapped via the rbd kernel module
250 (default) or other supported device.
251 device map [-t | --device-type device-type] [--read-only] [--exclusive]
253 [-o | --options device-options] image-spec | snap-spec
254 Map the specified image to a block device via the rbd kernel
255 module (default) or other supported device (nbd on Linux or
256 ggate on FreeBSD).
257 The --options argument is a comma separated list of device type
259 specific options (opt1,opt2=val,...).
260 device unmap [-t | --device-type device-type] [-o | --options
262 device-options] image-spec | snap-spec | device-path
263 Unmap the block device that was mapped via the rbd kernel module
264 (default) or other supported device.
265 The --options argument is a comma separated list of device type
267 specific options (opt1,opt2=val,...).
268 diff [--from-snap snap-name] [--whole-object] image-spec | snap-spec
270 Dump a list of byte extents in the image that have changed since
271 the specified start snapshot, or since the image was created.
272 Each output line includes the starting offset (in bytes), the
273 length of the region (in bytes), and either 'zero' or 'data' to
274 indicate whether the region is known to be zeros or may contain
275 other data.
276 du [-p | --pool pool-name] [image-spec | snap-spec]
278 Will calculate the provisioned and actual disk usage of all
279 images and associated snapshots within the specified pool. It
280 can also be used against individual images and snapshots.
281 If the RBD fast-diff feature is not enabled on images, this
283 operation will require querying the OSDs for every potential
284 object within the image.
285 export [--export-format format (1 or 2)] (image-spec | snap-spec)
287 [dest-path]
288 Export image to dest path (use - for stdout). The --export-for‐
289 mat accepts '1' or '2' currently. Format 2 allow us to export
290 not only the content of image, but also the snapshots and other
291 properties, such as image_order, features.
292 export-diff [--from-snap snap-name] [--whole-object] (image-spec |
294 snap-spec) dest-path
295 Export an incremental diff for an image to dest path (use - for
296 stdout). If an initial snapshot is specified, only changes
297 since that snapshot are included; otherwise, any regions of the
298 image that contain data are included. The end snapshot is spec‐
299 ified using the standard --snap option or @snap syntax (see
300 below). The image diff format includes metadata about image
301 size changes, and the start and end snapshots. It efficiently
302 represents discarded or 'zero' regions of the image.
303 feature disable image-spec feature-name...
305 Disable the specified feature on the specified image. Multiple
306 features can be specified.
307 feature enable image-spec feature-name...
309 Enable the specified feature on the specified image. Multiple
310 features can be specified.
311 flatten image-spec
313 If image is a clone, copy all shared blocks from the parent
314 snapshot and make the child independent of the parent, severing
315 the link between parent snap and child. The parent snapshot can
316 be unprotected and deleted if it has no further dependent
317 clones.
318 This requires image format 2.
320 group create group-spec
322 Create a group.
323 group image add group-spec image-spec
325 Add an image to a group.
326 group image list group-spec
328 List images in a group.
329 group image remove group-spec image-spec
331 Remove an image from a group.
332 group ls [-p | --pool pool-name]
334 List rbd groups.
335 group rename src-group-spec dest-group-spec
337 Rename a group. Note: rename across pools is not supported.
338 group rm group-spec
340 Delete a group.
341 group snap create group-snap-spec
343 Make a snapshot of a group.
344 group snap list group-spec
346 List snapshots of a group.
347 group snap rm group-snap-spec
349 Remove a snapshot from a group.
350 group snap rename group-snap-spec snap-name
352 Rename group's snapshot.
353 group snap rollback group-snap-spec
355 Rollback group to snapshot.
356 image-meta get image-spec key
358 Get metadata value with the key.
359 image-meta list image-spec
361 Show metadata held on the image. The first column is the key and
362 the second column is the value.
363 image-meta remove image-spec key
365 Remove metadata key with the value.
366 image-meta set image-spec key value
368 Set metadata key with the value. They will displayed in
369 image-meta list.
370 import [--export-format format (1 or 2)] [--image-format format-id]
372 [--object-size size-in-B/K/M] [--stripe-unit size-in-B/K/M
373 --stripe-count num] [--image-feature feature-name]... [--image-shared]
374 src-path [image-spec]
375 Create a new image and imports its data from path (use - for
376 stdin). The import operation will try to create sparse rbd
377 images if possible. For import from stdin, the sparsification
378 unit is the data block size of the destination image (object
379 size).
380 The --stripe-unit and --stripe-count arguments are optional, but
382 must be used together.
383 The --export-format accepts '1' or '2' currently. Format 2 allow
385 us to import not only the content of image, but also the snap‐
386 shots and other properties, such as image_order, features.
387 import-diff src-path image-spec
389 Import an incremental diff of an image and applies it to the
390 current image. If the diff was generated relative to a start
391 snapshot, we verify that snapshot already exists before continu‐
392 ing. If there was an end snapshot we verify it does not already
393 exist before applying the changes, and create the snapshot when
394 we are done.
395 info image-spec | snap-spec
397 Will dump information (such as size and object size) about a
398 specific rbd image. If image is a clone, information about its
399 parent is also displayed. If a snapshot is specified, whether
400 it is protected is shown as well.
401 journal client disconnect journal-spec
403 Flag image journal client as disconnected.
404 journal export [--verbose] [--no-error] src-journal-spec path-name
406 Export image journal to path (use - for stdout). It can be make
407 a backup of the image journal especially before attempting dan‐
408 gerous operations.
409 Note that this command may not always work if the journal is
411 badly corrupted.
412 journal import [--verbose] [--no-error] path-name dest-journal-spec
414 Import image journal from path (use - for stdin).
415 journal info journal-spec
417 Show information about image journal.
418 journal inspect [--verbose] journal-spec
420 Inspect and report image journal for structural errors.
421 journal reset journal-spec
423 Reset image journal.
424 journal status journal-spec
426 Show status of image journal.
427 lock add [--shared lock-tag] image-spec lock-id
429 Lock an image. The lock-id is an arbitrary name for the user's
430 convenience. By default, this is an exclusive lock, meaning it
431 will fail if the image is already locked. The --shared option
432 changes this behavior. Note that locking does not affect any
433 operation other than adding a lock. It does not protect an image
434 from being deleted.
435 lock ls image-spec
437 Show locks held on the image. The first column is the locker to
438 use with the lock remove command.
439 lock rm image-spec lock-id locker
441 Release a lock on an image. The lock id and locker are as output
442 by lock ls.
443 ls [-l | --long] [pool-name]
445 Will list all rbd images listed in the rbd_directory object.
446 With -l, also show snapshots, and use longer-format output
447 including size, parent (if clone), format, etc.
448 merge-diff first-diff-path second-diff-path merged-diff-path
450 Merge two continuous incremental diffs of an image into one sin‐
451 gle diff. The first diff's end snapshot must be equal with the
452 second diff's start snapshot. The first diff could be - for
453 stdin, and merged diff could be - for stdout, which enables mul‐
454 tiple diff files to be merged using something like 'rbd
455 merge-diff first second - | rbd merge-diff - third result'. Note
456 this command currently only support the source incremental diff
457 with stripe_count == 1
458 migration abort image-spec
460 Cancel image migration. This step may be run after successful or
461 failed migration prepare or migration execute steps and returns
462 the image to its initial (before migration) state. All modifica‐
463 tions to the destination image are lost.
464 migration commit image-spec
466 Commit image migration. This step is run after a successful
467 migration prepare and migration execute steps and removes the
468 source image data.
469 migration execute image-spec
471 Execute image migration. This step is run after a successful
472 migration prepare step and copies image data to the destination.
473 migration prepare [--order order] [--object-size object-size]
475 [--image-feature image-feature] [--image-shared] [--stripe-unit
476 stripe-unit] [--stripe-count stripe-count] [--data-pool data-pool]
477 src-image-spec [dest-image-spec]
478 Prepare image migration. This is the first step when migrating
479 an image, i.e. changing the image location, format or other
480 parameters that can't be changed dynamically. The destination
481 can match the source, and in this case dest-image-spec can be
482 omitted. After this step the source image is set as a parent of
483 the destination image, and the image is accessible in
484 copy-on-write mode by its destination spec.
485 mirror image demote image-spec
487 Demote a primary image to non-primary for RBD mirroring.
488 mirror image disable [--force] image-spec
490 Disable RBD mirroring for an image. If the mirroring is config‐
491 ured in image mode for the image's pool, then it can be explic‐
492 itly disabled mirroring for each image within the pool.
493 mirror image enable image-spec
495 Enable RBD mirroring for an image. If the mirroring is config‐
496 ured in image mode for the image's pool, then it can be explic‐
497 itly enabled mirroring for each image within the pool.
498 This requires the RBD journaling feature is enabled.
500 mirror image promote [--force] image-spec
502 Promote a non-primary image to primary for RBD mirroring.
503 mirror image resync image-spec
505 Force resync to primary image for RBD mirroring.
506 mirror image status image-spec
508 Show RBD mirroring status for an image.
509 mirror pool demote [pool-name]
511 Demote all primary images within a pool to non-primary. Every
512 mirroring enabled image will demoted in the pool.
513 mirror pool disable [pool-name]
515 Disable RBD mirroring by default within a pool. When mirroring
516 is disabled on a pool in this way, mirroring will also be dis‐
517 abled on any images (within the pool) for which mirroring was
518 enabled explicitly.
519 mirror pool enable [pool-name] mode
521 Enable RBD mirroring by default within a pool. The mirroring
522 mode can either be pool or image. If configured in pool mode,
523 all images in the pool with the journaling feature enabled are
524 mirrored. If configured in image mode, mirroring needs to be
525 explicitly enabled (by mirror image enable command) on each
526 image.
527 mirror pool info [pool-name]
529 Show information about the pool mirroring configuration. It
530 includes mirroring mode, peer UUID, remote cluster name, and
531 remote client name.
532 mirror pool peer add [pool-name] remote-cluster-spec
534 Add a mirroring peer to a pool. remote-cluster-spec is [remote
535 client name@]remote cluster name.
536 The default for remote client name is "client.admin".
538 This requires mirroring mode is enabled.
540 mirror pool peer remove [pool-name] uuid
542 Remove a mirroring peer from a pool. The peer uuid is available
543 from mirror pool info command.
544 mirror pool peer set [pool-name] uuid key value
546 Update mirroring peer settings. The key can be either client or
547 cluster, and the value is corresponding to remote client name or
548 remote cluster name.
549 mirror pool promote [--force] [pool-name]
551 Promote all non-primary images within a pool to primary. Every
552 mirroring enabled image will promoted in the pool.
553 mirror pool status [--verbose] [pool-name]
555 Show status for all mirrored images in the pool. With --ver‐
556 bose, also show additionally output status details for every
557 mirroring image in the pool.
558 mv src-image-spec dest-image-spec
560 Rename an image. Note: rename across pools is not supported.
561 namespace create pool-name/namespace-name
563 Create a new image namespace within the pool.
564 namespace list pool-name
566 List image namespaces defined within the pool.
567 namespace remove pool-name/namespace-name
569 Remove an empty image namespace from the pool.
570 object-map check image-spec | snap-spec
572 Verify the object map is correct.
573 object-map rebuild image-spec | snap-spec
575 Rebuild an invalid object map for the specified image. An image
576 snapshot can be specified to rebuild an invalid object map for a
577 snapshot.
578 pool init [pool-name] [--force]
580 Initialize pool for use by RBD. Newly created pools must ini‐
581 tialized prior to use.
582 resize (-s | --size size-in-M/G/T) [--allow-shrink] image-spec
584 Resize rbd image. The size parameter also needs to be specified.
585 The --allow-shrink option lets the size be reduced.
586 rm image-spec
588 Delete an rbd image (including all data blocks). If the image
589 has snapshots, this fails and nothing is deleted.
590 snap create snap-spec
592 Create a new snapshot. Requires the snapshot name parameter
593 specified.
594 snap limit clear image-spec
596 Remove any previously set limit on the number of snapshots
597 allowed on an image.
598 snap limit set [--limit] limit image-spec
600 Set a limit for the number of snapshots allowed on an image.
601 snap ls image-spec
603 Dump the list of snapshots inside a specific image.
604 snap protect snap-spec
606 Protect a snapshot from deletion, so that clones can be made of
607 it (see rbd clone). Snapshots must be protected before clones
608 are made; protection implies that there exist dependent cloned
609 children that refer to this snapshot. rbd clone will fail on a
610 nonprotected snapshot.
611 This requires image format 2.
613 snap purge image-spec
615 Remove all unprotected snapshots from an image.
616 snap rename src-snap-spec dest-snap-spec
618 Rename a snapshot. Note: rename across pools and images is not
619 supported.
620 snap rm [--force] snap-spec
622 Remove the specified snapshot.
623 snap rollback snap-spec
625 Rollback image content to snapshot. This will iterate through
626 the entire blocks array and update the data head content to the
627 snapshotted version.
628 snap unprotect snap-spec
630 Unprotect a snapshot from deletion (undo snap protect). If
631 cloned children remain, snap unprotect fails. (Note that clones
632 may exist in different pools than the parent snapshot.)
633 This requires image format 2.
635 sparsify [--sparse-size sparse-size] image-spec
637 Reclaim space for zeroed image extents. The default sparse size
638 is 4096 bytes and can be changed via --sparse-size option with
639 the following restrictions: it should be power of two, not less
640 than 4096, and not larger image object size.
641 status image-spec
643 Show the status of the image, including which clients have it
644 open.
645 trash ls [pool-name]
647 List all entries from trash.
648 trash mv image-spec
650 Move an image to the trash. Images, even ones actively in-use by
651 clones, can be moved to the trash and deleted at a later time.
652 trash purge [pool-name]
654 Remove all expired images from trash.
655 trash restore image-id
657 Restore an image from trash.
658 trash rm image-id
660 Delete an image from trash. If image deferment time has not
661 expired you can not removed it unless use force. But an actively
662 in-use by clones or has snapshots can not be removed.
663 watch image-spec
665 Watch events on image.
666
668 image-spec is [pool-name/[namespace-name/]]image-name
669 snap-spec is [pool-name/[namespace-name/]]image-name@snap-name
670 group-spec is [pool-name/[namespace-name/]]group-name
671 group-snap-spec is [pool-name/[namespace-name/]]group-name@snap-name
672 journal-spec is [pool-name/[namespace-name/]]journal-name
673 The default for pool-name is "rbd" and namespace-name is "". If an
676 image name contains a slash character ('/'), pool-name is required.
677 The journal-name is image-id.
679 You may specify each name individually, using --pool, --namespace,
681 --image, and --snap options, but this is discouraged in favor of the
682 above spec syntax.
683
685 RBD images are striped over many objects, which are then stored by the
686 Ceph distributed object store (RADOS). As a result, read and write
687 requests for the image are distributed across many nodes in the clus‐
688 ter, generally preventing any single node from becoming a bottleneck
689 when individual images get large or busy.
690 The striping is controlled by three parameters:
692 object-size
694 The size of objects we stripe over is a power of two. It will be
695 rounded up the nearest power of two. The default object size is
696 4 MB, smallest is 4K and maximum is 32M.
697 stripe_unit
699 Each [stripe_unit] contiguous bytes are stored adjacently in the
700 same object, before we move on to the next object.
701 stripe_count
703 After we write [stripe_unit] bytes to [stripe_count] objects, we
704 loop back to the initial object and write another stripe, until
705 the object reaches its maximum size. At that point, we move on
706 to the next [stripe_count] objects.
707 By default, [stripe_unit] is the same as the object size and
709 [stripe_count] is 1. Specifying a different [stripe_unit] requires
710 that the STRIPINGV2 feature be supported (added in Ceph v0.53) and for‐
711 mat 2 images be used.
712
714 Most of these options are useful mainly for debugging and benchmarking.
715 The default values are set in the kernel and may therefore depend on
716 the version of the running kernel.
717 Per client instance rbd device map options:
719 · fsid=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee - FSID that should be
721 assumed by the client.
722 · ip=a.b.c.d[:p] - IP and, optionally, port the client should use.
724 · share - Enable sharing of client instances with other mappings
726 (default).
727 · noshare - Disable sharing of client instances with other mappings.
729 · crc - Enable CRC32C checksumming for data writes (default).
731 · nocrc - Disable CRC32C checksumming for data writes.
733 · cephx_require_signatures - Require cephx message signing (since 3.19,
735 default).
736 · nocephx_require_signatures - Don't require cephx message signing
738 (since 3.19).
739 · tcp_nodelay - Disable Nagle's algorithm on client sockets (since 4.0,
741 default).
742 · notcp_nodelay - Enable Nagle's algorithm on client sockets (since
744 4.0).
745 · cephx_sign_messages - Enable message signing (since 4.4, default).
747 · nocephx_sign_messages - Disable message signing (since 4.4).
749 · mount_timeout=x - A timeout on various steps in rbd device map and
751 rbd device unmap sequences (default is 60 seconds). In particular,
752 since 4.2 this can be used to ensure that rbd device unmap eventually
753 times out when there is no network connection to a cluster.
754 · osdkeepalive=x - OSD keepalive timeout (default is 5 seconds).
756 · osd_idle_ttl=x - OSD idle TTL (default is 60 seconds).
758 Per mapping (block device) rbd device map options:
760 · rw - Map the image read-write (default).
762 · ro - Map the image read-only. Equivalent to --read-only.
764 · queue_depth=x - queue depth (since 4.2, default is 128 requests).
766 · lock_on_read - Acquire exclusive lock on reads, in addition to writes
768 and discards (since 4.9).
769 · exclusive - Disable automatic exclusive lock transitions (since
771 4.12).
772 · lock_timeout=x - A timeout on waiting for the acquisition of exclu‐
774 sive lock (since 4.17, default is 0 seconds, meaning no timeout).
775 · notrim - Turn off discard and write zeroes offload support to avoid
777 deprovisioning a fully provisioned image (since 4.17). When enabled,
778 discard requests will fail with -EOPNOTSUPP, write zeroes requests
779 will fall back to manually zeroing.
780 · abort_on_full - Fail write requests with -ENOSPC when the cluster is
782 full or the data pool reaches its quota (since 5.0). The default be‐
783 haviour is to block until the full condition is cleared.
784 · alloc_size - Minimum allocation unit of the underlying OSD object
786 store backend (since 5.1, default is 64K bytes). This is used to
787 round off and drop discards that are too small. For bluestore, the
788 recommended setting is bluestore_min_alloc_size (typically 64K for
789 hard disk drives and 16K for solid-state drives). For filestore with
790 filestore_punch_hole = false, the recommended setting is image object
791 size (typically 4M).
792 rbd device unmap options:
794 · force - Force the unmapping of a block device that is open (since
796 4.9). The driver will wait for running requests to complete and then
797 unmap; requests sent to the driver after initiating the unmap will be
798 failed.
799
801 To create a new rbd image that is 100 GB:
802 rbd create mypool/myimage --size 102400
804 To use a non-default object size (8 MB):
806 rbd create mypool/myimage --size 102400 --object-size 8M
808 To delete an rbd image (be careful!):
810 rbd rm mypool/myimage
812 To create a new snapshot:
814 rbd snap create mypool/myimage@mysnap
816 To create a copy-on-write clone of a protected snapshot:
818 rbd clone mypool/myimage@mysnap otherpool/cloneimage
820 To see which clones of a snapshot exist:
822 rbd children mypool/myimage@mysnap
824 To delete a snapshot:
826 rbd snap rm mypool/myimage@mysnap
828 To map an image via the kernel with cephx enabled:
830 rbd device map mypool/myimage --id admin --keyfile secretfile
832 To map an image via the kernel with different cluster name other than
834 default ceph:
835 rbd device map mypool/myimage --cluster cluster-name
837 To unmap an image:
839 rbd device unmap /dev/rbd0
841 To create an image and a clone from it:
843 rbd import --image-format 2 image mypool/parent
845 rbd snap create mypool/parent@snap
846 rbd snap protect mypool/parent@snap
847 rbd clone mypool/parent@snap otherpool/child
848 To create an image with a smaller stripe_unit (to better distribute
850 small writes in some workloads):
851 rbd create mypool/myimage --size 102400 --stripe-unit 65536B --stripe-count 16
853 To change an image from one image format to another, export it and then
855 import it as the desired image format:
856 rbd export mypool/myimage@snap /tmp/img
858 rbd import --image-format 2 /tmp/img mypool/myimage2
859 To lock an image for exclusive use:
861 rbd lock add mypool/myimage mylockid
863 To release a lock:
865 rbd lock remove mypool/myimage mylockid client.2485
867 To list images from trash:
869 rbd trash ls mypool
871 To defer delete an image (use --expires-at to set expiration time,
873 default is now):
874 rbd trash mv mypool/myimage --expires-at "tomorrow"
876 To delete an image from trash (be careful!):
878 rbd trash rm mypool/myimage-id
880 To force delete an image from trash (be careful!):
882 rbd trash rm mypool/myimage-id --force
884 To restore an image from trash:
886 rbd trash restore mypool/myimage-id
888 To restore an image from trash and rename it:
890 rbd trash restore mypool/myimage-id --image mynewimage
892
894 rbd is part of Ceph, a massively scalable, open-source, distributed
895 storage system. Please refer to the Ceph documentation at
896 http://ceph.com/docs for more information.
897
899 ceph(8), rados(8)
900
902 2010-2020, Inktank Storage, Inc. and contributors. Licensed under Cre‐
903 ative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)
904dev Apr 21, 2020 RBD(8)