How to connect to Raspberry Pi Desktop using wayvnc VNC Server

Written by - 2 comments

Published on - last updated on February 8th 2024 - Listed in Hardware Linux


If you have the latest Raspberry Pi OS (previously known as Raspbian) Bookworm installed on your Raspberry Pi, you might have noticed a "wayvnc" package, which is installed by default.

Raspberry Pi OS selection in Imager software

But how can wayvnc be used to remotely connect to and control the Raspberry Pi's desktop?

Start wayvnc VNC server on Raspberry Pi

Obviously the first part is to actually start the VNC server using the wayvnc service on the Raspberry Pi. Although wayvnc is already installed (if not, install with sudo apt-get install wayvnc), the service is by default disabled:

pi@raspberrypi:~ $ systemctl status wayvnc
- wayvnc.service - VNC Server
     Loaded: loaded (/lib/systemd/system/wayvnc.service; disabled; preset: enabled)
     Active: inactive (dead)
       Docs: man:wayvnc

A closer look at the wayvnc service unit file reveals there is a configuration file located at /etc/wayvnc/config:

pi@raspberrypi:~ $ cat /lib/systemd/system/wayvnc.service
[Unit]
Description=VNC Server
Documentation=man:wayvnc
After=network.target wayvnc-generate-keys.service
Requires=wayvnc-generate-keys.service
ConditionPathExists=/etc/wayvnc/config

[Service]
ExecStart=/bin/sh /usr/sbin/wayvnc-run.sh
Type=notify
NotifyAccess=all
Restart=always
User=vnc
KillSignal=INT

[Install]
WantedBy=multi-user.target

The config (by default) looks like this:

pi@raspberrypi:~ $ cat /etc/wayvnc/config
use_relative_paths=true
address=::
enable_auth=true
enable_pam=true
private_key_file=tls_key.pem
certificate_file=tls_cert.pem
rsa_private_key_file=rsa_key.pem

Looking at the (default) options, this means:

  • address=:: => VNC Server should listen on all enabled interfaces (= lo, eth0, wlan0)
  • enable_auth=true => Authentication is enabled (requires username+password as login)
  • enable_pam=true => Authentication uses PAM (local users, e.g. the "pi" user)
  • private_key_file=tls_key.pem => Encrypt the VNC session, use this private key
  • certificate_file=tls_cert.pem => Encrypt the VNC session, use this certificate
  • rsa_private_key_file=rsa_key.pem => Encrypt the VNC sessions, use this key file for RSA-AES encryption

After starting the service, we can find the wayvnc process listening on port tcp/5900:

pi@raspberrypi:~ $ sudo systemctl start wayvnc

pi@raspberrypi:~ $ systemctl status wayvnc
- wayvnc.service - VNC Server
     Loaded: loaded (/lib/systemd/system/wayvnc.service; disabled; preset: enabled)
     Active: active (running) since Wed 2024-02-07 09:24:27 CET; 2s ago
       Docs: man:wayvnc
   Main PID: 32884 (sh)
      Tasks: 6 (limit: 1578)
        CPU: 270ms
     CGroup: /system.slice/wayvnc.service
             |-32884 /bin/sh /usr/sbin/wayvnc-run.sh
             |-32888 wayvnc --render-cursor --detached --config /etc/wayvnc/config --socket /tmp/wayvnc/wayvncctl.sock

pi@raspimon:~ $ sudo netstat -lntup | grep wayvnc
tcp6       0      0 :::5900                 :::*                    LISTEN      32888/wayvnc 

So far so good, the VNC server is running. But how do we connect from a different machine?

vncviewer from xtightvncviewer package does not support encryption

