diff options
author | John Wilkins <john.wilkins@inktank.com> | 2012-05-31 15:35:33 -0700 |
---|---|---|
committer | John Wilkins <john.wilkins@inktank.com> | 2012-05-31 15:35:33 -0700 |
commit | fb7ce59b9a18ac26882836de366629a4593855a6 (patch) | |
tree | f8be3e4446f6d3d79e5c165715dc25cbccdb42da /doc | |
parent | 10b0db3b531f010281f4f5fd065284c5e5e0222e (diff) | |
download | ceph-fb7ce59b9a18ac26882836de366629a4593855a6.tar.gz |
doc: Added preliminary rbd and ko info.
Signed-off-by: John Wilkins <john.wilkins@inktank.com>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/index.rst | 1 | ||||
-rw-r--r-- | doc/rbd/rados-rbd-cmds.rst | 113 | ||||
-rw-r--r-- | doc/rbd/rbd-ko.rst | 73 | ||||
-rw-r--r-- | doc/rbd/rbd.rst | 31 |
4 files changed, 218 insertions, 0 deletions
diff --git a/doc/index.rst b/doc/index.rst index 77b6bf85ae6..01c70ff2c69 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -21,6 +21,7 @@ cluster to ensure that the storage hosts are running smoothly. install/index config-cluster/index init/index + rbd/rbd ops/index rec/index config diff --git a/doc/rbd/rados-rbd-cmds.rst b/doc/rbd/rados-rbd-cmds.rst new file mode 100644 index 00000000000..0f9542a2891 --- /dev/null +++ b/doc/rbd/rados-rbd-cmds.rst @@ -0,0 +1,113 @@ +==================== + 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 diff --git a/doc/rbd/rbd-ko.rst b/doc/rbd/rbd-ko.rst new file mode 100644 index 00000000000..1e01f0bec86 --- /dev/null +++ b/doc/rbd/rbd-ko.rst @@ -0,0 +1,73 @@ +============================== + 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 + diff --git a/doc/rbd/rbd.rst b/doc/rbd/rbd.rst new file mode 100644 index 00000000000..b1ad272a46e --- /dev/null +++ b/doc/rbd/rbd.rst @@ -0,0 +1,31 @@ +=============== + 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 |