1RBD(8)                               Ceph                               RBD(8)
2
3
4

NAME

6       rbd - manage rados block device (RBD) images
7

SYNOPSIS

9       rbd [ -c ceph.conf ] [ -m monaddr ] [--cluster cluster-name]
10       [ -p | --pool pool ] [ command ... ]
11
12

DESCRIPTION

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

OPTIONS

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
26       -m monaddress[:port]
27              Connect   to  specified  monitor  (instead  of  looking  through
28              ceph.conf).
29
30       --cluster cluster-name
31              Use different cluster name as compared to default  cluster  name
32              ceph.
33
34       -p pool-name, --pool pool-name
35              Interact with the given pool. Required by most commands.
36
37       --namespace namespace-name
38              Use a pre-defined image namespace within a pool
39
40       --no-progress
41              Do  not  output  progress information (goes to standard error by
42              default for some commands).
43

PARAMETERS

45       --image-format format-id
46              Specifies which object layout to use. The default is 2.
47
48              · 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
53              · 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
58       -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
63       --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
69       --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
74       --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
79       --snap snap
80              Specifies the snapshot name for the specific operation.
81
82       --id username
83              Specifies  the username (without the client. prefix) to use with
84              the map command.
85
86       --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
91       --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
96       --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
104       --format format
105              Specifies output formatting (default: plain, json, xml)
106
107       --pretty-format
108              Make json or xml formatted output more human-readable.
109
110       -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
116       --read-only
117              Map the image read-only.  Equivalent to -o ro.
118
119       --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
125              · layering: layering support
126
127              · striping: striping v2 support
128
129              · exclusive-lock: exclusive locking support
130
131              · object-map: object map support (requires exclusive-lock)
132
133              · fast-diff: fast diff calculations (requires object-map)
134
135              · deep-flatten: snapshot flatten support
136
137              · journaling: journaled IO support (requires exclusive-lock)
138
139              · data-pool: erasure coded pool support
140
141       --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
146       --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
155       --limit
156              Specifies the limit for the number of snapshots permitted.
157

