tigervncserver(1)

📦
version 1.15.0 · 4 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 tigervncserver — the TigerVNC standalone server starter 💖

okay bestie, welcome to the tigervncserver(1) page, from the Virtual Network Computing manual 💅 this is the one that gets your whole VNC desktop situation going, and I'm gonna walk you through every single bit of it, no skipping, no cap.

✨ NAME ✨

tigervncserver — start or stop a TigerVNC standalone server 🫶

🌸 SYNOPSIS 🌸

like, here's the shape of every way you can call her:

tigervncserver [[user@]host][:display#] [-rfbport rfbport#]
[-rfbunixpath Unixsocketpath] [-rfbunixmode permissions] [-localhost
[yes|no]] [-SecurityTypes sec-types] [-RequireUsername [yes|no]]
[-PasswordFile|-rfbauth passwd-file] [-PlainUsers user-list]
[-PAMService|-pam_service service-name] [-X509Key cert-key-file]
[-X509Cert cert-file] [-RSAKey rsa-key-file] [-fg] [-useold] [-verbose]
[-dry-run] [-geometry <width>x<height>] [-wmDecoration <width>x<height>]
[-xdisplaydefaults] [-xstartup script] [-noxstartup] [-desktop desktop-
name] [-depth depth] [-pixelformat format] [-autokill [yes|no]] [-fp
font-path] [-pidfile pid-file-path] [Xtigervnc options...]  [-- X
session or command with optional options...]
tigervncserver -kill [[user@]host][:display#|:*] [-rfbport rfbport#]
[-rfbunixpath Unixsocketpath] [-dry-run] [-verbose] [-clean]
tigervncserver -list [[user@]host][:display#|:*] [-rfbport rfbport#]
[-rfbunixpath Unixsocketpath] [-cleanstale]
tigervncserver -version

three modes, bestie: start it, kill it, list it, plus a lil version check. slay.

🦋 DESCRIPTION 🦋

tigervncserver is the thing you run to start a TigerVNC (Virtual Network Computing) desktop 🌈. Under the hood it's a Perl wrapper script — not me being dramatic, that's literally what it is — and its whole job is to make starting an instance of the Xtigervnc VNC server way less painful than doing it yourself 😭. It runs Xtigervnc with the appropriate options, and then it starts some X applications so you actually have stuff to look at in your TigerVNC desktop ✨.

Here's the cute part: you can run tigervncserver with no options at all 💚. In that case it'll:

  1. pick the first available display number (usually :1),
  2. start Xtigervnc as that display,
  3. and run a couple of basic applications to get you started 🎀

You can also specify the display number yourself, and then it'll use that number if it's available and just exit if it's not 🙈. Like:

tigervncserver :13

🧚 user@host energy 🧚

Moreover (iconic word), you can hand over a username and a hostname to start the tigervncserver via SSH on the given machine, under the provided user account 💜, like so:

tigervncserver franz@kopernikus:13
⚠️ Heads up bestie: this requires the same version of the tigervncserver wrapper script on the remote machine as is on the local machine. No version mismatches, fr fr.

🌸 making it yours 🌸

Creating the file ~/.config/tigervnc/xstartup lets you change the applications that run at startup 🫶 — but note that this will not affect an existing desktop, so don't come for me when your already-running session doesn't budge 💀.

👑 the config priority ladder (iykyk) 👑

System defaults for this wrapper script live in /etc/tigervnc/vncserver-config-defaults. Those defaults can be overwritten by the user defaults given in ~/.config/tigervnc/config.pl (go read the tigervnc.conf(5x) man page for that one 📖). Then, command-line options overwrite the settings in both tigervnc configuration files. And finally, options from /etc/tigervnc/vncserver-config-mandatory have the highest priority, overwriting all previous settings 👑✨.

So the vibe check order is, lowkey:

  1. /etc/tigervnc/vncserver-config-defaults
  2. ~/.config/tigervnc/config.pl
  3. command-line options
  4. /etc/tigervnc/vncserver-config-mandatory — main character, always wins 💅
🚨 WARNING! There is nothing stopping users from constructing their own wrapper script that calls Xtigervnc directly, to bypass any options defined in the /etc/tigervnc/vncserver-config-mandatory configuration file. So that "mandatory" file is mandatory-ish, and you should know that 🙈.

okay that's the setup, bestie — more coming, don't go anywhere 💖

✨ OPTIONS ✨

okay bestie, here's the tea 🍓 you can get a full list of options by handing -h to tigervncserver. and lowkey important: on top of everything listed down here, any option that doesn't get recognized just gets passed straight through to Xtigervnc — so go check the Xtigervnc(1) man page or run "Xtigervnc -help" for the deets. periodt.

  • :display# — tells you which X11 display the Xtigervnc server should create. iconic little colon-first moment 💅
  • -rfbport rfbport# — sets the TCP port where Xtigervnc listens for viewers (the VNC protocol is called RFB, aka "remote framebuffer", iykyk). default is 5900 plus the display number display#. wanna turn it off entirely? specify -1. 🫶
  • -rfbunixpath Unix socket path — gives a path for the Xtigervnc server to listen on as a Unix domain socket. no Unix domain socket gets created if you don't pass this one. no cap.
  • -rfbunixmode permissions — sets the mode of that Unix domain socket. default is 0600. 🔒
  • -localhost [yes|no] — should the TigerVNC server only listen on localhost for incoming TigerVNC connections? super useful if you're using SSH and wanna block non-SSH connections from every other host. if you don't specify this option at all, here's the vibe: we only listen on localhost if the sec-types list has zero TLS* or X509* security types, or if the list has at least one *None security type. otherwise? we listen on all the network addresses of the machine. 🌐
  • -SecurityTypes sec-types — pick 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 VncAuth if -localhost isn't given, and VncAuth,TLSVnc if -localhost no is given. 🔥
  • -RequireUsername [yes|no] — for the RSA-AES security types (that's RA2, RA2ne, RA2_256, and RA2ne_256), this decides whether auth happens via Unix username and password (-RequireUsername yes) or via the VNC password file (-RequireUsername no). default is authenticating through the VNC password file.
  • -PasswordFile passwd-file or -rfbauth passwd-file — points to the file holding the password used to authenticate viewers, for the security types VncAuth, TLSVnc, X509Vnc, RA2, RA2ne, RA2_256, and RA2ne_256. default password file is ~/.config/tigervnc/passwd. and heads up 💀 for the RSA-AES security types, auth via the VNC password file only happens when -RequireUsername is no, which is the default.
  • -PlainUsers user-list — a comma-separated list of usernames allowed to authenticate via any of the *Plain security types (Plain, TLSPlain, etc.) or the RSA-AES security types (RA2, RA2ne, etc.) when -RequireUsername is yes. specify * to let literally anyone authenticate with these security types. default only allows the user who started the tigervncserver wrapper script. 🫡
  • -PAMService service-name or -pam_service service-name — the PAM service name to use when authenticating users via any of the *Plain security types or the RSA-AES security types when -RequireUsername is yes. default is vnc if /etc/pam.d/vnc exists, and tigervnc otherwise. the tigervnc-common package ships the /etc/pam.d/tigervnc PAM service configuration for tigervncserver to use. 🌸
  • -X509Cert cert-path and -X509Key key-path — paths to a X509 certificate in PEM format used for all X509-based security types (like X509None, X509Vnc, etc.), plus its private key, also in PEM format. if the cert and key aren't provided through -X509Cert and -X509Key or their matching config parameters in /etc/tigervnc/vncserver-config-defaults, ~/.config/tigervnc/config.pl, or /etc/tigervnc/vncserver-config-mandatory, then the tigervncserver wrapper script auto-generates a self-signed certificate. that auto-generated self-signed cert and its private key live in ~/.config/tigervnc/host-SrvCert.pem and ~/.config/tigervnc/host-SrvKey.pem. ✨
  • -RSAKey rsa-key-path — path to an RSA key in PEM format used by all RSA-AES security types. if the RSA key isn't given via -RSAKey or the matching config parameter in /etc/tigervnc/vncserver-config-defaults, ~/.config/tigervnc/config.pl, or /etc/tigervnc/vncserver-config-mandatory, then the tigervncserver wrapper script auto-generates an RSA key. that auto-generated key gets stored in ~/.config/tigervnc/host-SrvRsaKey.pem. 🔑
  • -fg — runs the Xtigervnc server as a foreground process. so yes, you can abort the server with CTRL-C. main character behavior tbh. 😌
  • -useold — only spin up a new TigerVNC server if one isn't already running on your account at the requested display number display# and RFB port rfbport#. if no display number is requested, a new TigerVNC server only starts if there's no TigerVNC server running under your user account at all. either way, you get info printed about the newly started TigerVNC server or the reused TigerVNC server session. 🌀
  • -verbose — turns on some debug output. she's chatty. 💬
  • -dry-run — doesn't actually do anything, just runs the checks to see if the requested action would even be possible. for example, it checks whether the requested display number display# is available. peak "let's just see" energy. 👀
  • -geometry <width>x<height> — sets the size of the desktop being created. by default, a 1920x1200 desktop gets created.
  • -wmDecoration <width>x<height> — sets the adjustment of the dimensions derived by -xdisplaydefaults, to accommodate the window decoration used by the X11 window manager. this is so the VNC desktop fully displays even when the VNC viewer isn't in full screen mode. 🎀
  • -xdisplaydefaults — lets you derive values for the above three options, meaning -geometry through -pixelformat, from the running X session. the derived dimensions get adjusted by the -wmDecoration option.
  • -xstartup script — run a custom startup script instead of ~/.config/tigervnc/xstartup, after launching Xtigervnc. super handy for running full-screen applications. 🖥️
  • -noxstartup — don't run the ~/.config/tigervnc/xstartup script after launching Xtigervnc. this option lets you manually start a window manager inside your TigerVNC session.
  • -desktop desktop-name — every desktop has a name that the viewer might display. it defaults to "host:display# (username)" but you can change it with this option. it gets passed into the Xtigervnc-session script via the $VNCDESKTOP environment variable, which lets you run a whole different set of applications depending on the desktop's name. 💖
  • -depth depth — the pixel depth in bits of the desktop being created. default is 24, other possible values are 16 and 32. anything else is likely to cause strange behaviour by applications and may even stop the server from starting at all. > bestie do NOT freestyle this one. 💀
  • -pixelformat format — the pixel format for the server to use (BGRnnn or RGBnnn). the default for depth 16 is RGB565 (meaning the most significant five bits represent red, the next six green, and the least significant five represent blue), and for depth 24 and 32 it's RGB888. 🌈
  • -autokill [yes|no] — -autokill is enabled by default. when it's on, the TigerVNC server automatically gets killed when the Xtigervnc-session script exits. in most cases this means Xtigervnc terminates when the user logs out of the window manager. to turn it off, use -autokill no.
  • -fp font-path — specifies a font path. otherwise, if no font path is configured, the Xtigervnc server falls back to its own preferred method of font handling. 🔤
  • -pidfile — specifies the file that stores the pid of the Xtigervnc server to be started.
  • -- X session — this special option controls which X session type gets started. it should match one of the files in /usr/share/xsessions. for example, if there's a file called gnome.desktop, then -- gnome would start this X session. ⭐
  • -kill [[user@]host][:display#|:*] [-rfbport rfbport#] — this kills a TigerVNC server that was previously started with tigervncserver or x0tigervncserver. it does this by killing the Xtigervnc process, whose process ID is stored in the file ~/.config/tigervnc/host:rfbport#.pid. this is useful so you can write "tigervncserver -kill $DISPLAY", e.g., at the end of your Xtigervnc-session file after a particular application exits. if :* is given, then tigervncserver tries to kill all Xtigervnc processes with pidfiles in ~/.config/tigervnc on the local machine. if no display number is given, then tigervncserver tries to kill the Xtigervnc processes of the user on the local machine — but only if just one such process is running and has a pidfile in ~/.config/tigervnc. if a host is specified, then tigervncserver uses SSH to kill an Xtigervnc process on the remote machine. 🔪
  • -clean — if given with -kill, then the logfile ~/.config/tigervnc/host:rfbport#.log also gets removed. tidy queen 🧹
  • -list [[user@]host][:display#|:*] [-rfbport rfbport#] — lists all running TigerVNC servers previously started with tigervncserver or x0tigervncserver. if a host is specified, then tigervncserver uses SSH to list VNC desktops on the remote machine. stale entries get marked with (stale) in the output. 📋
  • -cleanstale — if given with -list, then stale entries get cleaned up and are not shown in the -list output. these are the ones resulting from missed cleanups of pidfiles in ~/.config/tigervnc as well as stale X11 locks and sockets in /tmp caused by Xtigervnc or X0tigervnc server crashes. 🧼

🎀 FILES 🎀

Okay bestie, here's where TigerVNC keeps all its lil treasures. Several TigerVNC-related files live in the ~/.config/tigervnc directory:

  • ~/.config/tigervnc/xstartup — a shell script that says which X applications get run when a TigerVNC desktop starts up. If it doesn't exist, the system default provided in /etc/tigervnc/vncserver-config-defaults is used. A mandatory start script can also be given in /etc/tigervnc/vncserver-config-mandatory.
  • ~/.config/tigervnc/passwd — the TigerVNC password file for the security types VncAuth, TLSVnc, and X509Vnc.
  • ~/.config/tigervnc/<host>:<display#>.log — the log file for the VNC server and the applications started by Xtigervnc-session.
  • ~/.config/tigervnc/<host>:<display#>.pid — identifies the VNC server process ID, used by the -kill option.
  • ~/.config/tigervnc/<host>-SrvCert.pem and <host>-SrvKey.pem — the security types X509None, X509Vnc, and X509Plain need a certificate and the corresponding private key. If these are not provided via the -X509Cert and -X509Key command-line options or their corresponding configuration parameters in the configuration files /etc/tigervnc/vncserver-config-defaults, ~/.config/tigervnc/config.pl, or /etc/tigervnc/vncserver-config-mandatory, then the tigervncserver wrapper script auto-generates a self-signed certificate for the -X509Cert and -X509Key options of the Xtigervnc server. The auto-generated self-signed certificate and its private key are stored in the above given two files. If the user wants their own certificate – instead of the on-demand auto-generated one – they can either specify it via the tigervncserver options -X509Cert and -X509Key or replace the files ~/.config/tigervnc/host-SrvCert.pem and ~/.config/tigervnc/host-SrvKe.pem. These files will not be overwritten once generated by the tigervncserver wrapper script.
  • ~/.config/tigervnc/<host>-SrvRsaKey.pem — the RSA-AES security types (i.e., RA2, RA2ne, RA2_256, and RA2ne_256) need an RSA private key. If this key is not provided via the -RSAKey command-line option or the corresponding parameter in the configuration files /etc/tigervnc/vncserver-config-defaults, ~/.config/tigervnc/config.pl, or /etc/tigervnc/vncserver-config-mandatory, then the tigervncserver wrapper script auto-generates an RSA key for the -RSAKey option of the Xtigervnc server. The auto-generated key is stored in the file ~/.config/tigervnc/host-SrvRsaKey.pem.
  • ~/.config/tigervnc/config.pl — the user configuration file for tigervncserver. To be compatible with the upstream provided wrapper scripts, we will fall back to trying to load configuration from ~/.config/tigervnc/config if ~/.config/tigervnc/config.pl is not present. Note that the config file uses key=value lines as configuration syntax, while the config.pl and the tigervncserver-config-* files in the /etc/tigervnc directory use perl(1) syntax.

Furthermore, there are global configuration files for tigervncserver in the /etc/tigervnc directory:

  • /etc/tigervnc/vncserver-config-defaults — the global configuration file specifying the defaults for tigervncserver.
  • /etc/tigervnc/vncserver-config-mandatory — if this file exists and defines options to be passed to Xtigervnc, they will override any of the same options defined in a user's config.pl file or ones given on the command line of this wrapper script. This file offers a mechanism to establish some basic form of system-wide policy.
⚠️ WARNING! There is nothing stopping users from constructing their own wrapper script that calls Xtigervnc directly to bypass any options defined in the /etc/tigervnc/vncserver-config-mandatory configuration file. 💀 Like, the door is locked but the window is wide open, bestie.

✨ SEE ALSO ✨

Go read these too, they're all part of the fam:

👑 AUTHOR 👑

Joachim Falk, 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 Debian packaging project. 🫶

And that's the whole page, bestie! This masterpiece is from TigerVNC 1.14.1, dated Nov 10th, 2024 — slay, iconic, no notes. 💅✨

📦 where this page comes from