Add more user documentation

Document how to use USB redirection, multiple monitors, and how
to setup secure SPICE connections.

1 files changed, 247 insertions, 5 deletions

diff --git a/books/docbook/SpiceUserManual-Basics.xml b/books/docbook/SpiceUserManual-Basics.xml
index dd1eec3..f1da024 100644
--- a/books/docbook/SpiceUserManual-Basics.xml
+++ b/books/docbook/SpiceUserManual-Basics.xml
@@ -327,69 +327,311 @@ host# virsh domdisplay $vmname
     <section xml:id="USB">
         <title>USB redirection</title>
         <para>
-            USB redirection support is needed because of xxx and yyy, and prerequisites are zzz.
+            With USB redirection, USB devices plugged into the client machine can be
+            transparently redirected to the guest OS. This redirection can either be
+            automatic (all newly plugged devices are redirected), or manual
+            (the user selects which devices (s)he wants to redirect).
+        </para>
+        <para>
+            For redirection to work, the virtual machine must have an USB2 EHCI controller
+            (this implies 3 additional UHCI controllers). It also needs to have
+            Spice channels for USB redirection. The number of such channels correspond
+            to the number of USB devices that it will be possible to redirect at the same
+            time.
         </para>
 
         <section>
             <title>Using virt-manager</title>
+            <para>
+                Virtual machines created with virt-manager should have a USB controller
+                by default. In the virtual machine details, select "Controller USB" in
+                the left pane, and make sure its model is set to USB2. You can then
+                click on "Add Hardware" and add as many "USB Redirection" items as
+                the number of USB devices you want to be able to redirect simultaneously.
+            </para>
         </section>
 
         <section>
             <title>Using libvirt</title>
+                <para>
+                    You need to add the needed USB controllers to the libvirt XML (make
+                    sure there is no pre-existing USB controller in your virtual machine
+                    XML before doing this), as well as one Spice USB redirection channel
+                    per device you want to redirect simultaneously.
+                    <programlisting>
+ &lt;controller type='usb' index='0' model='ich9-ehci1'/&gt;
+&lt;controller type='usb' index='0' model='ich9-uhci1'&gt;
+  &lt;master startport='0'/&gt;
+&lt;/controller&gt;
+&lt;controller type='usb' index='0' model='ich9-uhci2'&gt;
+  &lt;master startport='2'/&gt;
+&lt;/controller&gt;
+&lt;controller type='usb' index='0' model='ich9-uhci3'&gt;
+  &lt;master startport='4'/&gt;
+&lt;/controller&gt;
+&lt;redirdev bus='usb' type='spicevmc'/&gt;
+&lt;redirdev bus='usb' type='spicevmc'/&gt;
+&lt;redirdev bus='usb' type='spicevmc'/&gt;
+&lt;redirdev bus='usb' type='spicevmc'/&gt;
+                    </programlisting>
+                </para>
         </section>
 
         <section>
             <title>Using QEMU</title>
+            <para>
+                Similarly to libvirt, we need to add EHCI/UHCI controllers to QEMU
+                command line, and we also need to add one Spice redirection channel per
+                device we want to redirect simultaneously.
+                <screen>
+-device ich9-usb-ehci1,id=usb \
+-device ich9-usb-uhci1,masterbus=usb.0,firstport=0,multifunction=on \
+-device ich9-usb-uhci2,masterbus=usb.0,firstport=2 \
+-device ich9-usb-uhci3,masterbus=usb.0,firstport=4 \
+-chardev spicevmc,name=usbredir,id=usbredirchardev1 \
+-device usb-redir,chardev=usbredirchardev1,id=usbredirdev1 \
+-chardev spicevmc,name=usbredir,id=usbredirchardev2 \
+-device usb-redir,chardev=usbredirchardev2,id=usbredirdev2 \
+-chardev spicevmc,name=usbredir,id=usbredirchardev3 \
+-device usb-redir,chardev=usbredirchardev3,id=usbredirdev3
+                </screen>
+            </para>
         </section>
 
         <section>
             <title>Client</title>
