ceph/doc/rbd/rados-rbd-cmds.rst

   1 =======================
   2  Block Device Commands
   3 =======================
   4
   5 .. index:: Ceph Block Device; image management
   6
   7 The ``rbd`` command enables you to create, list, introspect and remove block
   8 device images. You can also use it to clone images, create snapshots,
   9 rollback an image to a snapshot, view a snapshot, etc. For details on using
  10 the ``rbd`` command, see `RBD – Manage RADOS Block Device (RBD) Images`_ for
  11 details.
  12
  13 .. important:: To use Ceph Block Device commands, you must have access to
  14    a running Ceph cluster.
  15
  16
  17 Creating a Block Device Image
  18 =============================
  19
  20 Before you can add a block device to a node, you must create an image for it in
  21 the :term:`Ceph Storage Cluster` first. To create a block device image, execute
  22 the  following::
  23
  24         rbd create --size {megabytes} {pool-name}/{image-name}
  25
  26 For example, to create a 1GB image named ``bar`` that stores information in a
  27 pool named ``swimmingpool``, execute the following::
  28
  29         rbd create --size 1024 swimmingpool/bar
  30
  31 If you don't specify pool when creating an image, it will be stored in the
  32 default pool ``rbd``. For example, to create a 1GB image named ``foo`` stored in
  33 the default pool ``rbd``, execute the following::
  34
  35         rbd create --size 1024 foo
  36
  37 .. note:: You must create a pool first before you can specify it as a
  38    source. See `Storage Pools`_ for details.
  39
  40 Listing Block Device Images
  41 ===========================
  42
  43 To list block devices in the ``rbd`` pool, execute the following
  44 (i.e., ``rbd`` is the default pool name)::
  45
  46         rbd ls
  47
  48 To list block devices in a particular pool, execute the following,
  49 but replace ``{poolname}`` with the name of the pool::
  50
  51         rbd ls {poolname}
  52
  53 For example::
  54
  55         rbd ls swimmingpool
  56
  57 Retrieving Image Information
  58 ============================
  59
  60 To retrieve information from a particular image, execute the following,
  61 but replace ``{image-name}`` with the name for the image::
  62
  63         rbd info {image-name}
  64
  65 For example::
  66
  67         rbd info foo
  68
  69 To retrieve information from an image within a pool, execute the following,
  70 but replace ``{image-name}`` with the name of the image and replace ``{pool-name}``
  71 with the name of the pool::
  72
  73         rbd info {pool-name}/{image-name}
  74
  75 For example::
  76
  77         rbd info swimmingpool/bar
  78
  79 Resizing a Block Device Image
  80 =============================
  81
  82 :term:`Ceph Block Device` images are thin provisioned. They don't actually use
  83 any physical storage  until you begin saving data to them. However, they do have
  84 a maximum capacity  that you set with the ``--size`` option. If you want to
  85 increase (or decrease) the maximum size of a Ceph Block Device image, execute
  86 the following::
  87
  88         rbd resize --size 2048 foo (to increase)
  89         rbd resize --size 2048 foo --allow-shrink (to decrease)
  90
  91
  92 Removing a Block Device Image
  93 =============================
  94
  95 To remove a block device, execute the following, but replace ``{image-name}``
  96 with the name of the image you want to remove::
  97
  98         rbd rm {image-name}
  99
 100 For example::
 101
 102         rbd rm foo
 103
 104 To remove a block device from a pool, execute the following, but replace
 105 ``{image-name}`` with the name of the image to remove and replace
 106 ``{pool-name}`` with the name of the pool::
 107
 108         rbd rm {pool-name}/{image-name}
 109
 110 For example::
 111
 112         rbd rm swimmingpool/bar
 113
 114
 115
 116 .. _Storage Pools: ../../rados/operations/pools
 117 .. _RBD – Manage RADOS Block Device (RBD) Images: ../../man/8/rbd/