tigervnc.conf(5x)

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

💖 tigervnc.conf — the manual page, bestie edition 💖

okay so this is tigervnc.conf(5x) from the Virtual Network Computing manual. it's the page about config files. yes those config files. buckle up 🎀

✨ NAME ✨

tigervnc.conf — configuration files for Virtual Network Computing 🦋

✨ SYNOPSIS ✨

$variable = "someValue";

$variable = "someValue";

$variable .= "someValue";

$variable = $var1 . $var2;

like. that's the whole vibe. assignment. slay. 💅

✨ DESCRIPTION ✨

bestie. listen. this man page is describing the syntax and the options of the three configuration files that tigervncserver(1) loads — and tigervncserver(1) is the free X server for Virtual Network Computing (VNC), in case you were wondering. 🌈

these config files let you change how the server behaves at startup time. and ngl, for every single value there are already perfectly good inbuilt defaults preset. so you don't have to touch anything. but you can. and that's the fun part. ✨

here's the order, and the order is everything:

  1. first, /etc/tigervnc/vncserver-config-defaults gets read. this is the system defaults. 🏠
  2. then tigervncserver(1) moves on and reads $HOME/.config/tigervnc/config.pl — a file you can change on a per-user basis. the options in this file override the system defaults. 👑
  3. next, command-line options overwrite both the system defaults and the settings in $HOME/.config/tigervnc/config.pl. command line said what it said. 💅
  4. finally, /etc/tigervnc/vncserver-config-mandatory gets parsed. if this file exists and defines options to pass to Xtigervnc, they override any of the same options defined in a user's $HOME/.config/tigervnc/config.pl as well as options given via the command line. this file is literally the mechanism for establishing some basic form of system-wide policy. it's giving admin energy. 🔥
⚠️ WARNING! there is nothing stopping users from constructing their own start script that calls Xtigervnc directly to bypass any options defined in /etc/tigervnc/vncserver-config-mandatory. so like. it's policy, not a prison. 💀

✨ EXAMPLES ✨

the system configuration file /etc/tigervnc/vncserver-config-defaults should come with the Debian package tigervnc-standalone-server. 🍓

this file serves as an example for the user file $HOME/.config/tigervnc/config.pl. the system configuration file is pretty self-descriptive, and this document will mainly repeat the information that already can be found there. (yes bestie, we're being redundant on purpose. it's for you. 🫶)

✨ OVERVIEW ✨

the file is in perl(1) syntax — but okay don't panic, only variable assignment is allowed, for your safety and your convenience. 🧚

but there's still a variety of possibilities to set the string variables. lowkey a lot of possibilities actually.

  • all variable names are prefixed by $.
  • you can assign a string to a variable using the = operator. ✅
  • you can append a string to a variable using the .= operator. ➕
  • you can concatenate two strings using the . operator. 🔗
  • you can substitute variables even inside quotes. 🪄
  • you can access the environment variables using the notation $ENV{VARIABLE}. 🌍

you can also unset a variable by assigning undef to it. use this to return the state of the variable from set back to use default. it's the undo button. 😌

and you must end a line with a semicolon. no semicolon, no dice. periodt. 💅

(part 1 of 3, bestie — there's more coming, don't go anywhere 🌸)

✨ OPTIONS ✨

okay so the options are given with their default value if this is known 💅

  • $fontPath = "<font_dir>,<font_dir>,..."; — Should be a comma-separated list of fonts to be added to the font path. If not specified, the default will apply. no font drama, just vibes 🎀
  • $PAMService = "tigervnc"; — This parameter specifies the PAM service utilized for Unix username and password authentication. This service is used for the *Plain security types (i.e., Plain, TLSPlain, and X509Plain) or when $RequireUsername is "yes" and any of the RSA-AES security types (i.e., RA2, RA2ne, RA2_256, and RA2ne_256) is used to establish the connection to the VNC server. If /etc/pam.d/vnc is not present, then tigervncserver(1) expects to use the tigervnc PAM service for Unix username and password authentication. Note that the tigervnc-common package provides the PAM service configuration file /etc/pam.d/tigervnc. Otherwise, if /etc/pam.d/vnc is present, the vnc PAM service will be used. the plot twist is real 😭
  • $sslAutoGenCertCommand — default:
$sslAutoGenCertCommand = "openssl req
                    -newkey ec:/etc/tigervnc/openssl-ecparams.pem
                    -x509 -days 2190 -nodes";

The command specified by the $sslAutoGenCertCommand parameter is used to auto-generate the certificate for the -X509Cert and -X509Key options of Xtigervnc(1). The configuration for openssl(1SSL) is taken from /etc/tigervnc/openssl.cnf where we substitute @HostName@ by the fully qualified domain name of the host. certificate glow-up, automated ✨

  • $sslAutoGenRSAKeyCommand — default:
$sslAutoGenRSAKeyCommand = "openssl genrsa
                    -out RSAKeyFile 4096";

