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.