dwww Home | Manual pages | Find package

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 Sun Jun 16 14:05:23 CEST 2024.