TigerVNC

TigerVNC is an implementation of the Virtual Network Computing (VNC) protocol. This article focuses on the server functionality.

Installation

Install the tigervnc package.

Running vncserver for virtual (headless) sessions

Initial setup

Note: Linux systems can have as many VNC servers as memory allows, all of which will be running in parallel to each other.

For a quick start, see the steps below. Users are encouraged to read vncserver(8) for the complete list of configuration options.

1. Create a password using vncpasswd which will store the hashed password in ~/.vnc/passwd.
2. Edit /etc/tigervnc/vncserver.users to define user mappings. Each user defined in this file will have a corresponding port on which its session will run. The number in the file corresponds to a TCP port. By default, :1 is TCP port 5901 (5900+1). If another parallel server is needed, a second instance can then run on the next highest, free port, i.e 5902 (5900+2).
3. Create and at a minimum, define the type of session desired with a line like session=foo where foo corresponds to whichever desktop environment is to run. One can see which desktop environments are available on the system by seeing their corresponding .desktop files within . For example:

Starting and stopping tigervnc

Start an instance of the vncserver@.service template and optionally enable it to run at boot time/shutdown. Note that the instance identifier in this case is the display number (e.g. instance vncserver@:1.service for display number ).

Expose the local display directly

Tigervnc comes with which can be directly loaded during X initialization which provides better performance. Create a following file and restart X:

Running x0vncserver to directly control the local display

tigervnc also provides which allows direct control over a physical X session. After defining a session password using the vncpasswd tool, invoke the server like so:

$ x0vncserver -rfbauth ~/.vnc/passwd

With xprofile

A simple way to start x0vncserver is adding a line in one of the xprofile files such as:

With a system service

This option will allow the users to access the current display, including the login screen provided by your display manager.

The service will be relaunched automatically every time an user logs off of their session.

LightDM is used for the example below, but it should be possible to adapt it to other display managers by modifying the variable.

As this is a system unit, -rfbauth ~/.vnc/passwd refers to

Start/enable x0vncserver.service.

With a user service

In order to have a VNC Server running x0vncserver, which is the easiest way for most users to quickly have remote access to the current desktop, create a systemd unit as follows replacing the user and the options with the desired ones:

The line waits for Xorg to be started by .

To login with your username and password, replace by .

Start/enable the x0vncserver.service user unit.

Running Xvnc with XDMCP for on demand sessions

One can use systemd socket activation in combination with XDMCP to automatically spawn VNC servers for each user who attempts to login, so there is no need to set up one server/port per user. This setup uses the display manager to authenticate users and login, so there is no need for VNC passwords. The downside is that users cannot leave a session running on the server and reconnect to it later.

To get this running, first set up XDMCP and make sure the display manager is running. Then create:

Start/enable . Now, any number of users can get unique desktops by connecting to port 5900.

If the VNC server is exposed to the internet, add the -localhost option to in xvnc@.service (note that and -localhost are different switches) and follow #Accessing vncserver via SSH tunnels. Since we only select a user after connecting, the VNC server runs as user nobody and uses directly instead of the script, so any options in are ignored. Optionally, autostart vncconfig so that the clipboard works (vncconfig exits immediately in non-VNC sessions). One way is to create:

Connecting to vncserver

Any number of clients can connect to a vncserver. A simple example is given below where vncserver is running on 10.1.10.2 port 5901, or :1 in shorthand notation:

$ vncviewer 10.1.10.2:1

Passwordless authentication

The switch allows one to define the location of the server's ~/.vnc/passwd file. It is expected that the user has access to this file on the server through SSH or through physical access. In either case, place that file on the client's file system in a safe location, i.e. one that has read access ONLY to the expected user.

$ vncviewer -passwd /path/to/server-passwd-file

The password can also be provided directly.

Note: The password below is not secured; anyone who can run ps on the machine will see it.

$ vncviewer -passwd <(echo MYPASSWORD | vncpasswd -f)

Example GUI-based clients

• remmina
• vncviewer-jar^AUR

TigerVNC's vncviewer also has a simple GUI when run without any parameters:

$ vncviewer

Accessing vncserver via SSH tunnels

For servers offering SSH connection, an advantage of this method is that it is not necessary to open any other port than the already opened SSH port to the outside, since the VNC traffic is tunneled through the SSH port.

On the server

On the server side, vncserver or x0vncserver must be run.

When running either one of these, it is recommended to use the option in or the -localhost switch (for x0vncserver) since it allows connections from the localhost only and by analogy, only from users ssh'ed and authenticated on the box. For example:

Make sure to Start or Restart the vncserver@.service, for example (see also #Initial setup):

# systemctl start vncserver@:1

or for x0vncserver:

$ x0vncserver -localhost -SecurityTypes none

On the client

The VNC server has been setup on the remote machine to only accept local connections. Now, the client must open a secure shell with the remote machine (10.1.10.2 in this example) and create a tunnel from the client port, for instance 9901, to the remote server 5901 port. For more details on this feature, see OpenSSH#Forwarding other ports and .

$ ssh 10.1.10.2 -L 9901:localhost:5901

Once connected via SSH, leave this shell window open since it is acting as the secured tunnel with the server. Alternatively, directly run SSH in the background using the option. On the client side, to connect via this encrypted tunnel, point the vncviewer to the forwarded client port on the localhost.

$ vncviewer localhost:9901

What happens in practice is that the vncviewer connects locally to port 9901 which is tunneled to the server's localhost port 5901. The connection is established to the right port within the secure shell.

Connecting to a vncserver from Android devices over SSH

To connect to a VNC server over SSH using an Android device as a client, consider having the following setup:

1. SSH running on the server
2. vncserver running on server (with -localhost flag for security)
3. SSH client on the Android device: ConnectBot is a popular choice and will be used in this guide as an example
4. VNC client on the Android device: androidVNC used here

In ConnectBot, connect to the desired machine. Tap the options key, select Port Forwards and add a port:

Type: Local
Source port: 5901
Destination: 127.0.0.1:5901

In androidVNC, connect to the VNC port; this is the local address following the SSH connection:

Password: the vncserver password
Address: 127.0.0.1
Port: 5901

Tips and tricks

Connecting to a macOS system

See https://help.ubuntu.com/community/AppleRemoteDesktop. Tested with Remmina.

Recommended security settings

If not #Accessing vncserver via SSH tunnels where the identification and the encryption are handled via SSH, it is recommended to use X509Vnc, as TLSVnc lacks identity verification.

$ vncserver -x509key /path/to/key.pem -x509cert /path/to/cert.pem -SecurityTypes X509Vnc :1

Issuing x509 certificates is beyond the scope of this guide. However, Let's Encrypt provides an easy way to do so. Alternatively, one can issue certificates using OpenSSL, share the public key with the client and specify it with the parameter. An example is given below the server is running on 10.1.10.2:

$ vncviewer 10.1.10.2 -X509CA /path/to/cert.pem

Toggling fullscreen

This can be done through vnc client's menu. By default, vnc client's mkey is F8.

Workaround for mouse back and forward buttons not working

The VNC protocol currently only uses 7 mouse buttons (left, middle, right, scroll up, scroll down, scroll left, scroll right) which means if your mouse has a back and a forward button, these are not usable and input will be ignored.

evrouter can be used to work around this limitation by sending keyboard key presses when clicking the mouse back/forward buttons. Optionally, xte found in and can be used on the server to map the keyboard key presses back to mouse button clicks if needed.

Substituting mouse back/forward buttons with keyboard keys XF86Back/XF86Forward

This method is simple and suitable if you only need a way to navigate backward/forward while using web browsers or file browsers for example.

Install and on the client. Configure evrouter, see Mouse buttons#evrouter and evrouter man pages for instructions and tips on how to find the correct device name, window name, button names etc. Example config:

~/.evrouterrc

Window "OtherComputer:0 - TigerVNC": # Window title used as filter

# Using Shell to avoid repeating key presses (see evrouter manual)
"USB mouse" "/dev/input/by-id/usb-Mouse-name-event-mouse" none key/275 "Shell/xte 'key XF86Back'"
"USB mouse" "/dev/input/by-id/usb-Mouse-name-event-mouse" none key/276 "Shell/xte 'key XF86Forward'"

# Use XKey below instead if repeating keys is desired (see evrouter manual)
#"Logitech Gaming Mouse G400" "/dev/input/by-id/usb-Logitech_Gaming_Mouse_G400-event-mouse" none key/275 "XKey/XF86Back"
#"Logitech Gaming Mouse G400" "/dev/input/by-id/usb-Logitech_Gaming_Mouse_G400-event-mouse" none key/276 "XKey/XF86Forward"

Start evrouter on the client. With above configuration keyboard key is sent to the VNC server when clicking the back button on the mouse, and is sent when clicking the forward button.

Mapping the keyboard key presses back to mouse button clicks on the server

If needed, it is possible to map the keyboard keys back to mouse button clicks on the server. In this case, it might be a good idea to use keyboard keys which are never on the client or server. In the example below, keyboard keys / are used as mouse buttons 8/9.

Evrouter configuration on the client:

Install and on the server. Configure xbindkeys to map keyboard keys / to mouse buttons 8/9 with xte.

Start xbindkeys (xbindkeys -f ~/.xbindkeysrc). The server will now map / to mouse buttons 8/9.

Troubleshooting

Black rectangle instead of window

Most probably, this is due to the application strictly requiring the composite Xorg extension. For example webkit based app: midori, psi-plus, etc.

Restart vncserver in this case using something like following:

$ vncserver -geometry ... -depth 24 :1 +extension Composite

It looks like Composite extension in VNC will work only with 24bit depth.

Empty black window with mouse cursor

Verify that the user is not logged into a physical X session, unless this option was configured with . Multiple X sessions for a single user are not supported, see https://github.com/TigerVNC/tigervnc/issues/684#issuecomment-494385395.

Conversely, trying to log into a local X session while a VNC server service is running for that user will likely not work, and you may get stuck on a splash screen when using a desktop environment.

No mouse cursor

If no mouse cursor is visible when using x0vncserver, start vncviewer as follows:

$ vncviewer DotWhenNoCursor=1 server

Alternatively, put in the TigerVNC configuration file, which is at by default.

Copying clipboard content from the remote machine

If copying from the remote machine to the local machine does not work, run on the server, as mentioned in :

$ autocutsel -fork

Now, press F8 to display the VNC menu popup, and select option.

No window decoration / borders / titlebars / cannot move windows around

Start a window manager to fix an empty xterm frame. For example, on Xfce, run .

Desktop environment is displaying only boxes for font

Some desktop environments might be missing necessary font to display ASCII characters. Install ttf-dejavu.

See also

• https://github.com/TigerVNC/tigervnc