Ubuntu Manpage: tigervncserver - start or stop a TigerVNC standalone server

Provided by: tigervnc-standalone-server_1.15.0+dfsg-2_amd64

NAME

       tigervncserver - start or stop a TigerVNC standalone server

SYNOPSIS

       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

DESCRIPTION

tigervncserver is used to start a TigerVNC (Virtual Network Computing) desktop. tigervncserver is a Perl
wrapper script which simplifies the process of starting an instance of the Xtigervnc VNC server. It runs
Xtigervnc with appropriate options and starts some X applications to be displayed in the TigerVNC
desktop. tigervncserver can be run with no options at all. In this case it will choose the first
available display number (usually :1), start Xtigervnc as that display, and run a couple of basic
applications to get you started. You can also specify the display number, in which case it will use that
number if it is available and exit if not, e.g.:

tigervncserver :13

Moreover, a username and a hostname can be given to start the tigervncserver via SSH on the given machine
under the provided user account, e.g.:

tigervncserver franz@kopernikus:13

Note that this requires the same version of the tigervncserver wrapper script on the remote machine as is
on the local machine.

Creating the file ~/.config/tigervnc/xstartup allows you to change the applications run at startup (but
note that this will not affect an existing desktop).

System defaults for this wrapper script are found in /etc/tigervnc/vncserver-config-defaults. These
defaults can be overwritten by the user defaults given in ~/.config/tigervnc/config.pl (see the
tigervnc.conf(5x) man page). Next, command-line options overwrite the settings in both tigervnc
configuration files. Finally, options from /etc/tigervnc/vncserver-config-mandatory have the highest
priority overwriting all previous settings.

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.

OPTIONS

You can get a list of options by giving -h as an option to tigervncserver. In addition to the options
listed below, any unrecognized options will be passed to Xtigervnc – see the Xtigervnc(1) man page or
"Xtigervnc -help" for details.

:display#
Specifies the X11 display to be created by the Xtigervnc server.

-rfbport rfbport#
Specifies the TCP port on which Xtigervnc listens for connections from viewers (the protocol used
in VNC is called RFB – "remote framebuffer"). The default is 5900 plus the display number
display#. To disable, specify -1.

-rfbunixpath Unix socket path
Specifies a path to be used for listening on as a Unix domain socket by the Xtigervnc server. No
Unix domain socket is created if this option is not provided.

-rfbunixmode permissions
Specifies the mode of the Unix domain socket. The default is 0600.

-localhost [yes|no]
Should the TigerVNC server only listen on localhost for incoming TigerVNC connections. Useful if
you use SSH and want to stop non-SSH connections from any other hosts. If the option is not
specified, then the behavior is as follows: We will only listen on localhost if the sec-types list
does not contain any TLS* or X509* security types or if the list contains at least one *None
security type. Otherwise, we will listen on all network addresses of the machine.

-SecurityTypes sec-types
Specify 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 is not given and VncAuth,TLSVnc if
-localhost no is given.

-RequireUsername [yes|no]
Specifies for the RSA-AES security types (i.e., RA2, RA2ne, RA2_256, and RA2ne_256) if
authentication should be performed via Unix username and password (-RequireUsername yes) or the
VNC password file (-RequireUsername no). The default is to perform authentication via the VNC
password file.

-PasswordFile passwd-file | -rfbauth passwd-file
Specifies the file containing the password used to authenticate viewers for the security types
VncAuth, TLSVnc, X509Vnc, RA2, RA2ne, RA2_256, and RA2ne_256. The default password file is
~/.config/tigervnc/passwd. For the RSA-AES security types, authentication via the VNC password
file is only performed in case -RequireUsername is no, which is the default.

-PlainUsers user-list
Specifies a comma-separated list of user names that are allowed to authenticate via any of the
*Plain security types (Plain, TLSPlain, etc.) or the RSA-AES security types (RA2, RA2ne, etc.) in
case -RequireUsername is yes. Specify * to allow any user to authenticate using these security
types. The default only allows the user who has started the tigervncserver wrapper script.

