[ceph.git] / ceph / doc / start / quick-rbd.rst

==========================
 Block Device Quick Start
==========================

To use this guide, you must have executed the procedures in the `Storage
Cluster Quick Start`_ guide first. Ensure your :term:`Ceph Storage Cluster` is
in an ``active + clean`` state before working with the :term:`Ceph Block
Device`. 

.. note:: The Ceph Block Device is also known as :term:`RBD` or :term:`RADOS`
   Block Device.


.. ditaa:: 
           /------------------\         /----------------\
           |    Admin Node    |         |   ceph-client  |
           |                  +-------->+ cCCC           |
           |    ceph-deploy   |         |      ceph      |
           \------------------/         \----------------/


You may use a virtual machine for your ``ceph-client`` node, but do not 
execute the following procedures on the same physical node as your Ceph 
Storage Cluster nodes (unless you use a VM). See `FAQ`_ for details.


Install Ceph
============

#. Verify that you have an appropriate version of the Linux kernel. 
   See `OS Recommendations`_ for details. ::
   
	lsb_release -a
	uname -r

#. On the admin node, use ``ceph-deploy`` to install Ceph on your 
   ``ceph-client`` node. ::

	ceph-deploy install ceph-client
	
#. On the admin node, use ``ceph-deploy`` to copy the Ceph configuration file
   and the ``ceph.client.admin.keyring`` to the ``ceph-client``. :: 

	ceph-deploy admin ceph-client

   The ``ceph-deploy`` utility copies the keyring to the ``/etc/ceph`` 
   directory. Ensure that the keyring file has appropriate read permissions 
   (e.g., ``sudo chmod +r /etc/ceph/ceph.client.admin.keyring``).

Create an rbd pool
==================
#. On the admin node, use the ``ceph`` tool to `Create a Pool`_
   (we recommend the name 'rbd').

Configure a Block Device
========================

#. On the ``ceph-client`` node, create a block device image. :: 

	rbd create foo --size 4096 [-m {mon-IP}] [-k /path/to/ceph.client.admin.keyring]

#. On the ``ceph-client`` node, map the image to a block device. :: 

	sudo rbd map foo --name client.admin [-m {mon-IP}] [-k /path/to/ceph.client.admin.keyring]
	
#. Use the block device by creating a file system on the ``ceph-client`` 
   node. :: 

	sudo mkfs.ext4 -m0 /dev/rbd/rbd/foo
	
	This may take a few moments.
	
#. Mount the file system on the ``ceph-client`` node. ::

	sudo mkdir /mnt/ceph-block-device
	sudo mount /dev/rbd/rbd/foo /mnt/ceph-block-device
	cd /mnt/ceph-block-device

#. Optionally configure the block device to be automatically mapped and mounted
   at boot (and unmounted/unmapped at shutdown) - see the `rbdmap manpage`_.


See `block devices`_ for additional details.

.. _Create a Pool: ../../rados/operations/pools#createpool
.. _Storage Cluster Quick Start: ../quick-ceph-deploy
.. _block devices: ../../rbd/rbd
.. _FAQ: http://wiki.ceph.com/How_Can_I_Give_Ceph_a_Try
.. _OS Recommendations: ../os-recommendations
.. _rbdmap manpage: ../../man/8/rbdmap
Commit	Line	Data
7c673cae FG	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
224ce89b WB	50	Create an rbd pool
	51	==================
	52	#. On the admin node, use the ``ceph`` tool to `Create a Pool`_
	53	(we recommend the name 'rbd').
7c673cae FG	54
	55	Configure a Block Device
	56	========================
	57
	58	#. On the ``ceph-client`` node, create a block device image. ::
	59
	60	rbd create foo --size 4096 [-m {mon-IP}] [-k /path/to/ceph.client.admin.keyring]
	61
	62	#. On the ``ceph-client`` node, map the image to a block device. ::
	63
	64	sudo rbd map foo --name client.admin [-m {mon-IP}] [-k /path/to/ceph.client.admin.keyring]
	65
	66	#. Use the block device by creating a file system on the ``ceph-client``
	67	node. ::
	68
	69	sudo mkfs.ext4 -m0 /dev/rbd/rbd/foo
	70
	71	This may take a few moments.
	72
	73	#. Mount the file system on the ``ceph-client`` node. ::
	74
	75	sudo mkdir /mnt/ceph-block-device
	76	sudo mount /dev/rbd/rbd/foo /mnt/ceph-block-device
	77	cd /mnt/ceph-block-device
	78
	79	#. Optionally configure the block device to be automatically mapped and mounted
	80	at boot (and unmounted/unmapped at shutdown) - see the `rbdmap manpage`_.
	81
	82
	83	See `block devices`_ for additional details.
	84
224ce89b	85	.. _Create a Pool: ../../rados/operations/pools#createpool
7c673cae FG	86	.. _Storage Cluster Quick Start: ../quick-ceph-deploy
	87	.. _block devices: ../../rbd/rbd
	88	.. _FAQ: http://wiki.ceph.com/How_Can_I_Give_Ceph_a_Try
	89	.. _OS Recommendations: ../os-recommendations
	90	.. _rbdmap manpage: ../../man/8/rbdmap