tigervncserver
Section: Virtual Network Computing (1)
Updated: Jan 13th, 2022
Index
Return to Main Contents
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.
SEE ALSO
tigervnc.conf(5x),
tigervncconfig(1),
tigervncpasswd(1),
tigervncsession(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 development, testing and support. This manual is part
of the TigerVNC Debian packaging project.
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- OPTIONS
-
- FILES
-
- SEE ALSO
-
- AUTHOR
-
This document was created by
man2html,
using the manual pages.
Time: 16:03:32 GMT, April 27, 2024