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

Provided by: tigervnc-standalone-server_1.12.0+dfsg-8ubuntu0.23.10.1_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]
       [-PasswordFile|-rfbauth  passwd-file]  [-PlainUsers  user-list]  [-PAMService|-pam_service
       service-name] [-X509Key cert-key-file] [-X509Cert cert-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] [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 ~/.vnc/Xtigervnc-session 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
~/.vnc/tigervnc.conf (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, and X509Plain. Default is VncAuth if -localhost is not given and
VncAuth,TLSVnc if -localhost no is given.

-PasswordFile passwd-file | -rfbauth passwd-file
Specifies the file containing the password used to authenticate viewers for the
security types VncAuth, TLSVnc, and X509Vnc. The passwd-file is accessed each time
a connection comes in, so it can be changed on the fly via tigervncpasswd(1). The
default password file is ~/.vnc/passwd.

-PlainUsers user-list
A comma separated list of user names that are allowed to authenticate via any of
the *Plain security types (Plain, TLSPlain, etc.). Specify * to allow any user to
authenticate using this security type. Default is to only allow the user that has
started the tigervncserver wrapper script.

-PAMService service-name | -pam_service service-name
PAM service name to use when authenticating users using any of the *Plain security
types. 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
/etc/tigervnc/vncserver-config-defaults, ~/.vnc/tigervnc.conf, or
/etc/tigervnc/vncserver-config-mandatory, then the tigervncserver wrapper script
auto generates a self signed certificate. The auto generated self signed
certificates are stored in the files ~/.vnc/host-SrvCert.pem and ~/.vnc/host-
SrvKey.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 ~/.vnc/Xtigervnc-session, after launching
Xtigervnc. This is useful to run full-screen applications.

-noxstartup
Do not run the ~/.vnc/Xtigervnc-session 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.

-- 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 ~/.vnc/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 ~/.vnc 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 ~/.vnc. 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 ~/.vnc/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 ~/.vnc 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 ~/.vnc directory:

~/.vnc/Xtigervnc-session
A shell script specifying X applications to be run when a TigerVNC desktop is
started. To be compatible with the upstream provided wrapper scripts, we will also
use the file ~/.vnc/xstartup if it is present. 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.

~/.vnc/passwd
The TigerVNC password file for the security types VncAuth, TLSVnc, and X509Vnc.

~/.vnc/<host>:<display#>.log
The log file for the VNC server and the applications started by Xtigervnc-session.

~/.vnc/<host>:<display#>.pid
Identifies the VNC server process ID, used by the -kill option.

~/.vnc/<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
/etc/tigervnc/vncserver-config-defaults, ~/.vnc/tigervnc.conf, 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 certificates 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 -X509Cert and
-X509Key options to the tigervncserver wrapper script or replace the auto generated
files ~/.vnc/host-SrvCert.pem and ~/.vnc/host-SrvKey.pem. These files will not be
overwritten once generated by the tigervncserver wrapper script.

~/.vnc/tigervnc.conf
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
~/.vnc/config if tigervnc.conf is not present. Note that ~/.vnc/config uses
key=value lines as configuration syntax, while tigervnc.conf 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 tigervnc.conf 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