doc: extend QEMU/RBD docs

Describe running a vm from RBD, cache options, and discard support.

Signed-off-by: Josh Durgin <josh.durgin@inktank.com>

diff --git a/doc/rbd/qemu-rbd.rst b/doc/rbd/qemu-rbd.rst
index 4da52a8e9ecabfa15c3b9d85c36f8e3abed72d04..5f0b461f074eed5b294ec1533a915fbdda1c9583 100644 (file)
--- a/doc/rbd/qemu-rbd.rst
+++ b/doc/rbd/qemu-rbd.rst
@@ -63,6 +63,57 @@ For example::
 
        qemu-img info -f rbd rbd:data/foo
 
-   
+
+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
+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::
+
+    qemu-img convert -f qcow2 -O rbd debian_squeeze.qcow2 rbd:data/squeeze
+
+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::
+
+    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
+configuration (like any Ceph configuration option) as part of the
+'file' parameter::
+
+    qemu -m 1024 -drive format=raw,file=rbd:data/squeeze:rbd_cache=true
+
+.. _RBD caching: ../../config-cluster/rbd-config-ref/#rbd-cache-config-settings
+
+
+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.
+
+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::
+
+    qemu -m 1024 -drive format=raw,file=rbd:data/squeeze,id=drive1,if=none \
+         -device driver=ide-hd,drive=drive1,discard_granularity=512
+
+Note that this uses the IDE driver. The virtio driver does not
+support discard.
+
+
 .. _QEMU Open Source Processor Emulator: http://wiki.qemu.org/Main_Page
 .. _QEMU Manual: http://wiki.qemu.org/Manual