.\" Generated by scdoc 1.11.3 .\" Complete documentation for this program is not available as a GNU info page .ie \n(.g .ds Aq \(aq .el .ds Aq ' .nh .ad l .\" Begin generated content: .TH "wayvnc" "1" "2024-08-19" .PP .SH NAME .PP wayvnc - A VNC server for wlroots based Wayland compositors.\& .PP .SH SYNOPSIS .PP \fBwayvnc\fR [options] [address [port]] .PP .SH OPTIONS .PP \fB-C, --config=\fR .RS 4 Select a config file.\& .PP .RE \fB-g,--gpu\fR .RS 4 Enable features that require GPU.\& .PP .RE \fB-o, --output=\fR .RS 4 Select output to capture.\& .PP .RE \fB-k, --keyboard=[-variant]\fR .RS 4 Select keyboard layout.\& The variant can be appended if needed.\& .PP .RE \fB-s, --seat=\fR .RS 4 Select seat by name.\& .PP .RE \fB-S, --socket=\fR .RS 4 Set wayvnc control socket path.\& Default: $XDG_RUNTIME_DIR/wayvncctl or /tmp/wayvncctl-$UID .PP .RE \fB-r, --render-cursor\fR .RS 4 Enable overlay cursor rendering.\& .PP .RE \fB-f, --max-fps=\fR .RS 4 Set the rate limit (default 30).\& .PP .RE \fB-p, --show-performance\fR .RS 4 Show performance counters.\& .PP .RE \fB-u, --unix-socket\fR .RS 4 Create a UNIX domain socket instead of TCP, treating the address as a path.\& .PP .RE \fB-d, --disable-input\fR .RS 4 Disable all remote input.\& This allows using wayvnc without compositor support of virtual mouse / keyboard protocols.\& .PP .RE \fB-V, --version\fR .RS 4 Show version info.\& .PP .RE \fB-v,--verbose\fR .RS 4 Be more verbose.\& Same as setting `--log-level=info`.\& .PP .RE \fB-w,--websocket\fR .RS 4 Create a websocket.\& .PP .RE \fB-L,--log-level\fR .RS 4 Set log level.\& The levels are: error, warning, info, debug, trace and quiet.\& .PP .RE \fB-h, --help\fR .RS 4 Get help.\& .PP .RE .SH DESCRIPTION .PP 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.\& .PP .SS MULTIPLE OUTPUTS .PP 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 \fI-o\fR command line argument.\& The argument accepts the short name such as \fIeDP-1\fR or \fIDP-4\fR.\& Running wayvnc in verbose mode (\fI-v\fR) will display the names of all outputs on startup, or you can query them at runtime via the \fBwayvncctl output-list\fR command.\& .PP You can also change which output is being captured on the fly via the \fBwayvncctl output-set\fR command.\& .PP .SH CONFIGURATION .PP wayvnc searches for a config file in the location .RS 4 ~/$XDG_CONFIG_HOME/wayvnc/config .RE or if $XDG_CONFIG_HOME is not set .RS 4 ~/.\&config/wayvnc/config .PP .RE .SS SYNTAX .PP The configuration file is composed of key-value pairs separated with an \fBequal\fR sign.\& Whitespace around either the key or the value is insignificant and is not considered to be part of the key or the value.\& .PP .SS KEYWORDS .PP \fBaddress\fR .RS 4 The address to which the server shall bind, e.\&g.\& 0.\&0.\&0.\&0 or localhost.\& .PP .RE \fBcertificate_file\fR .RS 4 The path to the certificate file for encryption.\& Only applicable when \fBenable_auth\fR=true.\& .PP .RE \fBenable_auth\fR .RS 4 Enable authentication and encryption.\& Setting this value to \fBtrue\fR requires also setting \fBcertificate_file\fR, \fBprivate_key_file\fR, \fBusername\fR and \fBpassword\fR.\& .PP .RE \fBpassword\fR .RS 4 Choose a password for authentication.\& .PP .RE \fBport\fR .RS 4 The port to which the server shall bind.\& Default is 5900.\& .PP .RE \fBprivate_key_file_file\fR .RS 4 The path to the private key file for TLS encryption.\& Only applicable when \fBenable_auth\fR=true.\& .PP .RE \fBrelax_encryption\fR .RS 4 Don'\&t require encryption after the user has been authenticated.\& This enables some security types such as Apple Diffie-Hellman.\& .PP .RE \fBrsa_private_key_file\fR .RS 4 The path to the private key file for RSA-AES encryption.\& Only applicable when \fBenable_auth\fR=true.\& .PP .RE \fBusername\fR .RS 4 Choose a username for authentication.\& .PP .RE \fBuse_relative_paths\fR .RS 4 Make file paths relative to the location of the config file.\& .PP .RE \fBxkb_layout\fR .RS 4 The keyboard layout to use for key code lookup.\& .PP Default: \fIXKB_DEFAULT_LAYOUT\fR or system default.\& .PP .RE \fBxkb_model\fR .RS 4 The keyboard model by which to interpret keycodes and LEDs.\& .PP Default: "pc105" .PP .RE \fBxkb_options\fR .RS 4 A comma separated list of options, through which the user specifies non-layout related preferences such as which key is the Compose key.\& .PP Default: \fIXKB_DEFAULT_OPTIONS\fR or system default.\& .PP .RE \fBxkb_rules\fR .RS 4 The rules file describes how to interpret the values of the model, layout, variant and options fields.\& .PP Default: \fIXKB_DEFAULT_RULES\fR or system default.\& .PP .RE \fBxkb_variant\fR .RS 4 The keyboard variant to use for keycode lookup.\& .PP Default: \fIXKB_DEFAULT_VARIANT\fR or system default.\& .PP .RE .SS EXAMPLE .PP .nf .RS 4 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 .fi .RE .PP .SH WAYVNCCTL CONTROL SOCKET .PP To facilitate runtime interaction and control, wayvnc opens a unix domain socket at \fB$XDG_RUNTIME_DIR\fR/wayvncctl (or a fallback of /tmp/wayvncctl-\fB$UID\fR).\& A client can connect and exchange json-formatted IPC messages to query and control the running wayvnc instance.\& .PP .SS IPC COMMANDS .PP \fIHELP\fR .PP The \fBhelp\fR command, when issued without any parameters, lists the names of all available commands.\& .PP If an optional \fBcommand\fR parameter refers to one of those commands by name, the response data will be a detailed description of that command and its parameters.\& .PP \fIEVENT-RECEIVE\fR .PP The \fBevent-receive\fR command registers for asynchronous server events.\& See the \fIEVENTS\fR section below for details on the event message format, and the \fIIPC EVENTS\fR section below for a description of all possible server events.\& .PP 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.\& .PP \fICLIENT-LIST\fR .PP The \fBclient-list\fR command retrieves a list of all VNC clients currently connected to wayvnc.\& .PP \fICLIENT-DISCONNECT\fR .PP The \fBclient-disconnect\fR command disconnects a single VNC client.\& .PP Parameters: .PP \fBid\fR .RS 4 Required: The ID of the client to disconnect.\& This ID can be found from the \fIGET-CLIENTS\fR command or receipt of a \fICLIENT-CONNECTED\fR event.\& .PP .RE \fIOUTPUT-LIST\fR .PP The \fBoutput-list\fR command retrieves a list of all outputs known to wayvnc and whether or not each one is currently being captured.\& .PP \fIOUTPUT-CYCLE\fR .PP For multi-output wayland displays, the \fBoutput-cycle\fR 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.\& .PP \fIOUTPUT-SET\fR .PP For multi-output wayland displays, the \fBoutput-set\fR command switches which output is actively captured by wayvnc by name.\& .PP \fBoutput-name=name\fR .RS 4 Required: The name of the output to capture next.\& .PP .RE \fIVERSION\fR .PP The \fBversion\fR command queries the running wayvnc instance for its version information.\& Much like the \fI-V\fR option, the response data will contain the version numbers of wayvnc, as well as the versions of the neatvnc and aml components.\& .PP \fIWAYVNC-EXIT\fR .PP The \fBwayvnc-exit\fR command disconnects all clients and shuts down wayvnc.\& .PP .SS IPC EVENTS .PP \fICAPTURE_CHANGED\fR .PP The \fBcapture-changed\fR event is sent when the currently captured output changes.\& .PP Parameters: .PP \fBoutput=.\&.\&.\&\fR .RS 4 The name of the output now being captured.\& .PP .RE \fICLIENT-CONNECTED\fR .PP The \fBclient-connected\fR event is sent when a new VNC client connects to wayvnc.\& .PP Parameters: .PP \fBid=.\&.\&.\&\fR .RS 4 A unique identifier for this client.\& .PP .RE \fBconnection_count=.\&.\&.\&\fR .RS 4 The total number of connected VNC clients including this one.\& .PP .RE \fBaddress=.\&.\&.\&\fR .RS 4 The IP address of this client.\& May be null.\& .PP .RE \fBusername=.\&.\&.\&\fR .RS 4 The username used to authenticate this client.\& May be null.\& .PP .RE \fICLIENT-DISCONNECTED\fR .PP The \fBclient-disconnected\fR event is sent when a VNC cliwnt disconnects from wayvnc.\& .PP Parameters: .PP \fBid=.\&.\&.\&\fR .RS 4 A unique identifier for this client.\& .PP .RE \fBconnection_count=.\&.\&.\&\fR .RS 4 The total number of connected VNC clients not including this one.\& .PP .RE \fBaddress=.\&.\&.\&\fR .RS 4 The IP address of this client.\& May be null.\& .PP .RE \fBusername=.\&.\&.\&\fR .RS 4 The username used to authenticate this client.\& May be null.\& .PP .RE .SS IPC MESSAGE FORMAT .PP The \fBwayvncctl(1)\fR 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.\& .PP \fBNote\fR This message format is unstable and may change substantially over the next few releases.\& .PP \fIREQUEST\fR .PP The general form of a json-ipc request message is: .PP .nf .RS 4 { "method": "command-name", "id": 123, "params": { "key1": "value1", "key2": "value2", } } .fi .RE .PP The \fBmethod\fR is the name of the command to be executed.\& Use the \fBhelp\fR method to query a list of all valid method names.\& .PP The \fBid\fR 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.\& .PP The \fBparams\fR object supplies optional parameters on a per-method basis, and may be omitted if empty.\& .PP \fIRESPONSE\fR .PP .nf .RS 4 { "id": 123, "code": 0, "data": { \&.\&.\&. } } .fi .RE .PP If the request had an id, the response will have an identical value for \fBid\fR.\& .PP The numerical \fBcode\fR provides an indication of how the request was handled.\& A value of \fB0\fR always signifies success.\& Any other value means failure, and varies depending on the method in question.\& .PP The \fBdata\fR 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.\& .PP \fIEVENTS\fR .PP Events are aaynchronous messages sent from a server to all registered clients.\& The message format is identical to a \fIREQUEST\fR, but without an "id" field, and a client must not send a response.\& .PP Example event message: .PP .nf .RS 4 { "method": "event-name", "params": { "key1": "value1", "key2": "value2", } } .fi .RE .PP In order to receive any events, a client must first register to receive them by sending a \fIevent-receive\fR 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.\& .PP .SH ENVIRONMENT .PP The following environment variables have an effect on wayvnc: .PP \fIWAYLAND_DISPLAY\fR .RS 4 Specifies the name of the Wayland display that the compositor to which wayvnc shall bind is running on.\& .PP .RE \fIXDG_CONFIG_HOME\fR .RS 4 Specifies the location of configuration files.\& .PP .RE \fIXDG_RUNTIME_DIR\fR .RS 4 Specifies the default location for the wayvncctl control socket.\& .PP .RE .SH FAQ .PP \fBWayvnc complains that a protocol is not supported\fR .PP .RS 4 The error might look like this: .nf .RS 4 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 .fi .RE .PP 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.\& .PP .RE \fBHow can I run wayvnc in headless mode/over an SSH session?\&\fR .PP .RS 4 Set the environment variables \fIWLR_BACKENDS\fR=headless and \fIWLR_LIBINPUT_NO_DEVICES\fR=1 before starting the compositor, then run wayvnc as normal.\& .PP .RE \fBHow can I pass my mod-key from Sway to the remote desktop session?\&\fR .PP .RS 4 Create an almost empty mode in your sway config.\& Example: .nf .RS 4 mode passthrough { bindsym $mod+Pause mode default } bindsym $mod+Pause mode passthrough .fi .RE This makes it so that when you press $mod+Pause, all keybindings, except the one to switch back, are disabled.\& .PP .RE \fBNot all symbols show up when I'\&m typing.\& What can I do to fix this?\&\fR .PP .RS 4 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 symbols that you use.\& .PP .RE \fBHow do I enable the Compose key?\&\fR .PP .RS 4 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.\& .PP .RE .SH AUTHORS .PP Maintained by Andri Yngvason .\& 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.\& .PP .SH SEE ALSO .PP \fBwayvncctl(1)\fR