COMMANDS

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
169       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
173              This requires image format 2.
174
175       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
184              The  parent  snapshot  must be protected (see rbd snap protect).
185              This requires image format 2.
186
187       config global get config-entity key
188              Get a global-level configuration override.
189
190       config global list [--format plain | json | xml] [--pretty-format] con‐
191       fig-entity
192              List global-level configuration overrides.
193
194       config global set config-entity key value
195              Set a global-level configuration override.
196
197       config global remove config-entity key
198              Remove a global-level configuration override.
199
200       config image get image-spec key
201              Get an image-level configuration override.
202
203       config  image  list  [--format  plain  |  json | xml] [--pretty-format]
204       image-spec
205              List image-level configuration overrides.
206
207       config image set image-spec key value
208              Set an image-level configuration override.
209
210       config image remove image-spec key
211              Remove an image-level configuration override.
212
213       config pool get pool-name key
214              Get a pool-level configuration override.
215
216       config pool list  [--format  plain  |  json  |  xml]  [--pretty-format]
217       pool-name
218              List pool-level configuration overrides.
219
220       config pool set pool-name key value
221              Set a pool-level configuration override.
222
223       config pool remove pool-name key
224              Remove a pool-level configuration override.
225
226       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
231       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
242       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
247       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
252       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
258              The --options argument is a comma separated list of device  type
259              specific options (opt1,opt2=val,...).
260
261       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
266              The  --options argument is a comma separated list of device type
267              specific options (opt1,opt2=val,...).
268
269       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
277       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
282              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
286       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
293       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
304       feature disable image-spec feature-name...
305              Disable  the  specified feature on the specified image. Multiple
306              features can be specified.
307
308       feature enable image-spec feature-name...
309              Enable the specified feature on the  specified  image.  Multiple
310              features can be specified.
311
312       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
319              This requires image format 2.
320
321       group create group-spec
322              Create a group.
323
324       group image add group-spec image-spec
325              Add an image to a group.
326
327       group image list group-spec
328              List images in a group.
329
330       group image remove group-spec image-spec
331              Remove an image from a group.
332
333       group ls [-p | --pool pool-name]
334              List rbd groups.
335
336       group rename src-group-spec dest-group-spec
337              Rename a group.  Note: rename across pools is not supported.
338
339       group rm group-spec
340              Delete a group.
341
342       group snap create group-snap-spec
343              Make a snapshot of a group.
344
345       group snap list group-spec
346              List snapshots of a group.
347
348       group snap rm group-snap-spec
349              Remove a snapshot from a group.
350
351       group snap rename group-snap-spec snap-name
352              Rename group's snapshot.
353
354       group snap rollback group-snap-spec
355              Rollback group to snapshot.
356
357       image-meta get image-spec key
358              Get metadata value with the key.
359
360       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
364       image-meta remove image-spec key
365              Remove metadata key with the value.
366
367       image-meta set image-spec key value
368              Set  metadata  key  with  the  value.  They  will  displayed  in
369              image-meta list.
370
371       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
381              The --stripe-unit and --stripe-count arguments are optional, but
382              must be used together.
383
384              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
388       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
396       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
402       journal client disconnect journal-spec
403              Flag image journal client as disconnected.
404
405       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
410              Note  that  this  command  may not always work if the journal is
411              badly corrupted.
412
413       journal import [--verbose] [--no-error] path-name dest-journal-spec
414              Import image journal from path (use - for stdin).
415
416       journal info journal-spec
417              Show information about image journal.
418
419       journal inspect [--verbose] journal-spec
420              Inspect and report image journal for structural errors.
421
422       journal reset journal-spec
423              Reset image journal.
424
425       journal status journal-spec
426              Show status of image journal.
427
428       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
436       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
440       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
444       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
449       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
459       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
465       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
470       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
474       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
486       mirror image demote image-spec
487              Demote a primary image to non-primary for RBD mirroring.
488
489       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
494       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
499              This requires the RBD journaling feature is enabled.
500
501       mirror image promote [--force] image-spec
502              Promote a non-primary image to primary for RBD mirroring.
503
504       mirror image resync image-spec
505              Force resync to primary image for RBD mirroring.
506
507       mirror image status image-spec
508              Show RBD mirroring status for an image.
509
510       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
514       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
520       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
528       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
533       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
537              The default for remote client name is "client.admin".
538
539              This requires mirroring mode is enabled.
540
541       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
545       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
550       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
554       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
559       mv src-image-spec dest-image-spec
560              Rename an image.  Note: rename across pools is not supported.
561
562       namespace create pool-name namespace-name
563              Create a new image namespace within the pool.
564
565       namespace list pool-name
566              List image namespaces defined within the pool.
567
568       namespace remove pool-name namespace-name
569              Remove an empty image namespace from the pool.
570
571       object-map check image-spec | snap-spec
572              Verify the object map is correct.
573
574       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
579       pool init [pool-name] [--force]
580              Initialize  pool  for  use by RBD. Newly created pools must ini‐
581              tialized prior to use.
582
583       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
587       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
591       snap create snap-spec
592              Create a new snapshot.  Requires  the  snapshot  name  parameter
593              specified.
594
595       snap limit clear image-spec
596              Remove  any  previously  set  limit  on  the number of snapshots
597              allowed on an image.
598
599       snap limit set [--limit] limit image-spec
600              Set a limit for the number of snapshots allowed on an image.
601
602       snap ls image-spec
603              Dump the list of snapshots inside a specific image.
604
605       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
612              This requires image format 2.
613
614       snap purge image-spec
615              Remove all unprotected snapshots from an image.
616
617       snap rename src-snap-spec dest-snap-spec
618              Rename a snapshot. Note: rename across pools and images  is  not
619              supported.
620
621       snap rm [--force] snap-spec
622              Remove the specified snapshot.
623
624       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
629       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
634              This requires image format 2.
635
636       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
642       status image-spec
643              Show the status of the image, including which  clients  have  it
644              open.
645
646       trash ls [pool-name]
647              List all entries from trash.
648
649       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
653       trash purge [pool-name]
654              Remove all expired images from trash.
655
656       trash restore image-id
657              Restore an image from trash.
658
659       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
664       watch image-spec
665              Watch events on image.
666

IMAGE, SNAP, GROUP AND JOURNAL SPECS

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
674
675       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
678       The journal-name is image-id.
679
680       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

STRIPING

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
691       The striping is controlled by three parameters:
692
693       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
698       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
702       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
708       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

