pxcloud/spice
6
0
Fork 0
mirror of https://gitlab.uni-freiburg.de/opensourcevdi/spice synced 2026-08-11 11:26:33 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Translate docbook -> asciidoc

Browse Source 
It's much much easier to read and edit, and the end results looks better
as well, see http://elmarco.fedorapeople.org/manual.html
This commit is contained in:
Marc-André Lureau 2014-03-19 12:34:47 +01:00
parent 25f6745202
commit 2e730453bf
14 changed files with 1038 additions and 1525 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
configure.ac
View File

@ -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

37
docs/manual/Makefile.am
View File

@ -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 $@
.txt.html:
$(AM_V_GEN) $(ASCIIDOC) $(ASCIIDOC_FLAGS) $<
html: html-stamp
# 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

689
docs/manual/SpiceUserManual-Basics.xml
View File

@ -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>
&lt;graphics type='spice'/&gt;
</programlisting>
You should also add a <link xlink:href="http://libvirt.org/formatdomain.html#elementsVideo">QXL video device</link>
<programlisting>
&lt;video&gt;
&lt;model type='qxl'&gt;
&lt;/video&gt;
</programlisting>
</para>
<para>
After stopping and restarting the virtual machine $vmname, it should be
accessible through Spice. You can check the connection parameters with:
<screen>
host# virsh domdisplay $vmname
</screen>
</para>
</section>
<section>
<title>Using QEMU</title>
<para>
To enable Spice support to your virtual machine, you only need to
append the following to your QEMU command line:
<screen>
-spice port=3001,disable-ticketing
</screen>
This will setup a Spice session listening on port 3001 exporting
your virtual machine display.
</para>
<para>
You can also add a QXL device by appending this to the command line:
<screen>
-vga qxl
</screen>
</para>
</section>
<section xml:id="client_basics">
<title>Connecting to guest</title>
<para>
The following section will show you basic usage of the Spice
client. The example connection will be related to the qemu instance
started in <link xlink:href="#qemu_basics">the previous section</link>.
</para>
<para>
Be aware that the port used for spice communication
<emphasis role="italic">(port 3001 in our case)</emphasis> should not be
blocked by firewall. <emphasis role="bold">Host myhost is referring to the
machine which is running our qemu instance.</emphasis>
</para>
<screen>client# remote-viewer spice://myhost:3001</screen>
<figure>
<title>Established connection to Windows 2008 guest</title>
<mediaobject>
<imageobject>
<imagedata fileref="resources/spicec01.png"/>
</imageobject>
</mediaobject>
</figure>
</section>
</section>
<section xml:id="ticketing">
<title>Ticketing</title>
<para>
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>
&lt;graphics type='spice' passwd='mysecretpassword'/&gt;
</programlisting>
</para>
</section>
<section>
<title>Using QEMU</title>
<para>
Adding a ticket with QEMU involves a slight modification of the -spice
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>
&lt;devices&gt;
&lt;controller type='virtio-serial' index='0'/&gt;
&lt;channel type='spicevmc'&gt;
&lt;target type='virtio' name='com.redhat.spice.0'/&gt;
&lt;/channel&gt;
&lt;/devices&gt;
</programlisting>
</para>
</section>
<section>
<title>Using QEMU</title>
<para>
Adding the following parameters to your QEMU command line will
enable the needed devices for agent support in the guest OS:
<screen>
-device virtio-serial \
-chardev spicevmc,id=vdagent,debug=0,name=vdagent \
-device virtserialport,chardev=vdagent,name=com.redhat.spice.0 \
</screen>
</para>
</section>
</section>
<section xml:id="USB">
<title>USB redirection</title>
<para>
With USB redirection, USB devices plugged into the client machine can be
transparently redirected to the guest OS. This redirection can either be
automatic (all newly plugged devices are redirected), or manual
(the user selects which devices (s)he wants to redirect).
</para>
<para>
For redirection to work, the virtual machine must have an USB2 EHCI controller
(this implies 3 additional UHCI controllers). It also needs to have
Spice channels for USB redirection. The number of such channels correspond
to the number of USB devices that it will be possible to redirect at the same
time.
</para>
<section>
<title>Using virt-manager</title>
<para>
Virtual machines created with virt-manager should have a USB controller
by default. In the virtual machine details, select "Controller USB" in
the left pane, and make sure its model is set to USB2. You can then
click on "Add Hardware" and add as many "USB Redirection" items as
the number of USB devices you want to be able to redirect simultaneously.
</para>
</section>
<section>
<title>Using libvirt</title>
<para>
You need to add the needed USB controllers to the libvirt XML (make
sure there is no pre-existing USB controller in your virtual machine
XML before doing this), as well as one Spice USB redirection channel
per device you want to redirect simultaneously.
<programlisting>
&lt;controller type='usb' index='0' model='ich9-ehci1'/&gt;
&lt;controller type='usb' index='0' model='ich9-uhci1'&gt;
&lt;master startport='0'/&gt;
&lt;/controller&gt;
&lt;controller type='usb' index='0' model='ich9-uhci2'&gt;
&lt;master startport='2'/&gt;
&lt;/controller&gt;
&lt;controller type='usb' index='0' model='ich9-uhci3'&gt;
&lt;master startport='4'/&gt;
&lt;/controller&gt;
&lt;redirdev bus='usb' type='spicevmc'/&gt;
&lt;redirdev bus='usb' type='spicevmc'/&gt;
&lt;redirdev bus='usb' type='spicevmc'/&gt;
&lt;redirdev bus='usb' type='spicevmc'/&gt;
</programlisting>
</para>
</section>
<section>
<title>Using QEMU</title>
<para>
Similarly to libvirt, we need to add EHCI/UHCI controllers to QEMU
command line, and we also need to add one Spice redirection channel per
device we want to redirect simultaneously.
<screen>
-device ich9-usb-ehci1,id=usb \
-device ich9-usb-uhci1,masterbus=usb.0,firstport=0,multifunction=on \
-device ich9-usb-uhci2,masterbus=usb.0,firstport=2 \
-device ich9-usb-uhci3,masterbus=usb.0,firstport=4 \
-chardev spicevmc,name=usbredir,id=usbredirchardev1 \
-device usb-redir,chardev=usbredirchardev1,id=usbredirdev1 \
-chardev spicevmc,name=usbredir,id=usbredirchardev2 \
-device usb-redir,chardev=usbredirchardev2,id=usbredirdev2 \
-chardev spicevmc,name=usbredir,id=usbredirchardev3 \
-device usb-redir,chardev=usbredirchardev3,id=usbredirdev3
</screen>
</para>
</section>
<section>
<title>Client</title>
<para>
The client needs to have support for USB redirection. In remote-viewer,
you can select which USB devices to redirect in File/USB device selection
once the Spice connection is established. There are also various command
line redirection options which are described when running remote-viewer
with --help-spice.
</para>
</section>
</section>
<section xml:id="multi-monitors">
<title>Multiple monitor support</title>
<para>
When using Spice, it's possible to use multiple monitors. For that, the guest
must have multiple QXL devices (for Windows guests), or a single QXL device
configured to support multiple heads (for Linux guests).
</para>
<para>
Before following the instructions in this section, make sure your virtual machine
already has a QXL device. If that is not the case, refer to
<link xlink:href="qemu_spice">this section</link>. Your guest OS will
also need to have the QXL driver installed or multiple monitor support will
not work.
</para>
<para>
Once your virtual machine is using a QXL device, you don't need to make
any other change to get multiple heads in a Linux guest. The following
paragraph will deal with adding multiple QXL devices to get multiple
monitors in a Windows guest.
</para>
<section>
<title>Using virt-manager</title>
<para>
To add an additional QXL device for Windows guests, simply go to your
virtual machine details. Check that you already have a "Video QXL" device,
if notclick on "Add Hardware", and add a "Video" device
with model "QXL". This can also work with Linux guests if your are willing
to configure X.Org to use Xinerama (instead of XRandR).
</para>
<para>
If you are using a new enough distribution (for example Fedora 19), and if your
virtual machine already has a QXL device, you should not need to make any changes
in virt-manager. If you are using an older distribution, you can't do the required
changes from virt-manager, you'll need to edit libvirt XML as described on this
<link xlink:href="http://hansdegoede.livejournal.com/12969.html">blog post</link>.
</para>
</section>
<section>
<title>Using libvirt</title>
<para>
To add an additional QXL device to your virtual machine managed by
libvirt, you simply need to append a new video node whose model is
QXL:
<programlisting>
&lt;video&gt;
&lt;model type='qxl'&gt;
&lt;/video&gt;
&lt;video&gt;
&lt;model type='qxl'&gt;
&lt;/video&gt;
</programlisting>
</para>
</section>
<section>
<title>Using QEMU</title>
<para>
To get a second QXL device in your virtual machine, you need to append
-device qxl to your QEMU command line in addition to the -vga qxl that
is already there:
<screen>
-vga qxl -device qxl
</screen>
</para>
</section>
<section>
<title>Client</title>
<para>
You can enable additional displays either from the Display/Displays menu
in remote-viewer, or from your guest OS display configuration tool.
</para>
</section>
</section>
<section xml:id="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>
&lt;graphics type='spice' autoport='yes' defaultMode='secure'/&gt;
</programlisting>
</para>
</section>
<section>
<title>Using QEMU</title>
<para>
QEMU expects the certificates to be named the same way as what
libvirt expects in the previous paragraph. The directory where
these certificates can be found is specified as options to the
-spice command line parameters:
<screen>
-spice port=5900,tls-port=5901,disable-ticketing,x509-dir=/etc/pki/libvirt-spice
</screen>
</para>
</section>
<section>
<title>Client</title>
<para>
We need to change 2 things when starting the client:
<itemizedlist>
<listitem>specify the tls port to use</listitem>
<listitem>specify the CA certificate to use when verifying the host certificate</listitem>
</itemizedlist>
With remote-viewer, this is done this way:
<screen>
client# remote-viewer --spice-ca-file=/etc/pki/libvirt-spice/ca-cert.ca spice://myhost?tls-port=5901
</screen>
</para>
</section>
<section>
<title>Generating self-signed certificates for use with Spice</title>
<para>
The following script can be used to create the various certificates
needed to use a TLS Spice connection. Make sure to substitute the hostname
of your Spice host in the subject of the certificate signing request.
<screen>
SERVER_KEY=server-key.pem
# creating a key for our ca
if [ ! -e ca-key.pem ]; then
openssl genrsa -des3 -out ca-key.pem 1024
fi
# creating a ca
if [ ! -e ca-cert.pem ]; then
openssl req -new -x509 -days 1095 -key ca-key.pem -out ca-cert.pem -utf8 -subj "/C=IL/L=Raanana/O=Red Hat/CN=my CA"
fi
# create server key
if [ ! -e $SERVER_KEY ]; then
openssl genrsa -out $SERVER_KEY 1024
fi
# create a certificate signing request (csr)
if [ ! -e server-key.csr ]; then
openssl req -new -key $SERVER_KEY -out server-key.csr -utf8 -subj "/C=IL/L=Raanana/O=Red Hat/CN=myhostname.example.com"
fi
# signing our server certificate with this ca
if [ ! -e server-cert.pem ]; then
openssl x509 -req -days 1095 -in server-key.csr -CA ca-cert.pem -CAkey ca-key.pem -set_serial 01 -out server-cert.pem
fi
# now create a key that doesn't require a passphrase
openssl rsa -in $SERVER_KEY -out $SERVER_KEY.insecure
mv $SERVER_KEY $SERVER_KEY.secure
mv $SERVER_KEY.insecure $SERVER_KEY
# show the results (no other effect)
openssl rsa -noout -text -in $SERVER_KEY
openssl rsa -noout -text -in ca-key.pem
openssl req -noout -text -in server-key.csr
openssl x509 -noout -text -in server-cert.pem
openssl x509 -noout -text -in ca-cert.pem
</screen>
</para>
</section>
</section>
<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>

