x0tigervncserver(1)

📦
version 1.15.0 · 4 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

🌸 x0tigervncserver(1) — Virtual Network Computing 🦋

okay bestie, sit down, hydrate, because we're about to learn how to share a whole entire X display over the network and honestly? it's iconic.

✨ 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 the little matchmaker that starts up the X0tigervnc server, which is the thing that makes an X display remotely accessible via VNC (Virtual Network Computing). 🫶

And here's the tea: unlike Xtigervnc, this server does not create a virtual display. Nope. Instead it just shares an existing X server — typically, the one that's connected to your physical screen. It's giving "come look at my actual desktop" energy, no cap. 👑

The XDamage extension gets used if the existing X server supports it. Otherwise, X0tigervnc falls back to polling the screen for changes. (bestie it will simply keep asking "any change? any change?" like a very patient friend. 😭)

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 live in /etc/tigervnc/vncserver-config-defaults. Those defaults can be overwritten by the user defaults given in ~/.config/tigervnc/config.pl (peep the tigervnc.conf(5x) man page for that one 💜). Next up, command-line options overwrite the settings in both tigervnc configuration files. And finally — the drama — options from /etc/tigervnc/vncserver-config-mandatory have the highest priority, overwriting all previous settings. periodt.

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. 🚨 like, the rulebook has a back door and everyone knows it. 💀

🔥 OPTIONS 🔥

You can get a list of options by giving -h as an option to x0tigervncserver. And 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. 🖥️ it's the main character here, fr fr.
  • -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 📁

okay so here's the tea on where everything lives, bestie — a whole lil fam of TigerVNC-related files hangs out in the ~/.config/tigervnc directory:

  • ~/.config/tigervnc/passwd — the TigerVNC password file, and it's the one that handles the security types VncAuth, TLSVnc, and X509Vnc. 💖
  • ~/.config/tigervnc/<host>:<display#>.log — the log file for the VNC server. And if a VNC server is already running for that display? Then either ~/.config/tigervnc/<host>:<display#>-<rfbport#>.log or ~/.config/tigervnc/<host>:<display#>-<rfbunixpath>.log gets used as the log file instead. ✨
  • ~/.config/tigervnc/<host>:<display#>.pid — this one identifies the VNC server process ID, and it's what the -kill option goes looking for. Same deal as above: if a VNC server is already running for the display, then either ~/.config/tigervnc/<host>:<display#>-<rfbport#>.pid or ~/.config/tigervnc/<host>:<display#>-<rfbunixpath>.pid is used as a pid file. 🎀
  • ~/.config/tigervnc/<host>-SrvCert.pem and ~/.config/tigervnc/<host>-SrvKey.pem — so the security types X509None, X509Vnc, and X509Plain are highkey needy: they need a certificate and the matching private key. If those aren't handed over via the -X509Cert and -X509Key command-line options, or via their corresponding configuration parameters in the config files /etc/tigervnc/vncserver-config-defaults, ~/.config/tigervnc/config.pl, or /etc/tigervnc/vncserver-config-mandatory, then the x0tigervncserver wrapper script just auto-generates a self-signed certificate for the -X509Cert and -X509Key options of the X0tigervnc server. That auto-generated self-signed certificate and its private key get stashed in the two files above. And if you want your own certificate instead of the on-demand auto-generated one? You can either specify it through the x0tigervncserver options -X509Cert and -X509Key, or just replace the files ~/.config/tigervnc/host-SrvCert.pem and ~/.config/tigervnc/host-SrvKe.pem. These files will not be overwritten once the x0tigervncserver wrapper script has generated them. 💅
  • ~/.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 that key isn't provided via the -RSAKey command-line option or the corresponding parameter in the config 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. That auto-generated key lives in ~/.config/tigervnc/host-SrvRsaKey.pem. 🔑
  • ~/.config/tigervnc/config.pl — the user configuration file for x0tigervncserver. Now, to stay compatible with the upstream-provided wrapper scripts, if ~/.config/tigervnc/config.pl isn't present, we fall back to trying to load configuration from ~/.config/tigervnc/config. Heads up though: the config file uses key=value lines as its configuration syntax, while the config.pl and the tigervncserver-config-* files in the /etc/tigervnc directory use perl(1) syntax. Two different vibes, same directory. 🦋

Furthermore — and yes there's more — there are global configuration files for x0tigervncserver chilling 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. Basically it's the mechanism for establishing 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. 💀

👀 SEE ALSO 👀

tigervnc.conf(5x), tigervncpasswd(1), X0tigervnc(1), xtigervncviewer(1), tigervncserver(1)

https://www.tigervnc.org/

💖 AUTHOR 💖

Joachim Falk, Constantin Kaplinsky 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. 🌈

and that's the whole page, bestie — this was TigerVNC 1.14.1, dated Nov 10th, 2024, for x0tigervncserver(1). go forth and serve them displays, you absolute icon 💅✨

📦 where this page comes from