+            <para>
+                The client needs to have support for USB redirection. In remote-viewer,
+                you can select which USB devices to redirect in File/USB device selection
+                once the Spice connection is established. There are also various command
+                line redirection options which are described when running remote-viewer
+                with --help-spice.
+            </para>
         </section>
     </section>
 
     <section xml:id="multi-monitors">
         <title>Multiple monitor support</title>
         <para>
-            Multiple monitor support allows to...
+            When using Spice, it's possible to use multiple monitors. For that, the guest
+            must have multiple QXL devices (for Windows guests), or a single QXL device
+            configured to support multiple heads (for Linux guests).
+        </para>
+        <para>
+            Before following the instructions in this section, make sure your virtual machine
+            already has a QXL device. If that is not the case, refer to
+            <link xlink:href="qemu_spice">this section</link>. Your guest OS will
+            also need to have the QXL driver installed or multiple monitor support will
+            not work.
+        </para>
+        <para>
+            Once your virtual machine is using a QXL device, you don't need to make
+            any other change to get multiple heads in a Linux guest. The following
+            paragraph will deal with adding multiple QXL devices to get multiple
+            monitors in a Windows guest.
         </para>
 
         <section>
             <title>Using virt-manager</title>
+            <para>
+                To add an additional QXL device for Windows guests, simply go to your
+                virtual machine details. Check that you already have a "Video QXL" device,
+                if notclick on "Add Hardware", and add a "Video" device
+                with model "QXL". This can also work with Linux guests if your are willing
+                to configure X.Org to use Xinerama (instead of XRandR).
+            </para>
+            <para>
+                If you are using a new enough distribution (for example Fedora 19), and if your
+                virtual machine already has a QXL device, you should not need to make any changes
+                in virt-manager. If you are using an older distribution, you can't do the required
+                changes from virt-manager, you'll need to edit libvirt XML as described on this
+                <link xlink:href="http://hansdegoede.livejournal.com/12969.html">blog post</link>.
+            </para>
         </section>
 
         <section>
             <title>Using libvirt</title>
+            <para>
+                To add an additional QXL device to your virtual machine managed by
+                libvirt, you simply need to append a new video node whose model is
+                QXL:
+                <programlisting>
+&lt;video&gt;
+    &lt;model type='qxl'&gt;
+&lt;/video&gt;
+&lt;video&gt;
+    &lt;model type='qxl'&gt;
+&lt;/video&gt;
+                </programlisting>
+            </para>
         </section>
 
         <section>
             <title>Using QEMU</title>
+            <para>
+                To get a second QXL device in your virtual machine, you need to append
+                -device qxl to your QEMU command line in addition to the -vga qxl that
+                is already there:
+                <screen>
+-vga qxl -device qxl
+                </screen>
+            </para>
         </section>
 
         <section>
             <title>Client</title>
+            <para>
+                You can enable additional displays either from the Display/Displays menu
+                in remote-viewer, or from your guest OS display configuration tool.
+            </para>
         </section>
     </section>
 
-    <section xml:id="ssl">
-        <title>SSL</title>
+    <section xml:id="tls">
+        <title>TLS</title>
         <para>
-            SSL support is needed because of xxx and yyy, and prerequisites are zzz.
+            TLS support allows to encrypt all/some of the channels Spice uses
+            for its communication.
+            A separate port is used for the encrypted channels.
+            When connecting through a TLS channel, the Spice client will verify
+            the certificate sent by the host. It will check that this
+            certificate matches the hostname it's connecting, and that
+            this certificate is signed by a known certificate authority
+            (CA). This can be achieved by either getting the host
+            certificate signed by an official CA, or by passing to the client
+            the certificate of the authority which signed the host certificate.
+            The latter allows the use of self-signed certificates.
         </para>
 
         <section>
             <title>Using virt-manager</title>
+            <para>
+                It's not possible to define the CA certificate/host certificate
+                to use for the TLS connection using virt-manager, see the next
+                section for how to enable this using libvirt.
+            </para>
         </section>
 
         <section>
             <title>Using libvirt</title>
