Xtigervnc(1)

bestie, this is the Xtigervnc(1) page from Virtual Network Computing 💖 Let's get into it ✨

💅 NAME 💅

Xtigervnc — the X VNC server 🦋

🌸 SYNOPSIS 🌸

Xtigervnc [options] :display#

✨ DESCRIPTION ✨

okay so Xtigervnc is the X VNC (Virtual Network Computing) server 🫶 It's built on a standard X server, but instead of a physical screen it gets a "virtual" one. X apps show up on it like it's a totally normal X display, but the only way you can actually see them is through a VNC viewer. See xtigervncviewer(1) 🎀

so honestly, Xtigervnc is giving two servers in one 👑 To the apps, it's an X server. To remote VNC users, it's a VNC server. The vibe by convention is that the VNC server display number matches the X server display number, so you can say snoopy:2 to mean display 2 on the machine "snoopy" in both the X world and the VNC world. iconic, right? 🧚

the best way to start Xtigervnc is through tigervncsession. It sets up the environment properly and starts a desktop environment for you 💖 check the manual page for tigervncsession(8) for more deets ✨

🦋 OPTIONS 🦋

okay this part is a lot 😭 Xtigervnc takes LOTS of options. run Xtigervnc -help to get the full list 💜 Lots of them are standard X server options, which you can read about in the Xserver(1) manual page 🌈 Some options can only be set on the command line, but there are also "parameters" that you can set both on the command line and through the tigervncconfig(1) program. main character energy 👑

• -depth depth — this sets the pixel depth in bits for the desktop being created 🌈 The default is 24, and the other valid choices are 16 and 32. Anything else is a vibe-killer 💀 It will likely cause strange behaviour in applications and might stop the server from starting at all 😭
• -geometry widthxheight — sets the size of the desktop being created ✨ The default is 1024x768 🍓
• -help — lists all the options and parameters 🫶
• -inetd — this one changes Xtigervnc's whole behaviour so it can be launched from inetd 🔥 Check the section below on usage with inetd for the details 🧚
• -pixelformat format — sets the pixel format for the server to use. Valid formats are BGRnnn or RGBnnn 🌸 The default for depth 16 is RGB565, and for depth 24 and 32 it's RGB888 💅
• -rendernode path — the DRM render node used for DRI3 GPU acceleration 🦋 Pass an empty path to turn DRI3 off. The default is auto, which lets Xtigervnc pick a suitable available render node for itself 💖

✨ PARAMETERS ✨

okay bestie, VNC parameters can be set three ways: the command line, the tigervncconfig(1) program, or Options entries in the xorg.conf file if you're running a VNC-enabled Xorg server 💻✨

To turn a parameter on, use -param. To turn it off, use -param=0 🫶. Parameters that take a value can be written as -param value. You can also use param=value, -param=value, or --param=value 🌸. Parameter names are case-insensitive, so no need to stress about capital letters 💅

