Ubuntu Manpage: x0tigervncserver - start or stop a TigerVNC scraping server

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

NAME

       x0tigervncserver - start or stop a TigerVNC scraping server

SYNOPSIS

       x0tigervncserver   [:display#|-display   :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>[{+,-}<xoffset>{+,-}<yoffset>]]  [-pidfile  pid-file-path]  [X0tigervnc
       options...]
       x0tigervncserver  -kill  [{:display#,:*}|-display  {:display#,:*}]  [-rfbport   rfbport#]   [-rfbunixpath
       Unixsocketpath] [-dry-run] [-verbose] [-clean]
       x0tigervncserver   -list   [{:display#,:*}|-display  {:display#,:*}]  [-rfbport  rfbport#]  [-rfbunixpath
       Unixsocketpath] [-cleanstale]
       x0tigervncserver -version

DESCRIPTION

       The x0tigervncserver wrapper script is used to start the  X0tigervnc  server  that  makes  an  X  display
       remotely  accessible via VNC (Virtual Network Computing). Unlike Xtigervnc, this server does not create a
       virtual display. Instead, it just shares an existing X server  (typically,  that  one  connected  to  the
       physical  screen).  The  XDamage  extension will be used if the existing X server supports it. Otherwise,
       X0tigervnc will fall back to polling the screen for changes.

       As usual, the VNC desktop can be connected to with the  xtigervncviewer  VNC  viewer  or  any  other  VNC
       viewer. For details, see the xtigervncviewer(1) man page or execute "xtigervncviewer -help".

       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 X0tigervnc
       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 x0tigervncserver. In addition to the options
listed below, any unrecognized options will be passed to X0tigervnc – see the X0tigervnc(1) man page or
"X0tigervnc -help" for details.

:display#|-display :display#
Specifies the X11 display to be shared by the X0tigervnc server.

-rfbport rfbport#
Specifies the TCP port on which X0tigervnc 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 X0tigervnc 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 x0tigervncserver 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 x0tigervncserver.

-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
x0tigervncserver 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 x0tigervncserver wrapper script auto-generates
an RSA key. The auto-generated key is stored in the file ~/.config/tigervnc/host-SrvRsaKey.pem.

-fg Runs the X0tigervnc 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>[{+,-}<xoffset>{+,-}<yoffset>]
Specifies the screen area that will be shown to VNC clients, e.g., 640x480+320+240. The format is
<width>x<height>+<xoffset>+<yoffset>, where `+' signs can be replaced with `-' signs to specify
offsets from the right and/or from the bottom of the screen. Offsets are optional, +0+0 is assumed
by default (top left corner). If the argument is empty, full screen is shown to VNC clients (this
is the default).

-pidfile
Specifies the file that stores the pid of the X0tigervnc server to be started.

-kill [ :{display#,*} | -display :{display#,*} ] [ -rfbport rfbport# ]
This kills a TigerVNC server previously started with x0tigervncserver or tigervncserver. It does
this by killing the VNC server process, whose process ID is stored in the file
~/.config/tigervnc/host:rfbport#.pid. If :* is given, then x0tigervncserver tries to kill all VNC
server processes with pidfiles in ~/.config/tigervnc on the local machine. If no display number is
given, then x0tigervncserver tries to kill the VNC server process of the user on the local machine
if only one such process is running and has a pidfile in ~/.config/tigervnc.

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

-list [ :{display#,*} | -display :{display#,*} ] [ -rfbport rfbport# ]
This lists all running TigerVNC servers previously started with x0tigervncserver or
tigervncserver. 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/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.  In case there is already a VNC server running for the display,
              either <host>:<display#>-<rfbport#>.log or <host>:<display#>-<rfbunixpath>.log will be used  as  a
              log file.

       ~/.config/tigervnc/<host>:<display#>.pid
              Identifies  the  VNC  server process ID, used by the -kill option.  In case there is already a VNC
              server    running    for    the    display,     either     <host>:<display#>-<rfbport#>.pid     or
              <host>:<display#>-<rfbunixpath>.pid will be used as a pid file.

       ~/.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 x0tigervncserver wrapper script auto-generates a self-signed certificate for the -X509Cert and
              -X509Key  options  of  the  X0tigervnc  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 x0tigervncserver
              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
              x0tigervncserver 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 x0tigervncserver wrapper script  auto-generates
              an  RSA  key  for the -RSAKey option of the X0tigervnc server. The auto-generated key is stored in
              the file ~/.config/tigervnc/host-SrvRsaKey.pem.

       ~/.config/tigervnc/config.pl
              The user configuration file for x0tigervncserver.  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 x0tigervncserver in the /etc/tigervnc directory:

       /etc/tigervnc/vncserver-config-defaults
              The global configuration file specifying the defaults for x0tigervncserver.

       /etc/tigervnc/vncserver-config-mandatory
              If this file exists and defines options to be passed to X0tigervnc, 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
              X0tigervnc  directly to bypass any options defined in the /etc/tigervnc/vncserver-config-mandatory
              configuration file.

AUTHOR