The obvious choice (if you're on a Linux Desktop like me) would be to use the vncviewer command from the xtightvncviewer package and connect to the Raspberry Pi's IP address. However you will quickly notice that something's not working:

ck@mint ~ $ vncviewer 192.168.15.17
Connected to RFB server, using protocol version 3.8
Server did not offer supported security type

It turns out that the TightVNC Viewer does not support encrypted VNC sessions. The --help output doesn't show related encryption options either:

ck@mint ~ $ vncviewer --help
TightVNC Viewer version 1.3.10

Usage: vncviewer [<OPTIONS>] [<HOST>][:<DISPLAY#>]
       vncviewer [<OPTIONS>] [<HOST>][::<PORT#>]
       vncviewer [<OPTIONS>] -listen [<DISPLAY#>]
       vncviewer -help

<OPTIONS> are standard Xt options, or:
        -via <GATEWAY>
        -shared (set by default)
        -noshared
        -viewonly
        -fullscreen
        -noraiseonbeep
        -passwd <PASSWD-FILENAME> (standard VNC authentication)
        -encodings <ENCODING-LIST> (e.g. "tight copyrect")
        -bgr233
        -owncmap
        -truecolour
        -depth <DEPTH>
        -compresslevel <COMPRESS-VALUE> (0..9: 0-fast, 9-best)
        -quality <JPEG-QUALITY-VALUE> (0..9: 0-low, 9-high)
        -nojpeg
        -nocursorshape
        -x11cursor
        -autopass

Option names may be abbreviated, e.g. -bgr instead of -bgr233.
See the manual page for more information.

Time to look for an alternative VNC viewer.

VNC Session with RealVNC Viewer

It turns out that RealVNC, a VNC software I still remember from my Windows days a long time ago, supports encryption. And the RealVNC Viewer can also be downloaded as Linux package. Let's download and install the deb package:

ck@mint /tmp $ wget https://downloads.realvnc.com/download/file/viewer.files/VNC-Viewer-7.9.0-Linux-x64.deb
ck@mint /tmp $ sudo dpkg -i VNC-Viewer-7.9.0-Linux-x64.deb
[sudo] password for ck:       
Selecting previously unselected package realvnc-vnc-viewer.
dpkg: regarding VNC-Viewer-7.9.0-Linux-x64.deb containing realvnc-vnc-viewer:
 realvnc-vnc-viewer conflicts with xtightvncviewer
  xtightvncviewer (version 1:1.3.10-5) is present and installed.

dpkg: error processing archive VNC-Viewer-7.9.0-Linux-x64.deb (--install):
 conflicting packages - not installing realvnc-vnc-viewer
Errors were encountered while processing:
 VNC-Viewer-7.9.0-Linux-x64.deb

The installation failed because of a package conflict. RealVNC cannot be installed as long as xthightvncviewer package is installed. Both packages want to use the vncviewer command. In this case I decided to remove the xtightvncviewer package and try again:

ck@mint /tmp $ sudo apt-get remove xtightvncviewer
ck@mint /tmp $ sudo dpkg -i VNC-Viewer-7.9.0-Linux-x64.deb
(Reading database ... 574373 files and directories currently installed.)
Preparing to unpack VNC-Viewer-7.9.0-Linux-x64.deb ...
Unpacking realvnc-vnc-viewer (7.9.0.51979) ...
Setting up realvnc-vnc-viewer (7.9.0.51979) ...

Processing triggers for shared-mime-info (2.1-2) ...
Processing triggers for man-db (2.10.2-1) ...
Processing triggers for desktop-file-utils (0.26+mint3+victoria) ...
Processing triggers for mailcap (3.70+nmu1ubuntu1) ...
Processing triggers for gnome-menus (3.36.0-1ubuntu3) ...
Processing triggers for hicolor-icon-theme (0.17-2) ...

This time it worked and the vncviewer --help output looks very different than before (offering a lot of additional options, including encryption):

ck@mint /tmp $ vncviewer --help
RealVNC(R) Viewer 7.9.0 (r51979) x64 (Jan 9 2024 18:08:06)
Copyright (C) RealVNC Ltd.
RealVNC and VNC are trademarks of RealVNC Ltd and are protected by trademark
registrations and/or pending trademark applications in the European Union,
United States of America and other jurisdictions.
Protected by UK patent 2481870; US patent 8760366; EU patent 2652951.
See https://www.realvnc.com for information on VNC.
For third party acknowledgements see:
https://www.realvnc.com/docs/7/foss.html
OS: Linux Mint 21.2, Linux 6.5.0, amd64

Usage: vncviewer [OPTION...]
       vncviewer [OPTION...] COMMAND

Commands:
  HOST[:DISPLAY]          Connect to DISPLAY on HOST.
  -h[elp] [all]           Provide [advanced] usage information.
  -addlicense FILE/TOKEN  Apply the offline license FILE/TOKEN to VNC Viewer.
  -screenshot PID [FILE]  Direct the vncviewer process PID to save a screenshot
                          to the given file/directory. If a file is specified
                          it must end in either .png or .bmp
  -listen [PORT]          Listen for reverse connections on PORT (default
                          5500).

Options are parameters, and also the following:
  -config FILE     Load parameters from FILE.

Parameters can be turned on with -<param> or off with -<param>=0
Values can be specified as -<param> <value>
Other valid forms are <param>=<value> -<param>=<value> --<param>=<value>
Names are case-insensitive.  Valid parameters are listed below.

Connection parameters:
  AcceptBell     - Produce a system beep on request by the VNC Server computer.
                   (default=1)
  AudioVolume    - The playback volume for remote audio, from 0 to 100.
                   (default=0)
  AuthCertificate - Hash of the public key to use for authenticating to VNC
                   Server, "<auto>" to query for a public key to use, or empty
                   to disable key-based authentication. (default=<auto>)
  AutoReconnect  - Automatically reconnect to VNC Server in certain
                   circumstances, for example if the VNC Server computer is
                   logged or switched out. (default=1)
[...]
  EnableRemotePrinting - Allow a connected VNC Viewer user to print to a local
                   printer, if VNC Server provides this feature. (default=1)
  EnableToolbar  - Show a toolbar facilitating common operations. (default=1)
  Encryption     - Request that connections either be encrypted (AlwaysMaximum
                   | AlwaysOn | PreferOn), be unencrypted (PreferOff) or let
                   VNC Server choose (Server), if VNC Server provides this
                   feature. (default=Server)

  FullScreen     - Show the VNC Server computer's desktop in full screen mode.
                   Use the toolbar or F8 menu to return to windowed mode.
                   (default=0)
[...]

Let's try to connect to the Raspberry Pi now:

ck@mint ~ $ vncviewer 192.168.15.17

At the first start of the RealVNC vncviewer you're greeted with an EULA (end user license agreement) - I feel back in my Windows days.

After this, the RealVNC viewer asks to enter the authentication credentials. As mentioned above, the wayvnc VNC Server uses the local user authentication by default. This means we can use the "pi" user and its password.

And - finally - the Raspberry Pi Desktop can be seen and controlled from remote :-)

VNC Session with TigerVNC Viewer

Besides RealVNC, which is not an open source software, there's also TigerVNC which supports encrypted VNC sessions. This open source VNC viewer is also mentioned in the official Raspberry Pi documentation for remote access

On Debian and Ubuntu based Linux distributions, TigerVNC can be installed using apt:

ck@mint ~ $ sudo apt-get install tigervnc-viewer

Afterwards use the xtigervncviewer command to connect to the Raspberry Pi:

ck@mint ~ $ xtigervncviewer 192.168.15.17

TigerVNC Viewer 64-bit v1.12.0
Built on: 2024-01-23 19:20
Copyright (C) 1999-2021 TigerVNC Team and many others (see README.rst)
See https://www.tigervnc.org for information on TigerVNC.

Thu Feb  8 09:00:04 2024
 DecodeManager: Detected 12 CPU core(s)
 DecodeManager: Creating 4 decoder thread(s)
 CConn:       Connected to host 192.168.15.17 port 5900
 CConnection: Server supports RFB protocol version 3.8
 CConnection: Using RFB protocol version 3.8
 CConnection: Choosing security type VeNCrypt(19)
 CVeNCrypt:   Choosing security type X509Plain (262)
 TLS:         Could not load user specified certificate authority
 TLS:         Could not load user specified certificate revocation list

TigerVNC will most likely show a warning concerning the discovered server certificate. Click on Yes to continue:

The certificate itself is then shown and can be added as a persistent exception (because the certificate is self-signed and a local Root CA could not be found as issuer):

TigerVNC certificate warning

The next step is to add the login credentials:

TigerVNC authentication

And voilĂ , the Raspberry Pi Desktop shows up in TigerVNC:

TigerVNC connected to Raspberry Pi desktop

VNC over Internet: Don't do it

Security Note: Only use a VNC connection on LAN, never over Internet (even though you can nowadays encrypt the VNC session). Use a SSH port forwarding or VPN if you need to do this over the Internet.


Add a comment

Show form to leave a comment

Comments (newest first)

CK from Switzerland wrote on Mar 19th, 2024:

Curris, I am not sure, but I did not change this and WayVNC still was working after a reboot.


Curtis from wrote on Mar 19th, 2024:

Must VNC be enabled in raspi-config -> Interface Options?


RSS feed

Blog Tags:

  AWS   Android   Ansible   Apache   Apple   Atlassian   BSD   Backup   Bash   Bluecoat   CMS   Chef   Cloud   Coding   Consul   Containers   CouchDB   DB   DNS   Database   Databases   Docker   ELK   Elasticsearch   Filebeat   FreeBSD   Galera   Git   GlusterFS   Grafana   Graphics   HAProxy   HTML   Hacks   Hardware   Icinga   Influx   Internet   Java   KVM   Kibana   Kodi   Kubernetes   LVM   LXC   Linux   Logstash   Mac   Macintosh   Mail   MariaDB   Minio   MongoDB   Monitoring   Multimedia   MySQL   NFS   Nagios   Network   Nginx   OSSEC   OTRS   Office   PGSQL   PHP   Perl   Personal   PostgreSQL   Postgres   PowerDNS   Proxmox   Proxy   Python   Rancher   Rant   Redis   Roundcube   SSL   Samba   Seafile   Security   Shell   SmartOS   Solaris   Surveillance   Systemd   TLS   Tomcat   Ubuntu   Unix   VMWare   VMware   Varnish   Virtualization   Windows   Wireless   Wordpress   Wyse   ZFS   Zoneminder