path: root/books/docbook/user_guide.sgm

<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book>
<bookinfo>
<title>Spice User Manual</title>

<authorgroup>

<author>
<firstname>Lubos</firstname>
<surname>Kocman</surname>
</author>

<author>
<firstname>Arnon</firstname>
<surname>Gilboa</surname>
</author>

</authorgroup>

<copyright>
<year>2009</year>
<year>2010</year>
<year>2011</year>
<holder>Red Hat, Inc.</holder>
</copyright>

<legalnotice>
<para>
Licensed under a Creative Commons Attribution-Share Alike 3.0 United States License (see <ulink url="http://creativecommons.org/licenses/by-sa/3.0/us/legalcode">http://creativecommons.org/licenses/by-sa/3.0/us/legalcode</ulink>).
</para>
</legalnotice>
<releaseinfo>Draft 54</releaseinfo>
</bookinfo>

<chapter id="introduction">
<title>Introduction</title>
<para>
Spice is an open remote computing solution, providing client access to remote  displays and devices (e.g. keyboard, mouse, audio). 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>Spice protocol</para>
</listitem>
<listitem>
<para>Spice server</para>
</listitem>
<listitem><para>Spice client</para>
</listitem>
</orderedlist>

<para>
The following sections provide basic iformation on Spice components and features, obtaining, building installing and using Spice.
</para>

<section>
<title>Spice and Spice-related Compoments</title>

<section>
<title>Spice Server</title>

<para>
Spice server is implemented in libspice, a VDI pluggable library. 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. For more information, refer to [2]. 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>
<title>Spice Client</title>

<para>Spice cross-platform (Linux & Windows) client is the interface for the end user.</para>
</section>

<section>
<title>QXL Device and Drivers</title>
<para>
Spice server supports QXL VDI interface. When libspice is used with QEMU, a specific QEMU  QXL PCI device can be used for improving remote display performance and enhancing the graphic capabilities of the guest graphic system. QXL device requires guest QXL drivers for full functionality. However, standard VGA is supported when no driver exists. 
</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>
<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. In addition, it is used for configuration of the guest display settings.
</para>
</section>
</section>

<section>
<title>Features</title>

<section>
<title>Multiple Channels</title>

<para>
The server and client communicate via channels. Each channel is dedicated to a specific type of data. The available channels are:
</para>

<orderedlist>
<listitem>
<para>Main -  control and configuration</para>
</listitem>
<listitem>
<para>Display -  graphics commands images and video streams</para>
</listitem>
<listitem>
<para>Inputs - keyboard and mouse inputs</para>
</listitem> 
<listitem>
<para>Cursor - pointer device position and cursor shape</para>
</listitem>
<listitem>
<para>Playback - audio received from the server to be played by the client</para>
</listitem>
<listitem>
<para>Record - audio capture on the client side</para>
</listitem>
</orderedlist>

</section>

<section>
<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>
<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 image (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>
<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 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. For enabling client mouse, VDI host application must register an absolute pointing device (e.g. USB tablet in QEMU). This mode is appropriate for WAN or loaded server, since cursor has smooth motion and responsiveness. However, the cursor might loose synchronization (position and shape) for a while.
</para>
</listitem>

</orderedlist>
</section>

<section>
<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">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 caching</emphasis>
</para>
</listitem>


</orderedlist>
</section>
</section>
</chapter>

<chapter id="installation">
<title>Installation</title>

<section>
<title>Installing Spice in RHEL or Fedora environment</title>
<para>
Be aware that there is no build of spice-server for i386 so you can run only client part on i386. The reason for it is that there is no buld of qemu-kvm for RHEL of Fedora i386 either. 
</para>
<section>
<title>RHEL 6 and Fedora &gt;=13</title>
<para>
<screen>
yum install qemu-kvm spice-client
</screen>
</para>
<para>
Package spice-protocol will be downloaded automatically as a dependency for package kvm.
</para>
</section>
<section><title>RHEL 5</title>
<para>
<screen>
yum install kvm qspice-client
</screen>
</para>
<para>
Similarly as in RHEL6 package kvm has qspice-libs as a dependency.
</para>
</section>
<section><title>RHEVM Users</title>
<para>
<emphasis role="bold">RHEVM users could  be also interested in spice-xpi package as it's allow you to execute spice-client directly from the RHEVM UserPortal.</emphasis>
<screen>
yum install spice-xpi
</screen>
</para>
</section>
</section>
</chapter>

<chapter id="running_spice">
<title>Running Spice</title>
<para>
</para>
<section>
<title>Creating image</title>
<orderedlist>
<listitem>
<para>
<emphasis role="bold">A File based image</emphasis>
<screen>qemu-img create /path/to/image.img 10G</screen>
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">You can also use logical volumes in case that you already have at least one volume group configured</emphasis>
</para>
</listitem>
</orderedlist>
</section>
</chapter>
</book>