1wayvnc(1) General Commands Manual wayvnc(1)
2
6 wayvnc - A VNC server for wlroots based Wayland compositors.
7
9 wayvnc [options] [address [port]]
10
12 -C, --config=<path>
13 Select a config file.
14 -g,--gpu
16 Enable features that require GPU.
17 -o, --output=<name>
19 Select output to capture.
20 -k, --keyboard=<layout>[-variant]
22 Select keyboard layout. The variant can be appended if needed.
23 -s, --seat=<name>
25 Select seat by name.
26 -S, --socket=<path>
28 Set wayvnc control socket path. Default: $XDG_RUNTIME_DIR/wayvncctl
29 or /tmp/wayvncctl-$UID
30 -r, --render-cursor
32 Enable overlay cursor rendering.
33 -f, --max-fps=<fps>
35 Set the rate limit (default 30).
36 -p, --show-performance
38 Show performance counters.
39 -u, --unix-socket
41 Create a UNIX domain socket instead of TCP, treating the address as
42 a path.
43 -d, --disable-input
45 Disable all remote input. This allows using wayvnc without composi‐
46 tor support of virtual mouse / keyboard protocols.
47 -V, --version
49 Show version info.
50 -v,--verbose
52 Be more verbose. Same as setting `--log-level=info`.
53 -w,--websocket
55 Create a websocket.
56 -L,--log-level
58 Set log level. The levels are: error, warning, info, debug, trace
59 and quiet.
60 -h, --help
62 Get help.
63
65 This is a VNC server for wlroots based Wayland compositors. It attaches
66 to a running Wayland session, creates virtual input devices and exposes
67 a single display via the RFB protocol. The Wayland session may be a
68 headless one, so it is also possible to run wayvnc without a physical
69 display attached.
70 MULTIPLE OUTPUTS
72 If the Wayland session consists of multiple outputs, only one will be
73 captured. By default this will be the first one, but can be specified
74 by the -o command line argument. The argument accepts the short name
75 such as eDP-1 or DP-4. Running wayvnc in verbose mode (-v) will display
76 the names of all outputs on startup, or you can query them at runtime
77 via the wayvncctl output-list command.
78 You can also change which output is being captured on the fly via the
80 wayvncctl output-set command.
81
83 wayvnc searches for a config file in the location
84 ~/$XDG_CONFIG_HOME/wayvnc/config
85 or if $XDG_CONFIG_HOME is not set
86 ~/.config/wayvnc/config
87 SYNTAX
89 The configuration file is composed of key-value pairs separated with an
90 equal sign. Whitespace around either the key or the value is insignifi‐
91 cant and is not considered to be part of the key or the value.
92 KEYWORDS
94 address
95 The address to which the server shall bind, e.g. 0.0.0.0 or local‐
96 host.
97 certificate_file
99 The path to the certificate file for encryption. Only applicable
100 when enable_auth=true.
101 enable_auth
103 Enable authentication and encryption. Setting this value to true
104 requires also setting certificate_file, private_key_file, username
105 and password.
106 password
108 Choose a password for authentication.
109 port
111 The port to which the server shall bind. Default is 5900.
112 private_key_file_file
114 The path to the private key file for TLS encryption. Only applica‐
115 ble when enable_auth=true.
116 relax_encryption
118 Don't require encryption after the user has been authenticated.
119 This enables some security types such as Apple Diffie-Hellman.
120 rsa_private_key_file
122 The path to the private key file for RSA-AES encryption. Only ap‐
123 plicable when enable_auth=true.
124 username
126 Choose a username for authentication.
127 use_relative_paths
129 Make file paths relative to the location of the config file.
130 xkb_layout
132 The keyboard layout to use for key code lookup.
133 Default: XKB_DEFAULT_LAYOUT or system default.
135 xkb_model
137 The keyboard model by which to interpret keycodes and LEDs.
138 Default: "pc105"
140 xkb_options
142 A comma separated list of options, through which the user specifies
143 non-layout related preferences such as which key is the Compose
144 key.
145 Default: XKB_DEFAULT_OPTIONS or system default.
147 xkb_rules
149 The rules file describes how to interpret the values of the model,
150 layout, variant and options fields.
151 Default: XKB_DEFAULT_RULES or system default.
153 xkb_variant
155 The keyboard variant to use for keycode lookup.
156 Default: XKB_DEFAULT_VARIANT or system default.
158 EXAMPLE
160 use_relative_paths=true
161 address=0.0.0.0
162 enable_auth=true
163 username=luser
164 password=p455w0rd
165 rsa_private_key_file=rsa_key.pem
166 private_key_file=tls_key.pem
167 certificate_file=tls_cert.pem
168
170 To facilitate runtime interaction and control, wayvnc opens a unix do‐
171 main socket at $XDG_RUNTIME_DIR/wayvncctl (or a fallback of
172 /tmp/wayvncctl-$UID). A client can connect and exchange json-formatted
173 IPC messages to query and control the running wayvnc instance.
174 IPC COMMANDS
176 HELP
177 The help command, when issued without any parameters, lists the names
179 of all available commands.
180 If an optional command parameter refers to one of those commands by
182 name, the response data will be a detailed description of that command
183 and its parameters.
184 EVENT-RECEIVE
186 The event-receive command registers for asynchronous server events. See
188 the EVENTS section below for details on the event message format, and
189 the IPC EVENTS section below for a description of all possible server
190 events.
191 Event registration registers for all available server events and is
193 scoped to the current connection only. If a client disconnects and re‐
194 connects, it must re-register for events.
195 CLIENT-LIST
197 The client-list command retrieves a list of all VNC clients currently
199 connected to wayvnc.
200 CLIENT-DISCONNECT
202 The client-disconnect command disconnects a single VNC client.
204 Parameters:
206 id
208 Required: The ID of the client to disconnect. This ID can be found
209 from the GET-CLIENTS command or receipt of a CLIENT-CONNECTED
210 event.
211 OUTPUT-LIST
213 The output-list command retrieves a list of all outputs known to wayvnc
215 and whether or not each one is currently being captured.
216 OUTPUT-CYCLE
218 For multi-output wayland displays, the output-cycle command switches
220 which output is actively captured by wayvnc. Running this once will
221 switch to the next available output. If no more outputs are available,
222 it cycles back to the first again.
223 OUTPUT-SET
225 For multi-output wayland displays, the output-set command switches
227 which output is actively captured by wayvnc by name.
228 output-name=name
230 Required: The name of the output to capture next.
231 VERSION
233 The version command queries the running wayvnc instance for its version
235 information. Much like the -V option, the response data will contain
236 the version numbers of wayvnc, as well as the versions of the neatvnc
237 and aml components.
238 WAYVNC-EXIT
240 The wayvnc-exit command disconnects all clients and shuts down wayvnc.
242 IPC EVENTS
244 CAPTURE_CHANGED
245 The capture-changed event is sent when the currently captured output
247 changes.
248 Parameters:
250 output=...
252 The name of the output now being captured.
253 CLIENT-CONNECTED
255 The client-connected event is sent when a new VNC client connects to
257 wayvnc.
258 Parameters:
260 id=...
262 A unique identifier for this client.
263 connection_count=...
265 The total number of connected VNC clients including this one.
266 hostname=...
268 The hostname or IP of this client. May be null.
269 username=...
271 The username used to authenticate this client. May be null.
272 CLIENT-DISCONNECTED
274 The client-disconnected event is sent when a VNC cliwnt disconnects
276 from wayvnc.
277 Parameters:
279 id=...
281 A unique identifier for this client.
282 connection_count=...
284 The total number of connected VNC clients not including this one.
285 hostname=...
287 The hostname or IP of this client. May be null.
288 username=...
290 The username used to authenticate this client. May be null.
291 IPC MESSAGE FORMAT
293 The wayvncctl(1) command line utility will construct properly-formatted
294 json ipc messages, but any client will work. The client initiates the
295 connection and sends one or more request objects, each of which will
296 receive a corresponding response object.
297 Note This message format is unstable and may change substantially over
299 the next few releases.
300 REQUEST
302 The general form of a json-ipc request message is:
304 {
306 "method": "command-name",
307 "id": 123,
308 "params": {
309 "key1": "value1",
310 "key2": "value2",
311 }
312 }
313 The method is the name of the command to be executed. Use the help
315 method to query a list of all valid method names.
316 The id field is optional and may be any valid json number or string. If
318 provided, the response to this request will contain the identical id
319 value, which the client may use to coordinate multiple requests and re‐
320 sponses.
321 The params object supplies optional parameters on a per-method basis,
323 and may be omitted if empty.
324 RESPONSE
326 {
328 "id": 123,
329 "code": 0,
330 "data": {
331 ...
332 }
333 }
334 If the request had an id, the response will have an identical value for
336 id.
337 The numerical code provides an indication of how the request was han‐
339 dled. A value of 0 always signifies success. Any other value means
340 failure, and varies depending on the method in question.
341 The data object contains method-specific return data. This may be
343 structured data in response to a query, a simple error string in the
344 case of a failed request, or it may be omitted entirely if the error
345 code alone is sufficient.
346 EVENTS
348 Events are aaynchronous messages sent from a server to all registered
350 clients. The message format is identical to a REQUEST, but without an
351 "id" field, and a client must not send a response.
352 Example event message:
354 {
356 "method": "event-name",
357 "params": {
358 "key1": "value1",
359 "key2": "value2",
360 }
361 }
362 In order to receive any events, a client must first register to receive
364 them by sending a event-receive request IPC. Once the success response
365 has been sent by the server, the client must expect that asynchronous
366 event messages may be sent by the server at any time, even between a
367 request and the associated response.
368
370 The following environment variables have an effect on wayvnc:
371 WAYLAND_DISPLAY
373 Specifies the name of the Wayland display that the compositor to
374 which wayvnc shall bind is running on.
375 XDG_CONFIG_HOME
377 Specifies the location of configuration files.
378 XDG_RUNTIME_DIR
380 Specifies the default location for the wayvncctl control socket.
381
383 Wayvnc complains that a protocol is not supported
384 The error might look like this:
386 wl_registry@2: error 0: invalid version for global zxdg_output_manager_v1 (4): have 2, wanted 3
387 ERROR: ../src/main.c: 388: Screencopy protocol not supported by compositor. Exiting. Refer to FAQ section in man page.
388 ERROR: ../src/main.c: 1024: Failed to initialise wayland
389 This means that your wayland compositor does not implement the
391 screencopy protocol and wayvnc won't work with it. Screencopy is
392 implemented by wlroots based compositors such as Sway and Wayfire.
393 How can I run wayvnc in headless mode/over an SSH session?
395 Set the environment variables WLR_BACKENDS=headless and WLR_LIBIN‐
397 PUT_NO_DEVICES=1 before starting the compositor, then run wayvnc as
398 normal.
399 How can I pass my mod-key from Sway to the remote desktop session?
401 Create an almost empty mode in your sway config. Example:
403 mode passthrough {
404 bindsym $mod+Pause mode default
405 }
406 bindsym $mod+Pause mode passthrough
407 This makes it so that when you press $mod+Pause, all keybindings,
408 except the one to switch back, are disabled.
409 Not all symbols show up when I'm typing. What can I do to fix this?
411 Try setting the keyboard layout in wayvnc to the one that most
413 closely matches the keyboard layout that you're using on the client
414 side. An exact layout isn't needed, just one that has all the sym‐
415 bols that you use.
416 How do I enable the Compose key?
418 Set "xkb_options=compose:menu" in the config file. Any key that is
420 not otherwise used will work. There just needs to be some key for
421 wayvnc to match against.
422
424 Maintained by Andri Yngvason <andri@yngvason.is>. Up-to-date sources
425 can be found at https://github.com/any1/wayvnc and bugs reports or
426 patches can be submitted to GitHub's issue tracker.
427
429 wayvncctl(1)
430 2023-11-05 wayvnc(1)