[root tip] TigerVNC over SSH

Difficulty: ★★☆☆☆


VNC is a protocol where you use your keyboard/mouse/screen to monitor or control a remote system.

This document is from my notepad and a real-world implementation of the document(s) found at Archlinux Wiki - TigerVNC.

NOTE: The setup is not implementing any VNC encryption so SSH will be used to establish the connection. See [root tip] Set up your own SSH service.

The benefit of using SSH is that you can easily adapt this to target any remote server without sacrificing security.

Target system

On the system to be controlled install package tigervnc

VNC password

Create a password for your login



Replace the phrase $USERNAME with the username of the actual user you want to configure.

List the available sessions

ls /usr/share/xsessions

Create the file /home/$USERNAME/.vnc/config with content (replace $SESSION according to your installation e.g. openbox)


Alllow user on specific display

Edit /etc/tigervnc/vncserver.users and append e.g. :2 - which in turn will correspond to port 5902 - replace $USERNAME with the user you just created the password for.


Start a vncserver at the selected display

systemctl enable vncserver@:2

Reboot the device


Controlling system

Install the package tigervnc

Connect to target system

SSH provides a secure channel and using key based authentication is the recommended method.

Open a ssh connection using port mapping

ssh $USERNAME@target.system -L 9902:localhost:5902

Then launch the VNC viewer and input the following connection details and click connect


Input the password created earlier (ignore the warning as we are using an encrypted connection) and you will see the remote system - which could just be a Raspberry Pi sitting next to you on the desk.

Connected to Pi using TigerVNC on MacBook Pro M1