src/ceph/doc/start/quick-rbd.rst

   1 ==========================
   2  Block Device Quick Start
   3 ==========================
   4
   5 To use this guide, you must have executed the procedures in the `Storage
   6 Cluster Quick Start`_ guide first. Ensure your :term:`Ceph Storage Cluster` is
   7 in an ``active + clean`` state before working with the :term:`Ceph Block
   8 Device`.
   9
  10 .. note:: The Ceph Block Device is also known as :term:`RBD` or :term:`RADOS`
  11    Block Device.
  12
  13
  14 .. ditaa::
  15            /------------------\         /----------------\
  16            |    Admin Node    |         |   ceph-client  |
  17            |                  +-------->+ cCCC           |
  18            |    ceph-deploy   |         |      ceph      |
  19            \------------------/         \----------------/
  20
  21
  22 You may use a virtual machine for your ``ceph-client`` node, but do not
  23 execute the following procedures on the same physical node as your Ceph
  24 Storage Cluster nodes (unless you use a VM). See `FAQ`_ for details.
  25
  26
  27 Install Ceph
  28 ============
  29
  30 #. Verify that you have an appropriate version of the Linux kernel.
  31    See `OS Recommendations`_ for details. ::
  32
  33         lsb_release -a
  34         uname -r
  35
  36 #. On the admin node, use ``ceph-deploy`` to install Ceph on your
  37    ``ceph-client`` node. ::
  38
  39         ceph-deploy install ceph-client
  40
  41 #. On the admin node, use ``ceph-deploy`` to copy the Ceph configuration file
  42    and the ``ceph.client.admin.keyring`` to the ``ceph-client``. ::
  43
  44         ceph-deploy admin ceph-client
  45
  46    The ``ceph-deploy`` utility copies the keyring to the ``/etc/ceph``
  47    directory. Ensure that the keyring file has appropriate read permissions
  48    (e.g., ``sudo chmod +r /etc/ceph/ceph.client.admin.keyring``).
  49
  50 Create a Block Device Pool
  51 ==========================
  52
  53 #. On the admin node, use the ``ceph`` tool to `create a pool`_
  54    (we recommend the name 'rbd').
  55
  56 #. On the admin node, use the ``rbd`` tool to initialize the pool for use by RBD::
  57
  58         rbd pool init <pool-name>
  59
  60 Configure a Block Device
  61 ========================
  62
  63 #. On the ``ceph-client`` node, create a block device image. ::
  64
  65         rbd create foo --size 4096 [-m {mon-IP}] [-k /path/to/ceph.client.admin.keyring]
  66
  67 #. On the ``ceph-client`` node, map the image to a block device. ::
  68
  69         sudo rbd map foo --name client.admin [-m {mon-IP}] [-k /path/to/ceph.client.admin.keyring]
  70
  71 #. Use the block device by creating a file system on the ``ceph-client``
  72    node. ::
  73
  74         sudo mkfs.ext4 -m0 /dev/rbd/rbd/foo
  75
  76         This may take a few moments.
  77
  78 #. Mount the file system on the ``ceph-client`` node. ::
  79
  80         sudo mkdir /mnt/ceph-block-device
  81         sudo mount /dev/rbd/rbd/foo /mnt/ceph-block-device
  82         cd /mnt/ceph-block-device
  83
  84 #. Optionally configure the block device to be automatically mapped and mounted
  85    at boot (and unmounted/unmapped at shutdown) - see the `rbdmap manpage`_.
  86
  87
  88 See `block devices`_ for additional details.
  89
  90 .. _Storage Cluster Quick Start: ../quick-ceph-deploy
  91 .. _create a pool: ../../rados/operations/pools/#create-a-pool
  92 .. _block devices: ../../rbd
  93 .. _FAQ: http://wiki.ceph.com/How_Can_I_Give_Ceph_a_Try
  94 .. _OS Recommendations: ../os-recommendations
  95 .. _rbdmap manpage: ../../man/8/rbdmap