Add detailed documentation about the various SPICE feature

This documents how to enable Spice, QXL, tickets and agent support
in a VM, with examples to do that using virt-manager, libvirt or QEMU.

4 files changed, 311 insertions, 45 deletions

diff --git a/books/docbook/SpiceUserManual-Basics.xml b/books/docbook/SpiceUserManual-Basics.xml
index 270a008..dd1eec3 100644
--- a/books/docbook/SpiceUserManual-Basics.xml
+++ b/books/docbook/SpiceUserManual-Basics.xml
@@ -70,60 +70,326 @@
             required by <link xlink:href="SpiceUserManual-Introduction.xml#vdagent">the guest
             agent</link>.
         </para>
-       
     </section>
-    <section xml:id="spicec_basics">
-        <title>Connecting to guest</title>
-        
+
+    <section xml:id="qemu_spice">
+        <title>Adding Spice support to an existing virtual machine</title>
         <para>
-            The following section will show you basic usage of the spice
-            client. The example connection will be related to the qemu instance
-            started in <link xlink:href="#qemu_basics">the previous section</link>.
+            This section will assume that you already have a running QEMU virtual machine,
+            and that you are running it either through virt-manager, libvirt or through
+            direct QEMU use, and that you want to enable Spice support for this virtual
+            machine.
         </para>
-        
+
+        <section>
+            <title>Using virt-manager</title>
+            <para>
+                Double-click on the virtual machine you are interested in, go to View/Details.
+                If the left pane has a "Display Spice" entry, then the virtual machine already
+                has Spice support, and you can check the connection details (port number)
+                by clicking on it. If it has no Spice entry, click on "Add
+                Hardware", and add a "Graphics" element of type "Spice server".
+                If the host and the client are not the same machine, you should check
+                the "Listen on all public network interfaces" checkbox, otherwise you
+                don't need to make any changes.
+            </para>
+            <para>
+                You should also add a QXL video device. It can be done by double-clicking
+                on a virtual machine, then by going to View/Details, and  by clicking
+                on "Add Hardware" if the virtual machine does not have a "Video QXL" item
+                in its left pane. From the "Add hardware" dialog, you should then create
+                a "Video" device whose model is "QXL".
+            </para>
+            <para>
+                After stopping and restarting the virtual machine, it should be
+                accessible with a Spice client.
+            </para>
+            <para>
+                You can remove non-Spice display entries and non-QXL video entries from
+                the virtual machine configuration.
+            </para>
+            <para>
+                If you go to Edit/Preferences/VM Details in the main virt-manager window,
+                you can set Spice graphics type as the default setting for new virtual
+                machines.
+            </para>
+        </section>
+
+        <section>
+            <title>Using libvirt</title>
+            <para>
+                All libvirt examples will assume that the virtual machine to modify
+                is $vmname and that virsh is using the correct
+                <link xlink:href="http://libvirt.org/uri.html">libvirt connection</link>
+                by default.
+            </para>
+            <para>
+                To add Spice support to an existing virtual machine managed by libvirt,
+                you need to edit it:
+                <screen>
+host# virsh edit $vmname
+                </screen>
+                and then add a <link xlink:href="http://libvirt.org/formatdomain.html#elementsGraphics">Spice graphics element</link>:
+                <programlisting>
+&lt;graphics type='spice'/&gt;
+                </programlisting>
+                You should also add a <link xlink:href="http://libvirt.org/formatdomain.html#elementsVideo">QXL video device</link>
+                <programlisting>
+&lt;video&gt;
+    &lt;model type='qxl'&gt;
+&lt;/video&gt;
+                </programlisting>
+            </para>
+            <para>
+                After stopping and restarting the virtual machine $vmname, it should be
+                accessible through Spice. You can check the connection parameters with:
+                <screen>
+host# virsh domdisplay $vmname
+                </screen>
+            </para>
+        </section>
+
+        <section>
+            <title>Using QEMU</title>
+            <para>
+                To enable Spice support to your virtual machine, you only need to
+                append the following to your QEMU command line:
+                <screen>
+-spice port=3001,disable-ticketing
+                </screen>
+                This will setup a Spice session listening on port 3001 exporting
+                your virtual machine display.
+            </para>
+            <para>
+                You can also add a QXL device by appending this to the command line:
+                <screen>
+-vga qxl
+                </screen>
+            </para>
+
+        </section>
+
+        <section xml:id="client_basics">
+            <title>Connecting to guest</title>
+
+            <para>
+                The following section will show you basic usage of the Spice
+                client. The example connection will be related to the qemu instance
+                started in <link xlink:href="#qemu_basics">the previous section</link>.
+            </para>
+
+            <para>
+                Be aware that the port used for spice communication
+                <emphasis role="italic">(port 3001 in our case)</emphasis> should not be
+                blocked by firewall.  <emphasis role="bold">Host myhost is referring to the
+                machine which is running our qemu instance.</emphasis>
+            </para>
+
+            <screen>client# remote-viewer spice://myhost:3001</screen>
+            <figure>
+                <title>Established connection to Windows 2008 guest</title>
+                <mediaobject>
+                    <imageobject>
+                        <imagedata fileref="resources/spicec01.png"/>
+                    </imageobject>
+                </mediaobject>
+            </figure>
+         </section>
+    </section>
+
+     <section xml:id="ticketing">
+        <title>Ticketing</title>
         <para>