54
docs/manual/SpiceUserManual-Guest.xml
View File

@ -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>

199
docs/manual/SpiceUserManual-Installation.xml
View File

@ -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 &gt;=6 and Fedora &gt;=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 &gt; 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 &gt;=14 RHEL &gt;=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>

264
docs/manual/SpiceUserManual-Introduction.xml
View File

@ -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>

218
docs/manual/SpiceUserManual-References.xml
View File

@ -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 &lt;spice_options&gt;
</para>
<itemizedlist>
<listitem>
[port=&lt;port&gt;][,tls-port=&lt;tls-port&gt;][,addr=&lt;addr&gt;]
Listen on interface addr &lt;addr> (if given, otherwise any interface)
using port &lt;port&gt; and/or tls-port &lt;tls-port&gt; (at least one of them must be given)
</listitem>
<listitem>
ipv4=&lt;on|off&gt;
IPv4 only (default:off)
</listitem>
<listitem>
ipv6=&lt;on|off&gt;
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=&lt;all|filter|off&gt;
Set video streams detection and (lossy) compression (default=filter)
</listitem>
<listitem>
playback-compression=&lt;on|off&gt;
Set playback compression, using the CELT algorithm (default=on)
</listitem>
<listitem>
jpeg-wan-compression=&lt;auto|never|always&gt;
(default = auto)
</listitem>
<listitem>
zlib-glz-wan-compression=&lt;auto|never|always&gt;
(default = auto)
</listitem>
<!-- Security options -->
<listitem>
disable-ticketing
Enables client connection with no password.
</listitem>
<listitem>
password=&lt;password&gt;
Set ticket password, which must be used by a client for connection. The passwords never expires.
</listitem>
<listitem>
sasl=&lt;on|off&gt;
</listitem>
<listitem>
x509-dir=&lt;dir_name&gt;
</listitem>
<listitem>
x509-key-file=&lt;key_file&gt;
TLS private key file
</listitem>
<listitem>
x509-key-password=&lt;pem_password&gt;
Password to open the private key file which is in PEM format
</listitem>
<listitem>
x509-cert-file=&lt;cert_file&gt;
TLS certificate file
</listitem>
<listitem>
tls-cacert-file=&lt;ca_file&gt;
SSL certificates file of the trusted CA (certificate authority) and CRL (certificate revocation list)
</listitem>
<listitem>
x509-dh-key-file=&lt;dh_file&gt;
Symmetric Diffie-Hellman key file
</listitem>
<listitem>
tls-ciphers=&lt;ciphers&gt;
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=&lt;on|off&gt;
Define whether spice agent is used for client mouse mode (default=on)
</listitem>
<listitem>
disable-copy-paste=&lt;on|off&gt;
(default=off)
</listitem>
<listitem>
disable-agent-file-xfer=&lt;on|off&gt;
(default=off)
</listitem>
<listitem>
seamless-migration=&lt;on|off&gt;
(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 &lt;password&gt; [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>

69
docs/manual/SpiceUserManual.xml
View File

@ -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@redhat.com</email>
</author>
<author>
<personname>Arnon Giloba</personname>
<email>agiloba@redhat.com</email>
</author>
<author>
<personname>Yaniv Kamay</personname>
<email>ykamay@redhat.com</email>
</author>
<author>
<personname>Christophe Fergeau</personname>
<email>cfergeau@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>

BIN
docs/manual/images/icons/important.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.9 KiB

BIN
docs/manual/images/icons/note.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.4 KiB

0
docs/manual/resources/pepper.png → docs/manual/images/pepper.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 10 KiB

After

Width:  |  Height:  |  Size: 10 KiB

0
docs/manual/resources/spicec01.png → docs/manual/images/spicec01.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 10 KiB

After

Width:  |  Height:  |  Size: 10 KiB

21
docs/manual/manual.conf Normal file
View File

@ -0,0 +1,21 @@
[titles]
underlines="__","==","--","~~","^^"
[attributes]
caret=^
startsb=&#91;
endsb=&#93;
tilde=&#126;
[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[]

998
docs/manual/manual.txt Normal file
View File

@ -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).