The command specified by the $sslAutoGenRSAKeyCommand parameter is used to auto-generate an RSA key for the RSA-AES security types. RSA key, but make it fashion 💅

  • $vncUserDir = "$ENV{HOME}/.config/tigervnc"; — Contains the filename for the log files directory of Xtigervnc (the server) and the viewers that are connected to it. logs live here, bestie 🫶
  • $vncPasswdFile = $vncUserDir . "/passwd"; — Contains the filename of the password file for Xtigervnc. This file is only used for the security types VncAuth, TLSVnc, and X509Vnc. password file, but only for those three security types 🔐
  • $vncStartup = "/etc/X11/Xtigervnc-session"; — Points to a script that will be started at the very beginning when $vncUserDir/xstartup is not present. If $vncUserDir/xstartup. is present, it will be used. Otherwise, we use the $vncStartup script. If $vncStartup is specified in $vncUserDir/config.pl, then this script is used unconditionally. That is without checking for the presence of $vncUserDir/xstartup. the startup script hierarchy is giving main character energy 👑
  • $session = undef; — This option can be used to control which X session type will be started. This should match one of the files in /usr/share/xsessions. For example, if there is a file called gnome.desktop, then $session = "gnome" would start this X session. The command to start the session is passed to the $vncStartup script. If this is not specified, then /etc/X11/Xtigervnc-session will start the session specified by /usr/bin/x-session-manager. choose your own adventure, X session edition 🌈
  • $xauthorityFile = "$ENV{HOME}/.Xauthority"; — Specifies the path to the X authority file that should be used by your Xtigervnc server. X authority file, slay 💅
  • $desktopName = "${HOSTFQDN}:nn ($ENV{LOGNAME})"; — Should be set to the default name of the desktop. This can be changed at the command line with -desktop. name that desktop, bestie 🍓
  • $geometry = "<width>x<height>"; — This sets the framebuffer width & height to be used by the Xtigervnc server. On default, 1920x1200 is used. Values for this option as well as the $depth and $pixelformat options can be derived if the tigervncserver(1) is run in a X session – either $ENV{DISPLAY} or the session given by $getDefaultFrom – with the -xdisplaydefaults option. The geometry can also be changed at the command line with the -geometry option. Otherwise, the fixed defaults given here as well as in the following two configuration parameter documentations will be used. framebuffer size, but make it customizable ✨
  • $depth = "32"; — This sets the framebuffer color depth, i.e., the number of bits per pixel to use. It must be either 16, 24, or 32. depth check: 16, 24, or 32 only, no in-between 💜
  • $pixelformat = "rgb888"; — Specifies the pixel format for the Xtigervnc(1) 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 is RGB888. pixel format lore 📸
  • $wmDecoration = "8x64"; — Sets the adjustment of $geometry to accommodate the window decoration used by the X11 window manager. This is used to fully display the VNC desktop even if the VNC viewer is not in full screen mode. window decoration adjustment, because aesthetics matter 💅
  • $getDefaultFrom — This option lets you set the display from which you can query the default of the above three options, if you don't want to start tigervncserver from within a running X server. It will be added to the call of xdpyinfo. It is useful to get the default from the X server you will run xtigervncviewer in, because the data has not to be recalculated then.