+            <para>
+                The certificate must be specified in libvirtd configuration
+                file in /etc/libvirt/qemu.conf (or in
+                ~/.config/libvirt/qemu.conf if you are using a session libvirt).
+                See the documentation in this file reproduced below:
+                <screen>
+# Enable use of TLS encryption on the SPICE server.
+#
+# It is necessary to setup CA and issue a server certificate
+# before enabling this.
+#
+spice_tls = 1
+
+
+# Use of TLS requires that x509 certificates be issued. The
+# default it to keep them in /etc/pki/libvirt-spice. This directory
+# must contain
+#
+#  ca-cert.pem - the CA master certificate
+#  server-cert.pem - the server certificate signed with ca-cert.pem
+#  server-key.pem  - the server private key
+#
+# This option allows the certificate directory to be changed.
+#
+spice_tls_x509_cert_dir = "/etc/pki/libvirt-spice"
+                </screen>
+            </para>
+            <para>
+                Once the above is done, when the domain is running, you
+                should get something like what is below if you are leaving
+                Spice port allocation up to libvirt:
+                <screen>
+host# virsh domdisplay
+spice://127.0.0.1?tls-port=5901
+                </screen>
+            </para>
+            <para>
+                This means that the connection is possible both through TLS and
+                without any encryption. You can edit the libvirt graphics node
+                if you want to change that behaviour and only allow connections
+                through TLS:
+                <programlisting>
+&lt;graphics type='spice' autoport='yes' defaultMode='secure'/&gt;
+                </programlisting>
+            </para>
         </section>
 
         <section>
             <title>Using QEMU</title>
+            <para>
+                QEMU expects the certificates to be named the same way as what
+                libvirt expects in the previous paragraph. The directory where
+                these certificates can be found is specified as options to the
+                -spice command line parameters:
+                <screen>
+-spice port=5900,tls-port=5901,disable-ticketing,x509-dir=/etc/pki/libvirt-spice
+                </screen>
+            </para>
         </section>
 
         <section>
             <title>Client</title>
+            <para>
+                We need to change 2 things when starting the client:
+                <itemizedlist>
+                    <listitem>specify the tls port to use</listitem>
+                    <listitem>specify the CA certificate to use when verifying the host certificate</listitem>
+                </itemizedlist>
+                With remote-viewer, this is done this way:
+                <screen>
+client# remote-viewer --spice-ca-file=/etc/pki/libvirt-spice/ca-cert.ca spice://myhost?tls-port=5901
+                </screen>
+            </para>
+        </section>
+
+        <section>
+            <title>Generating self-signed certificates for use with Spice</title>
+            <para>
+                The following script can be used to create the various certificates
+                needed to use a TLS Spice connection. Make sure to substitute the hostname
+                of your Spice host in the subject of the certificate signing request.
+                <screen>
+SERVER_KEY=server-key.pem
+
+# creating a key for our ca
+if [ ! -e ca-key.pem ]; then
+    openssl genrsa -des3 -out ca-key.pem 1024
+fi
+# creating a ca
+if [ ! -e ca-cert.pem ]; then
+    openssl req -new -x509 -days 1095 -key ca-key.pem -out ca-cert.pem -utf8 -subj "/C=IL/L=Raanana/O=Red Hat/CN=my CA"
+fi
+# create server key
+if [ ! -e $SERVER_KEY ]; then
+    openssl genrsa -out $SERVER_KEY 1024
+fi
+# create a certificate signing request (csr)
+if [ ! -e server-key.csr ]; then
+    openssl req -new -key $SERVER_KEY -out server-key.csr -utf8 -subj "/C=IL/L=Raanana/O=Red Hat/CN=myhostname.example.com"
+fi
+# signing our server certificate with this ca
+if [ ! -e server-cert.pem ]; then
+    openssl x509 -req -days 1095 -in server-key.csr -CA ca-cert.pem -CAkey ca-key.pem -set_serial 01 -out server-cert.pem
+fi
+
+# now create a key that doesn't require a passphrase
+openssl rsa -in $SERVER_KEY -out $SERVER_KEY.insecure
+mv $SERVER_KEY $SERVER_KEY.secure
+mv $SERVER_KEY.insecure $SERVER_KEY
+
+# show the results (no other effect)
+openssl rsa -noout -text -in $SERVER_KEY
+openssl rsa -noout -text -in ca-key.pem
+openssl req -noout -text -in server-key.csr
+openssl x509 -noout -text -in server-cert.pem
+openssl x509 -noout -text -in ca-cert.pem
+                </screen>
+            </para>
         </section>
     </section>
 </chapter>