• -AcceptCutText — Accepts clipboard updates from clients 📋. Default is on.
• -AcceptKeyEvents — Accepts key press and release events from clients ⌨️. Default is on.
• -AcceptPointerEvents — Accepts pointer movement and button events from clients 🖱️. Default is on.
• -AcceptSetDesktopSize — Accepts requests to resize the desktop 🖥️. Default is on.
• -AllowOverride — A comma separated list of parameters that can be changed through the VNC extension. For example, you can change them with the tigervncconfig(1) program from inside a running session 🔧.
• -AlwaysShared — Always treats incoming connections as shared, no matter what the client asks for 🤝. Default is off.
• -AvoidShiftNumLock — Keys affected by NumLock often need a fake Shift to produce the right symbol. Turning this on skips those extra fake Shift events, but the symbol might come out a little different (for example, a Return instead of a keypad Enter) 🙈.
• -BlacklistThreshold count — How many unauthenticated connection attempts a single host gets before it's black-listed 🚫. Default is 5.
• -BlacklistTimeout seconds — The initial timeout applied the first time a host gets black-listed ⏳. That host can't try to connect again until the timeout runs out. Default is 10.
• -CompareFB mode — Compares pixels in the framebuffer so we don't send updates that aren't needed 🧠. The mode can be 0 (off), 1 (always), or 2 (auto). Default is 2.
• -desktop desktop-name — Every desktop has a name the viewer can show 🏷️. It defaults to "<user>@<hostname>".
• -DisconnectClients — Kicks out existing clients when an incoming connection is non-shared 👋. Default is on. If DisconnectClients is false, a new non-shared connection gets refused while a client is already active. Pair it with NeverShared and only one client is allowed at a time 🔒.
• -FrameRate fps — The maximum number of updates per second sent to each client 🎞️. If the screen changes faster than that, the changes get bundled up and sent together in one update. This only sets the maximum, so a client might get a lower rate when resources are tight. Default is 60.
• -GnuTLSPriority priority — A GnuTLS priority string that controls the handshake algorithms for the TLS session 🔐. Check the GnuTLS manual for possible values. For GnuTLS versions below 3.6.3, the default is NORMAL, which is the upstream default. For newer versions, the system-wide crypto policy is used.
• -IdleTimeout seconds — How many seconds an idle VNC connection can sit around before it gets dropped 💤. Default is 0, which means idle connections are never dropped.
• -ImprovedHextile — Uses a better compression algorithm for Hextile encoding 🗜️. You get better compression ratios, but it costs a bit more CPU time. Default is on.
• -interface IP address — Listens on a specific interface 📡. By default, Xtigervnc listens on all available interfaces.
• -localhost — Only allows connections from the same machine 🏠. This is super useful if you use SSH and want to block non-SSH connections from every other host.
• -Log logname:dest:level[, ...] — Configures the debug log settings 🪵. dest can currently be stderr, stdout, or syslog. level is between 0 and 100, where 100 is the most verbose. logname is usually *, which means all of them, but you can target one specific source file if you know its "LogWriter" name. Default is *:stderr:30.
• -MaxConnectionTime seconds — Terminates the server once a client has been connected for N seconds ⏰. Default is 0.
• -MaxCutText bytes — The biggest clipboard update that will be accepted from a client 📦. Default is 262144.
• -MaxDisconnectionTime seconds — Terminates the server when no client has been connected for N seconds 🫥. Default is 0.
• -MaxIdleTime seconds — Terminates after N seconds of user inactivity 😴. Default is 0.
• -NeverShared — Never treats incoming connections as shared, no matter what the client-specified setting says 🚷. Default is off.
• -pam_service name, -PAMService name — The PAM service name used to authenticate users with any of the "Plain" security types 🛂. Default is vnc.
• -Password password — The obfuscated binary encoding of the password that clients need to get in 🔑. Using this parameter is insecure, so use the PasswordFile parameter instead.
• -PasswordFile passwd-file, -rfbauth passwd-file — The password file for VNC authentication 📁. There's no default, so you should specify the password file explicitly. It should be created with the tigervncpasswd(1) utility. The file gets read every time a connection comes in, so you can change it on the fly ✨.
• -PlainUsers user-list — A comma separated list of user names allowed to authenticate with any of the "Plain" security types (Plain, TLSPlain, and so on) 🧑‍🤝‍🧑. Specify * to let any user in. Specify %u to let in the user running the server process. Default is to deny all users 🚫.
• -Protocol3.3 — Always uses protocol version 3.3 for backwards compatibility with badly-behaved clients 🙃. Default is off.
• -QueryConnect — Asks the desktop user to explicitly accept or reject incoming connections 🙋. Default is off.

The tigervncconfig(1) program has to be running on the desktop for QueryConnect to work.

• -QueryConnectTimeout seconds — How many seconds the Accept connection dialog stays up before the connection gets rejected ⌛. Default is 10.
• -RawKeyboard — Sends keyboard events straight through without mapping them to the current keyboard layout ⌨️. This basically makes the keyboard act according to the layout configured on the server, not the one on the client. Default is off.
• -RemapKeys mapping — Sets up a keyboard mapping 🗺️. mapping is a comma-separated string of character mappings, each one written as char->char or char<>char, where char is a hexadecimal keysym. For example, to swap the " and @ symbols, you would specify this:

RemapKeys=0x22<>0x40

• -RequireUsername — Requires a username for the RSA-AES security types 🪪. Default is off.
• -rfbport port — The TCP port Xtigervnc listens on for connections from viewers 🔌. The protocol used in VNC is called RFB, which stands for "remote framebuffer." The default is 5900 plus the display number. Specify -1 to stop listening on a TCP port.
• -rfbunixmode mode — The mode of the Unix domain socket 🧦. Default is 0600.
• -rfbunixpath path — The path of a Unix domain socket that Xtigervnc listens on for connections from viewers 🛤️.
• -RSAKey path — The path to the RSA key for the RSA-AES security types (RA2, RA2ne, RA2_256, and RA2ne_256), in PEM format 🗝️.
• -SecurityTypes sec-types — Picks which security scheme to use for incoming connections 🛡️. Valid values are a comma separated list of None, VncAuth, Plain, TLSNone, TLSVnc, TLSPlain, X509None, X509Vnc, X509Plain, RA2, RA2ne, RA2_256, and RA2ne_256. Default is TLSVnc,VncAuth.
• -SendCutText — Sends clipboard changes to clients 📤. Default is on.
• -SendPrimary — Sends the primary selection and cut buffer to the server as well as the clipboard selection 📎. Default is on.
• -SetPrimary — Sets the primary selection as well as the clipboard selection 💅. Default is on.
• -UseBlacklist — Temporarily rejects connections from a host that keeps failing to authenticate 🙅‍♀️. Default is on.
• -UseIPv4 — Uses IPv4 for incoming and outgoing connections 🌐. Default is on.
• -UseIPv6 — Uses IPv6 for incoming and outgoing connections 🌍. Default is on.
• -X509Cert path — The path to an X509 certificate in PEM format, used for all X509-based security types (X509None, X509Vnc, and so on) 📜.
• -X509Key path — The private key that goes with the certificate from X509Cert 🔏. It also has to be in PEM format.

