doc: Added some of the troubleshooting steps into the libvirt procedure and removed path for virsh edit.

Signed-off-by: John Wilkins <john.wilkins@inktank.com>

1 files changed, 104 insertions, 27 deletions

diff --git a/doc/rbd/libvirt.rst b/doc/rbd/libvirt.rst
index 2f6c998aca4..ad9c240868c 100644
--- a/doc/rbd/libvirt.rst
+++ b/doc/rbd/libvirt.rst
@@ -64,7 +64,7 @@ Installing ``libvirt`` on Earlier Versions of Ubuntu
 
 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
@@ -73,14 +73,17 @@ installation. For example::
 	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
@@ -88,18 +91,41 @@ 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
@@ -127,33 +153,44 @@ To create a VM with ``virt-manager``, perform the following steps:
 
 #. 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. :: 
 
@@ -161,15 +198,21 @@ To configure the VM for use with Ceph, perform the following steps:
 		<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. :: 
 
@@ -180,9 +223,10 @@ To configure the VM for use with Ceph, perform the following steps:
 		<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").
@@ -220,7 +264,7 @@ To configure the VM for use with Ceph, perform the following steps:
    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::
 
@@ -232,11 +276,43 @@ To configure the VM for use with Ceph, perform the following steps:
 	<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/
@@ -253,4 +329,5 @@ begin using the Ceph block device within your VM.
 .. _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