Ubuntu Manpage: tigervncserver - start or stop a TigerVNC server

Provided by: tigervnc-standalone-server_1.10.1+dfsg-3ubuntu0.20.04.1_amd64

NAME

       tigervncserver - start or stop a TigerVNC server

SYNOPSIS

       tigervncserver  [[user@]host][:display#]  [-dry-run]  [-verbose]  [-useold]  [-cleanstale]
       [-localhost  [yes|no]]  [-name  desktop-name]  [-geometry  widthxheight]  [-depth   depth]
       [-pixelformat  format]  [-xdisplaydefaults]  [-wmDecoration  widthxheight] [-fp font-path]
       [-fg] [-autokill] [-noxstartup] [-xstartup  script]  [-rfbport  port#]  [-httpPort  port#]
       [-baseHttpPort  port#]  [-SecurityTypes  sec-types]  [-PlainUsers  user-list] [-PAMService
       service-name]  [-PasswordFile|-passwd|-rfbauth   passwd-file]   [-X509Key   cert-key-file]
       [-X509Cert cert-file] [Xtigervnc-options...]  [-- [Xtigervnc-session options...]]
       tigervncserver -kill [[user@]host][:display#|:*] [-dry-run] [-verbose] [-clean]
       tigervncserver -list [[user@]host][:display#|:*] [-cleanstale]

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 TigerVNC server Xtigervnc. 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. System defaults for this wrapper script are
found in /etc/vnc.conf. This defaults can be overwritten by the user defaults given in
$HOME/.vnc/vnc.conf. Finally, commandline options have the highest priority overwriting
the settings in both /etc/vnc.conf and $HOME/.vnc/vnc.conf. Editing the file
$HOME/.vnc/Xvnc-session allows you to change the applications run at startup (but note
that this will not affect an existing desktop).

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.

-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#.

-verbose
This will turn on some debug output.

-useold
Only start a new TigerVNC server if a Xtigervnc server for your account is not
already running on the requested display number display#. 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.

-cleanstale
Sometimes the Xtigervnc server crashes and does not clean up correctly. In this
case, there will be a stale pidfile in $HOME/.vnc as well as stale X11 locks and
sockets in /tmp. When the -cleanstale option is given, then tigervncserver first
tries to cleanup all these stale files before trying to determine which X display
number is available for use.

-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.

-name 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 Xvnc-session script via the $VNCDESKTOP environment variable, allowing you
to run a different set of applications according to the name of the desktop.

-geometry widthxheight
Specify the size of the desktop to be created. Default is 1024x768.

-depth depth
Specify the pixel depth in bits of the desktop to be created. Default is 24, other
possible values are 8, 15 and 16 - anything else is likely to cause strange
behavior by applications.

-pixelformat format
Specify pixel format for server to use (BGRnnn or RGBnnn). The default for depth 8
is BGR233 (meaning the most significant two bits represent blue, the next three
green, and the least significant three represent red), the default for depth 16 is
RGB565 and for depth 24 is RGB888.

-cc 3 As an alternative to the default TrueColor visual, this allows you to run an
Xtigervnc server with a PseudoColor visual (i.e. one which uses a color map or
palette), which can be useful for running some old X applications which only work
on such a display. Values other than 3 (PseudoColor) and 4 (TrueColor) for the -cc
option may result in strange behavior, and PseudoColor desktops must be 8 bits
deep.

-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.

-wmDecoration widthxheight
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.

-fp font-path
If the tigervncserver script detects that a font path is configured in
/etc/X11/xorg.conf, it will attempt to use this font path for Xtigervnc.
Otherwise, if no fond path is configured, the tigervncserver script will attempt to
start Xtigervnc and allow Xtigervnc to use its own preferred method of font
handling (which may be a hard-coded font path or, on more recent systems, a font
catalog.) The -fp argument allows you to override the above logic and specify a
font path for Xtigervnc to use.

-fg Runs the Xvnc-session as a foreground process. This has two effects: (1) The Xvnc-
session can be aborted with CTRL-C, and (2) the TigerVNC server will be killed as
soon as the user logs out of the window manager in the Xvnc-session. This may be
necessary when launching TigerVNC from within certain grid computing environments.

-autokill
Automatically kills the TigerVNC server whenever the Xvnc-session script exits. In
most cases, this has the effect of terminating Xtigervnc when the user logs out of
the window manager.

-noxstartup
Do not run the $HOME/.vnc/Xvnc-session script after launching Xtigervnc. This
option allows you to manually start a window manager in your TigerVNC session.

-xstartup script
Run a custom startup script, instead of $HOME/.vnc/Xvnc-session, after launching
Xtigervnc. This is useful to run full-screen applications.

-rfbport port#
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#.

-httpPort port#
Specifies the port on which the mini-HTTP server runs. On default, the server is
not started.

-baseHttpPort port#
Specifies the base for the port number on which the mini-HTTP server runs. The
real -httpPort option will be derived from this base plus the display number.

-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.

-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 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.

-PasswordFile passwd-file | -passwd 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 $HOME/.vnc/passwd.

-X509Cert cert-path and -X509Key key-path
Path to a X509 certificate in PEM format to be used for all X509 based security
types (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
commandline options or their corresponding configuration parameters in
/etc/vnc.conf or $HOME/.vnc/vnc.conf, then the tigervncserver wrapper script auto
generates a self signed certificate. The auto generated self signed certificates
are stored in the files $HOME/.vnc/host-SrvCert.pem and $HOME/.vnc/host-SrvKey.pem.

-kill [[user@]host][:display#|:*]
This kills a TigerVNC desktop previously started with tigervncserver. It does this
by killing the Xtigervnc process, whose process ID is stored in the file
$HOME/.vnc/host:display#.pid. This can be useful so you can write "tigervncserver
-kill $DISPLAY", e.g., at the end of your Xvnc-session file after a particular
application exits. If :* is given, then tigervncserver tries to kill all Xtigervnc
processes with pidfiles in $HOME/.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
$HOME/.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 $HOME/.vnc/host:display#.log is also removed.

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

FILES

Several TigerVNC-related files are found in the directory $HOME/.vnc:

$HOME/.vnc/vnc.conf
The user configuration file for tigervncserver.

$HOME/.vnc/Xvnc-session
A shell script specifying X applications to be run when a TigerVNC desktop is
started. If it doesn't exist and no system default is provided in /etc/vnc.conf,
tigervncserver will create a new one which runs a couple of basic applications. To
be compatible with older versions of this wrapper script, we will also use the file
$HOME/.vnc/xstartup if it is present.

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

$HOME/.vnc/host:display#.log
The log file for Xtigervnc and applications started in Xvnc-session.

$HOME/.vnc/host:display#.pid
Identifies the Xtigervnc process ID, used by the -kill option.

$HOME/.vnc/host-SrvCert.pem and $HOME/.vnc/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 commandline options or their corresponding configuration parameters in
/etc/vnc.conf or $HOME/.vnc/vnc.conf, 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 $HOME/.vnc/host-SrvCert.pem and $HOME/.vnc/host-SrvKey.pem. These files will
not be overwritten once generated by the tigervncserver wrapper script.

Furthermore, there is a global configuration file for tigervncserver:

/etc/vnc.conf
The global configuration file for tigervncserver.

AUTHOR