README.md

   1 Spice agent for Linux
   2 =====================
   3
   4 The spice agent for Linux consists of 2 parts, a daemon spice-vdagentd and
   5 a per X-session process spice-vdagent. The daemon gets started in Spice guests
   6 through a Sys-V initscript or a systemd unit. The per X-session gets
   7 automatically started in desktop environments which honor /etc/xdg/autostart,
   8 and under gdm.
   9
  10 The main daemon needs to know which X-session daemon is in the currently
  11 active X-session (think switch user functionality) for this console kit or
  12 systemd-logind (compile time option) is used. If no session info is
  13 available only one X-session agent is allowed.
  14
  15 Features:
  16 * Client mouse mode (no need to grab mouse by client, no mouse lag)
  17   this is handled by the daemon by feeding mouse events into the kernel
  18   via uinput. This will only work if the active X-session is running a
  19   spice-vdagent process so that its resolution can be determined.
  20 * Automatic adjustment of the X-session resolution to the client resolution
  21 * Support of copy and paste (text and images) between the active X-session
  22   and the client. This supports both the primary selection and the clipboard.
  23 * Support for transferring files from the client to the agent
  24 * Full support for multiple displays using Xrandr, this requires a new
  25   enough xorg-x11-drv-qxl driver, as well as a new enough host.
  26 * Limited support for multiple displays using Xinerama.
  27 * Limited support for setups with multiple Screens (multiple qxl devices each
  28   mapped to their own screen)
  29
  30 ## Install
  31
  32 From inside your virtual machine (e.g., GNOME Boxes), use your guest system’s
  33 package manager to install.
  34
  35 For example, if you’re running a Debian/Ubuntu derivative in a VM, use:
  36
  37 ```shell
  38 sudo apt install spice-vdagent
  39 ```
  40
  41 ## How it works
  42
  43 All vdagent communications on the guest side run over a single pipe which
  44 gets presented to the guest os as a virtio serial port.
  45
  46 Under windows this virtio serial port has the following name:
  47 >>>
  48     \\\\.\\Global\\com.redhat.spice.0
  49 >>>
  50
  51 Under Linux this virtio serial port has the following name:
  52 >>>
  53     /dev/virtio-ports/com.redhat.spice.0
  54 >>>
  55
  56 To enable the virtio serial port you need to pass the following params on
  57 the qemu cmdline:
  58
  59 >>>
  60     -device virtio-serial-pci,id=virtio-serial0,max_ports=16,bus=pci.0,addr=0x5 \
  61     -chardev spicevmc,name=vdagent,id=vdagent \
  62     -device virtserialport,nr=1,bus=virtio-serial0.0,chardev=vdagent,name=com.redhat.spice.0
  63 >>>