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.

SYNTAX¶

The configuration file is composed of key-value pairs separated with an equal sign. Whitespace around either the key or the value is insignificant and is not considered to be part of the key or the value.

KEYWORDS¶

address

certificate_file

enable_auth

password

port

private_key_file_file

relax_encryption

rsa_private_key_file

username

use_relative_paths

xkb_layout

xkb_model

xkb_options

xkb_rules

xkb_variant

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

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 reconnects, 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

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

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=...

CLIENT-CONNECTED

The client-connected event is sent when a new VNC client connects to wayvnc.

Parameters:

id=...

connection_count=...

address=...

username=...

CLIENT-DISCONNECTED

The client-disconnected event is sent when a VNC cliwnt disconnects from wayvnc.

Parameters:

id=...

connection_count=...

address=...

username=...

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 responses.

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 handled. 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.