-            Be aware that the port used for spice communication <emphasis role="italic">(port 3001 in our case)</emphasis> should not be blocked by firewall.
-            <emphasis role="bold">Host myhost is referring to the machine which is running our qemu instance.</emphasis>
+            Spice does not currently support multiple connections to the same qemu
+            instance.  So anybody who will connect to the same host and port can simply
+            take over your session.
+
+            <emphasis role="bold">You can eliminate this problem by using
+            <link xlink:href="#ticketing">ticketing</link> or SSL.</emphasis>
         </para>
-        
-        <screen>client# spicec -h myhost -p 3001</screen>
-        <figure>
-            <title>Established connection to Windows 2008 guest</title>
-            <mediaobject>
-                <imageobject>
-                    <imagedata fileref="resources/spicec01.png"/>
-                </imageobject>
-            </mediaobject>
-        </figure>
-        
+
         <para>
-            Spice does not currently support multiple connections to the same qemu instance.
-            So anybody who will connect to the same host and port can simply take over your session.
-            
-            <emphasis role="bold">You can eliminate this problem by using <link xlink:href="#ticketing">ticketing</link> or SSL.</emphasis>
-           
+            Ticketing is a simple authentication system which enables you to set simple
+            tickets to a vm.
+            Client has to authentificate before the connection can be established. See
+            the spice option password in the following example.
         </para>
-        
-        <para xml:id="ticketing">
-            Ticketing is a simple authentication system which enables you to set simple tickets to a vm. 
-            Client has to authentificate before the connection can be established. See the spice option password in
-            the following example.
+
+        <section>
+            <title>Using virt-manager</title>
+            <para>
+                To set a Spice password for a virtual machine, go to this machine
+                details in virt-manager, and then click on the "Display Spice" item in
+                the left pane, and enter the ticket you want to use in the "Password"
+                field.
+            </para>
+        </section>
+
+        <section>
+            <title>Using libvirt</title>
+            <para>
+                All you need to do is to append a passwd attribute to the Spice
+                graphics node for your virtual machine:
+                <programlisting>
+&lt;graphics type='spice' passwd='mysecretpassword'/&gt;
+                </programlisting>
+            </para>
+        </section>
+
+        <section>
+            <title>Using QEMU</title>
+            <para>
+                Adding a ticket with QEMU involves a slight modification of the -spice
+                parametr used when running QEMU:
+                <screen>
+-spice port=3001,password=mysecretpassword
+                </screen>
+            </para>
+        </section>
+
+        <section>
+            <title>Client</title>
+            <para>
+                When you start the client as usual, if ticketing was enabled on the host,
+                remote-viewer will pop up a window asking for a password before starting
+                the Spice session. It won't be established if an incorrect ticket was
+                passed to the client.
+            </para>
+
+            <para>
+                You might have figured out that passing tickets as a commandline option isn't very safe.
+                <emphasis role="bold">It's not safe as everybody with access to the host can read it from the output of ps(1).</emphasis>
+                To prevent this, the ticket can be also set by using the qemu console command spice._set_ticket.
+            </para>
+        </section>
+    </section>
+
+    <section xml:id="agent">
+        <title>Agent</title>
+        <para>
+            Agent support allows better integration with the guest. For example, it
+            allows copy and paste between the guest and the host OSes, dynamic resolution
+            changes when the client window is resized/fullscreened, file transfers through
+            drag and drop, ...
         </para>
-        
-        <screen>host# sudo qemu-kvm -boot order=dc -vga qxl \
-         -spice port=3001,password=mysecretpassword -soundhw ac97 \
-         -device virtio-serial -chardev spicevmc,id=vdagent,debug=0,name=vdagent \
-         -device virtserialport,chardev=vdagent,name=com.redhat.spice.0 \
-         -cdrom /path/to/your.iso /path/to/your.img</screen>
-        
-        <screen>client# spicec -h myhost -p 3001 -w mysecretpassword</screen>
-        
-        <para>The Spice session won't be established if an incorrect ticket was passed to the client.</para>
-        
         <para>
