Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
RBD(8)				     Ceph				RBD(8)

       rbd - manage rados block	device (RBD) images

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

       rbd is a	utility	for manipulating rados block device (RBD) images, used
       by the Linux rbd	driver and the rbd storage driver for  QEMU/KVM.   RBD
       images  are  simple  block  devices  that  are striped over objects and
       stored in a RADOS object	store. The size	of the objects	the  image  is
       striped over must be a power of two.

       -c ceph.conf, --conf ceph.conf
	      Use   ceph.conf	configuration  file  instead  of  the  default
	      /etc/ceph/ceph.conf  to  determine  monitor   addresses	during

       -m monaddress[:port]
	      Connect	to  specified  monitor	(instead  of  looking  through

       --cluster cluster-name
	      Use different cluster name as compared to	default	 cluster  name

       -p pool-name, --pool pool-name
	      Interact with the	given pool. Required by	most commands.

       --namespace namespace-name
	      Use a pre-defined	image namespace	within a pool

	      Do  not  output  progress	information (goes to standard error by
	      default for some commands).

       --image-format format-id
	      Specifies	which object layout to use. The	default	is 2.

	      o	format 1 - (deprecated)	Use the	original format	for a new  rbd
		image. This format is understood by all	versions of librbd and
		the kernel rbd module, but does	 not  support  newer  features
		like cloning.

	      o	format	2  -  Use the second rbd format, which is supported by
		librbd and kernel since	version	3.11  (except  for  striping).
		This adds support for cloning and is more easily extensible to
		allow more features in the future.

       -s size-in-M/G/T, --size	size-in-M/G/T
	      Specifies	the size of the	new rbd	image or the new size  of  the
	      existing	rbd  image in M/G/T.  If no suffix is given, unit M is

       --object-size size-in-B/K/M
	      Specifies	the object size	in B/K/M.  Object size will be rounded
	      up  the  nearest	power of two; if no suffix is given, unit B is
	      assumed.	The default object size	is 4M, smallest	is 4K and max-
	      imum is 32M.

       --stripe-unit size-in-B/K/M
	      Specifies	the stripe unit	size in	B/K/M.	If no suffix is	given,
	      unit B is	assumed.  See striping section (below)	for  more  de-

       --stripe-count num
	      Specifies	 the  number  of objects to stripe over	before looping
	      back to the first	object.	 See striping section (below) for more

       --snap snap
	      Specifies	the snapshot name for the specific operation.

       --id username
	      Specifies	 the username (without the client. prefix) to use with
	      the map command.

       --keyring filename
	      Specifies	a keyring file containing a secret for	the  specified
	      user to use with the map command.	 If not	specified, the default
	      keyring locations	will be	searched.

       --keyfile filename
	      Specifies	a file containing the secret key of --id user  to  use
	      with the map command.  This option is overridden by --keyring if
	      the latter is also specified.

       --shared	lock-tag
	      Option for lock add that allows multiple	clients	 to  lock  the
	      same  image  if  they  use the same tag. The tag is an arbitrary
	      string. This is useful for situations where  an  image  must  be
	      open  from more than one client at once, like during live	migra-
	      tion of a	virtual	machine, or for	 use  underneath  a  clustered

       --format	format
	      Specifies	output formatting (default: plain, json, xml)

	      Make json	or xml formatted output	more human-readable.

       -o krbd-options,	--options krbd-options
	      Specifies	 which options to use when mapping or unmapping	an im-
	      age via the rbd kernel driver.  krbd-options  is	a  comma-sepa-
	      rated  list of options (similar to mount(8) mount	options).  See
	      kernel rbd (krbd)	options	section	below for more details.

	      Map the image read-only.	Equivalent to -o ro.

       --image-feature feature-name
	      Specifies	which RBD format 2 feature should be enabled when cre-
	      ating  an	 image.	 Multiple features can be enabled by repeating
	      this option multiple times.  The	following  features  are  sup-

	      o	layering: layering support

	      o	striping: striping v2 support

	      o	exclusive-lock:	exclusive locking support

	      o	object-map: object map support (requires exclusive-lock)

	      o	fast-diff: fast	diff calculations (requires object-map)

	      o	deep-flatten: snapshot flatten support

	      o	journaling: journaled IO support (requires exclusive-lock)

	      o	data-pool: erasure coded pool support

	      Specifies	 that  the image will be used concurrently by multiple
	      clients.	This will disable features that	are dependent upon ex-
	      clusive ownership	of the image.

	      Specifies	 that  the  diff should	be limited to the extents of a
	      full object instead of showing intra-object deltas. When the ob-
	      ject  map	 feature  is enabled on	an image, limiting the diff to
	      the object extents will dramatically improve  performance	 since
	      the  differences	can be computed	by examining the in-memory ob-
	      ject map instead of querying RADOS for each  object  within  the

	      Specifies	the limit for the number of snapshots permitted.

       bench   --io-type   <read   |   write  |	 readwrite  |  rw>  [--io-size
       size-in-B/K/M/G/T]   [--io-threads    num-ios-in-flight]	   [--io-total
       size-in-B/K/M/G/T]  [--io-pattern  seq |	rand] [--rw-mix-read read pro-
       portion in readwrite] image-spec
	      Generate a series	of  IOs	 to  the  image	 and  measure  the  IO
	      throughput  and  latency.	  If no	suffix is given, unit B	is as-
	      sumed  for  both	--io-size  and	--io-total.    Defaults	  are:
	      --io-size	 4096,	--io-threads  16,  --io-total 1G, --io-pattern
	      seq, --rw-mix-read 50.

       children	snap-spec
	      List the clones of the image at the given	snapshot. This	checks
	      every pool, and outputs the resulting poolname/imagename.

	      This requires image format 2.

       clone   [--object-size	size-in-B/K/M]	 [--stripe-unit	 size-in-B/K/M
       --stripe-count  num]  [--image-feature  feature-name]  [--image-shared]
       parent-snap-spec	child-image-spec
	      Will  create  a  clone (copy-on-write child) of the parent snap-
	      shot.  Object size will be identical to that of the parent image
	      unless  specified. Size will be the same as the parent snapshot.
	      The --stripe-unit	and --stripe-count arguments are optional, but
	      must be used together.

	      The  parent  snapshot  must be protected (see rbd	snap protect).
	      This requires image format 2.

       config global get config-entity key
	      Get a global-level configuration override.

       config global list [--format plain | json | xml]	[--pretty-format] con-
	      List global-level	configuration overrides.

       config global set config-entity key value
	      Set a global-level configuration override.

       config global remove config-entity key
	      Remove a global-level configuration override.

       config image get	image-spec key
	      Get an image-level configuration override.

       config  image  list [--format plain | json | xml] [--pretty-format] im-
	      List image-level configuration overrides.

       config image set	image-spec key value
	      Set an image-level configuration override.

       config image remove image-spec key
	      Remove an	image-level configuration override.

       config pool get pool-name key
	      Get a pool-level configuration override.

       config pool list	 [--format  plain  |  json  |  xml]  [--pretty-format]
	      List pool-level configuration overrides.

       config pool set pool-name key value
	      Set a pool-level configuration override.

       config pool remove pool-name key
	      Remove a pool-level configuration	override.

       cp (src-image-spec | src-snap-spec) dest-image-spec
	      Copy  the	content	of a src-image into the	newly created dest-im-
	      age.  dest-image will have the same size,	object size, and image
	      format as	src-image.

       create  (-s  |  --size size-in-M/G/T) [--image-format format-id]	[--ob-
       ject-size size-in-B/K/M]	 [--stripe-unit	 size-in-B/K/M	--stripe-count
       num]    [--thick-provision]   [--no-progress]   [--image-feature	  fea-
       ture-name]... [--image-shared] image-spec
	      Will create a new	rbd image. You must also specify the size  via
	      --size.	The --stripe-unit and --stripe-count arguments are op-
	      tional, but must be used together.  If the --thick-provision  is
	      enabled,	it  will  fully	allocate storage for the image at cre-
	      ation time. It will take a long time to do.  Note: thick	provi-
	      sioning requires zeroing the contents of the entire image.

       deep cp (src-image-spec | src-snap-spec)	dest-image-spec
	      Deep  copy  the  content	of  a src-image	into the newly created
	      dest-image.  Dest-image will have	the same  size,	 object	 size,
	      image format, and	snapshots as src-image.

       device  list  [-t | --device-type device-type] [--format	plain |	json |
       xml] --pretty-format
	      Show the rbd images that are mapped via the  rbd	kernel	module
	      (default)	or other supported device.

       device map [-t |	--device-type device-type] [--read-only] [--exclusive]
       [-o | --options device-options] image-spec | snap-spec
	      Map the specified	image to a block device	 via  the  rbd	kernel
	      module  (default)	 or  other  supported  device (nbd on Linux or
	      ggate on FreeBSD).

	      The --options argument is	a comma	separated list of device  type
	      specific options (opt1,opt2=val,...).

       device  unmap  [-t  |  --device-type  device-type]  [-o | --options de-
       vice-options] image-spec	| snap-spec | device-path
	      Unmap the	block device that was mapped via the rbd kernel	module
	      (default)	or other supported device.

	      The  --options argument is a comma separated list	of device type
	      specific options (opt1,opt2=val,...).

       diff [--from-snap snap-name] [--whole-object] image-spec	| snap-spec
	      Dump a list of byte extents in the image that have changed since
	      the  specified  start  snapshot, or since	the image was created.
	      Each output line includes	the starting offset  (in  bytes),  the
	      length  of the region (in	bytes),	and either 'zero' or 'data' to
	      indicate whether the region is known to be zeros or may  contain
	      other data.

       du [-p |	--pool pool-name] [image-spec |	snap-spec]
	      Will  calculate the provisioned and actual disk usage of all im-
	      ages and associated snapshots within the specified pool.	It can
	      also be used against individual images and snapshots.

	      If  the RBD fast-diff feature is not enabled on images, this op-
	      eration will require querying the	OSDs for every	potential  ob-
	      ject within the image.

       export  [--export-format	 format	 (1  or	 2)]  (image-spec | snap-spec)
	      Export image to dest path	(use - for stdout).  The --export-for-
	      mat  accepts  '1'	 or '2'	currently. Format 2 allow us to	export
	      not only the content of image, but also the snapshots and	 other
	      properties, such as image_order, features.

       export-diff  [--from-snap  snap-name]  [--whole-object]	(image-spec  |
       snap-spec) dest-path
	      Export an	incremental diff for an	image to dest path (use	-  for
	      stdout).	 If  an	 initial  snapshot  is specified, only changes
	      since that snapshot are included;	otherwise, any regions of  the
	      image that contain data are included.  The end snapshot is spec-
	      ified using the standard --snap option or	@snap syntax (see  be-
	      low).   The image	diff format includes metadata about image size
	      changes, and the start and end snapshots.	 It efficiently	repre-
	      sents discarded or 'zero'	regions	of the image.

       feature disable image-spec feature-name...
	      Disable  the  specified feature on the specified image. Multiple
	      features can be specified.

       feature enable image-spec feature-name...
	      Enable the specified feature on the  specified  image.  Multiple
	      features can be specified.

       flatten image-spec
	      If  image	 is  a	clone,	copy all shared	blocks from the	parent
	      snapshot and make	the child independent of the parent,  severing
	      the link between parent snap and child.  The parent snapshot can
	      be unprotected and  deleted  if  it  has	no  further  dependent

	      This requires image format 2.

       group create group-spec
	      Create a group.

       group image add group-spec image-spec
	      Add an image to a	group.

       group image list	group-spec
	      List images in a group.

       group image remove group-spec image-spec
	      Remove an	image from a group.

       group ls	[-p | --pool pool-name]
	      List rbd groups.

       group rename src-group-spec dest-group-spec
	      Rename a group.  Note: rename across pools is not	supported.

       group rm	group-spec
	      Delete a group.

       group snap create group-snap-spec
	      Make a snapshot of a group.

       group snap list group-spec
	      List snapshots of	a group.

       group snap rm group-snap-spec
	      Remove a snapshot	from a group.

       group snap rename group-snap-spec snap-name
	      Rename group's snapshot.

       group snap rollback group-snap-spec
	      Rollback group to	snapshot.

       image-meta get image-spec key
	      Get metadata value with the key.

       image-meta list image-spec
	      Show metadata held on the	image. The first column	is the key and
	      the second column	is the value.

       image-meta remove image-spec key
	      Remove metadata key with the value.

       image-meta set image-spec key value
	      Set metadata key with the	value.	They  will  displayed  in  im-
	      age-meta list.

       import  [--export-format	 format	 (1  or	2)] [--image-format format-id]
       [--object-size	  size-in-B/K/M]     [--stripe-unit	 size-in-B/K/M
       --stripe-count  num] [--image-feature feature-name]... [--image-shared]
       src-path	[image-spec]
	      Create a new image and imports its data from  path  (use	-  for
	      stdin).	The import operation will try to create	sparse rbd im-
	      ages if possible.	 For import  from  stdin,  the	sparsification
	      unit  is	the  data  block size of the destination image (object

	      The --stripe-unit	and --stripe-count arguments are optional, but
	      must be used together.

	      The --export-format accepts '1' or '2' currently.	Format 2 allow
	      us to import not only the	content	of image, but also  the	 snap-
	      shots and	other properties, such as image_order, features.

       import-diff src-path image-spec
	      Import  an  incremental  diff  of	an image and applies it	to the
	      current image.  If the diff was generated	relative  to  a	 start
	      snapshot,	we verify that snapshot	already	exists before continu-
	      ing.  If there was an end	snapshot we verify it does not already
	      exist  before applying the changes, and create the snapshot when
	      we are done.

       info image-spec | snap-spec
	      Will dump	information (such as size and  object  size)  about  a
	      specific	rbd image.  If image is	a clone, information about its
	      parent is	also displayed.	 If a snapshot is  specified,  whether
	      it is protected is shown as well.

       journal client disconnect journal-spec
	      Flag image journal client	as disconnected.

       journal export [--verbose] [--no-error] src-journal-spec	path-name
	      Export  image journal to path (use - for stdout).	It can be make
	      a	backup of the image journal especially before attempting  dan-
	      gerous operations.

	      Note  that  this	command	 may not always	work if	the journal is
	      badly corrupted.

       journal import [--verbose] [--no-error] path-name dest-journal-spec
	      Import image journal from	path (use - for	stdin).

       journal info journal-spec
	      Show information about image journal.

       journal inspect [--verbose] journal-spec
	      Inspect and report image journal for structural errors.

       journal reset journal-spec
	      Reset image journal.

       journal status journal-spec
	      Show status of image journal.

       lock add	[--shared lock-tag] image-spec lock-id
	      Lock an image. The lock-id is an arbitrary name for  the	user's
	      convenience.  By	default, this is an exclusive lock, meaning it
	      will fail	if the image is	already	locked.	 The  --shared	option
	      changes this behavior. Note that locking does not	affect any op-
	      eration other than adding	a lock.	It does	not protect  an	 image
	      from being deleted.

       lock ls image-spec
	      Show  locks held on the image. The first column is the locker to
	      use with the lock	remove command.

       lock rm image-spec lock-id locker
	      Release a	lock on	an image. The lock id and locker are as	output
	      by lock ls.

       ls [-l |	--long]	[pool-name]
	      Will  list  all  rbd  images listed in the rbd_directory object.
	      With -l, also show snapshots, and	use longer-format  output  in-
	      cluding size, parent (if clone), format, etc.

       merge-diff first-diff-path second-diff-path merged-diff-path
	      Merge two	continuous incremental diffs of	an image into one sin-
	      gle diff.	The first diff's end snapshot must be equal  with  the
	      second  diff's  start  snapshot.	 The first diff	could be - for
	      stdin, and merged	diff could be -	for stdout, which enables mul-
	      tiple  diff  files  to  be  merged  using	 something  like  'rbd
	      merge-diff first second -	| rbd merge-diff - third result'. Note
	      this  command currently only support the source incremental diff
	      with stripe_count	== 1

       migration abort image-spec
	      Cancel image migration. This step	may be run after successful or
	      failed  migration	prepare	or migration execute steps and returns
	      the image	to its initial (before migration) state. All modifica-
	      tions to the destination image are lost.

       migration commit	image-spec
	      Commit  image migration. This step is run	after a	successful mi-
	      gration prepare and migration  execute  steps  and  removes  the
	      source image data.

       migration execute image-spec
	      Execute image migration. This step is run	after a	successful mi-
	      gration prepare step and copies image data to the	destination.

       migration prepare [--order order]  [--object-size  object-size]	[--im-
       age-feature image-feature] [--image-shared] [--stripe-unit stripe-unit]
       [--stripe-count stripe-count]  [--data-pool  data-pool]	src-image-spec
	      Prepare  image  migration. This is the first step	when migrating
	      an image,	i.e. changing the image	location, format or other  pa-
	      rameters	that can't be changed dynamically. The destination can
	      match the	source,	and in this case dest-image-spec can be	 omit-
	      ted.  After this step the	source image is	set as a parent	of the
	      destination image, and the image is accessible in	 copy-on-write
	      mode by its destination spec.

       mirror image demote image-spec
	      Demote a primary image to	non-primary for	RBD mirroring.

       mirror image disable [--force] image-spec
	      Disable  RBD mirroring for an image. If the mirroring is config-
	      ured in image mode for the image's pool, then it can be  explic-
	      itly disabled mirroring for each image within the	pool.

       mirror image enable image-spec
	      Enable  RBD  mirroring for an image. If the mirroring is config-
	      ured in image mode for the image's pool, then it can be  explic-
	      itly enabled mirroring for each image within the pool.

	      This requires the	RBD journaling feature is enabled.

       mirror image promote [--force] image-spec
	      Promote a	non-primary image to primary for RBD mirroring.

       mirror image resync image-spec
	      Force resync to primary image for	RBD mirroring.

       mirror image status image-spec
	      Show RBD mirroring status	for an image.

       mirror pool demote [pool-name]
	      Demote  all  primary images within a pool	to non-primary.	 Every
	      mirroring	enabled	image will demoted in the pool.

       mirror pool disable [pool-name]
	      Disable RBD mirroring by default within a	pool.  When  mirroring
	      is  disabled  on a pool in this way, mirroring will also be dis-
	      abled on any images (within the pool) for	 which	mirroring  was
	      enabled explicitly.

       mirror pool enable [pool-name] mode
	      Enable  RBD  mirroring  by default within	a pool.	 The mirroring
	      mode can either be pool or image.	 If configured in  pool	 mode,
	      all  images  in the pool with the	journaling feature enabled are
	      mirrored.	 If configured in image	mode, mirroring	 needs	to  be
	      explicitly  enabled (by mirror image enable command) on each im-

       mirror pool info	[pool-name]
	      Show information about the pool mirroring	configuration.	It in-
	      cludes  mirroring	 mode, peer UUID, remote cluster name, and re-
	      mote client name.

       mirror pool peer	add [pool-name]	remote-cluster-spec
	      Add a mirroring peer to a	pool.  remote-cluster-spec is  [remote
	      client name@]remote cluster name.

	      The default for remote client name is "client.admin".

	      This requires mirroring mode is enabled.

       mirror pool peer	remove [pool-name] uuid
	      Remove  a	mirroring peer from a pool. The	peer uuid is available
	      from mirror pool info command.

       mirror pool peer	set [pool-name]	uuid key value
	      Update mirroring peer settings.  The key can be either client or
	      cluster, and the value is	corresponding to remote	client name or
	      remote cluster name.

       mirror pool promote [--force] [pool-name]
	      Promote all non-primary images within a pool to primary.	 Every
	      mirroring	enabled	image will promoted in the pool.

       mirror pool status [--verbose] [pool-name]
	      Show  status  for	 all mirrored images in	the pool.  With	--ver-
	      bose, also show additionally output  status  details  for	 every
	      mirroring	image in the pool.

       mv src-image-spec dest-image-spec
	      Rename an	image.	Note: rename across pools is not supported.

       namespace create	pool-name/namespace-name
	      Create a new image namespace within the pool.

       namespace list pool-name
	      List image namespaces defined within the pool.

       namespace remove	pool-name/namespace-name
	      Remove an	empty image namespace from the pool.

       object-map check	image-spec | snap-spec
	      Verify the object	map is correct.

       object-map rebuild image-spec | snap-spec
	      Rebuild  an invalid object map for the specified image. An image
	      snapshot can be specified	to rebuild an invalid object map for a

       pool init [pool-name] [--force]
	      Initialize  pool	for  use by RBD. Newly created pools must ini-
	      tialized prior to	use.

       resize (-s | --size size-in-M/G/T) [--allow-shrink] image-spec
	      Resize rbd image.	The size parameter also	needs to be specified.
	      The --allow-shrink option	lets the size be reduced.

       rm image-spec
	      Delete  an  rbd  image (including	all data blocks). If the image
	      has snapshots, this fails	and nothing is deleted.

       snap create snap-spec
	      Create a new snapshot.  Requires	the  snapshot  name  parameter

       snap limit clear	image-spec
	      Remove  any  previously set limit	on the number of snapshots al-
	      lowed on an image.

       snap limit set [--limit]	limit image-spec
	      Set a limit for the number of snapshots allowed on an image.

       snap ls image-spec
	      Dump the list of snapshots inside	a specific image.

       snap protect snap-spec
	      Protect a	snapshot from deletion,	so that	clones can be made  of
	      it  (see	rbd clone).  Snapshots must be protected before	clones
	      are made;	protection implies that	there exist  dependent	cloned
	      children	that refer to this snapshot.  rbd clone	will fail on a
	      nonprotected snapshot.

	      This requires image format 2.

       snap purge image-spec
	      Remove all unprotected snapshots from an image.

       snap rename src-snap-spec dest-snap-spec
	      Rename a snapshot. Note: rename across pools and images  is  not

       snap rm [--force] snap-spec
	      Remove the specified snapshot.

       snap rollback snap-spec
	      Rollback	image  content	to snapshot. This will iterate through
	      the entire blocks	array and update the data head content to  the
	      snapshotted version.

       snap unprotect snap-spec
	      Unprotect	 a  snapshot  from  deletion  (undo snap protect).  If
	      cloned children remain, snap unprotect fails.  (Note that	clones
	      may exist	in different pools than	the parent snapshot.)

	      This requires image format 2.

       sparsify	[--sparse-size sparse-size] image-spec
	      Reclaim  space for zeroed	image extents. The default sparse size
	      is 4096 bytes and	can be changed via --sparse-size  option  with
	      the  following restrictions: it should be	power of two, not less
	      than 4096, and not larger	image object size.

       status image-spec
	      Show the status of the image, including which  clients  have  it

       trash ls	[pool-name]
	      List all entries from trash.

       trash mv	image-spec
	      Move an image to the trash. Images, even ones actively in-use by
	      clones, can be moved to the trash	and deleted at a later time.

       trash purge [pool-name]
	      Remove all expired images	from trash.

       trash restore image-id
	      Restore an image from trash.

       trash rm	image-id
	      Delete an	image from trash. If image deferment time has not  ex-
	      pired  you  can not removed it unless use	force. But an actively
	      in-use by	clones or has snapshots	can not	be removed.

       watch image-spec
	      Watch events on image.

       image-spec      is [pool-name/[namespace-name/]]image-name
       snap-spec       is [pool-name/[namespace-name/]]image-name@snap-name
       group-spec      is [pool-name/[namespace-name/]]group-name
       group-snap-spec is [pool-name/[namespace-name/]]group-name@snap-name
       journal-spec    is [pool-name/[namespace-name/]]journal-name

       The default for pool-name is "rbd" and namespace-name is	"". If an  im-
       age name	contains a slash character ('/'), pool-name is required.

       The journal-name	is image-id.

       You  may	 specify  each	name  individually, using --pool, --namespace,
       --image,	and --snap options, but	this is	discouraged in	favor  of  the
       above spec syntax.

       RBD  images are striped over many objects, which	are then stored	by the
       Ceph distributed	object store (RADOS).  As a result, read and write re-
       quests  for the image are distributed across many nodes in the cluster,
       generally preventing any	single node from becoming  a  bottleneck  when
       individual images get large or busy.

       The striping is controlled by three parameters:

	      The size of objects we stripe over is a power of two. It will be
	      rounded up the nearest power of two.  The	default	object size is
	      4	MB, smallest is	4K and maximum is 32M.

	      Each [stripe_unit] contiguous bytes are stored adjacently	in the
	      same object, before we move on to	the next object.

	      After we write [stripe_unit] bytes to [stripe_count] objects, we
	      loop  back to the	initial	object and write another stripe, until
	      the object reaches its maximum size.  At that point, we move  on
	      to the next [stripe_count] objects.

       By   default,  [stripe_unit]  is	 the  same  as	the  object  size  and
       [stripe_count] is 1.  Specifying	 a  different  [stripe_unit]  requires
       that the	STRIPINGV2 feature be supported	(added in Ceph v0.53) and for-
       mat 2 images be used.

       Most of these options are useful	mainly for debugging and benchmarking.
       The  default  values  are set in	the kernel and may therefore depend on
       the version of the running kernel.

       Per client instance rbd device map options:

       o fsid=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee - FSID that should  be  as-
	 sumed by the client.

       o ip=a.b.c.d[:p]	- IP and, optionally, port the client should use.

       o share	-  Enable sharing of client instances with other mappings (de-

       o noshare - Disable sharing of client instances with other mappings.

       o crc - Enable CRC32C checksumming for data writes (default).

       o nocrc - Disable CRC32C	checksumming for data writes.

       o cephx_require_signatures - Require cephx message signing (since 3.19,

       o nocephx_require_signatures  -	Don't  require	cephx  message signing
	 (since	3.19).

       o tcp_nodelay - Disable Nagle's algorithm on client sockets (since 4.0,

       o notcp_nodelay	-  Enable  Nagle's  algorithm on client	sockets	(since

       o cephx_sign_messages - Enable message signing (since 4.4, default).

       o nocephx_sign_messages - Disable message signing (since	4.4).

       o mount_timeout=x - A timeout on	various	steps in rbd  device  map  and
	 rbd  device  unmap sequences (default is 60 seconds).	In particular,
	 since 4.2 this	can be used to ensure that rbd device unmap eventually
	 times out when	there is no network connection to a cluster.

       o osdkeepalive=x	- OSD keepalive	timeout	(default is 5 seconds).

       o osd_idle_ttl=x	- OSD idle TTL (default	is 60 seconds).

       Per mapping (block device) rbd device map options:

       o rw - Map the image read-write (default).

       o ro - Map the image read-only.	Equivalent to --read-only.

       o queue_depth=x - queue depth (since 4.2, default is 128	requests).

       o lock_on_read -	Acquire	exclusive lock on reads, in addition to	writes
	 and discards (since 4.9).

       o exclusive -  Disable  automatic  exclusive  lock  transitions	(since

       o lock_timeout=x	 -  A timeout on waiting for the acquisition of	exclu-
	 sive lock (since 4.17,	default	is 0 seconds, meaning no timeout).

       o notrim	- Turn off discard and write zeroes offload support  to	 avoid
	 deprovisioning	 a fully provisioned image (since 4.17). When enabled,
	 discard requests will fail with -EOPNOTSUPP,  write  zeroes  requests
	 will fall back	to manually zeroing.

       o abort_on_full	- Fail write requests with -ENOSPC when	the cluster is
	 full or the data pool reaches its quota (since	5.0).  The default be-
	 haviour is to block until the full condition is cleared.

       o alloc_size  -	Minimum	 allocation  unit of the underlying OSD	object
	 store backend (since 5.1, default is 64K bytes).   This  is  used  to
	 round	off  and drop discards that are	too small.  For	bluestore, the
	 recommended setting is	bluestore_min_alloc_size  (typically  64K  for
	 hard disk drives and 16K for solid-state drives).  For	filestore with
	 filestore_punch_hole =	false, the recommended setting is image	object
	 size (typically 4M).

       rbd device unmap	options:

       o force	-  Force  the  unmapping of a block device that	is open	(since
	 4.9).	The driver will	wait for running requests to complete and then
	 unmap;	requests sent to the driver after initiating the unmap will be

       To create a new rbd image that is 100 GB:

	  rbd create mypool/myimage --size 102400

       To use a	non-default object size	(8 MB):

	  rbd create mypool/myimage --size 102400 --object-size	8M

       To delete an rbd	image (be careful!):

	  rbd rm mypool/myimage

       To create a new snapshot:

	  rbd snap create mypool/myimage@mysnap

       To create a copy-on-write clone of a protected snapshot:

	  rbd clone mypool/myimage@mysnap otherpool/cloneimage

       To see which clones of a	snapshot exist:

	  rbd children mypool/myimage@mysnap

       To delete a snapshot:

	  rbd snap rm mypool/myimage@mysnap

       To map an image via the kernel with cephx enabled:

	  rbd device map mypool/myimage	--id admin --keyfile secretfile

       To map an image via the kernel with different cluster name  other  than
       default ceph:

	  rbd device map mypool/myimage	--cluster cluster-name

       To unmap	an image:

	  rbd device unmap /dev/rbd0

       To create an image and a	clone from it:

	  rbd import --image-format 2 image mypool/parent
	  rbd snap create mypool/parent@snap
	  rbd snap protect mypool/parent@snap
	  rbd clone mypool/parent@snap otherpool/child

       To  create  an  image  with a smaller stripe_unit (to better distribute
       small writes in some workloads):

	  rbd create mypool/myimage --size 102400 --stripe-unit	65536B --stripe-count 16

       To change an image from one image format	to another, export it and then
       import it as the	desired	image format:

	  rbd export mypool/myimage@snap /tmp/img
	  rbd import --image-format 2 /tmp/img mypool/myimage2

       To lock an image	for exclusive use:

	  rbd lock add mypool/myimage mylockid

       To release a lock:

	  rbd lock remove mypool/myimage mylockid client.2485

       To list images from trash:

	  rbd trash ls mypool

       To  defer delete	an image (use --expires-at to set expiration time, de-
       fault is	now):

	  rbd trash mv mypool/myimage --expires-at "tomorrow"

       To delete an image from trash (be careful!):

	  rbd trash rm mypool/myimage-id

       To force	delete an image	from trash (be careful!):

	  rbd trash rm mypool/myimage-id  --force

       To restore an image from	trash:

	  rbd trash restore mypool/myimage-id

       To restore an image from	trash and rename it:

	  rbd trash restore mypool/myimage-id --image mynewimage

       rbd is part of Ceph, a  massively  scalable,  open-source,  distributed
       storage	 system.   Please   refer   to	 the   Ceph  documentation  at for	more information.

       ceph(8),	rados(8)

       2010-2014, Inktank Storage, Inc.	and contributors. Licensed under  Cre-
       ative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)

dev				 Aug 28, 2020				RBD(8)


Want to link to this manual page? Use this URL:

home | help