[Spice-commits] Makefile.am configure.ac docs/Makefile.am docs/manual
Christophe Fergau
teuf at kemper.freedesktop.org
Mon Jan 20 03:19:52 PST 2014
Makefile.am | 3
configure.ac | 21
docs/Makefile.am | 3
docs/manual/Makefile.am | 38 +
docs/manual/SpiceUserManual-Basics.xml | 689 +++++++++++++++++++++++++++
docs/manual/SpiceUserManual-Guest.xml | 54 ++
docs/manual/SpiceUserManual-Installation.xml | 199 +++++++
docs/manual/SpiceUserManual-Introduction.xml | 264 ++++++++++
docs/manual/SpiceUserManual-References.xml | 218 ++++++++
docs/manual/SpiceUserManual.xml | 71 ++
docs/manual/resources/pepper.png |binary
docs/manual/resources/spicec01.png |binary
12 files changed, 1559 insertions(+), 1 deletion(-)
New commits:
commit 7095563153af0e3481605eb5979ca8e6982d95cc
Author: Christophe Fergeau <cfergeau at redhat.com>
Date: Mon Jan 13 20:01:42 2014 +0100
Add reference manual
This manual documents how to enable/use various SPICE features when
creating a VM by running QEMU directly, or when using libvirt, or when
using virt-manager.
This is based on work by Lubos Kocman
diff --git a/Makefile.am b/Makefile.am
index e260e00..c7a0e92 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,7 +1,7 @@
NULL =
ACLOCAL_AMFLAGS = -I m4
-SUBDIRS = spice-common server
+SUBDIRS = spice-common server docs
if SUPPORT_CLIENT
SUBDIRS += client
@@ -15,6 +15,7 @@ DISTCHECK_CONFIGURE_FLAGS = \
--enable-opengl \
--enable-smartcard \
--with-sasl \
+ --enable-manual \
$(NULL)
EXTRA_DIST = \
diff --git a/configure.ac b/configure.ac
index c897368..aaa7ffc 100644
--- a/configure.ac
+++ b/configure.ac
@@ -415,6 +415,23 @@ if test "x$enable_automated_tests" = "xyes"; then
AC_MSG_RESULT([found])
fi
+
+AC_ARG_ENABLE([manual],
+ AS_HELP_STRING([--enable-manual=@<:@auto/yes/no@:>@],
+ [Build SPICE manual]),
+ [],
+ [enable_manual="auto"])
+if test "x$enable_manual" != "xno"; then
+ AC_PATH_PROG([XMLTO], [xmlto])
+ AS_IF([test -z "$XMLTO" && test "x$enable_manual" = "xyes"],
+ [AC_MSG_ERROR([xmlto is missing and build of manual was requested])]
+ [have_xmlto = no]
+ )
+fi
+AS_IF([test -n "$XMLTO"], [have_xmlto=yes], [have_xmlto=no])
+AM_CONDITIONAL([BUILD_MANUAL], [test -n "$XMLTO"])
+
+
dnl ===========================================================================
dnl check compiler flags
@@ -495,6 +512,8 @@ spice-server.pc
server/Makefile
server/tests/Makefile
client/Makefile
+docs/Makefile
+docs/manual/Makefile
])
dnl ==========================================================================
@@ -525,6 +544,8 @@ echo "
SASL support: ${enable_sasl}
Automated tests: ${enable_automated_tests}
+
+ Manual: ${have_xmlto}
"
if test $os_win32 == "yes" ; then
diff --git a/docs/Makefile.am b/docs/Makefile.am
new file mode 100644
index 0000000..18e785f
--- /dev/null
+++ b/docs/Makefile.am
@@ -0,0 +1,3 @@
+if BUILD_MANUAL
+SUBDIRS = manual
+endif
diff --git a/docs/manual/Makefile.am b/docs/manual/Makefile.am
new file mode 100644
index 0000000..75cc4f7
--- /dev/null
+++ b/docs/manual/Makefile.am
@@ -0,0 +1,38 @@
+SUFFIXES = .xml .html .txt .1
+
+# apparently, xmlto does not support validation of docbook5 docs
+# that's why it's disabled with --skip-validation
+.xml.html:
+ $(AM_V_GEN)$(XMLTO) --skip-validation -o html xhtml $<
+
+.xml.1:
+ $(AM_V_GEN)$(XMLTO) --skip-validation -o man man $<
+
+.xml.txt:
+ $(AM_V_GEN)$(XMLTO) --skip-validation -o txt txt $<
+
+all: allhtml manpages
+
+XMLMAN =
+XMLDOC = \
+ SpiceUserManual-Basics.xml \
+ SpiceUserManual-Guest.xml \
+ SpiceUserManual-Installation.xml \
+ SpiceUserManual-Introduction.xml \
+ SpiceUserManual-References.xml \
+ SpiceUserManual.xml
+XMLALL = $(XMLMAN) $(XMLDOC)
+SOURCES = $(XMLALL) $(TXTDOC)
+
+allhtml: $(XMLALL:.xml=.html)
+
+manpages: $(XMLMAN:.xml=.1)
+
+# Control what goes in the distribution tarball.
+# We include all of the XML, and also generated HTML pages
+# so people working from the distribution tarball won't need xmlto.
+EXTRA_DIST = $(SOURCES) html
+
+clean-local:
+ rm -fr html $(XMLMAN:.xml=.1)
+
diff --git a/docs/manual/SpiceUserManual-Basics.xml b/docs/manual/SpiceUserManual-Basics.xml
new file mode 100644
index 0000000..dfc8e56
--- /dev/null
+++ b/docs/manual/SpiceUserManual-Basics.xml
@@ -0,0 +1,689 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<?oxygen RNGSchema="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" type="xml"?>
+
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="basics">
+ <title>Spice basics</title>
+ <section xml:id="definitions">
+ <title>Basic Definitions</title>
+ <section xml:id="host">
+ <title>Host</title>
+ <para>Host is a machine running an instance of qemu-kvm.</para>
+ </section>
+
+ <section xml:id="guest">
+ <title>Guest</title>
+ <para>
+ Guest is a virtual machine hosted on the <link linkend="host">host</link>
+ which will be accessed with a spice client.
+ </para>
+ </section>
+
+ <section xml:id="client">
+ <title>Client</title>
+ <para>
+ Client is referring to a system running the spice client
+ (the recommended one is virt-viewer).
+ </para>
+ </section>
+ </section>
+
+ <section xml:id="qemu_basics">
+ <title>Launching qemu</title>
+ <para>I'll use qemu-kvm as a name for the executable. If you're using a manually built qemu or
+ a qemu without kvm then just replace qemu-kvm with your own binary. I'll use host# client#
+ guest# shell prompt notations to distinguish where the command should be the command. See
+ section <link xlink:href="definitions">Basic Definitions</link> to be sure that you know
+ difference between the host, client and guest. You can ignore the difference between guest, client
+ and host if they are all running on the same machine.</para>
+
+ <para>
+ <emphasis role="bold">The first important thing to do is to create a guest
+ image.</emphasis> You can use any raw device such as a clean logical volume, or an iSCSI
+ lun. You may also use a file as the disk image for the guest. I'll use a file created by qemu-img as a demonstration.
+ </para>
+
+ <para>
+ The following command will allocate a 10GB file. See qemu-img man page for further information.
+ </para>
+
+ <screen>host# qemu-img create /path/to/xp.img 10G</screen>
+
+ <para>
+ Now that we created an image, we can now start with image population. I assume that you have
+ a locally stored ISO of your favourite operating system so you can use it for installation.
+ </para>
+
+ <screen>host# sudo qemu-kvm -boot order=dc -vga qxl \
+ -spice port=3001,disable-ticketing -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>
+
+ <para>
+ Let's take a brief look at the qemu options that were used. The option -boot order=dc specifies that the guest system
+ should try to boot from the first cdrom and then fallback to the first disk, -vga qxl specifies that qemu should
+ emulate the qxl device adapter.
+ </para>
+ <para> The Spice port option defines what port will be used for communication with the client. The Spice
+ option disable-ticketing is telling us that ticketing <emphasis role="italic">(simple
+ authentication method)</emphasis> is not used. The virtio and chardev devices are
+ required by <link xlink:href="SpiceUserManual-Introduction.xml#vdagent">the guest
+ agent</link>.
+ </para>
+ </section>
+
+ <section xml:id="qemu_spice">
+ <title>Adding Spice support to an existing virtual machine</title>
+ <para>
+ 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>
+<graphics type='spice'/>
+ </programlisting>
+ You should also add a <link xlink:href="http://libvirt.org/formatdomain.html#elementsVideo">QXL video device</link>
+ <programlisting>
+<video>
+ <model type='qxl'>
+</video>
+ </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>
+ 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>
+
+ <para>
+ 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>
+
+ <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>
+<graphics type='spice' passwd='mysecretpassword'/>
+ </programlisting>
+ </para>
+ </section>
+
+ <section>
+ <title>Using QEMU</title>
+ <para>
+ Adding a ticket with QEMU involves a slight modification of the -spice
+ parameter 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>
+ <para>
+ 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>
+<devices>
+ <controller type='virtio-serial' index='0'/>
+ <channel type='spicevmc'>
+ <target type='virtio' name='com.redhat.spice.0'/>
+ </channel>
+</devices>
+ </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>
+ 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>
+ <controller type='usb' index='0' model='ich9-ehci1'/>
+<controller type='usb' index='0' model='ich9-uhci1'>
+ <master startport='0'/>
+</controller>
+<controller type='usb' index='0' model='ich9-uhci2'>
+ <master startport='2'/>
+</controller>
+<controller type='usb' index='0' model='ich9-uhci3'>
+ <master startport='4'/>
+</controller>
+<redirdev bus='usb' type='spicevmc'/>
+<redirdev bus='usb' type='spicevmc'/>
+<redirdev bus='usb' type='spicevmc'/>
+<redirdev bus='usb' type='spicevmc'/>
+ </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>
+ 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>
+<video>
+ <model type='qxl'>
+</video>
+<video>
+ <model type='qxl'>
+</video>
+ </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="tls">
+ <title>TLS</title>
+ <para>
+ 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>
+<graphics type='spice' autoport='yes' defaultMode='secure'/>
+ </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>
+
+ <section xml:id="sasl">
+ <title>SASL</title>
+ <para>
+ Spice server and client have support for SASL authentication. When using QEMU, /etc/sasl2/qemu.conf will be
+ used as a configuration file. For testing, you can use the digest-md5 mechanism, and populate a test database
+ using 'saslpasswd2 -f /etc/qemu/passwd.db -c foo'. These files have to be readable by the qemu process that will
+ handle your VM.
+ </para>
+
+ <para>
+ To troubleshoot SASL issues, running strace -e open on the QEMU process can be a useful first step.
+ </para>
+
+
+ <section>
+ <title>Using virt-manager</title>
+ <para>
+ It's currently not possible to enable SASL from virt-manager.
+ </para>
+ </section>
+
+ <section>
+ <title>Using libvirt</title>
+ <para>
+ SASL support for SPICE has been added to libvirt mid-October 2013 so you need a libvirt version
+ that was released after this date. To enable SASL, you need to add spice_sasl = 1 in /etc/libvirt/qemu.conf
+ for the system libvirtd instance, and to ~/.config/libvirt/qemu.conf for the session libvirtd instance.
+ </para>
+ </section>
+
+ <section>
+ <title>Using QEMU</title>
+ <para>
+ Using SASL with QEMU involves a slight modification of the -spice
+ parameter used when running QEMU:
+ <screen>
+-spice port=3001,sasl
+ </screen>
+ </para>
+ </section>
+
+ <section>
+ <title>Client</title>
+ <para>
+ When you start the client as usual, if SASL 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>
+ </section>
+ </section>
+</chapter>
diff --git a/docs/manual/SpiceUserManual-Guest.xml b/docs/manual/SpiceUserManual-Guest.xml
new file mode 100644
index 0000000..6648f83
--- /dev/null
+++ b/docs/manual/SpiceUserManual-Guest.xml
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<?oxygen RNGSchema="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" type="xml"?>
+
+<chapter xmlns="http://docbook.org/ns/docbook"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
+ <title>Spice Guest Additions</title>
+
+ <section xml:id="generic-guest">
+ <title>Introduction</title>
+ <para>
+ While you will be able to remotely access your virtual machine
+ through Spice without making any change to the virtual machine
+ configuration, you can get better integration if you tweak it
+ specially for Spice.
+ </para>
+ <para>
+ If your virtual machine has a QXL video device and you install
+ the corrresponding guest driver, your guest will support higher
+ resolutions, multiple monitors, resizing to arbitrary resolutions,
+ ...
+ </para>
+ <para>
+ Installing the Spice vdagent in your guest will let you copy and
+ paste between your guest and client OSes, to drag and drop files
+ between the 2 OSes, ... In order for the agent to work, your
+ virtual machine must have a virtio serial device (and the
+ corresponding guest drivers) as well as a Spice spicevmc channel.
+ </para>
+ </section>
+
+ <section xml:id="windows-guest">
+ <title>Windows Guest</title>
+ <para>
+ The recommended way of getting all the needed drivers installed is
+ to use the all-in-one Spice guest tools installer which can be
+ found <link xlink:href="http://spice-space.org/download/windows/spice-guest-tools/">
+ on spice-space.org</link>.
+ </para>
+ <para>
+ To get USB redirection working on Windows, you need to ...
+ </para>
+ <para>
+ If you want to manually install them, the QXL driver can be downloaded from
+ <link xlink:href="http://spice-space.org/download/windows/qxl/">this location
+ </link>, agent builds can be found
+ <link xlink:href="http://spice-space.org/download/windows/vdagent/">here
+ </link>. You also need the vioserial driver which is distributed with the
+ other <link xlink:href="https://alt.fedoraproject.org/pub/alt/virtio-win/latest/images/bin/">
+ virtio-win drivers</link>.
+ </para>
+ </section>
+
+</chapter>
diff --git a/docs/manual/SpiceUserManual-Installation.xml b/docs/manual/SpiceUserManual-Installation.xml
new file mode 100644
index 0000000..4e883ac
--- /dev/null
+++ b/docs/manual/SpiceUserManual-Installation.xml
@@ -0,0 +1,199 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<?oxygen RNGSchema="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" type="xml"?>
+
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
+ <title>Installation</title>
+
+ <section xml:id="rhel_fedora">
+ <title>Installing Spice on RHEL or Fedora </title>
+ <para>
+ Be aware that RHEL has no builds of qemu/spice-server for i386, only x86_64 builds are available.
+ </para>
+ <section>
+ <title>RHEL >=6 and Fedora >=13</title>
+ <para>
+ <screen>yum install qemu-kvm virt-viewer</screen>
+ </para>
+ <para>
+ The package spice-protocol will be downloaded automatically as a dependency of package kvm.
+ </para>
+ </section>
+ <section><title>RHEVM Users</title>
+ <para>
+ <emphasis role="bold">
+ <link xlink:href="http://www.ovirt.org">oVirt</link>/RHEVM users
+ could be also interested in the spice-xpi package as it allows you
+ to execute spice-client directly from the oVirt/RHEVM UserPortal.
+ </emphasis>
+ <screen>yum install spice-xpi</screen>
+ </para>
+ </section>
+ </section>
+
+ <section xml:id="linux_generic">
+ <title>Generic Build Instructions</title>
+
+ <para>
+ This section is for distributions that don't have *spice* packages in their repositories.
+ It will show you step by step how to build the required spice components.
+ </para>
+
+ <section xml:id="req_client">
+ <title>Client requirements</title>
+
+ <orderedlist>
+ <listitem><para><emphasis role="bold">autotools</emphasis></para></listitem>
+ <listitem><para><emphasis role="bold">gtk+2 > 2.18 or gtk+3</emphasis></para></listitem>
+ <listitem><para><emphasis role="bold">celt = 0.5.1.3</emphasis> The exact version is required due to the lack of backwards compatibility in newer celt releases.</para></listitem>
+ <listitem><para><emphasis role="bold">cyrus-sasl</emphasis></para></listitem>
+ <listitem><para><emphasis role="bold">pixman</emphasis></para></listitem>
+ <listitem><para><emphasis role="bold">openssl</emphasis></para></listitem>
+ <listitem><para><emphasis role="bold">pyparsing</emphasis></para></listitem>
+ <listitem><para><emphasis role="bold">usbredir</emphasis></para></listitem>
+ <listitem><para><emphasis role="bold">PolicyKit</emphasis></para></listitem>
+ </orderedlist>
+ </section>
+
+ <section xml:id="req_host">
+ <title>Host requirements</title>
+ <orderedlist>
+ <listitem><para><emphasis role="bold">KVM supported by kernel</emphasis> (It should work also without KVM, but
+ it's not being tested as most Linux distrubitions already support
+ KVM.)</para></listitem>
+ </orderedlist>
+
+ </section>
+
+ <section>
+ <title>Guest requirements</title>
+ <section>
+ <title>Linux Guest</title>
+ <para>
+ spice-vdagent requires virtio-serial support to be enabled. This is described in the <link xlink:href="SpiceUserManual-Basics.xml#basics">chapter Spice basics</link>.
+ Guest should have installed qxl driver (xorg-x11-drv-qxl on Fedora and RHEL).
+ </para>
+ </section>
+ <section>
+ <title>Windows Guest</title>
+ <para>
+ Drivers for QXL and drivers for virtio-serial require Win XP SP3 and Win 7.
+ </para>
+ </section>
+
+ <section xml:id="setting_be">
+ <title>Setting up the build environment</title>
+
+ <para>
+ <emphasis role="bold">This is a list of prerequisites on RHEL or Fedora. Install
+ equivalent packages for your distribution in case that you're not using RHEL
+ or Fedora.</emphasis>
+ </para>
+ <para>
+ <emphasis role="bold">All prerequisites for Windows are available in one big package which is available
+ at <link xlink:href="http://spice-space.org/download.html">http://spice-space.org/download.html</link>.</emphasis>
+ </para>
+ <screen>yum install git pixman-devel celt051-devel cegui-devel libjpeg-devel alsa-lib-devel log4cpp-devel \
+ openssl-devel libXrandr-devel libgcrypt-devel SDL-devel nss-devel dev86 iasl pyparsing</screen>
+
+ <para>
+ <emphasis role="bold">Package prerequisites for Ubuntu</emphasis>
+ </para>
+ <screen>apt-get install build-essential autoconf git-core libtool liblog4cpp5-dev libavcodec-dev \
+ libssl-dev xlibmesa-glu-dev libasound-dev libpng12-dev libfreetype6-dev libfontconfig1-dev \
+ libogg-dev libxrandr-dev kvm libgcrypt-dev libsdl-dev</screen>
+
+ </section>
+
+ <section xml:id="building_libcacard">
+ <title>Building libcacard</title>
+ <para>Fedora >=14 RHEL >=6.1 has libcacard already available. So you can install it directly trough yum.</para>
+ <screen>yum install libcacard</screen>
+ <para>Otherwise follow these instructions. <emphasis role="bold">The environment
+ variable $BUILD_ROOT will point to a directory with stored sources and will
+ be used during the whole build process. The variable $INST_ROOT will point to a
+ directory in which Spice will be installed.</emphasis></para>
+ <screen>export BUILD_ROOT=/tmp/spice; mkdir $BUILD_ROOT; cd $BUILD_ROOT;
+export INST_ROOT="/opt/spice"; mkdir $INST_ROOT
+git clone git://anongit.freedesktop.org/~alon/libcacard
+cd libcacard
+./configure --prefix=/usr --libdir=/usr/lib64 # Ignore --libdir at Ubuntu
+make
+make install</screen>
+
+ </section>
+
+ <section xml:id="getting_client">
+ <title>Getting client sources</title>
+
+ <screen>cd $BUILD_ROOT
+git clone git://cgit.freedesktop.org/spice/spice-protocol
+git clone git://cgit.freedesktop.org/spice/spice
+wget http://downloads.us.xiph.org/releases/celt/celt-0.5.1.3.tar.gz
+tar xvzf celt-0.5.1.3.tar.gz
+ </screen>
+ </section>
+
+ <section xml:id="getting_server">
+ <title>Getting client/server sources</title>
+ <para>Skip this section if you don't want to build server side.</para>
+ <screen>cd $BUILD_ROOT
+git clone git://cgit.freedesktop.org/spice/qemu
+cd qemu; git checkout -b spice.v13 origin/spice.v13; cd ..
+git clone git://cgit.freedesktop.org/spice/spice-protocol
+git clone git://cgit.freedesktop.org/spice/spice
+git clone git://cgit.freedesktop.org/spice/win32/vd_agent
+git clone git://cgit.freedesktop.org/spice/win32/qxl
+git clone git://cgit.freedesktop.org/spice/slirp
+wget http://downloads.us.xiph.org/releases/celt/celt-0.5.1.3.tar.gz
+tar xvzf celt-0.5.1.3.tar.gz</screen>
+
+ </section>
+
+ <section xml:id="building_common">
+ <title>Building common sources.</title>
+ <para>This part applies to both server and client build process.</para>
+ <screen>cd $BUILD_ROOT/spice-protocol
+mkdir m4
+./autogen.sh --prefix=$INST_ROOT
+sudo make install
+cd $BUILD_ROOT/celt-0.5.1.3
+./configure --prefix=$INST_ROOT
+sudo make install
+</screen>
+
+ </section>
+ <section>
+ <title>Building client side tools</title>
+ <screen>cd $BUILD_ROOT/spice
+./autogen.sh --prefix=$INST_ROOT --enable-smartcard
+cd client
+sudo make install</screen>
+ </section>
+
+ <section>
+ <title>Building server side tools</title>
+ <para>These instructions contain flags for a minimal working build of qemu with Spice support enabled.
+ You might want to build qemu with the --enable-io-thread option</para>
+ <screen>cd $SRC_ROOT/qemu
+./configure --prefix=$INST_ROOT --target-list=x86_64-softmmu --enable-spice
+make</screen>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Setting up PATH</title>
+ <para>Last steps before starting with Spice are to set proper PATH variable.
+ For example RHEL is using /usr/libexec as directory for spicec and qemu-kvm binaries.
+ The following setup should be suitable for qemu and Spice built according to the instructions in
+ this chapter.</para>
+
+
+ <screen>echo "export PATH=$PATH:$INST_ROOT/bin:$BUILD_ROOT/x86_64-softmmu >> ~/.bashrc
+source ~/.bashrc</screen>
+
+ <para>You should now be able to access the qemu-system-x86_64 and spicec binaries.</para>
+ </section>
+ </section>
+
+</chapter>
diff --git a/docs/manual/SpiceUserManual-Introduction.xml b/docs/manual/SpiceUserManual-Introduction.xml
new file mode 100644
index 0000000..f5618bd
--- /dev/null
+++ b/docs/manual/SpiceUserManual-Introduction.xml
@@ -0,0 +1,264 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<?oxygen RNGSchema="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" type="xml"?>
+
+ <chapter xmlns="http://docbook.org/ns/docbook"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
+ <title>Introduction</title>
+ <para>
+ Spice is an open remote computing solution, providing client access to remote displays and devices (e.g. keyboard, mouse, audio).
+ At the moment, it's mainly used to get remote access to virtual machines. Spice provides a desktop-like user experience, while trying to
+ offload most of the intensive CPU and GPU tasks to the client.
+
+ The basic building blocks of Spice are:
+ </para>
+
+ <orderedlist>
+ <listitem><para><link linkend="spice_server">Spice Server</link></para></listitem>
+ <listitem><para><link linkend="spice_client">Spice Client</link></para></listitem>
+ <listitem><para>Spice Protocol</para></listitem>
+ </orderedlist>
+
+ <para>
+ The following sections provide basic information on Spice components and features, obtaining, building installing and using Spice.
+ </para>
+
+ <section>
+ <title>Spice and Spice-related Components</title>
+ <section xml:id="spice_server">
+ <title>Spice Server</title>
+ <para>
+ Spice server is implemented in libspice, a VDI pluggable library.
+ Currently, the main user of this library is QEMU. QEMU uses spice-server
+ to provide remote access to virtual machines through the Spice protocol.
+ Virtual Device Interface (VDI) defines a set of interfaces that provide
+ a standard way to publish virtual devices (e.g. display device, keyboard,
+ mouse) and enables different Spice components to interact with those
+ devices. On one side, the server communicates with the remote client
+ using the Spice protocol and on the other side, it interacts with the
+ VDI host application (e.g QEMU).
+ </para>
+ </section>
+
+ <section xml:id="spice_client">
+ <title>Spice Client</title>
+ <para>
+ The Spice client is a cross-platform (Linux and Windows)
+ which is used by the end user to access remote systems through Spice.
+ The recommended client is <link xlink:href="https://fedorahosted.org/released/virt-viewer/">remote-viewer</link>
+ (which is shipped with virt-viewer).
+ <link xlink:href="https://wiki.gnome.org/Apps/Boxes">GNOME Boxes</link>
+ can also be used as a Spice client. spicec is an obsolete
+ legacy client, and spicy is only a test application.
+ </para>
+ </section>
+
+ <section>
+ <title>QXL Device and Drivers</title>
+ <para>
+ Spice server supports the QXL VDI interface. When libspice is used with
+ QEMU, a specific video PCI device can be used for improving
+ remote display performance and enhancing the graphic capabilities of the
+ guest graphic system. This video device is called a QXL
+ device and requires guest QXL drivers for full functionality. However,
+ standard VGA is supported when no driver exists.
+ </para>
+ </section>
+
+ <section xml:id="vdagent">
+ <title>Spice Agent</title>
+ <para>
+ The Spice agent is an optional component for enhancing user
+ experience and performing guest-oriented management tasks.
+ For example, the agent injects mouse position and state to
+ the guest when using client mouse mode. It also enables you to
+ move cursor freely between guest and client. Other features
+ of agent are shared clipboard (copy and paste between guest and host)
+ and aligning guest resolution with client when entering fullscreen mode.
+ </para>
+ </section>
+
+ <section>
+ <title>VDI Port Device</title>
+ <para>
+ Spice protocol supports a communication channel between the
+ client and the agent on the server side. When using QEMU, Spice agent
+ resides on the guest. VDI port is a QEMU PCI device used
+ for communication with the agent.
+ </para>
+ </section>
+
+ </section>
+
+ <section xml:id="features">
+ <title>Features</title>
+ <para>
+ The server and client communicate via channels. Each channel is dedicated to
+ a specific type of data. The available channels are following.
+ </para>
+ <section xml:id="multiple_channels">
+ <title>Multiple Channels</title>
+
+ <orderedlist numeration="arabic">
+ <listitem>
+ <para><emphasis role="bold">Main</emphasis> - control and configuration</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">Display</emphasis> - graphics commands images and video streams</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">Inputs</emphasis> - keyboard and mouse inputs</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">Cursor</emphasis> - pointer device position and cursor shape</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">Playback</emphasis> - audio received from the server to be played by the client</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">Record</emphasis> - audio captured on the client side</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">Smartcard</emphasis> - passthrough of smartcard data from the client machine to the guest OS</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">USB</emphasis> - redirection of USB devices plugged into the client to the guest OS</para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section xml:id="image_compression">
+ <title>Image Compression</title>
+
+ <para>
+ Spice offers several image compression algorithms, which
+ can be chosen on server initiation and dynamically at run-time. Quic is a
+ Spice proprietary image compression technology based on the SFALIC
+ algorithm. The Lempel-Ziv (LZ) algorithm is another option. Both Quic and
+ LZ are local algorithms encoding each image separately. Global LZ (GLZ) is
+ another proprietary Spice technology that uses LZ with history-based global
+ dictionary. GLZ takes advantage of repeating patterns among images to
+ shrink the traffic and save bandwidth, which is critical in a WAN
+ environment. Spice also offers an automatic mode for compression selection
+ per image, where the choice between LZ/GLZ and Quic is heuristically based
+ on image properties. Conceptually, synthetic images are better compressed
+ with LZ/GLZ and real images are better with Quic.
+ </para>
+ </section>
+
+ <section xml:id="video_compression">
+ <title>Video Compression</title>
+
+ <para>
+ Spice uses loss-less compression for images sent to the
+ client. However, video streams are handled differently. Spice server
+ heuristically identifies video areas and sends them as a video stream coded
+ using M-JPEG. This handling saves a lot of traffic, improving Spice
+ performance, especially in a WAN environment. However, in some
+ circumstances the heuristic behavior might cause low quality images (e.g.
+ identifying updated text area as a video stream). Video streaming can be
+ chosen on server initiation and dynamically at run-time.
+ </para>
+ </section>
+
+ <section xml:id="mouse_modes">
+ <title>Mouse modes</title>
+
+ <para>
+ Spice supports two mouse modes: server and client. The mode
+ can be changed dynamically and is negotiated between the client and the
+ server.
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">Server mouse</emphasis> - When a user
+ clicks inside the Spice client window, the client mouse is
+ captured and set invisible. In this mode, the server controls
+ the mouse position on display. However, it might be problematic
+ on WAN or on a loaded server, where mouse cursor might have some
+ latency or non-responsiveness.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis role="bold">Client mouse</emphasis> - Not
+ captured and is used as the effective pointing device. To enable
+ client mouse, the VDI host application must register an absolute
+ pointing device (e.g. USB tablet in QEMU). This mode is
+ appropriate for WAN or or for a loaded server, since cursor has
+ smooth motion and responsiveness. However, the cursor might
+ lose synchronization (position and shape) for a while.
+ </para>
+ </listitem>
+
+ </orderedlist>
+ </section>
+
+ <section xml:id="other_features">
+ <title>Other Features</title>
+ <orderedlist>
+
+ <listitem>
+ <para>
+ <emphasis role="bold">Multiple Monitors</emphasis> - any number of monitors is supported
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis role="bold">Arbitrary Resolution</emphasis> - when
+ using the QXL driver, the resolution of the guest OS will be
+ automatically adjusted to the size of the client window.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis role="bold">USB Redirection</emphasis> - Spice
+ can be used to redirect USB devices that are plugged in the
+ client 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>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis role="bold">Smartcard Redirection</emphasis> -
+ data from smartcard that are inserted into the client machine
+ can be passed through to the guest OS. The smartcard can be
+ used by both the client OS and the guest OS.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis role="bold">Bidirectional Audio</emphasis> - Spice supports audio playback and recording. Playback is compressed using the CELT algorithm
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis role="bold">Lip-sync</emphasis> - between video and audio. Available only when video streaming is enabled.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis role="bold">Migration</emphasis> - switching channel connectivity for supporting server migration
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis role="bold">Pixmap and Palette caching</emphasis>
+ </para>
+ </listitem>
+
+ </orderedlist>
+ </section>
+ </section>
+
+</chapter>
diff --git a/docs/manual/SpiceUserManual-References.xml b/docs/manual/SpiceUserManual-References.xml
new file mode 100644
index 0000000..6fcee02
--- /dev/null
+++ b/docs/manual/SpiceUserManual-References.xml
@@ -0,0 +1,218 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<?oxygen RNGSchema="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" type="xml"?>
+
+<chapter xmlns="http://docbook.org/ns/docbook"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
+ <title>QEMU Spice Reference</title>
+
+ <section xml:id="commandline-spice">
+ <title>QEMU Spice command line options</title>
+ <para>
+ They are covered in <link xlink:href="http://qemu.weilnetz.de/qemu-doc.html#index-g_t_002dspice-58">QEMU online documentation</link>.
+ Basic syntax is -spice <spice_options>
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ [port=<port>][,tls-port=<tls-port>][,addr=<addr>]
+ Listen on interface addr <addr> (if given, otherwise any interface)
+ using port <port> and/or tls-port <tls-port> (at least one of them must be given)
+ </listitem>
+
+ <listitem>
+ ipv4=<on|off>
+ IPv4 only (default:off)
+ </listitem>
+
+ <listitem>
+ ipv6=<on|off>
+ IPv6 only (default:off)
+ </listitem>
+
+<!-- Image, video & audio options -->
+ <listitem>
+ image-compression=on|auto_glz|auto_lz|quic|glz|lz|off
+ Set image compression (default=on=auto_glz)
+ quic is based on the SFALIC algorithm
+ lz is the Lempel-Ziv algorithm, glz uses lz with history based global dictionary
+ The auto_[glz/lz] modes choose between the [glz/lz] and quic,
+ based on the image properties
+ </listitem>
+
+ <listitem>
+ streaming-video=<all|filter|off>
+ Set video streams detection and (lossy) compression (default=filter)
+ </listitem>
+
+ <listitem>
+ playback-compression=<on|off>
+ Set playback compression, using the CELT algorithm (default=on)
+ </listitem>
+
+ <listitem>
+ jpeg-wan-compression=<auto|never|always>
+ (default = auto)
+ </listitem>
+
+ <listitem>
+ zlib-glz-wan-compression=<auto|never|always>
+ (default = auto)
+ </listitem>
+
+<!-- Security options -->
+ <listitem>
+ disable-ticketing
+ Enables client connection with no password.
+ </listitem>
+
+ <listitem>
+ password=<password>
+ Set ticket password, which must be used by a client for connection. The passwords never expires.
+ </listitem>
+
+ <listitem>
+ sasl=<on|off>
+ </listitem>
+
+ <listitem>
+ x509-dir=<dir_name>
+ </listitem>
+
+ <listitem>
+ x509-key-file=<key_file>
+ TLS private key file
+ </listitem>
+
+ <listitem>
+ x509-key-password=<pem_password>
+ Password to open the private key file which is in PEM format
+ </listitem>
+
+ <listitem>
+ x509-cert-file=<cert_file>
+ TLS certificate file
+ </listitem>
+
+ <listitem>
+ tls-cacert-file=<ca_file>
+ SSL certificates file of the trusted CA (certificate authority) and CRL (certificate revocation list)
+ </listitem>
+
+ <listitem>
+ x509-dh-key-file=<dh_file>
+ Symmetric Diffie-Hellman key file
+ </listitem>
+
+ <listitem>
+ tls-ciphers=<ciphers>
+ Cipher suite to use, see http://www.openssl.org/docs/apps/ciphers.html or ciphers(1)
+ </listitem>
+
+ <listitem>
+ tls-channel=[all|channel_name]
+ plaintext-channel=[all|channel_name]
+ Force TLS/plain text connection on all/specific channels. This option
+ can be specified multiple times in order to force multiple channels
+ to use TLS or plain text.
+ Channels are: main, display, inputs, cursor, playback and record
+ By default, any channel allows both TLS and plain text connection, depending on the
+ port and tls-port parameters.
+ </listitem>
+
+<!-- Other options -->
+
+ <listitem>
+ agent-mouse=<on|off>
+ Define whether spice agent is used for client mouse mode (default=on)
+ </listitem>
+
+ <listitem>
+ disable-copy-paste=<on|off>
+ (default=off)
+ </listitem>
+
+ <listitem>
+ disable-agent-file-xfer=<on|off>
+ (default=off)
+ </listitem>
+
+ <listitem>
+ seamless-migration=<on|off>
+ (default=off)
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section xml:id="commandline-qxl">
+ <title>QEMU QXL command line options</title>
+ <itemizedlist>
+ <listitem>
+ ram_size
+ </listitem>
+ <listitem>
+ vram_size
+ </listitem>
+ <listitem>
+ revision
+ </listitem>
+ <listitem>
+ debug
+ </listitem>
+ <listitem>
+ guestdebug
+ </listitem>
+ <listitem>
+ cmdlog
+ </listitem>
+ <listitem>
+ ram_size_mb
+ </listitem>
+ <listitem>
+ vram_size_mb
+ </listitem>
+ <listitem>
+ vram64_size_mb
+ </listitem>
+ <listitem>
+ vgamem_mb
+ </listitem>
+ <listitem>
+ surfaces
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section xml:id="console-control">
+ <title>QEMU Console Spice control commands</title>
+ <itemizedlist>
+ <listitem>
+ set_password spice <password> [keep|disconnect]
+ Set the spice connection ticket (one time password). An
+ empty password prevents any connection. keep/disconnect
+ indicates what to do if a client is already connected
+ when the command is issued.
+ </listitem>
+
+ <listitem>
+ expire_password
+ </listitem>
+
+ <listitem>
+ client_migrate_info
+ </listitem>
+
+ </itemizedlist>
+ </section>
+
+ <section xml:id="console-info">
+ <title>QEMU Console Spice info commands</title>
+ <itemizedlist>
+ <listitem>
+ info spice
+ Show current spice state
+ </listitem>
+ </itemizedlist>
+ </section>
+
+</chapter>
diff --git a/docs/manual/SpiceUserManual.xml b/docs/manual/SpiceUserManual.xml
new file mode 100644
index 0000000..d710636
--- /dev/null
+++ b/docs/manual/SpiceUserManual.xml
@@ -0,0 +1,71 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<?oxygen RNGSchema="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" type="xml"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V5.0//EN"
+ "http://docbook.org/xml/5.0/dtd/docbook.dtd">
+<book xmlns="http://docbook.org/ns/docbook"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:lang="en">
+ <info>
+ <title>Spice User Manual</title>
+
+ <authorgroup>
+ <author>
+ <personname>Lubos Kocman</personname>
+ <email>lkocman at redhat.com</email>
+ </author>
+ <author>
+ <personname>Arnon Giloba</personname>
+ <email>agiloba at redhat.com</email>
+ </author>
+ <author>
+ <personname>Yaniv Kamay</personname>
+ <email>ykamay at redhat.com</email>
+ </author>
+ <author>
+ <personname>Christophe Fergeau</personname>
+ <email>cfergeau at redhat.com</email>
+ </author>
+ </authorgroup>
+
+ <copyright>
+ <year>2009</year>
+ <year>2010</year>
+ <year>2011</year>
+ <year>2013</year>
+ <holder>Red Hat, Inc.</holder>
+ </copyright>
+
+ <legalnotice>
+ <para>
+ Licensed under a Creative Commons Attribution-Share Alike 3.0 United States License
+ (see <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://creativecommons.org/licenses/by-sa/3.0/us/legalcode">http://creativecommons.org/licenses/by-sa/3.0/us/legalcode</link>).
+ </para>
+ </legalnotice>
+ <releaseinfo>Draft 6</releaseinfo>
+ <pubdate>Built on <?dbtimestamp format="Y-m-d H:M:S"?></pubdate>
+
+ <cover>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="resources/pepper.png" format="png">
+ <info>
+ <othercredit>
+ <personname>Lubos Kocman</personname>
+ </othercredit>
+ </info>
+ </imagedata>
+ </imageobject>
+ </mediaobject>
+ </cover>
+
+ </info>
+
+ <xi:include href="SpiceUserManual-Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="SpiceUserManual-Basics.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="SpiceUserManual-References.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="SpiceUserManual-Guest.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="SpiceUserManual-Installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+
+</book>
diff --git a/docs/manual/resources/pepper.png b/docs/manual/resources/pepper.png
new file mode 100644
index 0000000..e837194
Binary files /dev/null and b/docs/manual/resources/pepper.png differ
diff --git a/docs/manual/resources/spicec01.png b/docs/manual/resources/spicec01.png
new file mode 100644
index 0000000..e2cf8c5
Binary files /dev/null and b/docs/manual/resources/spicec01.png differ
More information about the Spice-commits
mailing list