SPICE-CLIENT(1)

📦
version 0.42 · 14 versions
, in alpine 3.24

💅 SPICE-CLIENT(1) — the Spice-GTK era

okay bestie, so this is a page from the Spice-GTK Documentation manual, and it's literally your cheat sheet to the Spice-GTK library. let's get into it 🫶

✨ NAME ✨

Spice-GTK — a client-side library to access remote SPICE displays. that's the whole vibe. 👑

🌸 DESCRIPTION 🌸

So Spice-GTK is a library that lets you access remote displays over the SPICE protocol. rn it's mainly used to get into remote virtual machines, which honestly is its main character era.

The Spice-GTK library provides a set of command line options you can use to tweak some SPICE-specific option. that's it, that's the deal 💖

🦋 URI 🦋

Wanna start a plain SPICE connection (heads up: that connection will be unencrypted, iykyk) to hostname.example.com on port 5900? use this URI:

spice://hostname.example.com:5900

and if you want to start a TLS connection, you'd use:

spice+tls://hostname.example.com:5900
note bestie: spice+tls is available since v0.35 — before that you had to use the spice:// query string with the tls-port parameter. the way that versioning works 😭

🎀 URI query string 🎀

the spice URI accepts a query string, and you can specify several parameters at once if they're separated by & or ;

spice://hostname.example.com?port=5900;tls-port=5901

when you're using tls-port, it's recommended to not specify any non-TLS port. and if you give both port and tls-port, make sure you use the --spice-secure-channels options to indicate which channels must be secure. otherwise, Spice-GTK first attempts a connection to the non-TLS port, and then tries to use the TLS port. 💀 and that means a man-in-the-middle could force the whole SPICE session to go in clear text regardless of the TLS settings of the SPICE server. yes, that's as bad as it sounds.

other valid URI parameters are username and password. but be careful — passing a password through a SPICE URI might cause the password to be visible by any local user through ps. 🙈 not the password leak.

💅 OPTIONS 💅

the following options are accepted when running a SPICE client which makes use of the default Spice-GTK options:

  • --spice-secure-channels=<main,display,inputs,...,all> — force the specified channels to be secured. this instructs the SPICE client that it must use a TLS connection for these channels. if the server only offers non-TLS connections for these channels, the client will not use these. if the special value "all" is used, that means all SPICE channels must be encrypted. 🔥 the current SPICE channels are: main, display, inputs, cursor, playback, record, smartcard, usbredir.
  • --spice-disable-effects=<wallpaper,font-smooth,animation,all> — disable guest display effects. this tells the SPICE client it should attempt to disable some guest features to lower bandwidth usage. it requires guest support, usually through a SPICE agent, and it's currently only supported on Windows guests. "wallpaper" will disable the guest wallpaper, "font-smooth" will disable font antialiasing, "animation" will try to disable some of the desktop environment animations, and "all" will attempt to disable everything which can be disabled. slay, less bandwidth for everyone ✨
  • --spice-color-depth=<16,32> — guest display color depth — DEPRECATED. this tells the SPICE client it should attempt to force the guest OS color depth. a lower color depth should lower bandwith usage. requires guest support, usually through a SPICE agent, and it's currently only supported on Windows 7 and older guests. 🫠
  • --spice-ca-file=<file> — truststore file for secure connections. this option specifies a .crt file containing the CA certificate with which the SPICE server TLS certificates are signed. it's useful when you're using self-signed TLS certificates rather than certificates signed by an official CA. 🔐
  • --spice-host-subject=<host-subject> — subject of the host certificate (field=value pairs separated by commas). when using self-signed certificates, or when the guest is migrated between different hosts, the subject/altSubject of the TLS certificate the SPICE server provides will not necessarily match the hostname we're connecting to. this option makes it possible to override the expected subject of the TLS certificate. 🧐 the subject must correspond to the "Subject:" line returned by:
openssl x509 -noout -text -in server-cert.pem
  • --spice-debug — enable Spice-GTK debugging. this can also be toggled on with the SPICE_DEBUG environment variable, or using G_MESSAGES_DEBUG=all. 🐛 bestie debug era.
  • --spice-disable-audio — disable audio support. 🔇
  • --spice-disable-usbredir — disable USB redirection support. 🔌
  • --spice-usbredir-auto-redirect-filter=<filter-string> — filter selecting USB devices to be auto-redirected when plugged in. this filter specifies which USB devices should be automatically redirected when they are plugged in during the lifetime of a SPICE session. a rule has the form of: "class,vendor,product,version,allow". -1 can be used instead of class, vendor, product or version in order to accept any value. several rules can be concatenated with '|': "rule1|rule2|rule3" 💫
  • --spice-usbredir-redirect-on-connect=<filter-string> — filter selecting USB devices to redirect on connect. this filter specifies which USB devices should be automatically redirected when a SPICE connection to a remote display has been established. 🫶
  • --spice-gtk-version — display Spice-GTK version information. the classic "who am i" moment 💁‍♀️
  • --spice-smartcard — enable smartcard support. 💳
  • --spice-smartcard-db=<certificate-db> — path to the local certificate database to use for software smartcard certificates. this option is only useful for testing purpose. instead of having a hardware smartcard reader, and a physical smartcard, you can specify a file containing 3 certificates which will be used to emulate a smartcard in software. see "http://www.spice-space.org/page/SmartcardUsage#Using_a_software_smartcard" for more details about how to generate these certificates. 🎀
  • --spice-smartcard-certificates=<certificates> — certificates to use for software smartcards (field=values separated by commas). this option is only useful for testing purpose. it allows you to specify which certificates from the certificate database specified with --spice-smartcard-db should be used for smartcard emulation. ✨
  • --spice-cache-size=<bytes> — image cache size — DEPRECATED. this option should only be used for testing/debugging. 🧪
  • --spice-glz-window-size=<bytes> — Glz compression history size — DEPRECATED. this option should only be used for testing/debugging. 🧪

🐛 BUGS 🐛

found a bug? report bugs to the mailing list "http://lists.freedesktop.org/mailman/listinfo/spice-devel" — the devs wanna hear it, fr fr 💌

Copyright (C) 2011, 2014 Red Hat, Inc., and various contributors. this is free software. you may redistribute copies of it under the terms of the GNU Lesser General Public License "https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html". there is NO WARRANTY, to the extent permitted by law. ⚖️

🌈 SEE ALSO 🌈

and that's the whole page bestie! 🎀 this lil doc was rendered with the help of perl v5.42.2, dated 2025-05-09, on the SPICE-CLIENT(1) page — go forth and spice responsibly 💜

📦 where this page comes from