--- /dev/null
+====================
+ RADOS RDB Commands
+====================
+The ``rbd`` command enables you to create, list, introspect and remove block
+device images. You can also use it to clone images, create snapshots,
+rollback an image to a snapshot, view a snapshot, etc. For details on using
+the ``rbd`` command, see `RBD – Manage RADOS Block Device (RBD) Images`_ for
+details.
+
+
+Creating a Block Device Image
+-----------------------------
+Before you can add a block device to a Ceph client, you must create an image for
+it in the OSD cluster first. To create a block device image, execute the
+following::
+
+ rbd create {image-name} --size {megabytes} --dest-pool {pool-name}
+
+For example, to create a 1GB image named ``foo`` that stores information in a
+pool named ``swimmingpool``, execute the following::
+
+ rbd create foo --size 1024
+ rbd create bar --size 1024 --pool swimmingpool
+
+.. note:: You must create a pool first before you can specify it as a
+ source. See `Storage Pools`_ for details.
+
+Listing Block Device Images
+---------------------------
+To list block devices in the ``rbd`` pool, execute the following::
+
+ rbd ls
+
+To list block devices in a particular pool, execute the following,
+but replace ``{poolname}`` with the name of the pool::
+
+ rbd ls {poolname}
+
+For example::
+
+ rbd ls swimmingpool
+
+Retrieving Image Information
+----------------------------
+To retrieve information from a particular image, execute the following,
+but replace ``{image-name}`` with the name for the image::
+
+ rbd --image {image-name} info
+
+For example::
+
+ rbd --image foo info
+
+To retrieve information from an image within a pool, execute the following,
+but replace ``{image-name}`` with the name of the image and replace ``{pool-name}``
+with the name of the pool::
+
+ rbd --image {image-name} -p {pool-name} info
+
+For example::
+
+ rbd --image bar -p swimmingpool info
+
+Resizing a Block Device Image
+-----------------------------
+RBD images are thin provisioned. They don't actually use any physical storage
+until you begin saving data to them. However, they do have a maximum capacity
+that you set with the ``--size`` option. If you want to increase (or decrease)
+the maximum size of a RADOS block device image, execute the following::
+
+ rbd resize --image foo --size 2048
+
+
+Removing a Block Device Image
+-----------------------------
+To remove a block device, execute the following, but replace ``{image-name}``
+with the name of the image you want to remove::
+
+ rbd rm {image-name}
+
+For example::
+
+ rbd rm foo
+
+To remove a block device from a pool, execute the following, but replace
+``{image-name}`` with the name of the image to remove and replace
+``{pool-name}`` with the name of the pool::
+
+ rbd rm {image-name} -p {pool-name}
+
+For example::
+
+ rbd rm bar -p swimmingpool
+
+
+Snapshotting Block Device Images
+--------------------------------
+One of the advanced features of RADOS block devices is that you can create
+snapshots of the images to retain a history of an image's state. Ceph supports
+RBD snapshots from the ``rbd`` command, from a kernel object, from a
+KVM, and from cloud solutions. Once you create snapshots of an image, you
+can rollback to a snapshot, list snapshots, remove snapshots and purge
+the snapshots.
+
+.. important:: Generally, you should stop i/o before snapshotting an image.
+ If the image contains a filesystem, the filesystem should be in a
+ consistent state before snapshotting too.
+
+
+
+
+.. _Storage Pools: ../../config-cluster/pools
+.. _RBD – Manage RADOS Block Device (RBD) Images: ../../man/8/rbd/
\ No newline at end of file
--- /dev/null
+==============================
+ RBD Kernel Object Operations
+==============================
+
+Add a Block Device
+------------------
+To add an RBD image as a kernel object, first load the Ceph RBD module::
+
+ modprobe rbd
+
+Map the RBD image to the kernel object with ``add``, specifying the IP address
+of the monitor, the user name, and the RBD image name as follows::
+
+ echo "{mon-ip-address} name={user-name} rbd {image-name}" | sudo tee /sys/bus/rbd/add
+
+For example::
+
+ echo "10.20.30.40 name=admin rbd foo" | sudo tee /sys/bus/rbd/add
+
+If you use ``cephx`` authentication, you must also specify a secret. ::
+
+ echo "10.20.30.40 name=admin,secret=/path/to/secret rbd foo" | sudo tee /sys/bus/rbd/add
+
+
+A kernel block device resides under the ``/sys/bus/rbd/devices`` directory and
+provides the following functions:
+
++------------------+------------------------------------------------------------+
+| Function | Description |
++==================+============================================================+
+| ``client_id`` | Returns the client ID of the given device ID. |
++------------------+------------------------------------------------------------+
+| ``create_snap`` | Creates a snap from a snap name and a device ID. |
++------------------+------------------------------------------------------------+
+| ``current_snap`` | Returns the most recent snap for the given device ID. |
++------------------+------------------------------------------------------------+
+| ``major`` | |
++------------------+------------------------------------------------------------+
+| ``name`` | Returns the RBD image name of the device ID. |
++------------------+------------------------------------------------------------+
+| ``pool`` | Returns the pool source of the device ID. |
++------------------+------------------------------------------------------------+
+| ``refresh`` | Refreshes the given device with the SDs. |
++------------------+------------------------------------------------------------+
+| ``size`` | Returns the size of the device. |
++------------------+------------------------------------------------------------+
+| ``uevent`` | |
++------------------+------------------------------------------------------------+
+
+
+List Block Devices
+------------------
+Images are mounted as devices sequentially starting from ``0``. To list the
+devices mounted, execute the following::
+
+ ls /sys/bus/rbd/devices
+
+
+Removing a Block Device
+-----------------------
+To remove an RBD image, specify its index and use ``tee`` to call ``remove`` as
+follows, but replace ``{device-number}`` with the number of the device you want
+to remove::
+
+ echo {device-number} | sudo tee /sys/bus/rbd/remove
+
+
+Creating a Snapshot
+-------------------
+To create a snapshot of a device, you must specify the device number. ::
+
+ echo sn1 | sudo tee /sys/bus/rbd/devices/0{device-number}/create_snap
+
--- /dev/null
+===============
+ Block Devices
+===============
+
+A block is a sequence of bytes (for example, a 512-byte block of data).
+Block-based storage interfaces are the most common way to store data with
+rotating media such as hard disks, CDs, floppy disks, and even traditional
+9-track tape. The ubiquity of block device interfaces makes a virtual block
+device an ideal candidate to interact with a mass data storage system like Ceph.
+
+Ceph's RADOS Block Devices (RBD) interact with RADOS OSDs using the
+``librados`` and ``librbd`` libraries. RBDs are thin-provisioned, resizable
+and store data striped over multiple OSDs in a Ceph cluster. RBDs inherit
+``librados`` capabilities such as snapshotting and cloning. Ceph's RBDs deliver
+high performance with infinite scalability to kernel objects, kernel virtual
+machines and cloud-based computing systems like OpenStack and CloudStack.
+
+The ``librbd`` library converts data blocks into objects for storage in
+RADOS OSD clusters--the same storage system for ``librados`` object stores and
+the Ceph FS filesystem. You can use the same cluster to operate object stores,
+the Ceph FS filesystem, and RADOS block devices simultaneously.
+
+.. toctree::
+ :maxdepth: 1
+
+ RADOS Commands <rados-rbd-cmds>
+ Kernel Objects <rbd-ko>
+
+
+
+
\ No newline at end of file
projects / ceph.git / commitdiff