FreeBSD Manual Pages
wayvnc(1) General Commands Manual wayvnc(1) NAME wayvnc - A VNC server for wlroots based Wayland compositors. SYNOPSIS wayvnc [options] [address [port]] OPTIONS -C, --config=<path> Select a config file. -d, --disable-input Disable all remote input. This allows using wayvnc without composi- tor support of virtual mouse / keyboard protocols. -D, --detached Start detached from a compositor. Run wayvncctl attach to attach to a compositor. -f, --max-fps=<fps> Set the rate limit (default 30). -g, --gpu Enable features that require GPU. -h, --help Get help. -k, --keyboard=<layout>[-variant] Select keyboard layout. The variant can be appended if needed. -L, --log-level Set log level. The levels are: error, warning, info, debug, trace and quiet. -o, --output=<name> Select output to capture. -p, --show-performance Show performance counters. -r, --render-cursor Enable overlay cursor rendering. -R, --disable-resizing Disable automatic desktop resizing. -s, --seat=<name> Select seat by name. -t, --transient-seat Create a transient seat for each client session. -S, --socket=<path> Set wayvnc control socket path. Default: $XDG_RUNTIME_DIR/wayvncctl or /tmp/wayvncctl-$UID -u, --unix-socket Create a UNIX domain socket instead of TCP, treating the address as a path. -v, --verbose Be more verbose. Same as setting `--log-level=info`. -V, --version Show version info. -w, --websocket Create a websocket. -x, --external-listener-fd Have the VNC server listen on an already bound socket. The address argument becomes a file descriptor which should be inherited from wayvnc's parent process. DESCRIPTION This is a VNC server 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. The Wayland session may be a headless one, so it is also possible to run wayvnc without a physical display attached. MULTIPLE OUTPUTS If the Wayland session consists of multiple outputs, only one will be captured. By default this will be the first one, but can be specified by the -o command line argument. The argument accepts the short name such as eDP-1 or DP-4. Running wayvnc in verbose mode (-v) will display the names of all outputs on startup, or you can query them at runtime via the wayvncctl output-list command. You can also change which output is being captured on the fly via the wayvncctl output-set command. CONFIGURATION wayvnc searches for a config file in the location ~/$XDG_CONFIG_HOME/wayvnc/config or if $XDG_CONFIG_HOME is not set ~/.config/wayvnc/config SYNTAX The configuration file is composed of key-value pairs separated with an equal sign. Whitespace around either the key or the value is insignifi- cant and is not considered to be part of the key or the value. KEYWORDS address The address to which the server shall bind, e.g. 0.0.0.0 or local- host. certificate_file The path to the certificate file for encryption. Only applicable when enable_auth=true. enable_auth Enable authentication and encryption. Setting this value to true requires also setting certificate_file, private_key_file, username and password. password Choose a password for authentication. port The port to which the server shall bind. Default is 5900. private_key_file_file The path to the private key file for TLS encryption. Only applica- ble when enable_auth=true. relax_encryption Don't require encryption after the user has been authenticated. This enables some security types such as Apple Diffie-Hellman. rsa_private_key_file The path to the private key file for RSA-AES encryption. Only ap- plicable when enable_auth=true. username Choose a username for authentication. use_relative_paths Make file paths relative to the location of the config file. xkb_layout The keyboard layout to use for key code lookup. Default: XKB_DEFAULT_LAYOUT or system default. xkb_model The keyboard model by which to interpret keycodes and LEDs. Default: "pc105" xkb_options A comma separated list of options, through which the user specifies non-layout related preferences such as which key is the Compose key. Default: XKB_DEFAULT_OPTIONS or system default. xkb_rules The rules file describes how to interpret the values of the model, layout, variant and options fields. Default: XKB_DEFAULT_RULES or system default. xkb_variant The keyboard variant to use for keycode lookup. Default: XKB_DEFAULT_VARIANT or system default. EXAMPLE use_relative_paths=true address=0.0.0.0 enable_auth=true username=luser password=p455w0rd rsa_private_key_file=rsa_key.pem private_key_file=tls_key.pem certificate_file=tls_cert.pem WAYVNCCTL CONTROL SOCKET To facilitate runtime interaction and control, wayvnc opens a unix do- main socket at $XDG_RUNTIME_DIR/wayvncctl (or a fallback of /tmp/wayvncctl-$UID). A client can connect and exchange json-formatted IPC messages to query and control the running wayvnc instance. IPC COMMANDS HELP The help command, when issued without any parameters, lists the names of all available commands. If an optional command parameter refers to one of those commands by name, the response data will be a detailed description of that command and its parameters. EVENT-RECEIVE The event-receive command registers for asynchronous server events. See the EVENTS section below for details on the event message format, and the IPC EVENTS section below for a description of all possible server events. Event registration registers for all available server events and is scoped to the current connection only. If a client disconnects and re- connects, it must re-register for events. CLIENT-LIST The client-list command retrieves a list of all VNC clients currently connected to wayvnc. CLIENT-DISCONNECT The client-disconnect command disconnects a single VNC client. Parameters: id Required: The ID of the client to disconnect. This ID can be found from the GET-CLIENTS command or receipt of a CLIENT-CONNECTED event. OUTPUT-LIST The output-list command retrieves a list of all outputs known to wayvnc and whether or not each one is currently being captured. OUTPUT-CYCLE For multi-output wayland displays, the output-cycle command switches which output is actively captured by wayvnc. Running this once will switch to the next available output. If no more outputs are available, it cycles back to the first again. OUTPUT-SET For multi-output wayland displays, the output-set command switches which output is actively captured by wayvnc by name. output-name=name Required: The name of the output to capture next. VERSION The version command queries the running wayvnc instance for its version information. Much like the -V option, the response data will contain the version numbers of wayvnc, as well as the versions of the neatvnc and aml components. WAYVNC-EXIT The wayvnc-exit command disconnects all clients and shuts down wayvnc. IPC EVENTS CAPTURE_CHANGED The capture-changed event is sent when the currently captured output changes. Parameters: output=... The name of the output now being captured. CLIENT-CONNECTED The client-connected event is sent when a new VNC client connects to wayvnc. Parameters: id=... A unique identifier for this client. connection_count=... The total number of connected VNC clients including this one. address=... The IP address of this client. May be null. username=... The username used to authenticate this client. May be null. CLIENT-DISCONNECTED The client-disconnected event is sent when a VNC cliwnt disconnects from wayvnc. Parameters: id=... A unique identifier for this client. connection_count=... The total number of connected VNC clients not including this one. address=... The IP address of this client. May be null. username=... The username used to authenticate this client. May be null. IPC MESSAGE FORMAT The wayvncctl(1) command line utility will construct properly-formatted json ipc messages, but any client will work. The client initiates the connection and sends one or more request objects, each of which will receive a corresponding response object. Note This message format is unstable and may change substantially over the next few releases. REQUEST The general form of a json-ipc request message is: { "method": "command-name", "id": 123, "params": { "key1": "value1", "key2": "value2", } } The method is the name of the command to be executed. Use the help method to query a list of all valid method names. The id field is optional and may be any valid json number or string. If provided, the response to this request will contain the identical id value, which the client may use to coordinate multiple requests and re- sponses. The params object supplies optional parameters on a per-method basis, and may be omitted if empty. RESPONSE { "id": 123, "code": 0, "data": { ... } } If the request had an id, the response will have an identical value for id. The numerical code provides an indication of how the request was han- dled. A value of 0 always signifies success. Any other value means failure, and varies depending on the method in question. The data object contains method-specific return data. This may be structured data in response to a query, a simple error string in the case of a failed request, or it may be omitted entirely if the error code alone is sufficient. EVENTS Events are aaynchronous messages sent from a server to all registered clients. The message format is identical to a REQUEST, but without an "id" field, and a client must not send a response. Example event message: { "method": "event-name", "params": { "key1": "value1", "key2": "value2", } } In order to receive any events, a client must first register to receive them by sending a event-receive request IPC. Once the success response has been sent by the server, the client must expect that asynchronous event messages may be sent by the server at any time, even between a request and the associated response. ENVIRONMENT The following environment variables have an effect on wayvnc: WAYLAND_DISPLAY Specifies the name of the Wayland display that the compositor to which wayvnc shall bind is running on. XDG_CONFIG_HOME Specifies the location of configuration files. XDG_RUNTIME_DIR Specifies the default location for the wayvncctl control socket. FAQ Wayvnc complains that a protocol is not supported The error might look like this: wl_registry@2: error 0: invalid version for global zxdg_output_manager_v1 (4): have 2, wanted 3 ERROR: ../src/main.c: 388: Screencopy protocol not supported by compositor. Exiting. Refer to FAQ section in man page. ERROR: ../src/main.c: 1024: Failed to initialise wayland This means that your wayland compositor does not implement the screencopy protocol and wayvnc won't work with it. Screencopy is implemented by wlroots based compositors such as Sway and Wayfire. How can I run wayvnc in headless mode/over an SSH session? Set the environment variables WLR_BACKENDS=headless and WLR_LIBIN- PUT_NO_DEVICES=1 before starting the compositor, then run wayvnc as normal. How can I pass my mod-key from Sway to the remote desktop session? Create an almost empty mode in your sway config. Example: mode passthrough { bindsym $mod+Pause mode default } bindsym $mod+Pause mode passthrough This makes it so that when you press $mod+Pause, all keybindings, except the one to switch back, are disabled. Not all symbols show up when I'm typing. What can I do to fix this? Try setting the keyboard layout in wayvnc to the one that most closely matches the keyboard layout that you're using on the client side. An exact layout isn't needed, just one that has all the sym- bols that you use. How do I enable the Compose key? Set "xkb_options=compose:menu" in the config file. Any key that is not otherwise used will work. There just needs to be some key for wayvnc to match against. AUTHORS Maintained by Andri Yngvason <andri@yngvason.is>. Up-to-date sources can be found at https://github.com/any1/wayvnc and bugs reports or patches can be submitted to GitHub's issue tracker. SEE ALSO wayvncctl(1) 2025-04-17 wayvnc(1)
NAME | SYNOPSIS | OPTIONS | DESCRIPTION | CONFIGURATION | WAYVNCCTL CONTROL SOCKET | ENVIRONMENT | FAQ | AUTHORS | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=wayvnc&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>