KERNEL RBD (KRBD) OPTIONS

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
718       Per client instance rbd device map options:
719
720       · fsid=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee  -  FSID  that  should   be
721         assumed by the client.
722
723       · ip=a.b.c.d[:p] - IP and, optionally, port the client should use.
724
725       · share  -  Enable  sharing  of  client  instances  with other mappings
726         (default).
727
728       · noshare - Disable sharing of client instances with other mappings.
729
730       · crc - Enable CRC32C checksumming for data writes (default).
731
732       · nocrc - Disable CRC32C checksumming for data writes.
733
734       · cephx_require_signatures - Require cephx message signing (since 3.19,
735         default).
736
737       · nocephx_require_signatures  -  Don't  require  cephx  message signing
738         (since 3.19).
739
740       · tcp_nodelay - Disable Nagle's algorithm on client sockets (since 4.0,
741         default).
742
743       · notcp_nodelay  -  Enable  Nagle's  algorithm on client sockets (since
744         4.0).
745
746       · cephx_sign_messages - Enable message signing (since 4.4, default).
747
748       · nocephx_sign_messages - Disable message signing (since 4.4).
749
750       · 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
755       · osdkeepalive=x - OSD keepalive timeout (default is 5 seconds).
756
757       · osd_idle_ttl=x - OSD idle TTL (default is 60 seconds).
758
759       Per mapping (block device) rbd device map options:
760
761       · rw - Map the image read-write (default).
762
763       · ro - Map the image read-only.  Equivalent to --read-only.
764
765       · queue_depth=x - queue depth (since 4.2, default is 128 requests).
766
767       · lock_on_read - Acquire exclusive lock on reads, in addition to writes
768         and discards (since 4.9).
769
770       · exclusive -  Disable  automatic  exclusive  lock  transitions  (since
771         4.12).
772
773       · 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
776       · 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
781       · 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
785       · 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
793       rbd device unmap options:
794
795       · 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

EXAMPLES

801       To create a new rbd image that is 100 GB:
802
803          rbd create mypool/myimage --size 102400
804
805       To use a non-default object size (8 MB):
806
807          rbd create mypool/myimage --size 102400 --object-size 8M
808
809       To delete an rbd image (be careful!):
810
811          rbd rm mypool/myimage
812
813       To create a new snapshot:
814
815          rbd snap create mypool/myimage@mysnap
816
817       To create a copy-on-write clone of a protected snapshot:
818
819          rbd clone mypool/myimage@mysnap otherpool/cloneimage
820
821       To see which clones of a snapshot exist:
822
823          rbd children mypool/myimage@mysnap
824
825       To delete a snapshot:
826
827          rbd snap rm mypool/myimage@mysnap
828
829       To map an image via the kernel with cephx enabled:
830
831          rbd device map mypool/myimage --id admin --keyfile secretfile
832
833       To map an image via the kernel with different cluster name  other  than
834       default ceph:
835
836          rbd device map mypool/myimage --cluster cluster-name
837
838       To unmap an image:
839
840          rbd device unmap /dev/rbd0
841
842       To create an image and a clone from it:
843
844          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
849       To  create  an  image  with a smaller stripe_unit (to better distribute
850       small writes in some workloads):
851
852          rbd create mypool/myimage --size 102400 --stripe-unit 65536B --stripe-count 16
853
854       To change an image from one image format to another, export it and then
855       import it as the desired image format:
856
857          rbd export mypool/myimage@snap /tmp/img
858          rbd import --image-format 2 /tmp/img mypool/myimage2
859
860       To lock an image for exclusive use:
861
862          rbd lock add mypool/myimage mylockid
863
864       To release a lock:
865
866          rbd lock remove mypool/myimage mylockid client.2485
867
868       To list images from trash:
869
870          rbd trash ls mypool
871
872       To  defer  delete  an  image  (use --expires-at to set expiration time,
873       default is now):
874
875          rbd trash mv mypool/myimage --expires-at "tomorrow"
876
877       To delete an image from trash (be careful!):
878
879          rbd trash rm mypool/myimage-id
880
881       To force delete an image from trash (be careful!):
882
883          rbd trash rm mypool/myimage-id  --force
884
885       To restore an image from trash:
886
887          rbd trash restore mypool/myimage-id
888
889       To restore an image from trash and rename it:
890
891          rbd trash restore mypool/myimage-id --image mynewimage
892

AVAILABILITY

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

SEE ALSO

899       ceph(8), rados(8)
900
902       2010-2014, Inktank Storage, Inc. and contributors. Licensed under  Cre‐
903       ative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)
904
905
906
907
908dev                              Apr 29, 2019                           RBD(8)
Impressum