diff options
| author | Christophe Fergeau <cfergeau@redhat.com> | 2014-01-13 20:01:42 +0100 |
|---|---|---|
| committer | Christophe Fergeau <cfergeau@redhat.com> | 2014-01-20 12:18:15 +0100 |
| commit | 7095563153af0e3481605eb5979ca8e6982d95cc (patch) | |
| tree | 94c8deb74a74571478755ed75c079ba4f1724d10 | |
| parent | 2ea58dd7a7ec2952e85814ead55d1694584aa471 (diff) | |
Add reference manual
This manual documents how to enable/use various SPICE features when
creating a VM by running QEMU directly, or when using libvirt, or when
using virt-manager.
This is based on work by Lubos Kocman
| -rw-r--r-- | Makefile.am | 3 | ||||
| -rw-r--r-- | configure.ac | 21 | ||||
| -rw-r--r-- | docs/Makefile.am | 3 | ||||
| -rw-r--r-- | docs/manual/Makefile.am | 38 | ||||
| -rw-r--r-- | docs/manual/SpiceUserManual-Basics.xml | 689 | ||||
| -rw-r--r-- | docs/manual/SpiceUserManual-Guest.xml | 54 | ||||
| -rw-r--r-- | docs/manual/SpiceUserManual-Installation.xml | 199 | ||||
| -rw-r--r-- | docs/manual/SpiceUserManual-Introduction.xml | 264 | ||||
| -rw-r--r-- | docs/manual/SpiceUserManual-References.xml | 218 | ||||
| -rw-r--r-- | docs/manual/SpiceUserManual.xml | 71 | ||||
| -rw-r--r-- | docs/manual/resources/pepper.png | bin | 0 -> 10582 bytes | |||
| -rw-r--r-- | docs/manual/resources/spicec01.png | bin | 0 -> 10244 bytes |
12 files changed, 1559 insertions, 1 deletions
diff --git a/Makefile.am b/Makefile.am index e260e007..c7a0e92d 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,7 +1,7 @@ NULL = ACLOCAL_AMFLAGS = -I m4 -SUBDIRS = spice-common server +SUBDIRS = spice-common server docs if SUPPORT_CLIENT SUBDIRS += client @@ -15,6 +15,7 @@ DISTCHECK_CONFIGURE_FLAGS = \ --enable-opengl \ --enable-smartcard \ --with-sasl \ + --enable-manual \ $(NULL) EXTRA_DIST = \ diff --git a/configure.ac b/configure.ac index c897368a..aaa7ffc1 100644 --- a/configure.ac +++ b/configure.ac @@ -415,6 +415,23 @@ if test "x$enable_automated_tests" = "xyes"; then AC_MSG_RESULT([found]) fi + +AC_ARG_ENABLE([manual], + AS_HELP_STRING([--enable-manual=@<:@auto/yes/no@:>@], + [Build SPICE manual]), + [], + [enable_manual="auto"]) +if test "x$enable_manual" != "xno"; then + AC_PATH_PROG([XMLTO], [xmlto]) + AS_IF([test -z "$XMLTO" && test "x$enable_manual" = "xyes"], + [AC_MSG_ERROR([xmlto is missing and build of manual was requested])] + [have_xmlto = no] + ) +fi +AS_IF([test -n "$XMLTO"], [have_xmlto=yes], [have_xmlto=no]) +AM_CONDITIONAL([BUILD_MANUAL], [test -n "$XMLTO"]) + + dnl =========================================================================== dnl check compiler flags @@ -495,6 +512,8 @@ spice-server.pc server/Makefile server/tests/Makefile client/Makefile +docs/Makefile +docs/manual/Makefile ]) dnl ========================================================================== @@ -525,6 +544,8 @@ echo " SASL support: ${enable_sasl} Automated tests: ${enable_automated_tests} + + Manual: ${have_xmlto} " if test $os_win32 == "yes" ; then diff --git a/docs/Makefile.am b/docs/Makefile.am new file mode 100644 index 00000000..18e785f0 --- /dev/null +++ b/docs/Makefile.am @@ -0,0 +1,3 @@ +if BUILD_MANUAL +SUBDIRS = manual +endif diff --git a/docs/manual/Makefile.am b/docs/manual/Makefile.am new file mode 100644 index 00000000..75cc4f79 --- /dev/null +++ b/docs/manual/Makefile.am @@ -0,0 +1,38 @@ +SUFFIXES = .xml .html .txt .1 + +# apparently, xmlto does not support validation of docbook5 docs +# that's why it's disabled with --skip-validation +.xml.html: + $(AM_V_GEN)$(XMLTO) --skip-validation -o html xhtml $< + +.xml.1: + $(AM_V_GEN)$(XMLTO) --skip-validation -o man man $< + +.xml.txt: + $(AM_V_GEN)$(XMLTO) --skip-validation -o txt txt $< + +all: allhtml manpages + +XMLMAN = +XMLDOC = \ + SpiceUserManual-Basics.xml \ + SpiceUserManual-Guest.xml \ + SpiceUserManual-Installation.xml \ + SpiceUserManual-Introduction.xml \ + SpiceUserManual-References.xml \ + SpiceUserManual.xml +XMLALL = $(XMLMAN) $(XMLDOC) +SOURCES = $(XMLALL) $(TXTDOC) + +allhtml: $(XMLALL:.xml=.html) + +manpages: $(XMLMAN:.xml=.1) + +# Control what goes in the distribution tarball. +# We include all of the XML, and also generated HTML pages +# so people working from the distribution tarball won't need xmlto. +EXTRA_DIST = $(SOURCES) html + +clean-local: + rm -fr html $(XMLMAN:.xml=.1) + diff --git a/docs/manual/SpiceUserManual-Basics.xml b/docs/manual/SpiceUserManual-Basics.xml new file mode 100644 index 00000000..dfc8e563 --- /dev/null +++ b/docs/manual/SpiceUserManual-Basics.xml @@ -0,0 +1,689 @@ +<?xml version="1.0" encoding="UTF-8"?> +<?oxygen RNGSchema="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" type="xml"?> + +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="basics"> + <title>Spice basics</title> + <section xml:id="definitions"> + <title>Basic Definitions</title> + <section xml:id="host"> + <title>Host</title> + <para>Host is a machine running an instance of qemu-kvm.</para> + </section> + + <section xml:id="guest"> + <title>Guest</title> + <para> + Guest is a virtual machine hosted on the <link linkend="host">host</link> + which will be accessed with a spice client. + </para> + </section> + + <section xml:id="client"> + <title>Client</title> + <para> + Client is referring to a system running the spice client + (the recommended one is virt-viewer). + </para> + </section> + </section> + + <section xml:id="qemu_basics"> + <title>Launching qemu</title> + <para>I'll use qemu-kvm as a name for the executable. If you're using a manually built qemu or + a qemu without kvm then just replace qemu-kvm with your own binary. I'll use host# client# + guest# shell prompt notations to distinguish where the command should be the command. See + section <link xlink:href="definitions">Basic Definitions</link> to be sure that you know + difference between the host, client and guest. You can ignore the difference between guest, client + and host if they are all running on the same machine.</para> + + <para> + <emphasis role="bold">The first important thing to do is to create a guest + image.</emphasis> You can use any raw device such as a clean logical volume, or an iSCSI + lun. You may also use a file as the disk image for the guest. I'll use a file created by qemu-img as a demonstration. + </para> + + <para> + The following command will allocate a 10GB file. See qemu-img man page for further information. + </para> + + <screen>host# qemu-img create /path/to/xp.img 10G</screen> + + <para> + Now that we created an image, we can now start with image population. I assume that you have + a locally stored ISO of your favourite operating system so you can use it for installation. + </para> + + <screen>host# sudo qemu-kvm -boot order=dc -vga qxl \ + -spice port=3001,disable-ticketing -soundhw ac97 \ + -device virtio-serial -chardev spicevmc,id=vdagent,debug=0,name=vdagent \ + -device virtserialport,chardev=vdagent,name=com.redhat.spice.0 \ + -cdrom /path/to/your.iso /path/to/your.img</screen> + + <para> + Let's take a brief look at the qemu options that were used. The option -boot order=dc specifies that the guest system + should try to boot from the first cdrom and then fallback to the first disk, -vga qxl specifies that qemu should + emulate the qxl device adapter. + </para> + <para> The Spice port option defines what port will be used for communication with the client. The Spice + option disable-ticketing is telling us that ticketing <emphasis role="italic">(simple + authentication method)</emphasis> is not used. The virtio and chardev devices are + required by <link xlink:href="SpiceUserManual-Introduction.xml#vdagent">the guest + agent</link>. + </para> + </section> + + <section xml:id="qemu_spice"> + <title>Adding Spice support to an existing virtual machine</title> + <para> + This section will assume that you already have a running QEMU virtual machine, + and that you are running it either through virt-manager, libvirt or through + direct QEMU use, and that you want to enable Spice support for this virtual + machine. + </para> + + <section> + <title>Using virt-manager</title> + <para> + Double-click on the virtual machine you are interested in, go to View/Details. + If the left pane has a "Display Spice" entry, then the virtual machine already + has Spice support, and you can check the connection details (port number) + by clicking on it. If it has no Spice entry, click on "Add + Hardware", and add a "Graphics" element of type "Spice server". + If the host and the client are not the same machine, you should check + the "Listen on all public network interfaces" checkbox, otherwise you + don't need to make any changes. + </para> + <para> + You should also add a QXL video device. It can be done by double-clicking + on a virtual machine, then by going to View/Details, and by clicking + on "Add Hardware" if the virtual machine does not have a "Video QXL" item + in its left pane. From the "Add hardware" dialog, you should then create + a "Video" device whose model is "QXL". + </para> + <para> + After stopping and restarting the virtual machine, it should be + accessible with a Spice client. + </para> + <para> + You can remove non-Spice display entries and non-QXL video entries from + the virtual machine configuration. + </para> + <para> + If you go to Edit/Preferences/VM Details in the main virt-manager window, + you can set Spice graphics type as the default setting for new virtual + machines. + </para> + </section> + + <section> + <title>Using libvirt</title> + <para> + All libvirt examples will assume that the virtual machine to modify + is $vmname and that virsh is using the correct + <link xlink:href="http://libvirt.org/uri.html">libvirt connection</link> + by default. + </para> + <para> + To add Spice support to an existing virtual machine managed by libvirt, + you need to edit it: + <screen> +host# virsh edit $vmname + </screen> + and then add a <link xlink:href="http://libvirt.org/formatdomain.html#elementsGraphics">Spice graphics element</link>: + <programlisting> +<graphics type='spice'/> + </programlisting> + You should also add a <link xlink:href="http://libvirt.org/formatdomain.html#elementsVideo">QXL video device</link> + <programlisting> +<video> + <model type='qxl'> +</video> + </programlisting> + </para> + <para> + After stopping and restarting the virtual machine $vmname, it should be + accessible through Spice. You can check the connection parameters with: + <screen> +host# virsh domdisplay $vmname + </screen> + </para> + </section> + + <section> + <title>Using QEMU</title> + <para> + To enable Spice support to your virtual machine, you only need to + append the following to your QEMU command line: + <screen> +-spice port=3001,disable-ticketing + </screen> + This will setup a Spice session listening on port 3001 exporting + your virtual machine display. + </para> + <para> + You can also add a QXL device by appending this to the command line: + <screen> +-vga qxl + </screen> + </para> + + </section> + + <section xml:id="client_basics"> + <title>Connecting to guest</title> + + <para> + The following section will show you basic usage of the Spice + client. The example connection will be related to the qemu instance + started in <link xlink:href="#qemu_basics">the previous section</link>. + </para> + + <para> + Be aware that the port used for spice communication + <emphasis role="italic">(port 3001 in our case)</emphasis> should not be + blocked by firewall. <emphasis role="bold">Host myhost is referring to the + machine which is running our qemu instance.</emphasis> + </para> + + <screen>client# remote-viewer spice://myhost:3001</screen> + <figure> + <title>Established connection to Windows 2008 guest</title> + <mediaobject> + <imageobject> + <imagedata fileref="resources/spicec01.png"/> + </imageobject> + </mediaobject> + </figure> + </section> + </section> + + <section xml:id="ticketing"> + <title>Ticketing</title> + <para> + Spice does not currently support multiple connections to the same qemu + instance. So anybody who will connect to the same host and port can simply + take over your session. + + <emphasis role="bold">You can eliminate this problem by using + <link xlink:href="#ticketing">ticketing</link> or SSL.</emphasis> + </para> + + <para> + Ticketing is a simple authentication system which enables you to set simple + tickets to a vm. + Client has to authentificate before the connection can be established. See + the spice option password in the following example. + </para> + + <section> + <title>Using virt-manager</title> + <para> + To set a Spice password for a virtual machine, go to this machine + details in virt-manager, and then click on the "Display Spice" item in + the left pane, and enter the ticket you want to use in the "Password" + field. + </para> + </section> + + <section> + <title>Using libvirt</title> + <para> + All you need to do is to append a passwd attribute to the Spice + graphics node for your virtual machine: + <programlisting> +<graphics type='spice' passwd='mysecretpassword'/> + </programlisting> + </para> + </section> + + <section> + <title>Using QEMU</title> + <para> + Adding a ticket with QEMU involves a slight modification of the -spice + parameter used when running QEMU: + <screen> +-spice port=3001,password=mysecretpassword + </screen> + </para> + </section> + + <section> + <title>Client</title> + <para> + When you start the client as usual, if ticketing was enabled on the host, + remote-viewer will pop up a window asking for a password before starting + the Spice session. It won't be established if an incorrect ticket was + passed to the client. + </para> + + <para> + You might have figured out that passing tickets as a commandline option isn't very safe. + <emphasis role="bold">It's not safe as everybody with access to the host can read it from the output of ps(1).</emphasis> + To prevent this, the ticket can be also set by using the qemu console command spice._set_ticket. + </para> + </section> + </section> + + <section xml:id="agent"> + <title>Agent</title> + <para> + Agent support allows better integration with the guest. For example, it + allows copy and paste between the guest and the host OSes, dynamic resolution + changes when the client window is resized/fullscreened, file transfers through + drag and drop, ... + </para> + <para> + The agent is a daemon/service running in the guest OS so it must be installed + if it was not installed by default during the guest OS installation. It also + relies on a virtio-serial PCI device and a dedicated spicevmc char device + to achieve communication between the guest and the host. These devices must + be added to the virtual machine if we want to agent to work properly in the + guest. + </para> + + <section> + <title>Using virt-manager</title> + <para> + The needed devices can be added from the virtual machine details. Click + on "Add hardware" and then add a "Channel" device with type + "Spice agent (spicevmc)". This will automatically add the needed + virtio-serial device in addition to the spicevmc channel. + </para> + </section> + + <section> + <title>Using libvirt</title> + <para> + Two distinct devices must be added: + <itemizedlist> + <listitem>a <link xlink:href="http://libvirt.org/formatdomain.html#elementsControllers">virtio serial device</link></listitem> + <listitem>a <link xlink:href="http://libvirt.org/formatdomain.html#elementCharChannel">spicevmc channel</link></listitem> + </itemizedlist> + <programlisting> +<devices> + <controller type='virtio-serial' index='0'/> + <channel type='spicevmc'> + <target type='virtio' name='com.redhat.spice.0'/> + </channel> +</devices> + </programlisting> + </para> + </section> + + <section> + <title>Using QEMU</title> + <para> + Adding the following parameters to your QEMU command line will + enable the needed devices for agent support in the guest OS: + <screen> +-device virtio-serial \ +-chardev spicevmc,id=vdagent,debug=0,name=vdagent \ +-device virtserialport,chardev=vdagent,name=com.redhat.spice.0 \ + </screen> + </para> + </section> + </section> + + <section xml:id="USB"> + <title>USB redirection</title> + <para> + With USB redirection, USB devices plugged into the client machine can be + transparently redirected to the guest OS. This redirection can either be + automatic (all newly plugged devices are redirected), or manual + (the user selects which devices (s)he wants to redirect). + </para> + <para> + For redirection to work, the virtual machine must have an USB2 EHCI controller + (this implies 3 additional UHCI controllers). It also needs to have + Spice channels for USB redirection. The number of such channels correspond + to the number of USB devices that it will be possible to redirect at the same + time. + </para> + + <section> + <title>Using virt-manager</title> + <para> + Virtual machines created with virt-manager should have a USB controller + by default. In the virtual machine details, select "Controller USB" in + the left pane, and make sure its model is set to USB2. You can then + click on "Add Hardware" and add as many "USB Redirection" items as + the number of USB devices you want to be able to redirect simultaneously. + </para> + </section> + + <section> + <title>Using libvirt</title> + <para> + You need to add the needed USB controllers to the libvirt XML (make + sure there is no pre-existing USB controller in your virtual machine + XML before doing this), as well as one Spice USB redirection channel + per device you want to redirect simultaneously. + <programlisting> + <controller type='usb' index='0' model='ich9-ehci1'/> +<controller type='usb' index='0' model='ich9-uhci1'> + <master startport='0'/> +</controller> +<controller type='usb' index='0' model='ich9-uhci2'> + <master startport='2'/> +</controller> +<controller type='usb' index='0' model='ich9-uhci3'> + <master startport='4'/> +</controller> +<redirdev bus='usb' type='spicevmc'/> +<redirdev bus='usb' type='spicevmc'/> +<redirdev bus='usb' type='spicevmc'/> +<redirdev bus='usb' type='spicevmc'/> + </programlisting> + </para> + </section> + + <section> + <title>Using QEMU</title> + <para> + Similarly to libvirt, we need to add EHCI/UHCI controllers to QEMU + command line, and we also need to add one Spice redirection channel per + device we want to redirect simultaneously. + <screen> +-device ich9-usb-ehci1,id=usb \ +-device ich9-usb-uhci1,masterbus=usb.0,firstport=0,multifunction=on \ +-device ich9-usb-uhci2,masterbus=usb.0,firstport=2 \ +-device ich9-usb-uhci3,masterbus=usb.0,firstport=4 \ +-chardev spicevmc,name=usbredir,id=usbredirchardev1 \ +-device usb-redir,chardev=usbredirchardev1,id=usbredirdev1 \ +-chardev spicevmc,name=usbredir,id=usbredirchardev2 \ +-device usb-redir,chardev=usbredirchardev2,id=usbredirdev2 \ +-chardev spicevmc,name=usbredir,id=usbredirchardev3 \ +-device usb-redir,chardev=usbredirchardev3,id=usbredirdev3 + </screen> + </para> + </section> + + <section> + <title>Client</title> + <para> + The client needs to have support for USB redirection. In remote-viewer, + you can select which USB devices to redirect in File/USB device selection + once the Spice connection is established. There are also various command + line redirection options which are described when running remote-viewer + with --help-spice. + </para> + </section> + </section> + + <section xml:id="multi-monitors"> + <title>Multiple monitor support</title> + <para> + When using Spice, it's possible to use multiple monitors. For that, the guest + must have multiple QXL devices (for Windows guests), or a single QXL device + configured to support multiple heads (for Linux guests). + </para> + <para> + Before following the instructions in this section, make sure your virtual machine + already has a QXL device. If that is not the case, refer to + <link xlink:href="qemu_spice">this section</link>. Your guest OS will + also need to have the QXL driver installed or multiple monitor support will + not work. + </para> + <para> + Once your virtual machine is using a QXL device, you don't need to make + any other change to get multiple heads in a Linux guest. The following + paragraph will deal with adding multiple QXL devices to get multiple + monitors in a Windows guest. + </para> + + <section> + <title>Using virt-manager</title> + <para> + To add an additional QXL device for Windows guests, simply go to your + virtual machine details. Check that you already have a "Video QXL" device, + if notclick on "Add Hardware", and add a "Video" device + with model "QXL". This can also work with Linux guests if your are willing + to configure X.Org to use Xinerama (instead of XRandR). + </para> + <para> + If you are using a new enough distribution (for example Fedora 19), and if your + virtual machine already has a QXL device, you should not need to make any changes + in virt-manager. If you are using an older distribution, you can't do the required + changes from virt-manager, you'll need to edit libvirt XML as described on this + <link xlink:href="http://hansdegoede.livejournal.com/12969.html">blog post</link>. + </para> + </section> + + <section> + <title>Using libvirt</title> + <para> + To add an additional QXL device to your virtual machine managed by + libvirt, you simply need to append a new video node whose model is + QXL: + <programlisting> +<video> + <model type='qxl'> +</video> +<video> + <model type='qxl'> +</video> + </programlisting> + </para> + </section> + + <section> + <title>Using QEMU</title> + <para> + To get a second QXL device in your virtual machine, you need to append + -device qxl to your QEMU command line in addition to the -vga qxl that + is already there: + <screen> +-vga qxl -device qxl + </screen> + </para> + </section> + + <section> + <title>Client</title> + <para> + You can enable additional displays either from the Display/Displays menu + in remote-viewer, or from your guest OS display configuration tool. + </para> + </section> + </section> + + <section xml:id="tls"> + <title>TLS</title> + <para> + TLS support allows to encrypt all/some of the channels Spice uses + for its communication. + A separate port is used for the encrypted channels. + When connecting through a TLS channel, the Spice client will verify + the certificate sent by the host. It will check that this + certificate matches the hostname it's connecting, and that + this certificate is signed by a known certificate authority + (CA). This can be achieved by either getting the host + certificate signed by an official CA, or by passing to the client + the certificate of the authority which signed the host certificate. + The latter allows the use of self-signed certificates. + </para> + + <section> + <title>Using virt-manager</title> + <para> + It's not possible to define the CA certificate/host certificate + to use for the TLS connection using virt-manager, see the next + section for how to enable this using libvirt. + </para> + </section> + + <section> + <title>Using libvirt</title> + <para> + The certificate must be specified in libvirtd configuration + file in /etc/libvirt/qemu.conf (or in + ~/.config/libvirt/qemu.conf if you are using a session libvirt). + See the documentation in this file reproduced below: + <screen> +# Enable use of TLS encryption on the SPICE server. +# +# It is necessary to setup CA and issue a server certificate +# before enabling this. +# +spice_tls = 1 + + +# Use of TLS requires that x509 certificates be issued. The +# default it to keep them in /etc/pki/libvirt-spice. This directory +# must contain +# +# ca-cert.pem - the CA master certificate +# server-cert.pem - the server certificate signed with ca-cert.pem +# server-key.pem - the server private key +# +# This option allows the certificate directory to be changed. +# +spice_tls_x509_cert_dir = "/etc/pki/libvirt-spice" + </screen> + </para> + <para> + Once the above is done, when the domain is running, you + should get something like what is below if you are leaving + Spice port allocation up to libvirt: + <screen> +host# virsh domdisplay +spice://127.0.0.1?tls-port=5901 + </screen> + </para> + <para> + This means that the connection is possible both through TLS and + without any encryption. You can edit the libvirt graphics node + if you want to change that behaviour and only allow connections + through TLS: + <programlisting> +<graphics type='spice' autoport='yes' defaultMode='secure'/> + </programlisting> + </para> + </section> + + <section> + <title>Using QEMU</title> + <para> + QEMU expects the certificates to be named the same way as what + libvirt expects in the previous paragraph. The directory where + these certificates can be found is specified as options to the + -spice command line parameters: + <screen> +-spice port=5900,tls-port=5901,disable-ticketing,x509-dir=/etc/pki/libvirt-spice + </screen> + </para> + </section> + + <section> + <title>Client</title> + <para> + We need to change 2 things when starting the client: + <itemizedlist> + <listitem>specify the tls port to use</listitem> + <listitem>specify the CA certificate to use when verifying the host certificate</listitem> + </itemizedlist> + With remote-viewer, this is done this way: + <screen> +client# remote-viewer --spice-ca-file=/etc/pki/libvirt-spice/ca-cert.ca spice://myhost?tls-port=5901 + </screen> + </para> + </section> + + <section> + <title>Generating self-signed certificates for use with Spice</title> + <para> + The following script can be used to create the various certificates + needed to use a TLS Spice connection. Make sure to substitute the hostname + of your Spice host in the subject of the certificate signing request. + <screen> +SERVER_KEY=server-key.pem + +# creating a key for our ca +if [ ! -e ca-key.pem ]; then + openssl genrsa -des3 -out ca-key.pem 1024 +fi +# creating a ca +if [ ! -e ca-cert.pem ]; then + openssl req -new -x509 -days 1095 -key ca-key.pem -out ca-cert.pem -utf8 -subj "/C=IL/L=Raanana/O=Red Hat/CN=my CA" +fi +# create server key +if [ ! -e $SERVER_KEY ]; then + openssl genrsa -out $SERVER_KEY 1024 +fi +# create a certificate signing request (csr) +if [ ! -e server-key.csr ]; then + openssl req -new -key $SERVER_KEY -out server-key.csr -utf8 -subj "/C=IL/L=Raanana/O=Red Hat/CN=myhostname.example.com" +fi +# signing our server certificate with this ca +if [ ! -e server-cert.pem ]; then + openssl x509 -req -days 1095 -in server-key.csr -CA ca-cert.pem -CAkey ca-key.pem -set_serial 01 -out server-cert.pem +fi + +# now create a key that doesn't require a passphrase +openssl rsa -in $SERVER_KEY -out $SERVER_KEY.insecure +mv $SERVER_KEY $SERVER_KEY.secure +mv $SERVER_KEY.insecure $SERVER_KEY + +# show the results (no other effect) +openssl rsa -noout -text -in $SERVER_KEY +openssl rsa -noout -text -in ca-key.pem +openssl req -noout -text -in server-key.csr +openssl x509 -noout -text -in server-cert.pem +openssl x509 -noout -text -in ca-cert.pem + </screen> + </para> + </section> + </section> + + <section xml:id="sasl"> + <title>SASL</title> + <para> + Spice server and client have support for SASL authentication. When using QEMU, /etc/sasl2/qemu.conf will be + used as a configuration file. For testing, you can use the digest-md5 mechanism, and populate a test database + using 'saslpasswd2 -f /etc/qemu/passwd.db -c foo'. These files have to be readable by the qemu process that will + handle your VM. + </para> + + <para> + To troubleshoot SASL issues, running strace -e open on the QEMU process can be a useful first step. + </para> + + + <section> + <title>Using virt-manager</title> + <para> + It's currently not possible to enable SASL from virt-manager. + </para> + </section> + + <section> + <title>Using libvirt</title> + <para> + SASL support for SPICE has been added to libvirt mid-October 2013 so you need a libvirt version + that was released after this date. To enable SASL, you need to add spice_sasl = 1 in /etc/libvirt/qemu.conf + for the system libvirtd instance, and to ~/.config/libvirt/qemu.conf for the session libvirtd instance. + </para> + </section> + + <section> + <title>Using QEMU</title> + <para> + Using SASL with QEMU involves a slight modification of the -spice + parameter used when running QEMU: + <screen> +-spice port=3001,sasl + </screen> + </para> + </section> + + <section> + <title>Client</title> + <para> + When you start the client as usual, if SASL was enabled on the host, + remote-viewer will pop up a window asking for a password before starting + the Spice session. It won't be established if an incorrect ticket was + passed to the client. + </para> + </section> + </section> +</chapter> diff --git a/docs/manual/SpiceUserManual-Guest.xml b/docs/manual/SpiceUserManual-Guest.xml new file mode 100644 index 00000000..6648f831 --- /dev/null +++ b/docs/manual/SpiceUserManual-Guest.xml @@ -0,0 +1,54 @@ +<?xml version="1.0" encoding="UTF-8"?> +<?oxygen RNGSchema="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" type="xml"?> + +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xi="http://www.w3.org/2001/XInclude" + xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"> + <title>Spice Guest Additions</title> + + <section xml:id="generic-guest"> + <title>Introduction</title> + <para> + While you will be able to remotely access your virtual machine + through Spice without making any change to the virtual machine + configuration, you can get better integration if you tweak it + specially for Spice. + </para> + <para> + If your virtual machine has a QXL video device and you install + the corrresponding guest driver, your guest will support higher + resolutions, multiple monitors, resizing to arbitrary resolutions, + ... + </para> + <para> + Installing the Spice vdagent in your guest will let you copy and + paste between your guest and client OSes, to drag and drop files + between the 2 OSes, ... In order for the agent to work, your + virtual machine must have a virtio serial device (and the + corresponding guest drivers) as well as a Spice spicevmc channel. + </para> + </section> + + <section xml:id="windows-guest"> + <title>Windows Guest</title> + <para> + The recommended way of getting all the needed drivers installed is + to use the all-in-one Spice guest tools installer which can be + found <link xlink:href="http://spice-space.org/download/windows/spice-guest-tools/"> + on spice-space.org</link>. + </para> + <para> + To get USB redirection working on Windows, you need to ... + </para> + <para> + If you want to manually install them, the QXL driver can be downloaded from + <link xlink:href="http://spice-space.org/download/windows/qxl/">this location + </link>, agent builds can be found + <link xlink:href="http://spice-space.org/download/windows/vdagent/">here + </link>. You also need the vioserial driver which is distributed with the + other <link xlink:href="https://alt.fedoraproject.org/pub/alt/virtio-win/latest/images/bin/"> + virtio-win drivers</link>. + </para> + </section> + +</chapter> diff --git a/docs/manual/SpiceUserManual-Installation.xml b/docs/manual/SpiceUserManual-Installation.xml new file mode 100644 index 00000000..4e883acd --- /dev/null +++ b/docs/manual/SpiceUserManual-Installation.xml @@ -0,0 +1,199 @@ +<?xml version="1.0" encoding="UTF-8"?> +<?oxygen RNGSchema="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" type="xml"?> + +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"> + <title>Installation</title> + + <section xml:id="rhel_fedora"> + <title>Installing Spice on RHEL or Fedora </title> + <para> + Be aware that RHEL has no builds of qemu/spice-server for i386, only x86_64 builds are available. + </para> + <section> + <title>RHEL >=6 and Fedora >=13</title> + <para> + <screen>yum install qemu-kvm virt-viewer</screen> + </para> + <para> + The package spice-protocol will be downloaded automatically as a dependency of package kvm. + </para> + </section> + <section><title>RHEVM Users</title> + <para> + <emphasis role="bold"> + <link xlink:href="http://www.ovirt.org">oVirt</link>/RHEVM users + could be also interested in the spice-xpi package as it allows you + to execute spice-client directly from the oVirt/RHEVM UserPortal. + </emphasis> + <screen>yum install spice-xpi</screen> + </para> + </section> + </section> + + <section xml:id="linux_generic"> + <title>Generic Build Instructions</title> + + <para> + This section is for distributions that don't have *spice* packages in their repositories. + It will show you step by step how to build the required spice components. + </para> + + <section xml:id="req_client"> + <title>Client requirements</title> + + <orderedlist> + <listitem><para><emphasis role="bold">autotools</emphasis></para></listitem> + <listitem><para><emphasis role="bold">gtk+2 > 2.18 or gtk+3</emphasis></para></listitem> + <listitem><para><emphasis role="bold">celt = 0.5.1.3</emphasis> The exact version is required due to the lack of backwards compatibility in newer celt releases.</para></listitem> + <listitem><para><emphasis role="bold">cyrus-sasl</emphasis></para></listitem> + <listitem><para><emphasis role="bold">pixman</emphasis></para></listitem> + <listitem><para><emphasis role="bold">openssl</emphasis></para></listitem> + <listitem><para><emphasis role="bold">pyparsing</emphasis></para></listitem> + <listitem><para><emphasis role="bold">usbredir</emphasis></para></listitem> + <listitem><para><emphasis role="bold">PolicyKit</emphasis></para></listitem> + </orderedlist> + </section> + + <section xml:id="req_host"> + <title>Host requirements</title> + <orderedlist> + <listitem><para><emphasis role="bold">KVM supported by kernel</emphasis> (It should work also without KVM, but + it's not being tested as most Linux distrubitions already support + KVM.)</para></listitem> + </orderedlist> + + </section> + + <section> + <title>Guest requirements</title> + <section> + <title>Linux Guest</title> + <para> + spice-vdagent requires virtio-serial support to be enabled. This is described in the <link xlink:href="SpiceUserManual-Basics.xml#basics">chapter Spice basics</link>. + Guest should have installed qxl driver (xorg-x11-drv-qxl on Fedora and RHEL). + </para> + </section> + <section> + <title>Windows Guest</title> + <para> + Drivers for QXL and drivers for virtio-serial require Win XP SP3 and Win 7. + </para> + </section> + + <section xml:id="setting_be"> + <title>Setting up the build environment</title> + + <para> + <emphasis role="bold">This is a list of prerequisites on RHEL or Fedora. Install + equivalent packages for your distribution in case that you're not using RHEL + or Fedora.</emphasis> + </para> + <para> + <emphasis role="bold">All prerequisites for Windows are available in one big package which is available + at <link xlink:href="http://spice-space.org/download.html">http://spice-space.org/download.html</link>.</emphasis> + </para> + <screen>yum install git pixman-devel celt051-devel cegui-devel libjpeg-devel alsa-lib-devel log4cpp-devel \ + openssl-devel libXrandr-devel libgcrypt-devel SDL-devel nss-devel dev86 iasl pyparsing</screen> + + <para> + <emphasis role="bold">Package prerequisites for Ubuntu</emphasis> + </para> + <screen>apt-get install build-essential autoconf git-core libtool liblog4cpp5-dev libavcodec-dev \ + libssl-dev xlibmesa-glu-dev libasound-dev libpng12-dev libfreetype6-dev libfontconfig1-dev \ + libogg-dev libxrandr-dev kvm libgcrypt-dev libsdl-dev</screen> + + </section> + + <section xml:id="building_libcacard"> + <title>Building libcacard</title> + <para>Fedora >=14 RHEL >=6.1 has libcacard already available. So you can install it directly trough yum.</para> + <screen>yum install libcacard</screen> + <para>Otherwise follow these instructions. <emphasis role="bold">The environment + variable $BUILD_ROOT will point to a directory with stored sources and will + be used during the whole build process. The variable $INST_ROOT will point to a + directory in which Spice will be installed.</emphasis></para> + <screen>export BUILD_ROOT=/tmp/spice; mkdir $BUILD_ROOT; cd $BUILD_ROOT; +export INST_ROOT="/opt/spice"; mkdir $INST_ROOT +git clone git://anongit.freedesktop.org/~alon/libcacard +cd libcacard +./configure --prefix=/usr --libdir=/usr/lib64 # Ignore --libdir at Ubuntu +make +make install</screen> + + </section> + + <section xml:id="getting_client"> + <title>Getting client sources</title> + + <screen>cd $BUILD_ROOT +git clone git://cgit.freedesktop.org/spice/spice-protocol +git clone git://cgit.freedesktop.org/spice/spice +wget http://downloads.us.xiph.org/releases/celt/celt-0.5.1.3.tar.gz +tar xvzf celt-0.5.1.3.tar.gz + </screen> + </section> + + <section xml:id="getting_server"> + <title>Getting client/server sources</title> + <para>Skip this section if you don't want to build server side.</para> + <screen>cd $BUILD_ROOT +git clone git://cgit.freedesktop.org/spice/qemu +cd qemu; git checkout -b spice.v13 origin/spice.v13; cd .. +git clone git://cgit.freedesktop.org/spice/spice-protocol +git clone git://cgit.freedesktop.org/spice/spice +git clone git://cgit.freedesktop.org/spice/win32/vd_agent +git clone git://cgit.freedesktop.org/spice/win32/qxl +git clone git://cgit.freedesktop.org/spice/slirp +wget http://downloads.us.xiph.org/releases/celt/celt-0.5.1.3.tar.gz +tar xvzf celt-0.5.1.3.tar.gz</screen> + + </section> + + <section xml:id="building_common"> + <title>Building common sources.</title> + <para>This part applies to both server and client build process.</para> + <screen>cd $BUILD_ROOT/spice-protocol +mkdir m4 +./autogen.sh --prefix=$INST_ROOT +sudo make install +cd $BUILD_ROOT/celt-0.5.1.3 +./configure --prefix=$INST_ROOT +sudo make install +</screen> + + </section> + <section> + <title>Building client side tools</title> + <screen>cd $BUILD_ROOT/spice +./autogen.sh --prefix=$INST_ROOT --enable-smartcard +cd client +sudo make install</screen> + </section> + + <section> + <title>Building server side tools</title> + <para>These instructions contain flags for a minimal working build of qemu with Spice support enabled. + You might want to build qemu with the --enable-io-thread option</para> + <screen>cd $SRC_ROOT/qemu +./configure --prefix=$INST_ROOT --target-list=x86_64-softmmu --enable-spice +make</screen> + </section> + + </section> + + <section> + <title>Setting up PATH</title> + <para>Last steps before starting with Spice are to set proper PATH variable. + For example RHEL is using /usr/libexec as directory for spicec and qemu-kvm binaries. + The following setup should be suitable for qemu and Spice built according to the instructions in + this chapter.</para> + + + <screen>echo "export PATH=$PATH:$INST_ROOT/bin:$BUILD_ROOT/x86_64-softmmu >> ~/.bashrc +source ~/.bashrc</screen> + + <para>You should now be able to access the qemu-system-x86_64 and spicec binaries.</para> + </section> + </section> + +</chapter> diff --git a/docs/manual/SpiceUserManual-Introduction.xml b/docs/manual/SpiceUserManual-Introduction.xml new file mode 100644 index 00000000..f5618bd0 --- /dev/null +++ b/docs/manual/SpiceUserManual-Introduction.xml @@ -0,0 +1,264 @@ +<?xml version="1.0" encoding="UTF-8"?> +<?oxygen RNGSchema="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" type="xml"?> + + <chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xi="http://www.w3.org/2001/XInclude" + xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"> + <title>Introduction</title> + <para> + Spice is an open remote computing solution, providing client access to remote displays and devices (e.g. keyboard, mouse, audio). + At the moment, it's mainly used to get remote access to virtual machines. Spice provides a desktop-like user experience, while trying to + offload most of the intensive CPU and GPU tasks to the client. + + The basic building blocks of Spice are: + </para> + + <orderedlist> + <listitem><para><link linkend="spice_server">Spice Server</link></para></listitem> + <listitem><para><link linkend="spice_client">Spice Client</link></para></listitem> + <listitem><para>Spice Protocol</para></listitem> + </orderedlist> + + <para> + The following sections provide basic information on Spice components and features, obtaining, building installing and using Spice. + </para> + + <section> + <title>Spice and Spice-related Components</title> + <section xml:id="spice_server"> + <title>Spice Server</title> + <para> + Spice server is implemented in libspice, a VDI pluggable library. + Currently, the main user of this library is QEMU. QEMU uses spice-server + to provide remote access to virtual machines through the Spice protocol. + Virtual Device Interface (VDI) defines a set of interfaces that provide + a standard way to publish virtual devices (e.g. display device, keyboard, + mouse) and enables different Spice components to interact with those + devices. On one side, the server communicates with the remote client + using the Spice protocol and on the other side, it interacts with the + VDI host application (e.g QEMU). + </para> + </section> + + <section xml:id="spice_client"> + <title>Spice Client</title> + <para> + The Spice client is a cross-platform (Linux and Windows) + which is used by the end user to access remote systems through Spice. + The recommended client is <link xlink:href="https://fedorahosted.org/released/virt-viewer/">remote-viewer</link> + (which is shipped with virt-viewer). + <link xlink:href="https://wiki.gnome.org/Apps/Boxes">GNOME Boxes</link> + can also be used as a Spice client. spicec is an obsolete + legacy client, and spicy is only a test application. + </para> + </section> + + <section> + <title>QXL Device and Drivers</title> + <para> + Spice server supports the QXL VDI interface. When libspice is used with + QEMU, a specific video PCI device can be used for improving + remote display performance and enhancing the graphic capabilities of the + guest graphic system. This video device is called a QXL + device and requires guest QXL drivers for full functionality. However, + standard VGA is supported when no driver exists. + </para> + </section> + + <section xml:id="vdagent"> + <title>Spice Agent</title> + <para> + The Spice agent is an optional component for enhancing user + experience and performing guest-oriented management tasks. + For example, the agent injects mouse position and state to + the guest when using client mouse mode. It also enables you to + move cursor freely between guest and client. Other features + of agent are shared clipboard (copy and paste between guest and host) + and aligning guest resolution with client when entering fullscreen mode. + </para> + </section> + + <section> + <title>VDI Port Device</title> + <para> + Spice protocol supports a communication channel between the + client and the agent on the server side. When using QEMU, Spice agent + resides on the guest. VDI port is a QEMU PCI device used + for communication with the agent. + </para> + </section> + + </section> + + <section xml:id="features"> + <title>Features</title> + <para> + The server and client communicate via channels. Each channel is dedicated to + a specific type of data. The available channels are following. + </para> + <section xml:id="multiple_channels"> + <title>Multiple Channels</title> + + <orderedlist numeration="arabic"> + <listitem> + <para><emphasis role="bold">Main</emphasis> - control and configuration</para> + </listitem> + <listitem> + <para><emphasis role="bold">Display</emphasis> - graphics commands images and video streams</para> + </listitem> + <listitem> + <para><emphasis role="bold">Inputs</emphasis> - keyboard and mouse inputs</para> + </listitem> + <listitem> + <para><emphasis role="bold">Cursor</emphasis> - pointer device position and cursor shape</para> + </listitem> + <listitem> + <para><emphasis role="bold">Playback</emphasis> - audio received from the server to be played by the client</para> + </listitem> + <listitem> + <para><emphasis role="bold">Record</emphasis> - audio captured on the client side</para> + </listitem> + <listitem> + <para><emphasis role="bold">Smartcard</emphasis> - passthrough of smartcard data from the client machine to the guest OS</para> + </listitem> + <listitem> + <para><emphasis role="bold">USB</emphasis> - redirection of USB devices plugged into the client to the guest OS</para> + </listitem> + </orderedlist> + </section> + + <section xml:id="image_compression"> + <title>Image Compression</title> + + <para> + Spice offers several image compression algorithms, which + can be chosen on server initiation and dynamically at run-time. Quic is a + Spice proprietary image compression technology based on the SFALIC + algorithm. The Lempel-Ziv (LZ) algorithm is another option. Both Quic and + LZ are local algorithms encoding each image separately. Global LZ (GLZ) is + another proprietary Spice technology that uses LZ with history-based global + dictionary. GLZ takes advantage of repeating patterns among images to + shrink the traffic and save bandwidth, which is critical in a WAN + environment. Spice also offers an automatic mode for compression selection + per image, where the choice between LZ/GLZ and Quic is heuristically based + on image properties. Conceptually, synthetic images are better compressed + with LZ/GLZ and real images are better with Quic. + </para> + </section> + + <section xml:id="video_compression"> + <title>Video Compression</title> + + <para> + Spice uses loss-less compression for images sent to the + client. However, video streams are handled differently. Spice server + heuristically identifies video areas and sends them as a video stream coded + using M-JPEG. This handling saves a lot of traffic, improving Spice + performance, especially in a WAN environment. However, in some + circumstances the heuristic behavior might cause low quality images (e.g. + identifying updated text area as a video stream). Video streaming can be + chosen on server initiation and dynamically at run-time. + </para> + </section> + + <section xml:id="mouse_modes"> + <title>Mouse modes</title> + + <para> + Spice supports two mouse modes: server and client. The mode + can be changed dynamically and is negotiated between the client and the + server. + </para> + <orderedlist> + <listitem> + <para> + <emphasis role="bold">Server mouse</emphasis> - When a user + clicks inside the Spice client window, the client mouse is + captured and set invisible. In this mode, the server controls + the mouse position on display. However, it might be problematic + on WAN or on a loaded server, where mouse cursor might have some + latency or non-responsiveness. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Client mouse</emphasis> - Not + captured and is used as the effective pointing device. To enable + client mouse, the VDI host application must register an absolute + pointing device (e.g. USB tablet in QEMU). This mode is + appropriate for WAN or or for a loaded server, since cursor has + smooth motion and responsiveness. However, the cursor might + lose synchronization (position and shape) for a while. + </para> + </listitem> + + </orderedlist> + </section> + + <section xml:id="other_features"> + <title>Other Features</title> + <orderedlist> + + <listitem> + <para> + <emphasis role="bold">Multiple Monitors</emphasis> - any number of monitors is supported + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Arbitrary Resolution</emphasis> - when + using the QXL driver, the resolution of the guest OS will be + automatically adjusted to the size of the client window. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">USB Redirection</emphasis> - Spice + can be used to redirect USB devices that are plugged in the + client to the guest OS. This redirection can either be + automatic (all newly plugged devices are redirected), or manual + (the user selects which devices (s)he wants to redirect). + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Smartcard Redirection</emphasis> - + data from smartcard that are inserted into the client machine + can be passed through to the guest OS. The smartcard can be + used by both the client OS and the guest OS. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Bidirectional Audio</emphasis> - Spice supports audio playback and recording. Playback is compressed using the CELT algorithm + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Lip-sync</emphasis> - between video and audio. Available only when video streaming is enabled. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Migration</emphasis> - switching channel connectivity for supporting server migration + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Pixmap and Palette caching</emphasis> + </para> + </listitem> + + </orderedlist> + </section> + </section> + +</chapter> diff --git a/docs/manual/SpiceUserManual-References.xml b/docs/manual/SpiceUserManual-References.xml new file mode 100644 index 00000000..6fcee02c --- /dev/null +++ b/docs/manual/SpiceUserManual-References.xml @@ -0,0 +1,218 @@ +<?xml version="1.0" encoding="UTF-8"?> +<?oxygen RNGSchema="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" type="xml"?> + +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xi="http://www.w3.org/2001/XInclude" + xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"> + <title>QEMU Spice Reference</title> + + <section xml:id="commandline-spice"> + <title>QEMU Spice command line options</title> + <para> + They are covered in <link xlink:href="http://qemu.weilnetz.de/qemu-doc.html#index-g_t_002dspice-58">QEMU online documentation</link>. + Basic syntax is -spice <spice_options> + </para> + + <itemizedlist> + <listitem> + [port=<port>][,tls-port=<tls-port>][,addr=<addr>] + Listen on interface addr <addr> (if given, otherwise any interface) + using port <port> and/or tls-port <tls-port> (at least one of them must be given) + </listitem> + + <listitem> + ipv4=<on|off> + IPv4 only (default:off) + </listitem> + + <listitem> + ipv6=<on|off> + IPv6 only (default:off) + </listitem> + +<!-- Image, video & audio options --> + <listitem> + image-compression=on|auto_glz|auto_lz|quic|glz|lz|off + Set image compression (default=on=auto_glz) + quic is based on the SFALIC algorithm + lz is the Lempel-Ziv algorithm, glz uses lz with history based global dictionary + The auto_[glz/lz] modes choose between the [glz/lz] and quic, + based on the image properties + </listitem> + + <listitem> + streaming-video=<all|filter|off> + Set video streams detection and (lossy) compression (default=filter) + </listitem> + + <listitem> + playback-compression=<on|off> + Set playback compression, using the CELT algorithm (default=on) + </listitem> + + <listitem> + jpeg-wan-compression=<auto|never|always> + (default = auto) + </listitem> + + <listitem> + zlib-glz-wan-compression=<auto|never|always> + (default = auto) + </listitem> + +<!-- Security options --> + <listitem> + disable-ticketing + Enables client connection with no password. + </listitem> + + <listitem> + password=<password> + Set ticket password, which must be used by a client for connection. The passwords never expires. + </listitem> + + <listitem> + sasl=<on|off> + </listitem> + + <listitem> + x509-dir=<dir_name> + </listitem> + + <listitem> + x509-key-file=<key_file> + TLS private key file + </listitem> + + <listitem> + x509-key-password=<pem_password> + Password to open the private key file which is in PEM format + </listitem> + + <listitem> + x509-cert-file=<cert_file> + TLS certificate file + </listitem> + + <listitem> + tls-cacert-file=<ca_file> + SSL certificates file of the trusted CA (certificate authority) and CRL (certificate revocation list) + </listitem> + + <listitem> + x509-dh-key-file=<dh_file> + Symmetric Diffie-Hellman key file + </listitem> + + <listitem> + tls-ciphers=<ciphers> + Cipher suite to use, see http://www.openssl.org/docs/apps/ciphers.html or ciphers(1) + </listitem> + + <listitem> + tls-channel=[all|channel_name] + plaintext-channel=[all|channel_name] + Force TLS/plain text connection on all/specific channels. This option + can be specified multiple times in order to force multiple channels + to use TLS or plain text. + Channels are: main, display, inputs, cursor, playback and record + By default, any channel allows both TLS and plain text connection, depending on the + port and tls-port parameters. + </listitem> + +<!-- Other options --> + + <listitem> + agent-mouse=<on|off> + Define whether spice agent is used for client mouse mode (default=on) + </listitem> + + <listitem> + disable-copy-paste=<on|off> + (default=off) + </listitem> + + <listitem> + disable-agent-file-xfer=<on|off> + (default=off) + </listitem> + + <listitem> + seamless-migration=<on|off> + (default=off) + </listitem> + </itemizedlist> + </section> + + <section xml:id="commandline-qxl"> + <title>QEMU QXL command line options</title> + <itemizedlist> + <listitem> + ram_size + </listitem> + <listitem> + vram_size + </listitem> + <listitem> + revision + </listitem> + <listitem> + debug + </listitem> + <listitem> + guestdebug + </listitem> + <listitem> + cmdlog + </listitem> + <listitem> + ram_size_mb + </listitem> + <listitem> + vram_size_mb + </listitem> + <listitem> + vram64_size_mb + </listitem> + <listitem> + vgamem_mb + </listitem> + <listitem> + surfaces + </listitem> + </itemizedlist> + </section> + + <section xml:id="console-control"> + <title>QEMU Console Spice control commands</title> + <itemizedlist> + <listitem> + set_password spice <password> [keep|disconnect] + Set the spice connection ticket (one time password). An + empty password prevents any connection. keep/disconnect + indicates what to do if a client is already connected + when the command is issued. + </listitem> + + <listitem> + expire_password + </listitem> + + <listitem> + client_migrate_info + </listitem> + + </itemizedlist> + </section> + + <section xml:id="console-info"> + <title>QEMU Console Spice info commands</title> + <itemizedlist> + <listitem> + info spice + Show current spice state + </listitem> + </itemizedlist> + </section> + +</chapter> diff --git a/docs/manual/SpiceUserManual.xml b/docs/manual/SpiceUserManual.xml new file mode 100644 index 00000000..d7106361 --- /dev/null +++ b/docs/manual/SpiceUserManual.xml @@ -0,0 +1,71 @@ +<?xml version="1.0" encoding="UTF-8"?> +<?oxygen RNGSchema="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" type="xml"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V5.0//EN" + "http://docbook.org/xml/5.0/dtd/docbook.dtd"> +<book xmlns="http://docbook.org/ns/docbook" + xmlns:xi="http://www.w3.org/2001/XInclude" + xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" + xml:lang="en"> + <info> + <title>Spice User Manual</title> + + <authorgroup> + <author> + <personname>Lubos Kocman</personname> + <email>lkocman@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> diff --git a/docs/manual/resources/pepper.png b/docs/manual/resources/pepper.png Binary files differnew file mode 100644 index 00000000..e837194e --- /dev/null +++ b/docs/manual/resources/pepper.png diff --git a/docs/manual/resources/spicec01.png b/docs/manual/resources/spicec01.png Binary files differnew file mode 100644 index 00000000..e2cf8c5d --- /dev/null +++ b/docs/manual/resources/spicec01.png |
