`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::
./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}
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. ::
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}
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
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::
.. _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
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
projects / ceph.git / commitdiff