src/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 Create a Block Device Pool
  17 ==========================
  18
  19 #. On the admin node, use the ``ceph`` tool to `create a pool`_.
  20
  21 #. On the admin node, use the ``rbd`` tool to initialize the pool for use by RBD::
  22
  23         rbd pool init <pool-name>
  24
  25 .. note:: The ``rbd`` tool assumes a default pool name of 'rbd' when not
  26    provided.
  27
  28 Create a Block Device User
  29 ==========================
  30
  31 Unless specified, the ``rbd`` command will access the Ceph cluster using the ID
  32 ``admin``. This ID allows full administrative access to the cluster. It is
  33 recommended that you utilize a more restricted user wherever possible.
  34
  35 To `create a Ceph user`_, with ``ceph`` specify the ``auth get-or-create``
  36 command, user name, monitor caps, and OSD caps::
  37
  38         ceph auth get-or-create client.{ID} mon 'profile rbd' osd 'profile {profile name} [pool={pool-name}][, profile ...]'
  39
  40 For example, to create a user ID named ``qemu`` with read-write access to the
  41 pool ``vms`` and read-only access to the pool ``images``, execute the
  42 following::
  43
  44         ceph auth get-or-create client.qemu mon 'profile rbd' osd 'profile rbd pool=vms, profile rbd-read-only pool=images'
  45
  46 The output from the ``ceph auth get-or-create`` command will be the keyring for
  47 the specified user, which can be written to ``/etc/ceph/ceph.client.{ID}.keyring``.
  48
  49 .. note:: The user ID can be specified when using the ``rbd`` command by
  50         providing the ``--id {id}`` optional argument.
  51
  52 Creating a Block Device Image
  53 =============================
  54
  55 Before you can add a block device to a node, you must create an image for it in
  56 the :term:`Ceph Storage Cluster` first. To create a block device image, execute
  57 the  following::
  58
  59         rbd create --size {megabytes} {pool-name}/{image-name}
  60
  61 For example, to create a 1GB image named ``bar`` that stores information in a
  62 pool named ``swimmingpool``, execute the following::
  63
  64         rbd create --size 1024 swimmingpool/bar
  65
  66 If you don't specify pool when creating an image, it will be stored in the
  67 default pool ``rbd``. For example, to create a 1GB image named ``foo`` stored in
  68 the default pool ``rbd``, execute the following::
  69
  70         rbd create --size 1024 foo
  71
  72 .. note:: You must create a pool first before you can specify it as a
  73    source. See `Storage Pools`_ for details.
  74
  75 Listing Block Device Images
  76 ===========================
  77
  78 To list block devices in the ``rbd`` pool, execute the following
  79 (i.e., ``rbd`` is the default pool name)::
  80
  81         rbd ls
  82
  83 To list block devices in a particular pool, execute the following,
  84 but replace ``{poolname}`` with the name of the pool::
  85
  86         rbd ls {poolname}
  87
  88 For example::
  89
  90         rbd ls swimmingpool
  91
  92 To list deferred delete block devices in the ``rbd`` pool, execute the
  93 following::
  94
  95         rbd trash ls
  96
  97 To list deferred delete block devices in a particular pool, execute the
  98 following, but replace ``{poolname}`` with the name of the pool::
  99
 100         rbd trash ls {poolname}
 101
 102 For example::
 103
 104         rbd trash ls swimmingpool
 105
 106 Retrieving Image Information
 107 ============================
 108
 109 To retrieve information from a particular image, execute the following,
 110 but replace ``{image-name}`` with the name for the image::
 111
 112         rbd info {image-name}
 113
 114 For example::
 115
 116         rbd info foo
 117
 118 To retrieve information from an image within a pool, execute the following,
 119 but replace ``{image-name}`` with the name of the image and replace ``{pool-name}``
 120 with the name of the pool::
 121
 122         rbd info {pool-name}/{image-name}
 123
 124 For example::
 125
 126         rbd info swimmingpool/bar
 127
 128 Resizing a Block Device Image
 129 =============================
 130
 131 :term:`Ceph Block Device` images are thin provisioned. They don't actually use
 132 any physical storage  until you begin saving data to them. However, they do have
 133 a maximum capacity  that you set with the ``--size`` option. If you want to
 134 increase (or decrease) the maximum size of a Ceph Block Device image, execute
 135 the following::
 136
 137         rbd resize --size 2048 foo (to increase)
 138         rbd resize --size 2048 foo --allow-shrink (to decrease)
 139
 140
 141 Removing a Block Device Image
 142 =============================
 143
 144 To remove a block device, execute the following, but replace ``{image-name}``
 145 with the name of the image you want to remove::
 146
 147         rbd rm {image-name}
 148
 149 For example::
 150
 151         rbd rm foo
 152
 153 To remove a block device from a pool, execute the following, but replace
 154 ``{image-name}`` with the name of the image to remove and replace
 155 ``{pool-name}`` with the name of the pool::
 156
 157         rbd rm {pool-name}/{image-name}
 158
 159 For example::
 160
 161         rbd rm swimmingpool/bar
 162
 163 To defer delete a block device from a pool, execute the following, but
 164 replace ``{image-name}`` with the name of the image to move and replace
 165 ``{pool-name}`` with the name of the pool::
 166
 167         rbd trash mv {pool-name}/{image-name}
 168
 169 For example::
 170
 171         rbd trash mv swimmingpool/bar
 172
 173 To remove a deferred block device from a pool, execute the following, but
 174 replace ``{image-id}`` with the id of the image to remove and replace
 175 ``{pool-name}`` with the name of the pool::
 176
 177         rbd trash rm {pool-name}/{image-id}
 178
 179 For example::
 180
 181         rbd trash rm swimmingpool/2bf4474b0dc51
 182
 183 .. note::
 184
 185   * You can move an image to the trash even it has shapshot(s) or actively
 186     in-use by clones, but can not be removed from trash.
 187
 188   * You can use *--delay* to set the defer time (default is 0), and if its
 189     deferment time has not expired, it can not be removed unless you use
 190     force.
 191
 192 Restoring a Block Device Image
 193 ==============================
 194
 195 To restore a deferred delete block device in the rbd pool, execute the
 196 following, but replace ``{image-id}`` with the id of the image::
 197
 198         rbd trash restore {image-d}
 199
 200 For example::
 201
 202         rbd trash restore 2bf4474b0dc51
 203
 204 To restore a deferred delete block device in a particular pool, execute
 205 the following, but replace ``{image-id}`` with the id of the image and
 206 replace ``{pool-name}`` with the name of the pool::
 207
 208         rbd trash restore {pool-name}/{image-id}
 209
 210 For example::
 211
 212         rbd trash restore swimmingpool/2bf4474b0dc51
 213
 214 Also you can use *--image* to rename the iamge when restore it, for
 215 example::
 216
 217         rbd trash restore swimmingpool/2bf4474b0dc51 --image new-name
 218
 219
 220 .. _create a pool: ../../rados/operations/pools/#create-a-pool
 221 .. _Storage Pools: ../../rados/operations/pools
 222 .. _RBD – Manage RADOS Block Device (RBD) Images: ../../man/8/rbd/
 223 .. _create a Ceph user: ../../rados/operations/user-management#add-a-user