VNC Remote Desktop Access with Weston 13#
Weston 13.0 provides VNC-based remote desktop access to the DriveOS platform, supporting both physical display (DRM + VNC) and headless (VNC-only) configurations. Weston loads DRM and VNC as simultaneous backends, enabling remote visual verification and input control.
For general Weston configuration, see Weston Backend Options.
Prerequisites#
Install VNC backend dependencies on the target (run once as root). The dependencies fall into two groups: packages that install normally through apt and packages that must be force-installed because of a known version conflict.
Before running apt-get update, synchronize the target’s system clock. A drifted clock causes apt to reject repository metadata as expired or not-yet-valid, which surfaces as confusing package conflict and signature errors:
ntpdate -s time.nist.gov
(Install ntpdate with apt-get install -y ntpdate if it is not already on the image. If the target has no outbound network access to time.nist.gov, use any reachable NTP server, or set the date manually with date -s.)
1. Packages installable through apt
apt-get update
apt-get install -y \
libneatvnc0 libaml0 \
libturbojpeg libpocketsphinx3 libzmq5 \
libserd-0-0 libsord-0-0 libsratom-0-0 libzix-0-0 \
libfftw3-double3 libunibreak5 libgme0 libopenmpt0t64 \
libchromaprint1 libbluray2 librabbitmq4 librist4 \
libsrt1.5-gnutls libssh-gcrypt-4 libpgm-5.3-0t64 \
libnorm1t64 libudfread0 libmbedcrypto7t64 libcjson1
2. Packages requiring forced install (gcc-14-base conflict)
The DriveOS Ubuntu 24.04 image ships gcc-14-base at a newer version than the Ubuntu Noble base repo’s libgfortran5 expects. This blocks the gfortran → lapack → sphinxbase → avfilter dependency chain when installed through apt. Download the packages and install them with dpkg --force-depends:
mkdir -p /tmp/vnc-debs && cd /tmp/vnc-debs
apt-get download \
libgfortran5 liblapack3 libblas3 libsphinxbase3t64 \
libavfilter9 libavformat60 libswscale7 libpostproc57
dpkg --force-depends -i *.deb
ldconfig
Verify the VNC backend is present:
ls /usr/local/lib/weston/vnc-backend.so
If the file does not exist, the DriveOS build does not include VNC support.
Setup#
Run setup commands on the target as root. Weston itself must run as a named non-root user (for example, nvidia); the VNC backend authenticates connecting clients as the user that owns the Weston process.
1. Ensure the XDG runtime directory exists for the Weston user
WESTON_USER=nvidia
mkdir -p /run/user/$(id -u "$WESTON_USER")
chmod 700 /run/user/$(id -u "$WESTON_USER")
chown "$WESTON_USER" /run/user/$(id -u "$WESTON_USER")
2. Generate a TLS certificate
openssl req -x509 -newkey rsa:2048 \
-keyout /etc/ssl/private/weston-vnc.key \
-out /etc/ssl/certs/weston-vnc.crt \
-days 3650 -nodes -subj "/CN=weston-vnc"
chmod 600 /etc/ssl/private/weston-vnc.key
chmod 644 /etc/ssl/certs/weston-vnc.crt
TLS encrypts the VNC session so that the username and password (sent via VeNCrypt X509Plain) are not transmitted in plaintext. The certificate is self-signed, which is sufficient for development use on a local network.
Set the key ownership so the Weston user can read it:
chown "$WESTON_USER" /etc/ssl/private/weston-vnc.key
3. Create the PAM configuration
sudo tee /etc/pam.d/weston-remote-access > /dev/null << 'EOF'
auth required pam_unix.so
account required pam_unix.so
EOF
The VNC backend hardcodes weston-remote-access as its PAM service name. VNC clients authenticate with a Linux username and password from the target.
4. Verify the libpam.so symlink
The VNC backend dynamically loads libpam.so at runtime. Some target images ship only the versioned libpam.so.0 and omit the unversioned symlink, which causes the backend to fail to load. Create the symlink if it is missing:
if [ ! -e /usr/lib/aarch64-linux-gnu/libpam.so ]; then
ln -sf libpam.so.0 /usr/lib/aarch64-linux-gnu/libpam.so
fi
5. Stop GDM if running
systemctl stop gdm
GDM holds the DRM master; Weston cannot acquire it while GDM is active.
Starting Weston#
See Starting Weston for full prerequisites.
Run the following commands as the Weston user (for example, su - nvidia).
DRM + VNC (physical display with remote access):
XDG_RUNTIME_DIR=/run/user/$(id -u) \
WAYLAND_DISPLAY=wayland-0 \
weston -B drm,vnc --no-config \
--port=5900 \
--width=1920 --height=1080 \
--vnc-tls-cert=/etc/ssl/certs/weston-vnc.crt \
--vnc-tls-key=/etc/ssl/private/weston-vnc.key
Headless (VNC only, no physical display):
XDG_RUNTIME_DIR=/run/user/$(id -u) \
weston -B vnc --no-config \
--port=5900 \
--width=1920 --height=1080 \
--vnc-tls-cert=/etc/ssl/certs/weston-vnc.crt \
--vnc-tls-key=/etc/ssl/private/weston-vnc.key
Verify the VNC listener is active:
ss -tln | grep 5900
Expected output:
LISTEN 0 128 0.0.0.0:5900 0.0.0.0:*
If port 5900 does not appear, check Weston logs:
journalctl -b | grep -i 'weston\|vnc'
Connecting from a VNC Client#
Connect to <TARGET_IP>:5900 using a VNC client that supports VeNCrypt / X509Plain security (for example, TigerVNC or KRDC). Authenticate with a Linux username and password from the target.
TigerVNC example:
vncviewer -SecurityTypes X509Plain -ViewOnly=0 "$TARGET_IP"
The -ViewOnly=0 flag explicitly enables keyboard and mouse input; some TigerVNC profiles default this to 1 (read-only viewing).
Most VNC clients will show an “untrusted certificate” warning on first connect because the certificate is self-signed. Accept the warning to proceed. The TLS connection still encrypts the session regardless of whether the certificate is trusted by the client.
Note
TigerVNC 1.10 (shipped with Ubuntu 20.04) may fail the VeNCrypt TLS handshake with some neatvnc versions. Use TigerVNC 1.12+ or KRDC if you encounter Authentication failure immediately after the TLS warning.
Alternative: TLSPlain (development only)
For quick local testing without distributing the server certificate, connect with TLSPlain. This uses anonymous TLS and skips server certificate verification entirely:
vncviewer -SecurityTypes TLSPlain -ViewOnly=0 "$TARGET_IP"
The session is still encrypted, but the client cannot verify the server’s identity. Use X509Plain for any non-development use.
VeNCrypt security subtypes
The Weston VNC backend offers the following VeNCrypt subtypes. Use X509Plain for production access and TLSPlain only for local development.
Subtype |
Description |
|---|---|
|
X.509 TLS + Linux username/password. Server identity verifiable via the certificate. Recommended. |
|
Anonymous TLS + Linux username/password. Encrypted but server identity is not verified. |
|
Username/password with no encryption. Not enabled in DriveOS configurations and should not be used. |
Optional: import the certificate for server verification
To suppress the warning and verify the server’s identity on future connections, copy the certificate to the client machine:
scp nvidia@<TARGET_IP>:/etc/ssl/certs/weston-vnc.crt ./weston-vnc.crt
Then import it into the VNC client:
TigerVNC:
vncviewer -SecurityTypes X509Plain -X509CA ./weston-vnc.crt <TARGET_IP>KRDC: Add to the system trusted certificate store.
Warning
Without TLS certificates and PAM configuration, VNC runs unauthenticated and unencrypted. Do not expose the VNC port on untrusted networks without both configured.
Troubleshooting#
Symptom |
Resolution |
|---|---|
Port 5900 not listening |
VNC backend failed to load. Check |
Weston exits with |
The unversioned libpam symlink is missing on the image. Create it with |
Authentication failed |
Verify |
TigerVNC shows the remote desktop but keyboard and mouse have no effect |
The viewer is in view-only mode. Reconnect with |
|
Expected on the DriveOS Ubuntu 24.04 image. Use the |
TLS / certificate error |
Verify cert and key exist at the paths passed to Weston. Check permissions: key must be mode |
|
Another process (GDM, another Weston instance) holds the DRM device. Run |