-            You might have figured out that passing tickets as a commandline option isn't very safe. 
-            <emphasis role="bold">It's not safe as everybody with access to the host can read it from the output of ps(1).</emphasis> 
-            To prevent this, the ticket can be also set by using the qemu console command spice._set_ticket.
+            The agent is a daemon/service running in the guest OS so it must be installed
+            if it was not installed by default during the guest OS installation. It also
+            relies on a virtio-serial PCI device and a dedicated spicevmc char device
+            to achieve communication between the guest and the host. These devices must
+            be added to the virtual machine if we want to agent to work properly in the
+            guest.
+        </para>
+
+        <section>
+            <title>Using virt-manager</title>
+            <para>
+                The needed devices can be added from the virtual machine details. Click
+                on "Add hardware" and then add a "Channel" device with type
+                "Spice agent (spicevmc)". This will automatically add the needed
+                virtio-serial device in addition to the spicevmc channel.
+            </para>
+        </section>
+
+        <section>
+            <title>Using libvirt</title>
+            <para>
+                Two distinct devices must be added:
+                <itemizedlist>
+                    <listitem>a <link xlink:href="http://libvirt.org/formatdomain.html#elementsControllers">virtio serial device</link></listitem>
+                    <listitem>a <link xlink:href="http://libvirt.org/formatdomain.html#elementCharChannel">spicevmc channel</link></listitem>
+                </itemizedlist>
+                <programlisting>
+&lt;devices&gt;
+    &lt;controller type='virtio-serial' index='0'/&gt;
+    &lt;channel type='spicevmc'&gt;
+        &lt;target type='virtio' name='com.redhat.spice.0'/&gt;
+    &lt;/channel&gt;
+&lt;/devices&gt;
+                </programlisting>
+            </para>
+        </section>
+
+        <section>
+            <title>Using QEMU</title>
+            <para>
+                Adding the following parameters to your QEMU command line will
+                enable the needed devices for agent support in the guest OS:
+                <screen>
+-device virtio-serial \
+-chardev spicevmc,id=vdagent,debug=0,name=vdagent \
+-device virtserialport,chardev=vdagent,name=com.redhat.spice.0 \
+                </screen>
+            </para>
+        </section>
+    </section>
+
+    <section xml:id="USB">
+        <title>USB redirection</title>
+        <para>
+            USB redirection support is needed because of xxx and yyy, and prerequisites are zzz.
         </para>
+
+        <section>
+            <title>Using virt-manager</title>
+        </section>
+
+        <section>
+            <title>Using libvirt</title>
+        </section>
+
+        <section>
+            <title>Using QEMU</title>
+        </section>
+
+        <section>
+            <title>Client</title>
+        </section>
+    </section>
+
+    <section xml:id="multi-monitors">
+        <title>Multiple monitor support</title>
+        <para>
+            Multiple monitor support allows to...
+        </para>
+
+        <section>
+            <title>Using virt-manager</title>
+        </section>
+
+        <section>
+            <title>Using libvirt</title>
+        </section>
+
+        <section>
+            <title>Using QEMU</title>
+        </section>
+
+        <section>
+            <title>Client</title>
+        </section>
+    </section>
+
+    <section xml:id="ssl">
+        <title>SSL</title>
+        <para>
+            SSL support is needed because of xxx and yyy, and prerequisites are zzz.
+        </para>
+
+        <section>
+            <title>Using virt-manager</title>
+        </section>
+
+        <section>
+            <title>Using libvirt</title>
+        </section>
+
+        <section>
+            <title>Using QEMU</title>
+        </section>
+
+        <section>
+            <title>Client</title>
+        </section>
     </section>
 </chapter>
diff --git a/books/docbook/resources/virt-manager-graphics-spice-password.png b/books/docbook/resources/virt-manager-graphics-spice-password.png
new file mode 100644
index 0000000..a21341b
--- /dev/null
+++ b/books/docbook/resources/virt-manager-graphics-spice-password.png
diff --git a/books/docbook/resources/virt-manager-graphics-spice.png b/books/docbook/resources/virt-manager-graphics-spice.png
new file mode 100644
index 0000000..9f07286
--- /dev/null
+++ b/books/docbook/resources/virt-manager-graphics-spice.png
diff --git a/books/docbook/resources/virt-manager-video-qxl.png b/books/docbook/resources/virt-manager-video-qxl.png
new file mode 100644
index 0000000..3ddfb87
--- /dev/null
+++ b/books/docbook/resources/virt-manager-video-qxl.png