Ubuntu Manpage: tigervnc.conf - configuration files for Virtual Network Computing

Provided by: tigervnc-common_1.14.1+dfsg-1_amd64

NAME

       tigervnc.conf - configuration files for Virtual Network Computing

SYNOPSIS

       $variable = "someValue";

       $variable = "someValue";

       $variable .= "someValue";

       $variable = $var1 . $var2;

DESCRIPTION

       This   man   page  describes  the  syntax  and  options  of  the  three  configuration  files  loaded  by
       tigervncserver(1), the free X server for Virtual Network Computing (VNC). These configuration  files  can
       be  used  to  change the behavior of the server at startup time, although for all values suitable inbuilt
       defaults are preset.

       First,  /etc/tigervnc/vncserver-config-defaults  is  read  specifying   the   system   defaults.    Then,
       tigervncserver(1) will proceed and read $HOME/.config/tigervnc/config.pl, a file that can be changed on a
       per-user  base.  The  options in this file will override the system defaults.  Next, command-line options
       overwrite both the system defaults and the settings in  $HOME/.config/tigervnc/config.pl.   Finally,  the
       configuration  file  /etc/tigervnc/vncserver-config-mandatory  is parsed. 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
       $HOME/.config/tigervnc/config.pl  as  well  as  options  given  via the command line.  This file offers a
       mechanism to establish some basic form of system-wide policy.

       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.

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.

OVERVIEW

       The  file  is  in  perl(1)  syntax,  although  only  variable  assignment  is allowed for your safety and
       convenience. But there still a variety of possibilities to set the string variables.

       All variable names are prefixed by `$'. You can assign a string to a variable using the `=' operator, and
       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 unset a variable by assigning undef to it. Use this to return the  state  of  the  variable  from
       `set' to `use default'.

       You must end a line with a semicolon.

OPTIONS

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.

$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.

$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.

$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.

$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.

$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.

$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.

$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.

$xauthorityFile = "$ENV{HOME}/.Xauthority";
Specifies the path to the X authority file that should be used by your Xtigervnc server.

$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.

$geometry = "<width>x<height>";
This sets the framebuffer width & height to be used by the Xtigervnc server. On default, 1920x1200
is used. A 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.

$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.

$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.

$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.

$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.

$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).

$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* secutity 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.

$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.

$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).

$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.

$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.

$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.

FILES

       /etc/tigervnc/vncserver-config-defaults
              The global configuration file specifying the defaults for tigervncserver and x0tigervncserver.

       ~/.config/tigervnc/config.pl
              The  user's  tigervnc.conf(5x)  configuration  file.   To be compatible with the upstream provided
              wrapper scripts, we will fall back to trying to load configuration from  ~/.config/tigervnc/config
              if  tigervnc.conf  is  not  present.  Note  that ~/.config/tigervnc/config uses key=value lines as
              configuration syntax.

       /etc/tigervnc/vncserver-config-mandatory
              If this file exists and defines options, they will override any of the same options defined  in  a
              user's  config.pl file or ones given on the command line of the wrapper scripts tigervncserver and
              x0tigervncserver. 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  or  X0tigervnc  directly  to bypass any options defined in the /etc/tigervnc/vncserver-
              config-mandatory configuration file.

AUTHOR

       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.

TigerVNC 1.14.1                                  Nov 10th, 2024                                tigervnc.conf(5x)