-PAMService service-name | -pam_service service-name
Specifies the PAM service name to use when authenticating users using any of the
*Plain security types or the RSA-AES security types in case -RequireUsername is yes. Default is
vnc if /etc/pam.d/vnc is present and tigervnc otherwise. The tigervnc-common package ships the
/etc/pam.d/tigervnc PAM service configuration for use by tigervncserver.

-X509Cert cert-path and -X509Key key-path
Path to a X509 certificate in PEM format to be used for all X509 based security types (i.e.,
X509None, X509Vnc, etc.) as well as its private key also in PEM format. If the certificate and its
key 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. The auto-generated self-signed
certificate and its private key are stored in the files ~/.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 is not
provided via the -RSAKey command-line option or the corresponding configuration 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. The auto-generated key is stored in the file ~/.config/tigervnc/host-SrvRsaKey.pem.

-fg Runs the Xtigervnc server as a foreground process. Thus, the server can be aborted with CTRL-C.

-useold
Only start a new TigerVNC server if a VNC server for your account is not already running on the
requested display number display# and RFB port rfbport#. If no display number is requested, a new
TigerVNC server will only be started if there is no TigerVNC server running under your user
account. In any case, information about the newly started TigerVNC server or the reused TigerVNC
server session will be printed.

-verbose
This will turn on some debug output.

-dry-run
Do not actually do anything, but only perform the checks if the requested action would be
possible. For example, there will be checks performed for the availability of the requested
display number display#.

-geometry <width>x<height>
This option specifies the size of the desktop to be created. On default, a 1920x1200 desktop is
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 used to fully display the VNC desktop even if
the VNC viewer is not in full screen mode.

-xdisplaydefaults
The -xdisplaydefaults option can be used to derive values for the above three options, i.e.,
-geometry to -pixelformat, from the running X session. The derived dimensions are adjusted by the
-wmDecoration option.

-xstartup script
Run a custom startup script, instead of ~/.config/tigervnc/xstartup, after launching Xtigervnc.
This is useful to run full-screen applications.

-noxstartup
Do not run the ~/.config/tigervnc/xstartup script after launching Xtigervnc. This option allows
you to manually start a window manager in your TigerVNC session.

-desktop desktop-name
Each desktop has a name which may be displayed by the viewer. It defaults to "host:display#
(username)" but you can change it with this option. It is passed in to the Xtigervnc-session
script via the $VNCDESKTOP environment variable, allowing you to run a different set of
applications according to the name of the desktop.

-depth depth
Specify the pixel depth in bits of the desktop to be created. Default is 24, other possible values
are 16 and 32. Anything else is likely to cause strange behaviour by applications and may prevent
the server from starting at all.

-pixelformat format
Specify 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 is RGB888.

-autokill [yes|no]
The -autokill option is enabled by default. If enabled, the TigerVNC server is automatically
killed when the Xtigervnc-session script exits. In most cases, this has the effect of terminating
Xtigervnc when the user logs out of the window manager. To disable this, use -autokill no.

-fp font-path
Specifies a font path. Otherwise, if no font path is configured, the Xtigervnc server will use 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 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 -- gnome would start this X session.

-kill [[user@]host][:display#|:*] [-rfbport rfbport#]
This kills a TigerVNC server 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 can be 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 if only one such process is
running and has a pidfile in ~/.config/tigervnc. If a host is specified, then tigervncserver will
use SSH to kill a Xtigervnc process on the remote machine.

-clean If given with -kill, then the logfile ~/.config/tigervnc/host:rfbport#.log is also removed.

-list [[user@]host][:display#|:*] [-rfbport rfbport#]
This lists all running TigerVNC servers previously started with tigervncserver or
x0tigervncserver. If a host is specified, then tigervncserver will use SSH to list VNC desktops on
the remote machine. Stale entries are marked with (stale) in the output.

-cleanstale
If given with -list, then stale entries – resulting from missed cleanups of pidfiles in
~/.config/tigervnc as well as stale X11 locks and sockets in /tmp due to Xtigervnc or X0tigervnc
server crashes – are cleaned up and not shown in the output of -list.

FILES

Several TigerVNC-related files are found in the ~/.config/tigervnc directory:

~/.config/tigervnc/xstartup
A shell script specifying X applications to be run when a TigerVNC desktop is started. 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.

AUTHOR