diff --git a/src/configuring-guacamole.md.j2 b/src/configuring-guacamole.md.j2 index 9793561..ea03598 100644 --- a/src/configuring-guacamole.md.j2 +++ b/src/configuring-guacamole.md.j2 @@ -1489,6 +1489,544 @@ the features of Guacamole's authentication API, you will be able to add a new RDP connection easily and intuitively using the administration interface built into Guacamole. You will not need to edit configuration files. +### SPICE + +The SPICE (Simple Protocol for Independent Computing Environments) protocol +provides remote display and device-sharing capabilities primarily used with +virtual machines managed by QEMU, KVM, or libvirt. Compared to VNC, SPICE +offers higher-performance display updates, native audio support, and a richer +set of device channels including clipboard, file transfer, and USB redirection. + +SPICE support for Guacamole is provided by the libguac-client-spice library, +which will be installed as part of guacamole-server if the required +dependencies are present during the build. + +:::{note} +In addition to the SPICE-specific parameters below, Guacamole's SPICE support +also accepts the parameters of several features that Guacamole provides for +multiple protocols: + +* [](disable-clipboard) +* [](common-sftp) +* [](graphical-recording) +* [](wake-on-lan) +::: + +(spice-network-parameters)= + +#### Network parameters + +SPICE connections require the hostname or IP address of the SPICE server and +the port number on which the SPICE server is listening. SPICE servers are +commonly exposed by QEMU virtual machines; the default port is 5900. + +`hostname` +: The hostname or IP address of the SPICE server Guacamole should connect to. + +`port` +: The port the SPICE server is listening on. This parameter is optional. If + omitted, the default SPICE port (5900) will be used. + +`tls-port` +: The port to use for TLS-encrypted SPICE connections. If specified, + Guacamole will attempt to upgrade the connection to TLS after the initial + plaintext handshake. This parameter is optional. + +`tls` +: If set to "true", the connection to the SPICE server will be established + over TLS (Transport Layer Security), providing an encrypted channel. This + parameter is optional. By default, connections are made without encryption. + +`proxy` +: The hostname and port of a SPICE proxy server through which the connection + should be routed, in the form `hostname:port`. This parameter is optional. + +(spice-authentication)= + +#### Authentication + +SPICE uses a ticket-based authentication mechanism. The password specified +here corresponds to the SPICE ticket configured on the server (for example, +via the `-spice password=...` QEMU option or the equivalent libvirt XML +setting). A username may also be provided, though SPICE does not use it for +authentication — it is retained mainly for logging and auditing purposes. + +`username` +: The username to associate with this connection. This parameter is optional. + Note that SPICE does not use the username for authentication; it is + retained for logging and auditing purposes only. + +`password` +: The SPICE ticket (password) to use when authenticating with the SPICE + server. This parameter is optional. If the SPICE server is configured + without a ticket, this parameter may be omitted. + +(spice-tls)= + +#### TLS and certificate settings + +When connecting to a SPICE server over TLS, Guacamole can optionally verify +the server's certificate against a known CA or a pinned public key. If none of +the verification parameters below are specified, no certificate verification is +performed. + +`ca-cert` +: The PEM-encoded certificate of the Certificate Authority (CA) that signed + the SPICE server's TLS certificate. If provided, the server's certificate + will be verified against this CA, and the connection will be rejected if + verification fails. This parameter is optional. + +`cert-subject` +: The expected subject string of the SPICE server's TLS certificate. If + provided, Guacamole will verify that the server's certificate subject + matches this value. This parameter is optional. + +`pubkey` +: The Base64-encoded DER-format public key of the SPICE server, used for + public-key pinning. If provided, the server's public key is verified + against this value, and the connection will be rejected if the keys do not + match. This parameter is optional. + +`ignore-cert` +: If set to "true", the TLS certificate returned by the server will be + ignored, even if that certificate cannot be validated. This is useful if + the server uses a self-signed certificate and you universally trust the + server and your connection to it. This parameter is optional. + +(spice-display-settings)= + +#### Display settings + +`color-depth` +: The color depth to request, in bits-per-pixel. This parameter is optional. + If specified, this must be either 8, 16, 24, or 32. Regardless of what + value is chosen here, if a particular update uses less than 256 colors, + Guacamole will always send that update as a 256-color PNG. + +`swap-red-blue` +: If the colors of your display appear wrong (blues appear orange or red, + etc.), it may be that the SPICE server is sending image data with the red + and blue components swapped. If this is the case, set this parameter to + "true" to work around the problem. This parameter is optional. + +`preferred-compression` +: The preferred image compression algorithm to request from the SPICE server. + This parameter is optional. If omitted, the server and client will + negotiate an algorithm automatically. + + Possible values are: + + off + : Request that no image compression be used. This requires the most + bandwidth but imposes the least CPU overhead. + + auto-glz + : Automatically select GLZ (Global LZ) compression based on image content. + This is a good general-purpose default. + + auto-lz + : Automatically select LZ compression based on image content. + + quic + : Use the QUIC (Quick Image Compression) algorithm. + + glz + : Use GLZ (Global LZ) compression. + + lz + : Use LZ compression. + + lz4 + : Use LZ4 compression, which offers very fast compression and decompression + at the cost of compression ratio. + +`preferred-video-codec` +: The video codec that the SPICE server should be asked to prefer when + encoding regions of the screen that it detects as video, such as a playing + video. This parameter is optional. If omitted, guacd sends no preference and + the SPICE server uses its own default, which is typically MJPEG. + + Requesting an efficient codec such as H.264 can significantly reduce the + bandwidth used by video content, but note the following requirements: + + - The host running guacd must have the corresponding GStreamer decoder + plugins installed (for example `gstreamer1.0-libav` and + `gstreamer1.0-plugins-good`, which provide the H.264, VP8, and VP9 + decoders). Without them, guacd cannot decode the codec and the SPICE + server falls back to sending those regions as ordinary image updates. + MJPEG is decoded natively and requires no additional plugins. + + - The SPICE server must be built with GStreamer support, have the matching + GStreamer *encoder* plugins installed, and have video streaming enabled + (for example, using the QEMU `-spice streaming-video=filter` option). + + :::{important} + Some SPICE server versions crash when a client requests a preferred video + codec while a video stream is active (see [SPICE issue + 99](https://gitlab.freedesktop.org/spice/spice/-/issues/99)). For this + reason, this parameter is unset by default; only enable it against a SPICE + server that is known to include the fix. When it is unset, guacd sends no + preference and the server's safe default (MJPEG) is used. + ::: + + Possible values are: + + h264 + : Prefer H.264, falling back to MJPEG if it is unavailable. H.264 generally + offers the best compression for video content. + + vp9 + : Prefer VP9, falling back to MJPEG if it is unavailable. + + vp8 + : Prefer VP8, falling back to MJPEG if it is unavailable. + + mjpeg + : Explicitly prefer MJPEG. This is the most widely supported codec and the + safest choice. + +`read-only` +: Whether this connection should be read-only. If set to "true", no input + will be accepted on the connection at all. Users will only see the desktop + and whatever other users sharing that same desktop are doing. This + parameter is optional. + +`disable-display-resize` +: Whether or not Guacamole should refrain from sending display size updates + to the SPICE server. By default, Guacamole sends the client's display + dimensions to the SPICE server when the connection is established and + whenever the browser window is resized. If this option is set to "true", + display size updates will not be sent, and the desktop will remain at + whatever size the SPICE server has configured. This parameter is optional. + +`secondary-monitors` +: The maximum number of *secondary* monitors (in addition to the primary + monitor) that a client may request for this connection. The default is 0, + which disables multi-monitor support. When set to a positive value, a + multi-monitor–capable Guacamole client may open that many additional monitor + windows; Guacamole requests the corresponding monitor layout from the guest, + and each monitor is rendered as a region of the single combined display. + + :::{important} + Multi-monitor support requires a guest that can activate additional heads on + request — in practice, a QXL virtual GPU with the SPICE guest agent + (`spice-vdagent`) running. The number of monitors is also limited by the + guest's graphics configuration (for QXL, typically up to four heads). + ::: + + :::{important} + With QXL, all monitors are composited into a **single combined framebuffer** + (the primary surface), so the QXL device must have enough framebuffer memory + for the *sum* of all monitors. This memory is the QXL `vgamem_mb` setting — + **not** `ram_size`/`vram_size`, which serve other purposes and do **not** + raise the maximum resolution. The primary surface requires roughly + + ``` + vgamem_mb ≳ (total_width × total_height × 4 bytes) / 1 MiB + headroom + ``` + + For example, two 2560×1600 monitors side by side form a 5120×1600 combined + surface (~32 MiB), which exceeds the common default of 16 MiB. If `vgamem_mb` + is too small the guest cannot build the wide surface and silently falls back + to **mirroring** the monitors (all heads at the same origin) instead of + extending them. Increase it before using multi-monitor at high resolution. + + On **Proxmox VE**, set this via the display memory option, e.g. + `vga: qxl2,memory=128` (the `memory=` value maps to `vgamem_mb`). Note that + selecting `qxl2`/`qxl3`/`qxl4` alone does **not** raise `vgamem_mb`, so the + `memory=` option must be set explicitly for high-resolution multi-monitor. + With `libvirt`/`virt-manager`, set `