[Spice-commits] 3 commits - configure.ac docs/manual server/reds.c spice-common
Marc-André Lureau
elmarco at kemper.freedesktop.org
Wed Mar 19 09:26:34 PDT 2014
configure.ac | 14
dev/null |binary
docs/manual/Makefile.am | 37
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 | 69 -
docs/manual/images/icons/important.png |binary
docs/manual/images/icons/note.png |binary
docs/manual/images/pepper.png |binary
docs/manual/images/spicec01.png |binary
docs/manual/manual.conf | 21
docs/manual/manual.txt | 1053 +++++++++++++++++++++++++++
server/reds.c | 7
spice-common | 2
17 files changed, 1100 insertions(+), 1527 deletions(-)
New commits:
commit 06d646352efcf5b37c1bef09409ef52a0fb5dde2
Author: Marc-André Lureau <marcandre.lureau at gmail.com>
Date: Wed Mar 19 17:02:28 2014 +0100
manual: add folder sharing section
diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
index 27ad4c8..d8effd5 100644
--- a/docs/manual/manual.txt
+++ b/docs/manual/manual.txt
@@ -790,6 +790,61 @@ 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.
+Folder sharing
+==============
+
+The Spice client can share a folder with the remote guest. By default,
+the client will share the XDG Public Share directory, or '~/Public' by
+default. You may specify a different folder with `--spice-share-dir`
+client option.
+
+Configuration
+-------------
+
+.Using virt-manager
+
+It's currently not possible to configure folder sharing with virt-manager.
+
+.Using libvirt
+
+In order to set up folder sharing, qemu needs to expose a
+`org.spice-space.webdav.0` virtio port, associated with a
+corresponding Spice port:
+
+[source,sh]
+<devices>
+ <channel type='spiceport'>
+ <source channel='org.spice-space.webdav.0'/>
+ <target type='virtio' name='org.spice-space.webdav.0'/>
+ </channel>
+</devices>
+
+.Using QEMU
+
+In order to set up folder sharing, qemu needs to expose a
+`org.spice-space.webdav.0` virtio port, associated with a
+corresponding Spice port:
+
+[source,sh]
+-device virtserialport,bus=virtio-serial0.0,nr=1,chardev=charchannel1,id=channel1,name=org.spice-space.webdav.0 -chardev spiceport,name=org.spice-space.webdav.0,id=charchannel1
+
+Guest configuration
+-------------------
+
+.Windows
+In a Windows guest, you must then install
+http://elmarco.fedorapeople.org/spice-webdavd-x86-0.1.24.msi[spice-webdavd]
+service, and register the drive (by running 'map-drive.bat' from
+'Program Files/Spice webdav').
+
+.Linux
+
+With a Linux guest, you must install the spice-webdavd service (the
+sources are available at https://git.gnome.org/browse/phodav). The
+folder will show up in GNOME Files network places (or Nautilus). It
+can then be mounted and browsed in traditional applications thanks to
+`gvfs-fuse`.
+
QEMU Spice reference
====================
@@ -807,7 +862,7 @@ online documentation]. Basic syntax is `-spice <spice_options>`.
QXL command line options
------------------------
- * ram_size
+ * ram_size
* vram_size
* revision
* debug
commit 2e730453bfe45636b611b86c2c619920f246977f
Author: Marc-André Lureau <marcandre.lureau at gmail.com>
Date: Wed Mar 19 12:34:47 2014 +0100
Translate docbook -> asciidoc
It's much much easier to read and edit, and the end results looks better
as well, see http://elmarco.fedorapeople.org/manual.html
diff --git a/configure.ac b/configure.ac
index aaa7ffc..53d05a2 100644
--- a/configure.ac
+++ b/configure.ac
@@ -422,14 +422,12 @@ AC_ARG_ENABLE([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]
- )
+ AC_PATH_PROG([ASCIIDOC], [asciidoc])
+ AS_IF([test -z "$ASCIIDOC" && test "x$enable_manual" = "xyes"],
+ [AC_MSG_ERROR([asciidoc is missing and build of manual was requested])])
fi
-AS_IF([test -n "$XMLTO"], [have_xmlto=yes], [have_xmlto=no])
-AM_CONDITIONAL([BUILD_MANUAL], [test -n "$XMLTO"])
+AS_IF([test -n "$ASCIIDOC"], [have_asciidoc=yes], [have_asciidoc=no])
+AM_CONDITIONAL([BUILD_MANUAL], [test -n "$ASCIIDOC"])
dnl ===========================================================================
@@ -545,7 +543,7 @@ echo "
Automated tests: ${enable_automated_tests}
- Manual: ${have_xmlto}
+ Manual: ${have_asciidoc}
"
if test $os_win32 == "yes" ; then
diff --git a/docs/manual/Makefile.am b/docs/manual/Makefile.am
index e8856a6..f464e7a 100644
--- a/docs/manual/Makefile.am
+++ b/docs/manual/Makefile.am
@@ -1,30 +1,19 @@
-all: html
-.PHONY: html
+NULL =
+SUFFIXES = .html
+ASCIIDOC_FLAGS = -a icons -a toc
-# apparently, xmlto does not support validation of docbook5 docs
-# that's why it's disabled with --skip-validation
-XMLTO_FLAGS = --skip-validation
-
-XMLDOC = \
- SpiceUserManual-Basics.xml \
- SpiceUserManual-Guest.xml \
- SpiceUserManual-Installation.xml \
- SpiceUserManual-Introduction.xml \
- SpiceUserManual-References.xml \
- SpiceUserManual.xml \
+EXTRA_DIST = \
+ docbook-xsl.css \
+ images/icons/*.png \
+ images/spicec01.png \
+ manual.html \
+ manual.txt \
$(NULL)
-html-stamp: $(XMLDOC)
- $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) -o html xhtml $(srcdir)/SpiceUserManual.xml
- touch $@
-
-html: html-stamp
+.txt.html:
+ $(AM_V_GEN) $(ASCIIDOC) $(ASCIIDOC_FLAGS) $<
-# 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 = $(XMLDOC) html html-stamp
+all-local: manual.html
clean-local:
- rm -fr html
- rm -f *-stamp
+ rm manual.html
diff --git a/docs/manual/SpiceUserManual-Basics.xml b/docs/manual/SpiceUserManual-Basics.xml
deleted file mode 100644
index dfc8e56..0000000
--- a/docs/manual/SpiceUserManual-Basics.xml
+++ /dev/null
@@ -1,689 +0,0 @@
-<?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
deleted file mode 100644
index 6648f83..0000000
--- a/docs/manual/SpiceUserManual-Guest.xml
+++ /dev/null
@@ -1,54 +0,0 @@
-<?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
deleted file mode 100644
index 4e883ac..0000000
--- a/docs/manual/SpiceUserManual-Installation.xml
+++ /dev/null
@@ -1,199 +0,0 @@
-<?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
deleted file mode 100644
index f5618bd..0000000
--- a/docs/manual/SpiceUserManual-Introduction.xml
+++ /dev/null
@@ -1,264 +0,0 @@
-<?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
deleted file mode 100644
index 6fcee02..0000000
--- a/docs/manual/SpiceUserManual-References.xml
+++ /dev/null
@@ -1,218 +0,0 @@
-<?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
deleted file mode 100644
index 875a0da..0000000
--- a/docs/manual/SpiceUserManual.xml
+++ /dev/null
@@ -1,69 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-
-<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/images/icons/important.png b/docs/manual/images/icons/important.png
new file mode 100644
index 0000000..be685cc
Binary files /dev/null and b/docs/manual/images/icons/important.png differ
diff --git a/docs/manual/images/icons/note.png b/docs/manual/images/icons/note.png
new file mode 100644
index 0000000..7c1f3e2
Binary files /dev/null and b/docs/manual/images/icons/note.png differ
diff --git a/docs/manual/images/pepper.png b/docs/manual/images/pepper.png
new file mode 100644
index 0000000..e837194
Binary files /dev/null and b/docs/manual/images/pepper.png differ
diff --git a/docs/manual/images/spicec01.png b/docs/manual/images/spicec01.png
new file mode 100644
index 0000000..e2cf8c5
Binary files /dev/null and b/docs/manual/images/spicec01.png differ
diff --git a/docs/manual/manual.conf b/docs/manual/manual.conf
new file mode 100644
index 0000000..d87294d
--- /dev/null
+++ b/docs/manual/manual.conf
@@ -0,0 +1,21 @@
+[titles]
+ underlines="__","==","--","~~","^^"
+
+[attributes]
+caret=^
+startsb=[
+endsb=]
+tilde=~
+
+[linkgit-inlinemacro]
+<ulink url="{target}.html">{target}{0?({0})}</ulink>
+
+ifdef::backend-docbook[]
+# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this.
+[listingblock]
+<example><title>{title}</title>
+<literallayout class="monospaced">
+|
+</literallayout>
+{title#}</example>
+endif::backend-docbook[]
diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
new file mode 100644
index 0000000..27ad4c8
--- /dev/null
+++ b/docs/manual/manual.txt
@@ -0,0 +1,998 @@
+Spice User Manual
+=================
+
+Licensed under a Creative Commons Attribution-Share Alike 3.0 United
+States License (see
+http://creativecommons.org/licenses/by-sa/3.0/us/legalcode).
+
+Introduction
+============
+
+Spice is an open remote computing solution, providing client access to
+remote displays and devices (e.g. keyboard, mouse, audio). The main
+use case is to get remote access to virtual machines, although other
+use cases are possible and in various development stage.
+
+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:
+
+ * <<spice-server, Spice Server>>
+ * <<spice-client, Spice Client>>
+ * <<spice-protocol, Spice Protocol>>
+
+The following sections provide basic information on Spice components
+and features, obtaining, building installing and using Spice.
+
+Spice and Spice-related components
+----------------------------------
+
+[[spice-server]]
+Spice Server
+~~~~~~~~~~~~
+
+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).
+
+[[spice-client]]
+Spice Client
+~~~~~~~~~~~~
+
+The Spice client is a program which is used by the end user to access
+remote systems through Spice. The recommended client is remote-viewer
+(which is shipped with virt-viewer). GNOME Boxes can also be used as a
+Spice client. spicec is an obsolete legacy client, and spicy is only a
+test application.
+
+QXL Device and Drivers
+~~~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+Spice Agent
+~~~~~~~~~~~
+
+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.
+
+VDI Port Device
+~~~~~~~~~~~~~~~
+
+The 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.
+
+[[spice-protocol]]
+Spice Protocol
+~~~~~~~~~~~~~~
+
+The Spice protocol defines the messages and rules for the
+communication between the various Spice components.
+
+Features
+--------
+
+Multiple Channels
+~~~~~~~~~~~~~~~~~
+
+The server and client communicate via channels. Each channel is
+dedicated to a specific type of data. The available channels are the
+following:
+
+Main::
+control and configuration
+
+Display::
+graphics commands images and video streams
+
+Inputs::
+keyboard and mouse inputs
+
+Cursor::
+pointer device position and cursor shape
+
+Playback::
+audio received from the server to be played by the client
+
+Record::
+audio captured on the client side
+
+Smartcard::
+passthrough of smartcard data from the client machine to the guest OS
+
+USB::
+redirection of USB devices plugged into the client to the guest OS
+
+Image Compression
+~~~~~~~~~~~~~~~~~
+
+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.
+
+Video Compression
+~~~~~~~~~~~~~~~~~
+
+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.
+
+Mouse modes
+~~~~~~~~~~~
+
+Spice supports two mouse modes: server and client. The mode can be
+changed dynamically and is negotiated between the client and the
+server.
+
+Server mouse::
+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.
+
+Client mouse::
+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.
+
+Other Features
+~~~~~~~~~~~~~~
+
+Multiple Monitors::
+any number of monitors is supported
+
+Arbitrary Resolution::
+when using the QXL driver, the resolution of the guest OS will be
+automatically adjusted to the size of the client window.
+
+USB Redirection::
+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).
+
+Smartcard Redirection::
+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.
+
+Bidirectional Audio::
+Spice supports audio playback and recording. Playback is compressed
+using the CELT algorithm
+
+Lip-sync::
+between video and audio. Available only when video streaming is
+enabled.
+
+Migration::
+switching channel connectivity for supporting server migration
+
+Pixmap and Palette caching::
+image data is cached on the client to avoid sending the same data
+
+Using Spice
+===========
+
+[NOTE]
+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$` and `guest$` shell
+prompt notations to distinguish where the command should be the
+command. See section <<glossary>> 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.
+
+Running qemu manually
+---------------------
+
+*The first thing to do* is to create a guest image. 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.
+
+The following command will allocate a 10GB file. See `qemu-img` man
+page for further information.
+
+[source,sh]
+host$ qemu-img create /path/to/xp.img 10G
+
+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.
+
+[source,sh]
+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
+
+
+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 uses a qxl graphics device.
+
+The Spice `port` option defines what port will be used for
+communication with the client. The Spice option `disable-ticketing` is
+specifying that ticketing (simple authentication method) is not
+used. The virtio and chardev devices are required by the guest agent.
+
+Basic configuration
+-------------------
+
+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.
+
+.Using virt-manager
+
+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.
+
+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".
+
+After stopping and restarting the virtual machine, it should be
+accessible with a Spice client.
+
+You can remove non-Spice display entries and non-QXL video entries
+from the virtual machine configuration.
+
+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.
+
+.Using libvirt
+
+All libvirt examples will assume that the virtual machine to modify is
+`$vmname` and that virsh is using the correct libvirt connection by
+default.
+
+To add Spice support to an existing virtual machine managed by
+libvirt, you need to edit it:
+
+[source,sh]
+host$ virsh edit $vmname
+
+and then add a Spice graphics element:
+
+[source,xml]
+<graphics type='spice'/>
+
+You should also add a QXL video device
+
+[source,xml]
+<video>
+ <model type='qxl'>
+</video>
+
+After stopping and restarting the virtual machine `$vmname`, it should
+be accessible through Spice. You can check the connection parameters
+with:
+
+[source,sh]
+host$ virsh domdisplay $vmname
+
+.Using QEMU
+
+To enable Spice support to your virtual machine, you only need to
+append the following to your QEMU command line:
+
+[source,sh]
+-spice port=3001,disable-ticketing
+
+This will setup a Spice session listening on port 3001 exporting your
+virtual machine display.
+
+You can also add a QXL device by appending `-vga qxl` to the command
+line.
+
+Connecting to the guest
+-----------------------
+
+The following section will show you basic usage of the Spice
+client. The example connection will be related to the qemu instance
+started in the previous sections.
+
+Be aware that the port used for spice communication (port 3001 in our
+case) should not be blocked by firewall. Host `myhost` is referring to
+the machine which is running our qemu instance.
+
+[source,sh]
+client$ remote-viewer spice://myhost:3001
+
+.Established connection to Windows 2008 guest
+image::images/spicec01.png[]
+
+
+Ticketing
+=========
+
+Spice does not support multiple connections to the same QEMU instance
+by default. So anybody who will connect to the same host and port can
+simply take over your session. You can solve this problem by using
+ticketing.
+
+Ticketing is a simple authentication system which enables you to set
+simple tickets to a VM. Client has to authenticate before the
+connection can be established. See the Spice option `password` in the
+following examples.
+
+Configuration
+-------------
+
+.Using virt-manager
+
+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.
+
+.Using libvirt
+
+All you need to do is to append a `passwd` attribute to the Spice
+graphics node for your virtual machine:
+
+[source,xml]
+<graphics type='spice' passwd='mysecretpassword'/>
+
+.Using QEMU
+
+Adding a ticket with QEMU involves a slight modification of the
+`-spice` parameter used when running QEMU:
+
+[source,sh]
+-spice port=3001,password=mysecretpassword
+
+Client
+------
+
+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.
+
+IMPORTANT: You might have figured out that passing tickets as a
+command-line option isn't very safe. It's not safe as everybody with
+access to the host can read it from the output of `ps(1)`. To prevent
+this, the ticket can be also set by using the QEMU console command
+`spice._set_ticket`.
+
+
+[[agent]]
+Agent
+=====
+
+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/full-screened,
+file transfers through drag and drop, ...
+
+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
+for the agent to work in the guest.
+
+Configuration
+-------------
+
+.Using virt-manager
+
+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.
+
+.Using libvirt
+
+Two distinct devices must be added:
+
+* http://libvirt.org/formatdomain.html#elementsControllers[a virtio serial device]
+* http://libvirt.org/formatdomain.html#elementCharChannel[a spicevmc channel]
+
+[source,xml]
+<devices>
+ <controller type='virtio-serial' index='0'/>
+ <channel type='spicevmc'>
+ <target type='virtio' name='com.redhat.spice.0'/>
+ </channel>
+</devices>
+
+.Using QEMU
+
+Adding the following parameters to your QEMU command line will enable
+the needed devices for agent support in the guest OS:
+
+[source,sh]
+-device virtio-serial \
+-chardev spicevmc,id=vdagent,debug=0,name=vdagent \
+-device virtserialport,chardev=vdagent,name=com.redhat.spice.0 \
+
+USB redirection
+===============
+
+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).
+
+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.
+
+Configuration
+-------------
+
+.Using virt-manager
+
+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.
+
+.Using libvirt
+
+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.
+
+[source,xml]
+<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'/>
+
+.Using QEMU
+
+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.
+
+[source,sh]
+-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
+
+Client
+------
+
+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`.
+
+[NOTE]
+You may need additional services running in the client, such as the
+Spice USB Clerk service on Windows.
+
+Multiple monitor support
+========================
+
+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).
+
+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 this section. Your guest OS will also need to have the QXL
+driver installed or multiple monitor support will not work.
+
+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.
+
+Configuration
+-------------
+
+.Using virt-manager
+
+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).
+
+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 blog post.
+
+.Using libvirt
+
+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:
+
+[source,xml]
+<video>
+ <model type='qxl'>
+</video>
+<video>
+ <model type='qxl'>
+</video>
+
+
+.Using QEMU
+
+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:
+
+[source,sh]
+-vga qxl -device qxl
+
+Client
+------
+
+You can enable additional displays either from the "Display/Displays"
+menu in remote-viewer, or from your guest OS display configuration
+tool.
+
+TLS
+===
+
+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.
+
+Configuration
+-------------
+
+.Using virt-manager
+
+IMPORTANT: It's not currently 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.
+
+.Using libvirt
+
+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:
+
+ # 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"
+
+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:
+
+****
+TODO proof-read the following section:
+*****
+
+[source,sh]
+host$ virsh domdisplay
+spice://127.0.0.1?tls-port=5901
+host$
+
+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:
+
+[source,xml]
+<graphics type='spice' autoport='yes' defaultMode='secure'/>
+
+.Using QEMU
+
+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:
+
+[source,sh]
+-spice port=5900,tls-port=5901,disable-ticketing,x509-dir=/etc/pki/libvirt-spice
+
+Client
+------
+
+We need to change 2 things when starting the client:
+
+* specify the tls port to use
+* specify the CA certificate to use when verifying the host certificate
+
+With remote-viewer, this is done this way:
+
+[source,sh]
+client$ remote-viewer --spice-ca-file=/etc/pki/libvirt-spice/ca-cert.ca spice://myhost?tls-port=5901
+
+Generating self-signed certificates
+-----------------------------------
+
+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.
+
+[source,sh]
+-------------------------------------------------
+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
+-------------------------------------------------
+
+SASL
+====
+
+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.
+
+To troubleshoot SASL issues, running `strace -e open` on the QEMU
+process can be a useful first step.
+
+Configuration
+-------------
+
+.Using virt-manager
+
+It's currently not possible to enable SASL from virt-manager.
+
+.Using libvirt
+
+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.
+
+.Using QEMU
+
+Using SASL with QEMU involves a slight modification of the `-spice`
+parameter used when running QEMU:
+
+[source,sh]
+-spice port=3001,sasl
+
+Client
+------
+
+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.
+
+QEMU Spice reference
+====================
+
+****
+TODO, incomplete
+****
+
+Command line options
+--------------------
+
+They are covered in the
+http://qemu.weilnetz.de/qemu-doc.html#index-g_t_002dspice-58[QEMU
+online documentation]. Basic syntax is `-spice <spice_options>`.
+
+QXL command line options
+------------------------
+
+ * ram_size
+ * vram_size
+ * revision
+ * debug
+ * guestdebug
+ * cmdlog
+ * ram_size_mb
+ * vram_size_mb
+ * vram64_size_mb
+ * vgamem_mb
+ * surfaces
+
+QEMU console Spice commands
+---------------------------
+
+ * `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.
+ * `expire_password`
+ * `client_migrate_info`
+ * `info spice` Show current spice state
+
+[[guest-additions]]
+Spice guest additions
+=====================
+
+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.
+
+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, ...
+
+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.
+
+Windows guest
+-------------
+
+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 on
+http://spice-space.org/download/windows/spice-guest-tools/[spice-space.org].
+
+To get USB redirection working on Windows, you need to install USB
+Clerk (TODO: add link)
+
+If you want to manually install them, the QXL driver can be downloaded
+from http://spice-space.org/download/windows/qxl/[this location] ,
+agent builds can be found
+http://spice-space.org/download/windows/vdagent/[here]. You also need
+the vioserial driver which is distributed with the other
+https://alt.fedoraproject.org/pub/alt/virtio-win/latest/images/bin/[
+virtio-win drivers].
+
+Installation
+============
+
+Installing Spice on RHEL or Fedora
+----------------------------------
+
+Be aware that RHEL has no builds of qemu/spice-server for i386, only
+x86_64 builds are available. RHEL >=6 and Fedora >=13
+
+[source,sh]
+yum install qemu-kvm virt-viewer
+
+The package spice-protocol will be downloaded automatically as a
+dependency of package kvm.
+
+RHEVM Users
+~~~~~~~~~~~
+
+oVirt/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.
+
+[source,sh]
+yum install spice-xpi
+
+General build instructions
+--------------------------
+
+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.
+
+Client requirements
+~~~~~~~~~~~~~~~~~~~
+
+See the http://cgit.freedesktop.org/spice/spice-gtk/tree/README[README
+file in spice-gtk] for the list of dependencies.
+
+Host requirements
+~~~~~~~~~~~~~~~~~
+
+ * KVM supported by kernel (It should work also without KVM, but it's
+ not being tested as most Linux distrubitions already support KVM.)
+
+
+Guest requirements
+~~~~~~~~~~~~~~~~~~
+
+.Linux guest
+
+spice-vdagent requires virtio-serial support to be enabled. This is
+described in the chapter <<agent>>. Guest should have installed qxl
+driver (xorg-x11-drv-qxl on Fedora and RHEL).
+
+.Windows guest
+
+Drivers for QXL and drivers for virtio-serial require Win XP SP3.
+
+Building
+~~~~~~~~
+
+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.
+
+IMPORTANT: These instructions may be outdated. Feel free to ask on the
+Spice mailing list if you need help building from source.
+
+[source,sh]
+-------------------------------------------------
+export BUILD_ROOT=/tmp/spice; mkdir $BUILD_ROOT
+export INST_ROOT="/opt/spice"; mkdir $INST_ROOT
+export PKG_CONFIG_PATH=$INST_ROOT/lib/pkgconfig:$PKG_CONFIG_PATH
+
+cd $BUILD_ROOT
+git clone git://cgit.freedesktop.org/spice/spice
+cd $BUILD_ROOT/spice
+./configure --prefix=$INST_ROOT
+make
+make install
+
+cd $BUILD_ROOT
+git clone git://git.qemu.org/qemu.git
+cd $BUILD_ROOT/qemu
+./configure --prefix=$INST_ROOT --target-list=x86_64-softmmu --enable-spice
+make
+make install
+-------------------------------------------------
+
+Setting up PATH
+~~~~~~~~~~~~~~~
+
+Last steps before starting with Spice are to set proper `PATH`
+variable. For example RHEL is using /usr/libexec as directory for
+qemu-kvm binaries. The following setup should be suitable for qemu and
+Spice built according to the instructions in this chapter.
+
+[source,sh]
+-------------------------------------------------
+echo "export PATH=$PATH:$INST_ROOT/bin" >> ~/.bashrc
+source ~/.bashrc
+-------------------------------------------------
+
+You should now be able to access the qemu-system-x86_64 Spice binary.
+
+:numbered!:
+
+[appendix]
+Manual authors
+==============
+
+The following people have contributed to this manual:
+
+Arnon Giloba +
+Christophe Fergeau +
+Lubos Kocman +
+Marc-André Lureau +
+Yaniv Kamay
+
+[[glossary]]
+Glossary
+========
+
+[glossary]
+Host::
+Host is a machine running an instance of qemu-kvm.
+
+Guest::
+Guest is a virtual machine hosted on the host which will be accessed with a Spice client.
+
+Client::
+Client is referring to a system running the Spice client (the recommended one is virt-viewer).
diff --git a/docs/manual/resources/pepper.png b/docs/manual/resources/pepper.png
deleted file mode 100644
index e837194..0000000
Binary files a/docs/manual/resources/pepper.png and /dev/null differ
diff --git a/docs/manual/resources/spicec01.png b/docs/manual/resources/spicec01.png
deleted file mode 100644
index e2cf8c5..0000000
Binary files a/docs/manual/resources/spicec01.png and /dev/null differ
commit 25f6745202d204c25df5f9527128ec8fa95dafeb
Author: Marc-André Lureau <marcandre.lureau at gmail.com>
Date: Fri Nov 29 11:16:19 2013 +0100
Associate org.spice-space.webdav.0 port to webdav channel
For example, with qemu, a webdav channel can be created this way:
-chardev spiceport,name=org.spice-space.webdav.0,...
And redirected to a virtio port:
-device virtserialport,...,name=org.spice-space.webdav.0
diff --git a/server/reds.c b/server/reds.c
index 2ef4aad..b63699c 100644
--- a/server/reds.c
+++ b/server/reds.c
@@ -2975,7 +2975,11 @@ static int spice_server_char_device_add_interface(SpiceServer *s,
dev_state = spicevmc_device_connect(char_device, SPICE_CHANNEL_USBREDIR);
}
else if (strcmp(char_device->subtype, SUBTYPE_PORT) == 0) {
- dev_state = spicevmc_device_connect(char_device, SPICE_CHANNEL_PORT);
+ if (strcmp(char_device->portname, "org.spice-space.webdav.0") == 0) {
+ dev_state = spicevmc_device_connect(char_device, SPICE_CHANNEL_WEBDAV);
+ } else {
+ dev_state = spicevmc_device_connect(char_device, SPICE_CHANNEL_PORT);
+ }
}
if (dev_state) {
@@ -3513,6 +3517,7 @@ SPICE_GNUC_VISIBLE int spice_server_set_channel_security(SpiceServer *s, const c
[ SPICE_CHANNEL_SMARTCARD] = "smartcard",
#endif
[ SPICE_CHANNEL_USBREDIR ] = "usbredir",
+ [ SPICE_CHANNEL_WEBDAV ] = "webdav",
};
int i;
diff --git a/spice-common b/spice-common
index 57ce430..01955e7 160000
--- a/spice-common
+++ b/spice-common
@@ -1 +1 @@
-Subproject commit 57ce430ccd66bd1ca2447c14503234cfb88e2365
+Subproject commit 01955e70079876de62bb8c86ee6793c1405fb47d
More information about the Spice-commits
mailing list