yannick

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 the vncserver man page for the complete list of configuration options.

1.Create a password using vncpasswd which will stored 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 ~/.vnc/config and at a minimum, define the type of session desired with a line like session=foo where foo corresponds to which ever DE is to run. One can see which DEs are available on the system by seeing their corresponding .desktop files within /usr/share/xsessions/.

Starting and stopping tigervnc

Start vncserver@.service and optionally enable it to run at boot time/shutdown. Note that the display number needs to be specified following the literal @ sign. For :1 it would look like this:

# systemctl start vncserver@:1

Note: Direct calls to /usr/bin/vncserver are not supported as they will not establish a proper session scope. The systemd service is the only supported method of using TigerVNC. See: Issue #1096.

Expose the local display directly

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

/etc/X11/xorg.conf.d/10-vnc.conf

Option "UserPasswdVerifier" "VncAuth"

Option "PasswordFile" "/root/.vnc/passwd"

EndSection

Running x0vncserver to directly control the local display

tigervnc also provides x0vncserver 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

For more information, see x0vncserver(1).

Note: x11vnc is an alternative VNC server which can also provides direct control of the current X session.

Starting x0vncserver via xprofile

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

~/.xprofile

...

x0vncserver -rfbauth ~/.vnc/passwd &

Starting and stopping x0vncserver via systemd

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:

~/.config/systemd/user/x0vncserver.service

[Unit]

Description=Remote desktop service (VNC)

[Service]

Type=simple

# wait for Xorg started by ${USER}

ExecStartPre=/bin/sh -c 'while ! pgrep -U "$USER" Xorg; do sleep 2; done'

ExecStart=/usr/bin/x0vncserver -rfbauth %h/.vnc/passwd

# or login with your username & password

#ExecStart=/usr/bin/x0vncserver -PAMService=login -PlainUsers=${USER} -SecurityTypes=TLSPlain

[Install]

WantedBy=default.target

Start and enable the service x0vncserver.service in Systemd/User mode, i.e. with the --user parameter.

Connecting to vncserver

Warning: The default's TigerVNC security method is not secure, it lacks identity verification and will not prevent man-in-the-middle attack during the connection setup. Make sure you understand the security settings of your server and do not connect insecurely to a vncserver outside of a trusted LAN.

Note: By default, TigerVNC uses the TLSVnc authentication/encryption method unless specifically instructed via the SecurityTypes parameter. With TLSVnc, there is standard VNC authentication and traffic is encrypted with GNUTLS but the identity of the server is not verified. TigerVNC supports alternative security schemes such as X509Vnc that combines standard VNC authentication with GNUTLS encryption and server identification, this is the recommended mode for a secure connection. When SecurityTypes on the server is set to a non-encrypted option as high-priority (such as None, VncAuth, Plain, TLSNone, TLSPlain, X509None, X509Plain); which is ill-advised, then it is not possible to use encryption. When running vncviewer, it is safer to explicitly set SecurityTypes and not accept any unencrypted traffic. Any other mode is to be used only when #Accessing vncserver via SSH tunnels.

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

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 -localhost switch way since it allows connections from the localhost only and by analogy, only from users ssh'ed and authenticated on the box. For example run a command such as:

$ vncserver -geometry 1440x900 -alwaysshared -dpi 96 -localhost :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(1).

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

Tip: It is possible, with a one-liner, to keep the port forwarding active during the connection and close it right after:

$ ssh -fL 9901:localhost:5901 10.1.10.2 sleep 10; vncviewer localhost:9901

What it does is that the -f switch will make ssh go in the background, it will still be alive executing sleep 10. vncviewer is then executed and ssh remains open in the background as long as vncviewer makes use of the tunnel. ssh will close once the tunnel is dropped which is the wanted behavior.

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 an OSX system

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

Connecting to non-X environments on a Raspberry Pi (Arch ARM)

Install dispmanx_vncAUR on the Arch ARM device. Frame rates are not very high but it provides a working VNC access.

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