$getDefaultFrom = "-display localhost:0"; is an example how to do this. query the X server, skip the recalc 😌

  • $scrapingGeometry = "<width>x<height>+<xoffset>+<yoffset>"; — is only used by the scraping TigerVNC server. It specifies the screen area that will be shown to VNC clients, e.g., 640x480+320+240. The format is <width>x<height>+<xoffset>+<yoffset>, where '+' signs can be replaced with '-' signs to specify offsets from the right and/or from the bottom of the screen. Offsets are optional, +0+0 is assumed by default (top left corner). If the variable is not defined, full screen is shown to VNC clients (this is the default). scraping geometry, the screen area selector 🌈
  • $localhost = "yes"; — Should the TigerVNC server only listen on localhost for incoming TigerVNC connections. This is useful if you use SSH and want to stop non-SSH connections from any other hosts. Hence, $localhost = "yes" is the default if security types are not specified. In this case, only the security type VncAuth will be offered. If the security types are specified, either via the option -SecurityTypes given to tigervncserver(1) or via the $SecurityTypes configuration parameter in /etc/tigervnc/vncserver-config-defaults or in $HOME/.config/tigervnc/config.pl, then the default depends on the specified security types. The default will be $localhost = "no" if the specified security types contain at least one of the TLS* or X509* security types and also contain none of the *None security types. As always, the defaults can be overwritten on the command line via the -localhost option or via the $localhost configuration parameter in /etc/tigervnc/vncserver-config-defaults or in $HOME/.config/tigervnc/config.pl. localhost lockdown, but only when it makes sense 🔒
  • $SecurityTypes = "VncAuth"; — The $SecurityTypes parameter contains a comma-separated list of the default security types the Xtigervnc server will offer. Available security types are None, VncAuth, Plain, TLSNone, TLSVnc, TLSPlain, X509None, X509Vnc, X509Plain, RA2, RA2ne, RA2_256, and RA2ne_256. The *None security types do not offer any kind of user authentication for connecting VNC sessions. Hence, combining a *None security type and $localhost = "no" is a very bad idea. The TLS* and X509* security types do enforce SSL encryption for data transmission. Hence, combining a TLS* or X509* security type and $localhost = "yes" is a senseless idea. Thus, in the case of $localhost = "no", the default for $SecurityTypes will be extended from VncAuth to VncAuth,TLSVnc. security type tea ☕ — do NOT mix *None with localhost = "no", that's a disaster bestie 💀
  • $RequireUsername = "no"; — The $RequireUsername configuration parameter specifies if authentication should be performed via Unix username and password (yes) or the VNC password file (no) when utilizing one of the RSA-AES security types (i.e., RA2, RA2ne, RA2_256, or RA2ne_256). username required? yes or no, the choice is yours ✨
  • $PlainUsers = "$ENV{LOGNAME}"; — The $PlainUsers configuration parameter contains a comma-separated list of user names that are allowed to access the VNC server via any of the *Plain security types (i.e., Plain, TLSPlain, etc.) or the RSA-AES security types in the case that $RequireUsername is "yes". Specify "*" to allow any user to authenticate using these security types. The default only allows the user who has started the VNC server. The VNC server checks the password for a user via the PAM service given by the $PAMService configuration variable or the -PAMService option. allow list, but make it cute 🫶
  • $X509Cert and $X509Key — These two options contain the filenames for a certificate and its key used for the security types X509None, X509Vnc, and X509Plain. If nothing is specified – the default case – then a self-signed certificate is auto-generated by tigervncserver(1) and stored in $HOME/.config/tigervnc/${HOSTFQDN}-SrvCert.pem and $HOME/.config/tigervnc/${HOSTFQDN}-SrvKey.pem, respectively. If filenames are given for $X509Cert and $X509Key either here or on the command line via -X509Cert and -X509Key options, then the auto-generation is disabled and, the user has to take care that a usable certificate is present. cert and key, the iconic duo 🔐
  • $RSAKey — This option contains the filenames for an RSA key in PEM format used by the RSA-AES security types. If nothing is specified – the default case – then an RSA key is auto-generated by tigervncserver(1) and stored in $HOME/.config/tigervnc/${HOSTFQDN}-SrvRsaKey.pem. If a filename is given for $RSAKey either here or on the command line via the -RSAKey option, then the auto-generation is disabled, and the user has to take care that a usable RSA key is present. RSA key, PEM format, auto-generated unless you say otherwise 💅

📁 FILES 📁

okay so here's where the actual files live, bestie, and you need to know the pecking order because it's giving hierarchy 💅

  • /etc/tigervnc/vncserver-config-defaults — the global config file, aka the one that sets the defaults for both tigervncserver and x0tigervncserver. system-wide vibes, no cap 🫶
  • ~/.config/tigervnc/config.pl — this is your personal tigervnc.conf(5x) config file. but here's the tea: to stay compatible with the upstream-provided wrapper scripts, if tigervnc.conf isn't there, it'll fall back and try to load config from ~/.config/tigervnc/config instead. and heads up — ~/.config/tigervnc/config uses key=value lines as its config syntax, so don't get it twisted 🔥
  • /etc/tigervnc/vncserver-config-mandatory — if this file exists and defines options, those options override anything with the same name in a user's config.pl file or anything passed on the command line of the wrapper scripts tigervncserver and x0tigervncserver. it's basically the system-wide policy bouncer at the door 😤✨
⚠️ WARNING! There is nothing stopping users from constructing their own wrapper script that calls Xtigervnc or X0tigervnc directly to bypass any options defined in the /etc/tigervnc/vncserver-config-mandatory configuration file. 💀 so like, it's policy, not a prison. iykyk.

👀 SEE ALSO 👀

go read these next, they're iconic in their own right:

💖 AUTHOR 💖

the credits, because we always give credit, periodt 🎀

  • 2024 - Modified for TigerVNC 1.14.1 by Joachim Falk (Joachim.Falk@gmx.de)
  • 2024 - Modified for TigerVNC 1.13.1 by Joachim Falk (Joachim.Falk@gmx.de)
  • 2022 - Modified for TigerVNC 1.12.0 by Joachim Falk (Joachim.Falk@gmx.de)
  • 2021 - Modified for TigerVNC 1.11.0 by Joachim Falk (Joachim.Falk@gmx.de)
  • 2016 - Modified for TigerVNC 1.7 by Joachim Falk (Joachim.Falk@gmx.de)
  • 2006 - Modified for vnc 4.1.2 by Joachim Falk (Joachim.Falk@gmx.de)
  • 1998 - Originally written by Marcus Brinkmann (Marcus.Brinkmann@ruhr-uni-bochum.de) for the Debian GNU/Linux Distribution.

and that's a wrap on the whole page, bestie 🦋 this was TigerVNC 1.14.1, dated Nov 10th, 2024, and you just read tigervnc.conf(5x) from cover to cover. ate and left no crumbs ✨💜 go forth and configure responsibly 🫶

📦 where this page comes from