wayvnc

wayvnc is a VNC server designed specifically for wlroots-based Wayland compositors. It attaches to a running Wayland session, creates virtual input devices, and exposes a single display via the RFB protocol.

Important Compatibility Notes:

• Supported: wlroots-based compositors.
• Not Supported: GNOME, KDE, and Weston.
• Headless Support: It can run without a physical display attached, making it suitable for headless Wayland sessions.

wayvnc opens a Unix domain socket at $XDG_RUNTIME_DIR/wayvncctl (or /tmp/wayvnc-$UID) to allow runtime interaction and control.

Clients can connect to this socket and exchange JSON-formatted IPC messages to query or control the running instance.

• Command Line: Use the wayvncctl utility to interact with the socket.
• Automation: An event-loop mode is available to run commands when specific events occur in wayvnc. See examples/event-watcher for details.
• Reference: For an in-depth description of the IPC protocol and available commands, refer to the wayvnc(1) manpage.

To build wayvnc, use meson and ninja.

If you need to satisfy neatvnc and aml dependencies via subprojects, clone them into the wayvnc/subprojects directory and link them as shown in the documentation.

Build Steps

meson build
ninja -C build

Running Tests

To run unit tests:

meson test -C build

To run integration tests:

./test/integration/integration.sh

You can run the server directly from the build directory.

Default Behavior: The server only accepts connections from localhost by default.

Accepting External Connections: To allow connections from any interface, specify 0.0.0.0 as the address.

Security Warning: Do not listen on all interfaces on a public network without user authentication enabled. The recommended approach is to use SSH tunneling while listening on localhost.

RSA-AES provides secure authentication and encryption using a Trust on First Use (TOFU) scheme.

1. Generate an RSA key:

ssh-keygen -m pem -f ~/.config/wayvnc/rsa_key.pem -t rsa -N ""

2. Configure wayvnc: Set the rsa_private_key_file parameter in your config file:

use_relative_paths=true
address=0.0.0.0
enable_auth=true
username=luser
password=p455w0rd
rsa_private_key_file=rsa_key.pem

You can also combine RSA with TLS credentials; the client will select the appropriate method.

To use TLS (VeNCrypt), you need a private X509 key and a certificate.

1. Generate a self-signed certificate:

cd ~/.config/wayvnc
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:secp384r1 -sha384 \
	-days 3650 -nodes -keyout tls_key.pem -out tls_cert.pem \
	-subj /CN=localhost \
	-addext subjectAltName=DNS:localhost,DNS:localhost,IP:127.0.0.1
cd -

(Note: Replace localhost and 127.0.0.1 with your actual hostname/IP if not testing locally.)

2. Configure wayvnc: Create a configuration file at $HOME/.config/wayvnc/config or use the --config flag. Use the following keys:

use_relative_paths=true
address=0.0.0.0
enable_auth=true
username=luser
password=p455w0rd
private_key_file=tls_key.pem
certificate_file=tls_cert.pem

wayvnc allows you to specify what part of the Wayland compositor should be captured and sent via VNC. The priority for determining the image_source_type is as follows:

1. Output: If output (an output name) is specified, the source type is IMAGE_SOURCE_TYPE_OUTPUT using that name.
2. Desktop: If desktop (desktop capture) is specified, the source type is IMAGE_SOURCE_TYPE_DESKTOP.
3. Toplevel: If toplevel (a toplevel ID) is specified, the source type is IMAGE_SOURCE_TYPE_OUTPUT using that ID.
4. Unspecified: If none of the above are provided, the type is IMAGE_SOURCE_TYPE_UNSPEC.

⚠️ WARNING: DES authentication provides NO encryption. It is insecure and only intended for compatibility with clients like macOS Screen Sharing that do not support modern authentication.

To enable DES, add these keys to your config:

enable_auth=true
password=p455w0rd
relax_encryption=true
allow_broken_crypto=true

Note: DES authentication will not work if enable_pam is enabled, as PAM overrides password-based authentication.

The single-output-sway example demonstrates how to manage multi-output Wayland environments (specifically Sway) by collapsing all outputs into a single view when a VNC client connects, and restoring the original configuration when the client disconnects.

Depending on your Sway version, the mechanism differs:

• Sway 1.7 and earlier: The script temporarily disables all outputs except for the one being captured. This forces all workspaces to move to the single remaining output.
• Sway 1.8 and later: The script creates a temporary virtual output named HEADLESS-[0-9]+ and disables all physical outputs. This moves all workspaces to the virtual output. Upon client disconnection, the script re-enables all original physical outputs and destroys the virtual output.

wayvnc provides several authentication and encryption configuration options through its internal configuration system:

• Authentication: Can be enabled via enable_auth. If enabled, it can require a username (enable_pam) and password.
• PAM: If enable_pam is set, authentication is handled via PAM.
• Encryption: By default, encryption is required. This can be relaxed using relax_encryption.
• Broken Crypto: allow_broken_crypto can be used to permit weaker cryptographic methods.
• RSA Credentials: If rsa_private_key_file is provided, it is used for RSA-based authentication.
• TLS Credentials: If private_key_file and certificate_file are provided, TLS is enabled for the connection.