For Ubuntu distributions 11.10 oneiric and earlier, you must build ``libvirt``
from source. Clone the ``libvirt`` repository, and use `AutoGen`_ to generate
-the build. Then execute ``make`` and ``make install`` to complete the
+the build. Then, execute ``make`` and ``make install`` to complete the
installation. For example::
git clone git://libvirt.org/libvirt.git
make
sudo make install
-See `libvirt Installation`_ for details. For a reference of ``virsh`` commands,
-refer to `Virsh Command Reference`_.
+See `libvirt Installation`_ for details.
Using Ceph with Virtual Machines
================================
-To create VMs that use Ceph block devices, use the following procedures.
+To create VMs that use Ceph block devices, use the procedures in the following
+sections. In the exemplary embodiment, we've used ``libvirt-pool`` for the pool
+name, ``client.libvirt`` for the user name, and ``new-libvirt-image`` for the
+image name. You may use any value you like, but ensure you replace those values
+when executing commands in the subsequent procedures.
Configuring Ceph
To configure Ceph for use with ``libvirt``, perform the following steps:
-#. `Create a pool`_ (or use the default). ::
+#. `Create a pool`_ (or use the default). The following example uses the
+ pool name ``libvirt-pool`` with 128 placement groups. ::
ceph osd pool create libvirt-pool 128 128
-#. `Create a user`_ (or use ``client.admin`` for version 0.9.7 and earlier). ::
+ Verify the pool exists. ::
+
+ ceph osd lspools
+
+#. `Create a user`_ (or use ``client.admin`` for version 0.9.7 and earlier).
+ The following example uses the user name ``client.libvirt`` and references
+ ``libvirt-pool``. ::
ceph auth get-or-create client.libvirt mon 'allow r' osd 'allow class-read object_prefix rbd_children, allow rwx pool=libvirt-pool'
+
+ Verify the user exists. ::
+
+ ceph auth list
-#. Use QEMU to `create an image`_ in your RBD pool. ::
+ **NOTE**: ``libvirt`` will access Ceph using the ID ``libvirt``,
+ not username ``client.libvirt``.
+
+#. Use QEMU to `create an image`_ in your RBD pool.
+ The following example uses the image name ``new-libvirt-image``
+ and references ``libvirt-pool``. ::
qemu-img create -f rbd rbd:libvirt-pool/new-libvirt-image 2G
+ Verify the image exists. ::
+
+ rbd -p libvirt-pool ls
+
+ **NOTE:** You can also use `rbd create`_ to create an image, but we
+ recommend ensuring that QEMU is working properly.
+
Preparing the VM Manager
#. Press the **Create New Virtual Machine** button.
-#. Name the new virtual machine. ::
+#. Name the new virtual machine domain. In the exemplary embodiment, we
+ use the name ``libvirt-virtual-machine``. You may use any name you wish,
+ but ensure you replace ``libvirt-virtual-machine`` with the name you
+ choose in subsequent examples. ::
libvirt-virtual-machine
#. Import the image. ::
- /path/to/image/debian.img
+ /path/to/image/recent-linux.img
+ **NOTE:** Import a recent image. Some older images may not rescan for
+ virtual devices properly.
+
#. Configure and start the VM.
+#. You may use ``virsh list`` to verify the VM domain exists. ::
+
+ sudo virst list
+
#. Login to the VM (root/root)
-#. Stop the VM.
+#. Stop the VM before configuring it for use with Ceph.
Configuring the VM
------------------
-To configure the VM for use with Ceph, perform the following steps:
-
-#. Navigate to the VM configuration file directory. ::
+When configuring the VM for use with Ceph, it is important to use ``virsh``
+where appropriate. Additionally, ``virsh`` commands often require root
+privileges (i.e., ``sudo``) and will not return appropriate results or notify
+you that that ``sudo`` is required. For a reference of ``virsh`` commands, refer
+to `Virsh Command Reference`_.
- cd /etc/libvirt/qemu
-#. Open the configuration file. ::
+#. Open the configuration file with ``virsh edit``. ::
- sudo virsh edit libvirt-virtual-machine.xml
+ sudo virsh edit libvirt-virtual-machine
Under ``<devices>`` there should be a ``<disk>`` entry. ::
<emulator>/usr/bin/kvm</emulator>
<disk type='file' device='disk'>
<driver name='qemu' type='raw'/>
- <source file='/path/to/image/debian.img'/>
+ <source file='/path/to/image/recent-linux.img'/>
<target dev='hda' bus='ide'/>
<address type='drive' controller='0' bus='0' unit='0'/>
</disk>
- Replace ``/path/to/image/debian.img`` with the path to the OS image.
+ Replace ``/path/to/image/recent-linux.img`` with the path to the OS image.
- **NOTE:** Use ``virsh edit`` instead of a text editor.
+ **IMPORTANT:** Use ``sudo virsh edit`` instead of a text editor. If you edit
+ the file using ``vi`` under ``/etc/libvirt/qemu``, ``libvirt`` may not recognize
+ the change. If there is a discrepancy between the contents of the XML file under
+ ``/etc/libvirt/qemu`` and the result of
+ ``sudo virsh dumpxml {vm-domain-name}``, then your VM may not work
+ properly.
+
#. Add the Ceph RBD image you created as a ``<disk>`` entry. ::
<target dev='hdb' bus='ide'/>
</disk>
- Replace ``{monitor-host}`` with the name of your host. You may add multiple
- ``<host>`` entries for your Ceph monitors. The ``dev`` attribute is the
- logical device name that will appear under the ``/dev`` directory of your
+ Replace ``{monitor-host}`` with the name of your host, and replace the
+ pool and/or image name as necessary. You may add multiple ``<host>``
+ entries for your Ceph monitors. The ``dev`` attribute is the logical
+ device name that will appear under the ``/dev`` directory of your
VM. The optional ``bus`` attribute indicates the type of disk device to
emulate. The valid settings are driver specific (e.g., "ide", "scsi",
"virtio", "xen", "usb" or "sata").
entry to the ``<disk>`` element you entered earlier (replacing the
``uuid`` value with the result from the command line example above). ::
- sudo virsh edit libvirt-virtual-machine.xml
+ sudo virsh edit libvirt-virtual-machine
Then, add ``<auth></auth>`` element to the domain configuration file::
<target ...
- **NOTE:** The username is ``libvirt``, not ``client.libvirt``.
+ **NOTE:** The exemplary username is ``libvirt``, not ``client.libvirt`` as
+ generated at step 2 of `Configuring Ceph`_. Ensure you use the username
+ you generated. If for some reason you need to regenerate the secret, you
+ will have to execute ``sudo virsh secret-undefine {uuid}`` before executing
+ ``sudo virsh secret-set-value`` again.
+
+
+Summary
+-------
+
+Once you have configured the VM for use with Ceph, you can start the VM.
+To verify that the VM and Ceph are communicating, you may perform the
+following procedures.
+
+
+#. Check to see if Ceph is running::
+
+ ceph health
+
+#. Check to see if the VM is running. ::
+
+ sudo virsh list
+
+#. Check to see if the VM is communicating with Ceph. Replace
+ ``libvirt-virtual-machine`` with the name of your VM domain::
+
+ sudo virsh qemu-monitor-command --hmp libvirt-virtual-machine 'info block'
+
+#. Check to see if the device from ``<target dev='hdb' bus='ide'/>`` appears
+ under ``/dev`` or under ``proc/partitions``. ::
+
+ ls dev
+ cat proc/partitions
+If everything looks okay, you may begin using the Ceph block device
+within your VM.
-Once you have configured the VM for use with Ceph, you can start the VM and
-begin using the Ceph block device within your VM.
.. _AutoGen: http://www.gnu.org/software/autogen/
.. _Virsh Command Reference: http://www.libvirt.org/virshcmdref.html
.. _KVM/VirtManager: https://help.ubuntu.com/community/KVM/VirtManager
.. _Ceph Authentication: ../../rados/operations/auth-intro
-.. _Disks: http://www.libvirt.org/formatdomain.html#elementsDisks
\ No newline at end of file
+.. _Disks: http://www.libvirt.org/formatdomain.html#elementsDisks
+.. _rbd create: ../rados-rbd-cmds#creating-a-block-device-image
\ No newline at end of file
projects / ceph.git / commitdiff