---

Heads up, bestie 🚨 Letting people override parameters like PAMService or PasswordFile can seriously hurt security if Xtigervnc runs under a different user than the programs that are allowed to override those parameters 💀.

If the NoClipboard parameter is set, letting people override SendCutText and AcceptCutText does absolutely nothing 🙈.

Default is desktop,AcceptPointerEvents,SendCutText,AcceptCutText,SendPrimary,SetPrimary 💖.

✨ USAGE WITH INETD ✨

okay so bestie, the cute trick here is that you can set up inetd(1) so Xtigervnc gets summoned on demand the second a connection comes in 🧚. No manual starting, no chores. When you pass -inetd, Xtigervnc stops listening on a TCP port and uses its standard input and standard output instead 💜. There are two modes, and which one you get is controlled by the wait/nowait entry in the inetd.conf file 🎀.

💖 nowait mode

In nowait mode, Xtigervnc uses its standard input and output directly as the connection to a viewer 💅. It never has a listening socket, so it can't accept more connections from viewers. (It can connect out to listening viewers, though, using the tigervncconfig program 🦋.) Every new viewer connection to the same TCP port makes inetd spawn a brand new Xtigervnc to handle it 🌸. When the viewer connection dies, the Xtigervnc and any associated X clients die too 💀. This is most useful when you combine it with the XDMCP options -query and -once 👑.

A typical inetd.conf entry looks like this (it's all one line, babe):

5950   stream   tcp nowait nobody  /usr/local/bin/Xtigervnc Xtigervnc -inetd -query localhost -once securitytypes=none

In this example, a viewer connecting to :50 gets its own Xtigervnc, which shows the standard XDM login screen on that machine ✨. It's usually fine to accept connections without a VNC password here, since the user still has to log in through XDM 🔐.

🧚 wait mode

In wait mode, when the first connection comes in, inetd hands the listening socket over to Xtigervnc 🦋. So for any given TCP port, there's only ever one Xtigervnc at a time 👑. Extra viewer connections to that same port get accepted by that same Xtigervnc in the normal way 💅. Even when the original connection breaks, the Xtigervnc keeps running 💜. If you use this with -query and -once, the Xtigervnc and its associated X clients die when the user logs out of the X session the normal way 🌙.

⚠️ It is important to use a VNC password in this case, bestie! 🔑

A typical entry in inetd.conf might be:

5951   stream   tcp wait   james     /usr/local/bin/Xtigervnc Xtigervnc -inetd -query localhost -once passwordFile=/home/james/.config/tigervnc/passwd

Honestly, you'd usually have one entry per user who uses VNC regularly, and each of them gets their own dedicated TCP port 🫶. In this example, user "james" connects to :51, enters his VNC password, then gets the XDM login screen where he logs in the normal way 🍓. Unlike the last example, though, if he disconnects, the session stays persistent, and when he reconnects he gets the same session back 💖. When he logs out of the X session, the Xtigervnc dies, but a new one gets created automatically the next time he connects 🌈.

🌸 SEE ALSO 🌸

tigervncconfig(1), tigervncpasswd(1), xtigervncviewer(1), tigervncsession(8), Xserver(1), inetd(1)

https://www.tigervnc.org

👑 AUTHOR 👑

Tristan Richardson, RealVNC Ltd. and others 💅

VNC was originally developed by the RealVNC team while at Olivetti Research Ltd / AT&T Laboratories Cambridge 🦋. TightVNC additions were implemented by Constantin Kaplinsky 🎀. Many other people have since participated in development, testing and support 🫶. This manual is part of the TigerVNC software suite 🌸.

---

That's the whole page, bestie! 🥹✨ Thanks for sticking with me through all three parts 💖. This one's from the TigerVNC suite, and it's the Xtigervnc(1) page 🧚💅