tigervncserver(1) Virtual Network Computing tigervncserver(1)
NAME
tigervncserver - start or stop a TigerVNC standalone server
SYNOPSIS
tigervncserver [[user@]host][:display#] [-rfbport rfbport#] [-rfbunix-
path Unixsocketpath] [-rfbunixmode permissions] [-localhost [yes|no]]
[-SecurityTypes sec-types] [-PasswordFile|-rfbauth passwd-file] [-Plai-
nUsers 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 op-
tional 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 dis-
play 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 tigervnc-
server 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 ap-
plications run at startup (but note that this will not affect an exist-
ing desktop).
System defaults for this wrapper script are found in /etc/tigervnc/vnc-
server-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/vnc-
server-config-mandatory have the highest priority overwriting all pre-
vious settings.
WARNING! There is nothing stopping users from constructing their own
wrapper script that calls Xtigervnc directly to bypass any options de-
fined in the /etc/tigervnc/vncserver-config-mandatory configuration
file.
OPTIONS
You can get a list of options by giving -h as an option to tigervnc-
server. In addition to the options listed below, any unrecognized op-
tions 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 connec-
tions from viewers (the protocol used in VNC is called RFB –
"remote framebuffer"). The default is 5900 plus the display num-
ber 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 cre-
ated 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 ad-
dresses 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. De-
fault 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 authen-
ticate 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 tigervnc-
server 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 ac-
count is not already running on the requested display number
display# and RFB port rfbport#. If no display number is re-
quested, 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 -xdisplayde-
faults to accommodate the window decoration used by the X11 win-
dow 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-ses-
sion, 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 sig-
nificant 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-ses-
sion script exits. In most cases, this has the effect of termi-
nating 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 tigervnc-
server 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/xs-
tartup 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/vnc-
server-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 cer-
tificate 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 tigervnc-
server 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 tigervnc-
server wrapper script.
~/.vnc/tigervnc.conf
The user configuration file for tigervncserver. To be compati-
ble 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.
SEE ALSO
tigervnc.conf(5x), tigervncconfig(1), tigervncpasswd(1), tigervncses-
sion(8), Xtigervnc(1), xtigervncviewer(1), x0tigervncserver(1)
http://www.tigervnc.org
AUTHOR
Joachim Falk, Tristan Richardson, RealVNC Ltd., and others. VNC was
originally developed by the RealVNC team while at Olivetti Research Ltd
/ AT&T Laboratories Cambridge. TightVNC additions were implemented by
Constantin Kaplinsky. Many other people have since participated in de-
velopment, testing and support. This manual is part of the TigerVNC De-
bian packaging project.
TigerVNC 1.12.0 Jan 13th, 2022 tigervncserver(1)
Generated by dwww version 1.15 on Tue Jun 25 14:28:47 CEST 2024.