From: John Wilkins Date: Sat, 3 Nov 2012 19:12:11 +0000 (-0700) Subject: doc: Added qemu caching section. X-Git-Tag: v0.55~130^2~21 X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=4bff87da9a139102e24fd0108be09529b1efb24d;p=ceph.git doc: Added qemu caching section. fixes: #3332 Signed-off-by: John Wilkins --- diff --git a/doc/rbd/qemu-rbd.rst b/doc/rbd/qemu-rbd.rst index 5f0b461f074e..74d412277b2f 100644 --- a/doc/rbd/qemu-rbd.rst +++ b/doc/rbd/qemu-rbd.rst @@ -6,18 +6,20 @@ Ceph integrates with the QEMU virtual machine. For details on QEMU, see `QEMU Open Source Processor Emulator`_. For QEMU documentation, see `QEMU Manual`_. -.. important:: To use RBD with QEMU, you must have a running Ceph cluster. +.. important:: To use Ceph block devices with QEMU, you must have a running Ceph cluster. Installing QEMU on Ubuntu 12.04 Precise ---------------------------------------- +======================================= + QEMU packages are incorporated into the Ubuntu 12.04 precise distribution. To install QEMU on precise, execute the following:: sudo apt-get install qemu Installing QEMU on Earlier Versions of Ubuntu ---------------------------------------------- -For Ubuntu distributions 11.10 oneiric and earlier, you must install +============================================= + +For Ubuntu distributions 11.10 Oneiric and earlier, you must install the 0.15 version of QEMU or later. To build QEMU from source, use the following procedure:: @@ -27,11 +29,12 @@ following procedure:: ./configure --enable-rbd make; make install -Creating RBD Images with QEMU ------------------------------ -You can create an RBD image from QEMU. You must specify ``rbd``, -the pool name, and the name of the image you wish to create. You must also -specify the size of the image. :: +Creating Images with QEMU +========================= + +You can create a block device image from QEMU. You must specify ``rbd``, the +pool name, and the name of the image you wish to create. You must also specify +the size of the image. :: qemu-img create -f rbd rbd:{pool-name}/{image-name} {size} @@ -39,9 +42,10 @@ For example:: qemu-img create -f rbd rbd:data/foo 10G -Resizing RBD Images with QEMU ------------------------------ -You can resize an RBD image from QEMU. You must specify ``rbd``, +Resizing Images with QEMU +========================= + +You can resize a block device image from QEMU. You must specify ``rbd``, the pool name, and the name of the image you wish to resize. You must also specify the size of the image. :: @@ -52,9 +56,10 @@ For example:: qemu-img resize -f rbd rbd:data/foo 10G -Retrieving RBD Image Information with QEMU ------------------------------------------- -You can retrieve RBD image information from QEMU. You must +Retrieving Image Information with QEMU +====================================== + +You can retrieve block device image information from QEMU. You must specify ``rbd``, the pool name, and the name of the image. :: qemu-img info -f rbd rbd:{pool-name}/{image-name} @@ -65,16 +70,16 @@ For example:: Running QEMU with RBD ---------------------- +===================== QEMU can pass a block device from the host on to a guest, but since -QEMU 0.15, there's no need to map an RBD image as a block device on -the host. Instead, QEMU can access an RBD image as a virtual block +QEMU 0.15, there's no need to map an image as a block device on +the host. Instead, QEMU can access an image as a virtual block device directly via ``librbd``. This performs better because it avoids an additional context switch, and can take advantage of `RBD caching`_. -You can use ``qemu-img`` to convert existing virtual machine images to RBD. -For example, if you have a qcow2 image, you could run:: +You can use ``qemu-img`` to convert existing virtual machine images to Ceph +block device images. For example, if you have a qcow2 image, you could run:: qemu-img convert -f qcow2 -O rbd debian_squeeze.qcow2 rbd:data/squeeze @@ -82,12 +87,12 @@ To run a virtual machine booting from that image, you could run:: qemu -m 1024 -drive format=raw,file=rbd:data/squeeze -Using `RBD caching`_ can significantly improve performance. -Since QEMU 1.2, QEMU's cache options control RBD caching:: +`RBD caching`_ can significantly improve performance. +Since QEMU 1.2, QEMU's cache options control ``librbd`` caching:: qemu -m 1024 -drive format=rbd,file=rbd:data/squeeze,cache=writeback -If you have an older version of QEMU, you can set the RBD cache +If you have an older version of QEMU, you can set the ``librbd`` cache configuration (like any Ceph configuration option) as part of the 'file' parameter:: @@ -96,17 +101,17 @@ configuration (like any Ceph configuration option) as part of the .. _RBD caching: ../../config-cluster/rbd-config-ref/#rbd-cache-config-settings -Enabling discard/TRIM ---------------------- +Enabling Discard/TRIM +===================== -Since Ceph version 0.46 and QEMU version 1.1, RBD supports the discard -operation. This means that a guest can send TRIM requests to let RBD -reclaim unused space. This can be enabled in the guest by mounting -ext4 or xfs with the ``discard`` option. +Since Ceph version 0.46 and QEMU version 1.1, Ceph block devices support the +discard operation. This means that a guest can send TRIM requests to let a Ceph +block device reclaim unused space. This can be enabled in the guest by mounting +ext4 or XFS with the ``discard`` option. For this to be available to the guest, it must be explicitly enabled for the block device. To do this, you must specify a -discard_granularity associated with the drive:: +``discard_granularity`` associated with the drive:: qemu -m 1024 -drive format=raw,file=rbd:data/squeeze,id=drive1,if=none \ -device driver=ide-hd,drive=drive1,discard_granularity=512 @@ -115,5 +120,31 @@ Note that this uses the IDE driver. The virtio driver does not support discard. +QEMU Cache Options +================== + +QEMU's cache options correspond to the following Ceph `RBD Cache`_ settings. + +Writeback:: + + rbd_cache = true + +Writethrough:: + + rbd_cache = true + rbd_cache_max_dirty = 0 + +None:: + + rbd_cache = false + +QEMU's cache settings override Ceph's default settings (i.e., settings that are +not explicitly set in the Ceph configuration file). If you explicitly set `RBD +Cache`_ settings in your Ceph configuration file, your Ceph settings override +the QEMU cache settings. If you set cache settings on the QEMU command line, the +QEMU command line settings override the Ceph configuration file settings. + + .. _QEMU Open Source Processor Emulator: http://wiki.qemu.org/Main_Page .. _QEMU Manual: http://wiki.qemu.org/Manual +.. _RBD Cache: ../../config-cluster/rbd-config-ref/ \ No newline at end of file