1XPRA(1) General Commands Manual XPRA(1)
2
3
4
6 xpra - viewer for remote, persistent X applications
7
9 xpra start [CONNECTIONSTRING] | xpra start-desktop [CONNECTIONSTRING]
10 [OPTIONS..]
11 xpra attach [CONNECTIONSTRING] [OPTIONS..]
12 xpra shadow [CONNECTIONSTRING] [OPTIONS..]
13 xpra proxy [:DISPLAY] [OPTIONS..]
14 xpra stop | xpra exit | xpra detach | xpra screenshot filename | xpra
15 version | xpra info [CONNECTIONSTRING] | xpra top [CONNECTION‐
16 STRING] [OPTIONS..]
17 xpra control [CONNECTIONSTRING] command [arguments..] [--ssh=CMD]
18 [--remote-xpra=CMD] [--socket-dir=DIR] [--socket-dirs=DIRS]
19 xpra initenv [--socket-dir=DIR]
20 xpra list [--socket-dir=DIR]
21 xpra showconfig [OPTIONS..]
22 xpra showsetting [SETTING1..]
23 xpra list-mdns
24 xpra upgrade [:DISPLAY] [...any options accepted by xpra start...]
25 xpra upgrade-desktop [:DISPLAY] [...any options accepted by xpra start-
26 desktop...]
27
29 Xpra is a tool which allows you to run X programs — usually on a remote
30 host — and then direct their display to your local machine, disconnect
31 from these programs, and reconnect from the same or another machine,
32 all without losing any state. It differs from standard X forwarding in
33 that it allows disconnection and reconnection without disrupting the
34 forwarded application; it differs from VNC and similar remote display
35 technologies in that xpra can run rootless: i.e., applications for‐
36 warded by xpra appear on your desktop as normal windows managed by your
37 window manager, rather than being all "trapped in a box together".
38 Xpra also uses a custom protocol that is self-tuning and relatively
39 latency-insensitive, and thus is usable over network connections that
40 are too slow or unreliable for standard X forwarding. Xpra can also be
41 used to shadow an existing X11 display, or in desktop mode where it
42 behaves more like VNC.
43
44 By default the Xpra server announces available sessions (username and
45 display number) via mDNS to the local network. Use mdns=no to disable
46 it.
47
49 Xpra supports many types of connection strings (some may require extra
50 packages to be installed):
51
52 :DISPLAY
53 Local displays: this is the simplest form and is only valid for the
54 current local displays of the current user.
55
56 tcp://[USERNAME@]HOST:PORT[/DISPLAY]
57 TCP mode uses port numbers and not display numbers. If multiple dis‐
58 plays are available through a single TCP port (ie: using a proxy
59 server), then one can also specify the display number.
60
61 ssl://[USERNAME@]HOST:PORT[/DISPLAY]
62 SSL adds a secure socket layer on top of the TCP mode.
63
64 vsock://[USERNAME[:PASSWORD]@]HOST:PORT
65 Almost identical to the TCP mode, but using AF_VSOCK for transport.
66
67 ws://[USERNAME[:PASSWORD]@]HOST:PORT/[DISPLAY]
68 Connect using websocket protocol.
69
70 wss://[USERNAME[:PASSWORD]@]HOST:PORT/[DISPLAY]
71 Connect using secure websocket protocol. (websocket with SSL)
72
73 ssh://[USERNAME[:PASSWORD]@]HOST[:SSH_PORT]/[DISPLAY][?QUERYSTRING]
74 Connect using secure shell. (SSH)
75
76 Further options can be specified using the --ssh command line option.
77 The QUERYSTRING can be used to specify an ssh proxy:
78 ?proxy=ssh://[USERNAME[:PASSWORD]@]HOST[:SSH_PORT] xpra will then
79 establish an SSH connection to the specified "proxy" host, and from
80 that host xpra will set up an SSH connection to the xpra server.
81
82
83 For backwards compatibility, SSH mode also supports the syntax:
84 ssh:[USERNAME[:PASSWORD]@]HOST:DISPLAY but this form does not support
85 specifying the SSH port number. Older versions also used the form pro‐
86 tocol:host:port, but users are encouraged to move to a more standard
87 URI format using :// as separator.
88
89 The password need only be specified when the server authentication mod‐
90 ule requires it. (ie: often when authenticating against MS Windows
91 servers, or with multifile and sqlite authentication modules)
92
94 xpra start :7
95 Start an xpra server using display number :7. Note: using DIS‐
96 PLAY=:7 xterm to start applications against a specific display is
97 not recommended. Always prefer using xpra's --start= command line
98 option instead. See this next example:
99
100 xpra start --start=firefox
101 Start an xpra server, choosing a display automatically and start
102 firefox on that virtual display. No window will appear until you
103 attach with xpra attach. The start child commands will inherit an
104 environment tailored for running under xpra.
105
106 xpra start ssh://bigbox/7 --start=xterm
107 Start an xpra server on bigbox with an xterm in it, and connect to
108 it.
109
110 xpra start-desktop --start=xfce4-session
111 Start an xfce session in a nested X11 server on an automatically
112 assigned display number.
113
114 xpra list
115 Show a list of xpra servers you have running on the current host.
116
117 xpra list-mdns
118 Show a list of xpra servers found via mDNS. (local network)
119
120 xpra showconfig
121 Shows the configuration that would be used with other sub-com‐
122 mands, taking into account the command line arguments.
123
124 xpra showsetting [SETTING1..]
125 Shows the value of a specific configuration setting and which con‐
126 figuration directory set this value.
127
128 xpra attach :7
129 Attach to the xpra server that is using local display number :7.
130 Any apps running on that server will appear on your screen.
131
132 xpra attach ssh://foo@frodo/7
133 Use ssh to attach to the xpra server that is running on machine
134 frodo as user foo and using display :7. Any apps running on that
135 server will appear on your local screen.
136
137 xpra start :7 --start=screen
138 Start an xpra server and a screen(1) session. If any of the
139 applications inside screen attempt to use X, they will be directed
140 to the xpra server.
141
143 Understanding the basic idea of displays is critical to using xpra suc‐
144 cessfully.
145
146 The idea comes from standard X. If you have multiple X servers running
147 on the same host, then there has to be some way to distinguish them. X
148 does this by assigning each server a small, unique integer called (per‐
149 haps confusingly) its "display". In the common case of a desktop
150 machine that has only one X server running, that server uses display
151 ":0" (or sometimes you'll see ":0.0", which is effectively the same).
152 When an application starts under X, it needs to know how to find the
153 right X server to use; it does this by checking the environment vari‐
154 able $DISPLAY.
155
156 Xpra faces a similar problem — there may be multiple xpra servers run‐
157 ning on the same host, as well as multiple X servers. It solves this
158 problem by re-using X's solution — each xpra server has a display asso‐
159 ciated with it. This display functions as both an X display (for when
160 xpra is talking to X applications) and as an identifier by which xpra
161 clients (like xpra attach) can locate the xpra server.
162
163 You may omit the display number when using xpra start: a display will
164 be chosen for you automatically. The display number chosen will be
165 shown in the log output, you should also be able to see it with xpra
166 list. On Microsoft Windows and Mac OSX, the display number should be
167 omitted.
168
169 Otherwise, when starting an xpra server, you may want to specify the
170 name of the display to use. To do this, simply pick any number you
171 like and stick a colon in front of it. For instance :7, :12, and :3117
172 are all valid display names. Just keep in mind that:
173
174 · Every X or xpra server that is running on a single machine must
175 use a different display name. If you pick a number that is
176 already in use then xpra will not work.
177
178 · The first few numbers (0, 1, 2) are commonly used by real X
179 servers.
180
181 · Everyone who connects to a given machine using ssh(1) with X
182 forwarding enabled will also use a display number; ssh generally
183 picks numbers near ten (10, 11, 12, ...).
184
185 When specifying an xpra server to a client program like xpra attach,
186 xpra detach, xpra stop, xpra exit, xpra version, xpra info, xpra list
187 or xpra screenshot then you can use a display of the form :DISPLAY to
188 refer to a server on the local host, or one of the form
189 ssh://[USER@]HOST/DISPLAY to refer to a server on a remote host; xpra
190 will automatically connect to the remote host using ssh(1). Generally,
191 if you have only one xpra session running on a machine (which you can
192 verify by running xpra list on that machine), then you can omit the
193 number entirely; xpra attach alone will attach to the lone xpra server
194 on the current machine regardless of its number, xpra attach
195 ssh://frodo will similarly attach to the lone xpra session on a remote
196 machine.
197
198 Connecting using the display number assumes that the client and server
199 use the same configuration for socket directories, or at least that the
200 client can find at least one of the directories used by the unix domain
201 sockets (see bind, socket-dir and socket-dirs).
202
203 If the xpra server was given the --bind-tcp, --bind-ssl --bind-
204 udp=[HOST]:PORT, --bind-ws, --bind-wss or --bind-vsock option when
205 started then you can also connect to it using a display of the form
206 tcp://HOST:PORT[/DISPLAY], udp://HOST:PORT[/DISPLAY],
207 ssl://HOST:PORT[/DISPLAY], ws://HOST:PORT[/DISPLAY],
208 wss://HOST:PORT[/DISPLAY] or vsock://HOST:PORT[/DISPLAY].
209
211 xpra start
212 This command starts a new xpra server, including any necessary setup.
213 (When starting a remote server with the ssh://HOST/DISPLAY syntax, the
214 new session will also be attached.)
215
216 xpra start-desktop
217 Starts a nested X11 server, all child commands will be started in the
218 nested X11 server.
219
220 xpra attach
221 This command attaches to a running xpra server, and forwards any appli‐
222 cations using that server to appear on your current screen.
223
224 xpra detach
225 Detaches the given xpra display.
226
227 xpra screenshot
228 Takes a screenshot and saves it to the filename specified. Note:
229 screenshots can only be taken when a client is attached.
230
231 xpra version
232 Queries the server version and prints it out. Note: older servers may
233 not support this feature.
234
235 xpra info
236 Queries the server for version, status and statistics.
237
238 xpra top
239 Shows the server's key health attributes.
240
241 xpra control
242 Modify the server at runtime by issuing commands. The list of commands
243 can be obtained by specifying "help" as command. Some of those com‐
244 mands may support a "help" mode themselves.
245
246 xpra initenv
247 This internal command creates the run-xpra script used with ssh connec‐
248 tions.
249
250 xpra stop
251 This command attaches to a running xpra server, and requests that it
252 terminates immediately. This generally causes any applications using
253 that server to terminate as well.
254
255 xpra exit
256 This command attaches to a running xpra server, and requests that it
257 terminates immediately. Unlike xpra stop, the Xvfb process and its X11
258 clients (if any) will be left running.
259
260 xpra showconfig
261 This commands shows the configuration which would be used given the
262 arguments provided. You can also specify as extra arguments the spe‐
263 cific options that should be displayed, or use the special value all to
264 display all the options including the ones which are normally not dis‐
265 played because they are not relevant on the given system.
266
267 xpra list
268 This command finds all xpra servers that have been started by the cur‐
269 rent user on the current machine, and lists them.
270
271 xpra upgrade
272 This command starts a new xpra server, but instead of creating it from
273 scratch, it attaches to another existing server, tells it to exit, and
274 takes over managing the applications that it was managing before. As
275 the name suggests, the main use case is to replace a server running
276 against an older version of xpra with a newer version, without having
277 to restart your session. Any currently-running xpra attach command
278 will exit and need to be restarted.
279
280 xpra upgrade-desktop
281 Same as upgrade but for servers started using start-desktop. It is
282 possible to upgrade seamless server into a desktop server and vice
283 versa.
284
285 xpra shadow
286 This command shadows an existing X11 display. If there is only one X11
287 display active and its number is below 10, it can be auto-detected.
288
289 Note that this mode of operation uses screenscraping which is far less
290 efficient. Using a video encoder (h264 or vp8) is highly recommended
291 for this mode of operation.
292
293 xpra proxy
294 This command allows a single server to proxy connections for multiple
295 others, potentially serving as a load balancing or authentication entry
296 point for many sessions. The proxy server will spawn a new process for
297 each proxy connection, this proxy process will create an unauthenti‐
298 cated new unix domain socket which can be used with the subcommands
299 info, version and stop.
300
301
302 Important Note
303 Some platforms and package managers may choose to only build the client
304 and not the server. In this case, only the attach subcommand will be
305 available.
306
307
309 General options
310 --version
311 Displays xpra's version number.
312
313 -h, --help
314 Displays a summary of command line usage.
315
316 -d FILTER1,FILTER2,..., --debug=FILTER1,FILTER2,...
317 Enable debug logging. The special value all enables all debug‐
318 ging.
319
320 --mmap=yes|no|ABSOLUTEFILENAME
321 Enable or disable memory mapped pixel data transfer. By default
322 it is normally enabled automatically if the server and the
323 client reside on the same filesystem namespace. This method of
324 data transfer offers much lower overheads and reduces both CPU
325 consumption and local network traffic. When attaching, you can
326 also specify an absolute path where the mmap file will be cre‐
327 ated.
328
329 --mmap-group=GROUP
330 Sets the mmap file's gid to the group specified, and sets the
331 permissions to 660. This is necessary to share the mmap file
332 across user accounts. You can also use the special GROUP val‐
333 ues:
334
335 no Disable the functionality, the mmap file will use the
336 default file permissions and default group ownership.
337
338 SOCKET The group used will be the same one as found on the unix
339 domain socket file the client connects to. Obviously,
340 this can only work when connecting to unix domain sock‐
341 ets.
342
343 auto Will use the 'xpra' group if the user is a member, other‐
344 wise it will fallback to the same behaviour as SOCKET.
345
346
347 --windows=yes|no
348 Enable or disable the forwarding of windows. This is usually the
349 primary use for xpra and should be enabled.
350
351 --min-size=WIDTHxHEIGHT
352 Sets the minimum size for all decorated windows.
353
354 --max-size=WIDTHxHEIGHT
355 Sets the maximum size for all windows.
356
357 --readonly=yes|no
358 Read only mode ignores all keyboard and mouse activity.
359
360
361 --clipboard=yes|no|clipboard-type
362 Enable or disable clipboard synchronization. If disabled on the
363 server, no clients will be able to use clipboard synchronization
364 at all. If turned off on the client, only this particular con‐
365 nection will ignore clipboard data from the server. This can
366 also be used to specify a different clipboard implementation.
367 The clipboard types available will vary from platform to plat‐
368 form and also depend on build time environment and options so
369 this is best left on auto. Other clipboard types available may
370 include:
371
372 translated
373 Clipboard which can translate from one type of selection
374 to another
375
376 GDK The most complete clipboard implementation, includes full
377 X11 support
378
379 default
380 Fallback clipboard, with limited X11 support
381
382 OSX OSX specific clipboard
383
384
385 --clipboard-direction=to-server|to-client|both|disabled
386 Choose the direction of the clipboard synchronization.
387
388 --pulseaudio=yes|no
389 Enable or disable the starting of a pulseaudio server with the
390 session.
391
392 --pulseaudio-command=SERVER-START-COMMAND
393 Specifies the pulseaudio command to use to start the pulseaudio
394 server, unless disabled with pulseaudio=no.
395
396 --session-name=VALUE
397 Sets the name of this session. This value may be used in notifi‐
398 cations, utilities, tray menu, etc. Setting this value on the
399 server provides a default value which may be overridden on the
400 client.
401
402 --encoding=ENCODING
403 This specifies the image encoding to use, there are a number of
404 encodings supported: jpeg, png, png/P, png/L, webp, rgb, vp8,
405 vp9, h264 and h265 (some may not be available in your environ‐
406 ment). The default option is auto which allows the server to
407 select the best encoding automatically.
408
409
410 auto default mode: the built-in heuristics will choose the
411 most appropriate encoding
412
413 png compressed and lossless, can be quite slow.
414
415 png/P compressed and lossy: it uses a colour palette, which
416 means better compression but still slow.
417
418 png/L compressed and lossy: grayscale only using a palette.
419
420 rgb a raw pixel format (lossless) compressed with lz4, lzo or
421 zlib (see compressors) the compression ratio is lower,
422 but it is by far the fastest encoding available.
423
424 webp can be used in lossy or lossless mode, useful for graphi‐
425 cal applications, it compresses better than jpeg and is
426 reasonably fast except at high resolutions.
427
428 jpeg can be useful for graphical applications, it is lossy and
429 usually very fast.
430
431 vp8 lossy video encoding which always uses colour subsam‐
432 pling. Fast at encoding and decoding.
433
434 vp9 Video encoding which supports both lossy and lossless
435 modes, available if your ffmpeg library version is recent
436 enough.
437
438 h264 One of the best encoding available: it is fast, efficient
439 and tunable via the quality and speed options.
440
441 h265 Far too slow at encoding, avoid.
442
443 The default encoding which is automatically selected if you do not
444 specify one will depend on what options are available on both the
445 server and the client: rgb is always available (builtin), jpeg and png
446 require the Python Imaging Library, vp8, vp9, webp, h264 and h265 all
447 require their respective shared libraries, as well as the xpra codec
448 that uses them.
449
450 Note: when selecting a video encoding (usually h264, vp8 or vp9), it
451 will only be used if the screen is updating quickly enough, some of the
452 smaller screen updates will also be sent using one of the other non-
453 video encodings.
454
455
456 --video-scaling=on|off|SCALING
457 How much automatic video downscaling should be used, from 1
458 (rarely) to 100 (aggressively), 0 to disable. Video scaling is
459 normally used with video regions or very large windows (espe‐
460 cially full screen windows) to try to maintain a decent framer‐
461 ate. Video downscaling negatively affects visual quality and
462 will cause automatic refreshes (if enabled), it is most useful
463 on video content where it saves a considerable amount of band‐
464 width.
465
466
467 --socket-dir=DIR
468 Location where to write and look for the Xpra socket files. The
469 default location varies from platform to platform ("~/.xpra" on
470 most Posix systems). If unspecified, the first value from
471 socket-dirs will be used. It may also be specified using the
472 XPRA_SOCKET_DIR environment variable.
473
474 When using the socket-dir option, it is generally necessary to
475 specify socket-dir or socket-dirs on all following commands, for
476 xpra to work with the open sessions.
477
478 By specifying a shared directory this can be coupled with the
479 mmap-group and socket-permissions option to connect Xpra ses‐
480 sions across user accounts with shared memory acceleration.
481
482
483 --socket-dirs=DIR
484 Specifies the directories where to look for existing sockets if
485 a specific one was not set using socket-dir. You may specify
486 each directory using a new --socket-dirs command line argument,
487 or joined together by the path separator (: on Posix). The
488 paths will be expanded. (ie: --socket-dirs=~/.xpra:/tmp)
489
490
491 --file-transfer=on|off
492 Enable file transfers.
493
494 --open-files=on|off
495 This option may be used to allow the remote end to automatically
496 open files after they have been uploaded. This may be a secu‐
497 rity risk if you are using xpra to constrain what the clients
498 can execute on the server.
499
500
501 --forward-xdg-open=on|off
502 Intercept execution of xdg-open and forward the request to the
503 client.
504
505
506 --open-command=COMMAND
507 The command to use for opening files and URLs.
508
509
510 --bandwidth-limit=BITSPERSECOND
511 Restrict bandwidth usage to below the limit given. The client's
512 value cannot raise the limit of the server. The value may be
513 specified using standard units, ie: 1Mbps or 500K. In auto
514 mode, the client will set the bandwidth limit value to 80% of
515 the maximum speed of the network interface it is using to con‐
516 nect to the server.
517
518
519
520 Options for start, start-desktop, upgrade, proxy and shadow
521 --daemon=yes|no
522 By default, the xpra server puts itself into the background,
523 i.e. 'daemonizes', and redirects its output to a log file. This
524 can be used to prevent that behavior (useful mostly for debug‐
525 ging).
526
527
528 --resize-display=yes|no
529 Resize the virtual display to match the resolution of the client
530 currently connected. This only applies to the start and start-
531 desktop subcommands.
532
533
534 --fake-xinerama=PATH|auto|no
535 Specify the path to the libfakeXinerama.so library which will be
536 injected into all the child processes the server starts using
537 LD_PRELOAD. This can also be disabled or set to auto: the
538 server will then try to locate the library itself. This only
539 applies to the start subcommand.
540
541
542 --chdir=DIR
543 Change to this directory after daemonizing.
544
545
546 --uid=UID and --gid=GID
547 When launching the server as root, these options can be used to
548 drop privileges to the given UID / GID.
549
550
551 --pidfile=FILENAME
552 Writes the server process ID to this file on startup. If the
553 file has not been replaced, it will be deleted when the server
554 exits.
555
556
557 --bind=BIND_LOCATION
558 Create a local Unix domain socket (on Unix) or named-pipe (on MS
559 Windows) for each bind option specified.
560
561 This option can be specified multiple times to specify multiple
562 socket locations. These sockets support local connections with
563 the :7-style display address, and remote connections with the
564 ssh://frodo/7-style display address.
565
566 Local sockets may also process HTTP / Websocket connections if
567 the html switch is enabled.
568
569 The location can take the form:
570
571 none do not create a socket
572
573 auto backwards compatible default which uses the current
574 socket-dir
575
576 DIRECTORY/
577 create a socket in the directory specified, if the direc‐
578 tory does not exist then it will be created - you should
579 include the trailing slash to prevent the confusion with
580 the PATH form:
581
582 PATH create the socket using the path specified
583
584 --bind-tcp=[HOST]:PORT
585 Create a TCP socket for each --bind-tcp option specified. If
586 the host portion is omitted, then 127.0.0.1 (localhost) will be
587 used. If you wish to accept connections on all interfaces, pass
588 0.0.0.0 for the host portion.
589
590 Using this switch without using the tcp-auth option is not rec‐
591 ommended, and is a major security risk (especially when passing
592 0.0.0.0)! Anyone at all may connect to this port and access
593 your session.
594
595 TCP sockets may also process HTTP / Websocket connections if the
596 html switch is enabled. TCP sockets may also be upgraded to SSL
597 sockets if the ssl switch is enabled.
598
599 --bind-udp=[HOST]:PORT
600 Create a UDP socket for each --bind-udp option specified. If
601 the host portion is omitted, then 127.0.0.1 (localhost) will be
602 used. If you wish to accept connections on all interfaces, pass
603 0.0.0.0 for the host portion.
604
605 Using this switch without using the udp-auth option is not rec‐
606 ommended, and is a major security risk (especially when passing
607 0.0.0.0)! Anyone at all may connect to this port and access
608 your session. UDP sessions are trivial to hijack for anyone
609 able to sniff even just a single packet, it should only be used
610 in very specific use-cases, and never over unsecured networks.
611
612 --bind-ws=[HOST]:PORT
613 Create an HTTP / Websocket listener. See bind-tcp for host
614 restrictions, you should use the auth-ws to secure access.
615
616 --bind-wss=[HOST]:PORT
617 Create an HTTPS / Secure Websocket listener. See bind-tcp for
618 host restrictions, you should use the auth-wss to secure access.
619
620 --bind-ssl=[HOST]:PORT
621 Just like --bind-tcp but for SSL sockets. See ssl-auth and the
622 other SSL options.
623
624 --bind-rfb=[HOST]:PORT
625 Listens for RFB connections on the given port. These sockets
626 are only supported with the start-desktop and shadow modes.
627
628 --bind-vsock=CID:PORT
629 Create a VSOCK socket for each --bind-vsock option specified.
630
631 --auth=MODULE[:OPTION=VALUE]
632 Specifies the authentication module to use for unix domain sock‐
633 ets created using the bind switch. Authentication modules can
634 validate a username and password against a variety of backend
635 modules:
636
637 allow always allows authentication - this is dangerous and
638 should only be used for testing
639
640 fail always fails authentication, useful for testing
641
642 env matches against the environment variable specified by the
643 name option (which defaults to XPRA_PASSWORD). ie:
644 --auth=env:name=SOME_OTHER_ENV_VAR_NAME.
645
646 password
647 matches against the password specified using the value
648 option. ie: --auth=password:value=YOURPASSWORD. Note:
649 this command line option may be exposed to other pro‐
650 cesses on the same system.
651
652 file checks the password against the password data found in
653 the file specified using the filename option. ie:
654 --auth=file:filename=./password.txt.
655
656 The contents of this file will be treated as binary data,
657 there are no restrictions on character encodings or file
658 size. Beware of trailing newline characters which will
659 be included in the password data.
660
661
662 multifile
663 checks the username and password against the file speci‐
664 fied using the filename option. The file must contain
665 each user credentials on one line of the form:
666
667 username|password|uid|gid|displays|env_opts|session_opts
668
669 It is not possible to have usernames or password that
670 contain the pipe character | which is used as delimiter,
671 or newlines and carriage returns. This module is depre‐
672 cated, sqlite should be used instead.
673
674
675 sqlite
676
677 mysql
678
679 sql checks the username and password against the sqlite data‐
680 base file specified using the filename option (for the
681 sqlite backend), or the database specified using the uri
682 option (mysql and sql backends). The authentication will
683 be processed using the following query (which is config‐
684 urable using the password_query option): SELECT password
685 FROM users WHERE username=(?) The sessions available for
686 each user will be queried using: (this is configurable
687 using the sessions_query option): SELECT uid, gid, dis‐
688 plays, env_options, session_options FROM users WHERE
689 username=(?) Multiple displays may be specified as a
690 comma separated list.
691
692
693 hosts checks the host using the system's tcp-wrappers library.
694 (Posix only, and not available on Mac OS) See hosts.allow
695 and hosts.deny for details.
696
697
698 exec Executes the command specified using the command
699 attribute, the arguments to this command are: a descrip‐
700 tion of the access request and the timeout value. (also
701 configurable) If the command is not specified, the system
702 will try to locate and use the auth_dialog utility which
703 is shipped with xpra. The command should return 0 to
704 allow access, any other value will deny access.
705
706
707 peercred
708 checks the unix domain socket peer credentials using
709 SO_PEERCRED. This authentication module is only avail‐
710 able on some Posix compliant operating systems. This mod‐
711 ule will verify that the operating system provides the
712 uid and gid of the process that initiated the connection.
713 Access can be restricted by supplying in CSV format the
714 list of valid uids and gids that are allowed to connect.
715 Those id values may be specified using numerical values
716 or using the usernames / group names. This module is
717 different from the others in that it will not require the
718 client to supply a username or password, as those are
719 ignored. Environment variables and pseudo-environment
720 variables may also be used as values, ie: --auth=peer‐
721 cred:uid=\$UID.
722
723
724 pam validates the username and password using the PAM system
725
726 win32 validates the username and password using Microsoft Win‐
727 dows authentication (only available on this platform)
728
729 sys chooses the appropriate system authentication module
730 automatically (either pam or win32)
731
732
733 kerberos-password
734 validates the username and password using kerberos
735 authentication. Warning: this module does not use ker‐
736 beros tickets and the password will be sent in plain text
737 to the server. This should only be used for testing.
738
739 kerberos-ticket
740 validates a kerberos ticket obtained by the client.
741
742 gss validates a GSS ticket obtained by the client.
743
744 u2f requests a U2F token from the client.
745
746 ldap validates the username and password against an LDAP
747 server, using the python-ldap library.
748
749 ldap validates the username and password against an LDAP
750 server, using the python ldap3 library.
751
752 --tcp-auth=MODULE
753 Just like the auth switch, except this one only applies to TCP
754 sockets (sockets defined using the bind-tcp switch).
755
756 --udp-auth=MODULE
757 Just like the tcp-auth switch, except this one only applies to
758 UDP sockets (sockets defined using the bind-udp switch).
759
760 --ws-auth=MODULE
761 Just like the auth switch, except this one only applies to ws
762 sockets: sockets defined using the bind-ws switch, or TCP sock‐
763 ets upgraded to websockets. (if the html option is enabled).
764
765 --wss-auth=MODULE
766 Just like the auth switch, except this one only applies to wss
767 sockets: sockets defined using the bind-wss switch, ws sockets
768 upgraded to SSL (if the ssl option is enabled) or TCP sockets
769 upgraded to SSL and then to wss. (if both the ssl and html
770 options are enabled).
771
772 --ssl-auth=MODULE
773 Just like the auth switch, except this one only applies to SSL
774 sockets: sockets defined using the bind-ssl switch, or TCP sock‐
775 ets upgraded by ssl=auto or ssl=on.
776
777 --rfb-auth=MODULE
778 Authentication module to use for the bind-rfb sockets.
779
780 --vsock-auth=MODULE
781 Just like the auth switch, except this one only applies to VSOCK
782 sockets (sockets defined using the bind-vsock switch).
783
784 --challenge-handlers=MODULE:options
785 Configures which challenge handlers are used by the client and
786 in which order. This option may be repeated to specify multiple
787 handlers, which can be useful if the server sends more than one
788 authentication challenge. The default value is: all which cor‐
789 responds to: uri,file,env,kerberos,gss,u2f,prompt.
790
791 uri Use the password specified on the connection string, if
792 any.
793
794 file The filename used to store the password can be specified
795 using the filename option. If this option is not speci‐
796 fied, it will fallback to using the password filename
797 specified with the password-file switch.
798
799 env Use the password specified using the environment variable
800 specified using the name option, which defaults to
801 XPRA_PASSWORD if unspecified.
802
803 kerberos
804 Requests a kerberos token for the service specified.
805
806 gss Requests a gss token for the service specified.
807
808 u2f Requests a token from a U2F device.
809
810 prompt Prompt the user for the value. Terminal clients prompt
811 using text input, GUI clients use a dialog.
812
813 --min-port=PORT
814 The minimum port number allowed when creating UDP and TCP sock‐
815 ets. You can use a lower value to allow unprivileged users to
816 bind to privileged ports when starting sessions via the system
817 wide proxy server. The default value is 1024 which is the stan‐
818 dard value for privileged ports.
819
820 --mdns=yes|no
821 Enable or disable the publication of new sessions via mDNS.
822
823 --dbus-launch=COMMAND|no
824 Start the session within a dbus-launch context, you can specify
825 the dbus launch command to use, or turn it off completely. Some
826 features may not be available without a dbus context.
827
828 --dbus-proxy=yes|no
829 Allows the client to forward dbus calls to the server.
830
831 --dbus-control=yes|no
832 Start a dbus server which can be used to interact with the
833 server process.
834
835
836
837 Options for start, start-desktop, upgrade
838 --exec-wrapper=CMD
839 A wrapper command which is prepended to all start commands.
840 Typically, this is used for starting all sub-commands via Virtu‐
841 alGL.
842
843 --start=CMD
844 After starting the server, runs the command CMD using the
845 default shell. The command is run with its $DISPLAY set to
846 point to the newly-started server. This option may be given
847 multiple times to start multiple commands.
848
849 --start-child=CMD
850 Identical to --start, except that the commands are taken into
851 account by --exit-with-children.
852
853 --start-after-connect=CMD
854 Wait for the first client to connect before starting the com‐
855 mand.
856
857 --start-child-after-connect=CMD
858 Wait for the first client to connect before starting the child
859 command. See start-child.
860
861 --start-on-connect=CMD
862 Execute this command every time a client connects.
863
864 --start-child-on-connect=CMD
865 Execute this child command every time a client connects. See
866 start-child.
867
868 --start-on-last-client-exit=CMD
869 Execute this command every time a client disconnects and there
870 are no other clients left.
871
872 --start-child-on-last-client-exit=CMD
873 Execute this child command every time a client disconnects and
874 there are no other clients left. See start-child.
875
876 --terminate-children=yes|no
877 On server stop, terminate all the child commands that have been
878 started by the server. This does not affect server exit. Most
879 child commands are tied to the display so they are normally
880 forced to shutdown anyway, but this gives them more time to
881 cleanup properly and can be used to stop background commands
882 that aren't tied to a display.
883
884 --exit-with-children=yes|no
885 This option may only be used if --start-child is also given. If
886 it is given, then the xpra server will monitor the status of the
887 children started by --start-child, and will automatically termi‐
888 nate itself when the last of them has exited.
889
890 --exit-with-client=yes|no
891 The server will terminate when the last client disconnects.
892
893 --env=KEY=VALUE
894 Extra environment variables which will only affect commands
895 started using fB--start or --start-child.
896
897 --start-new-commands=yes|no
898 Allow clients to ask the server to execute new commands. (this
899 can also be used via the control channel)
900
901 --start-via-proxy=yes|no|auto
902 If enabled, the start and start-desktop subcommands will be del‐
903 egated to the system wide proxy server instance. With auto
904 mode, this delegation will only occur if the system wide proxy
905 server is found.
906
907 --systemd-run=yes|no|auto
908 Wrap server start commands with systemd-run.
909
910 --systemd-run-args=ARGS
911 Command line arguments passed to systemd-run.
912
913 --use-display
914 Use an existing display rather than starting one with xvfb. You
915 are responsible for starting the display yourself. This can
916 also be used to rescue an existing display whose xpra server
917 instance crashed or for running xpra against an accelerated X11
918 server.
919
920 --displayfd=FD
921 The xpra server will write the display number back on this file
922 descriptor as a newline-terminated string. This is most useful
923 when the display number is not specified with the xpra start or
924 start-desktop subcommands.
925
926 --xvfb=CMD
927 When starting a seamless server, xpra starts a virtual X server
928 to run the clients on. If your Xvfb is installed in a funny
929 location, or you want to use some other virtual X server, then
930 this switch allows you to specify how to run your preferred X
931 server executable. The default value used depends on your plat‐
932 form. For more information, see: https://xpra.org/Xdummy.html
933
934 --sync-xvfb=DELAY
935 The windows are normally only displayed on the client(s), they
936 are not painted on the virtual display. Some applications like
937 screen recorders may want to capture the window contents, you
938 can use this option to enable painting with a configurable delay
939 (in milliseconds). Warning: this extra painting is expensive
940 and quite slow, which is why it is not enabled by default.
941
942 --attach=yes|no|auto
943 Once the server has started, immediately connect a client to it.
944 With the value auto, a client is started for remote servers
945 only. (servers specified via a network URI)
946
947
948
949 Options for start, start-desktop, upgrade, shadow
950 --tcp-proxy=HOST:PORT
951 Specifies the address to which non-xpra packets will be for‐
952 warded. This can be used to share the same TCP port with
953 another TCP servers, usually a web server. xpra clients will
954 connect as usual, but any client that does not speak the xpra
955 protocol will be forwarded to the alternative server.
956
957
958 --html=on|off|auto|webrootpath
959 Respond to HTTP requests on the TCP port(s) and local sockets.
960 This requires at least one TCP or local socket to be configured
961 using the matching bind option. The auto mode will enable sup‐
962 port if possible. By default the server will provide access to
963 the HTML5 client. You can also specify your own web root path
964 as argument.
965
966
967 --rfb-upgrade=DELAY
968 Allows RFB clients (ie: VNC) to connect to a plain TCP socket.
969 If no data is received after DELAY seconds, the server will send
970 a RFB handshake. This option is only applicable to servers
971 started in start-desktop or shadow modes.
972
973
974 --video-encoders=ENCODERS
975 Specifies the video encoders to try to load. By default, all of
976 them are loaded, but one may want to specify a more restrictive
977 list of encoders. Use the special value 'help' to get a list of
978 options. Use the value 'none' to not load any video encoders.
979
980
981 --csc-modules=MODULES
982 Specifies the colourspace conversion modules to try to load. By
983 default, all of them are loaded, but one may want to specify a
984 more restrictive list of modules. Use the special value 'help'
985 to get a list of options. Use the value 'none' to not load any
986 colourspace conversion modules.
987
988
989 --socket-permissions=ACCESS-MODE
990 Specifies the file permissions on the server's unix domain sock‐
991 ets. Defaults to 600. This is ignored when mmap-group is
992 enabled.
993
994
995
996 Options for start, start-desktop, upgrade and attach
997 --encryption=CIPHER
998 Specifies the cipher to use for securing the connection from
999 prying eyes. This option requires the use of the --encryption-
1000 keyfile option. The only cipher supported at present is AES, if
1001 the client requests encryption it will be used by both the
1002 client and server for all communication after the initial pass‐
1003 word verification, but only if the server supports this feature
1004 too. Note: this feature has not been extensively reviewed and
1005 as it is it should not be considered safe from determined
1006 attackers.
1007
1008 --tcp-encryption=CIPHER
1009 Just like the encryption switch, except this one only applies to
1010 TCP sockets (sockets defined using the bind-tcp switch).
1011
1012 --encryption-keyfile=FILENAME
1013 Specifies the key to use with the encryption cipher specified
1014 with --encryption. The client and server must use the same key‐
1015 file contents.
1016
1017 --tcp-encryption-keyfile=FILENAME
1018 Just like the encryption-keyfile switch, except this one only
1019 applies to TCP sockets (sockets defined using the bind-tcp
1020 switch).
1021
1022 --idle-timeout=IDLETIMEOUT
1023 The connection will be terminated if there is no user activity
1024 (mouse clicks or key presses) for the given amount of time (in
1025 seconds). Use the value 0 to disable this timeout.
1026
1027 --server-idle-timeout=IDLETIMEOUT
1028 The server will exit if there are no active connections for the
1029 given amount of time (in seconds). Use the value 0 to disable
1030 this timeout.
1031
1032 --clipboard-filter-file=FILENAME
1033 Name of a file containing regular expressions, any clipboard
1034 data that matches one of these regular expressions will be
1035 dropped. Note: at present this only applies to copying from the
1036 machine where this option is used, not to it.
1037
1038 --dpi=VALUE
1039 The 'dots per inch' value that client applications should try to
1040 honour. This numeric value should be in the range 10 to 500 to
1041 be useful. Many applications will only read this value when
1042 starting up, so connecting to an existing session started with a
1043 different DPI value may not have the desired effect.
1044
1045 --pixel-depth=VALUE
1046 When starting a server, this switch controls the bits per pixel
1047 of the virtual framebuffer. Possible values: 0 (auto), 16, 24,
1048 30. When starting a client, this switch controls the picture
1049 rendering with the opengl backend: values higher than 24 will
1050 enable deep color, the value 24 enables regular true color ren‐
1051 dering. Use the value 0 to let the client decide if the render‐
1052 ing will benefit from using deep color. (this is only supported
1053 on some Posix clients) Other values should not be used.
1054
1055 --cursors=yes|no
1056 Enable or disable forwarding of custom application mouse cur‐
1057 sors. Client applications may change the mouse cursor at any
1058 time, which will cause the new cursor's pixels to be sent to the
1059 client each time. This disables the feature.
1060
1061 --notifications=yes|no
1062 Enable or disable forwarding of system notifications. System
1063 notifications require the xpra server to have its own instance
1064 of a dbus daemon, if it is missing a warning will be printed on
1065 startup. This switch disables the feature entirely, and avoids
1066 the warning.
1067
1068 --input-method=METHOD
1069 Specify which input method to configure. This sets a number of
1070 environment variables which should be honoured by applications
1071 started with the start-child option.
1072
1073 The following METHODs are currently supported:
1074
1075 none Disable input methods completely and prevent it from
1076 interfering with keyboard input. This is the default.
1077
1078 keep Keeps the environment unchanged. You are responsible for
1079 ensuring it is correct.
1080
1081 xim Enables the X Input Method.
1082
1083 IBus Enables the Intelligent Input Bus.
1084
1085 SCIM Enables the Smart Common Input Method.
1086
1087 uim Enables the Universal Input Method.
1088
1089 Any other value will also be set up, but will trigger a warning.
1090
1091
1092 --xsettings=yes|no
1093 Enable or disable xsettings synchronization. Xsettings are only
1094 forwarded from posix clients connecting to real posix servers
1095 (not shadows).
1096
1097 --system-tray=yes|no
1098 Enable or disable forwarding of system tray icons. This feature
1099 requires client support and may not be available on all plat‐
1100 forms.
1101
1102 --bell=yes|no
1103 Enable or disable forwarding of the system bell.
1104
1105 --webcam=yes|no
1106 Enable or disable webcam forwarding.
1107
1108 --mousewheel=on|off|invert|invert-x|invert-y|invert-z
1109 Mouse wheel handling: can be used to disable mouse wheel for‐
1110 warding or to invert some or all axes.
1111
1112 --remote-logging=yes|no|both
1113 Allow the client to forward its log output to the server. The
1114 client can specify the value both to both send it to the server
1115 and keep it locally.
1116
1117 --av-sync=yes|no
1118 Enable or disable audio-video synchronization. The video data
1119 will be delayed so that it is displayed in sync with the audio.
1120 Note: this only applies to video regions, either auto-detected
1121 via the builtin heuristics or specified using the dbus inter‐
1122 face.
1123
1124
1125
1126 Options for attach
1127 --modal-windows=yes|no
1128 Honour modal windows. This may have undesirable side effects
1129 when multiple applications are forwarded through the same xpra
1130 server: modal windows will be made modal for all the applica‐
1131 tions forwarded by xpra rather than just the one application
1132 which owns that window.
1133
1134 --password-file=FILENAME
1135 Supply the password to be used for connecting to a server that
1136 uses authentication. See auth, tcp-auth, ssl-auth and vsock-auth
1137 for details. Alternatively, you may use the XPRA_PASSWORD envi‐
1138 ronment variable.
1139
1140 --opengl=(yes|no|auto)[:backend]
1141 Use OpenGL accelerated rendering on the client. The default is
1142 to detect if the graphics card and drivers are supported (auto
1143 mode), but one can also disable OpenGL (no) or force it enabled
1144 (yes). On some platforms, it is also possible to specify which
1145 backends should be used, only gtk and native are currently sup‐
1146 ported and only on X11 platforms. ie: opengl=yes:native, or
1147 opengl=auto:gtk,native.
1148
1149 --webcam=yes|no|/dev/deviceXXX|DEVICEID
1150 Enable or disable webcam forwarding. The webcam device to use
1151 can also be specified.
1152
1153
1154 -zLEVEL, --compress=LEVEL
1155 Select the level of compression xpra will use when transmitting
1156 data over the network. With the lz4 and lzo compressors, there
1157 are only two possible values: 0 (meaning no compression) and 1
1158 (compression enabled). The zlib compressor supports values
1159 between 0 (meaning no compression) and 9, inclusive. It should
1160 only be used when lz4 and lzo are not available.
1161
1162 This compression is not used on pixel data (except when using
1163 the rgb encoding).
1164
1165 --quality=VALUE
1166 This option sets a fixed image compression quality for lossy
1167 encodings (jpeg, webp, h264/h265 and vp8/vp9). First, one of
1168 those lossy encodings must be enabled with --encoding. Values
1169 range from 1 (lowest quality, high compression - generally unus‐
1170 able) to 100 (highest quality, low compression). Specify a
1171 value of zero to let the system tune the quality dynamically to
1172 achieve the best bandwidth usage possible. It is usually best
1173 not to use this option and use min-quality instead.
1174
1175 --min-quality=MIN-QUALITY
1176 This option sets the minimum encoding quality allowed when the
1177 quality option is set to automatic mode.
1178
1179 --speed=SPEED
1180 This option sets the encoding speed. Slower compresses more,
1181 faster will give better latency. The system normally uses a
1182 variable speed, this option forces a fixed speed setting to be
1183 used instead. It is usually best not to use this option and use
1184 min-speed instead.
1185
1186 --min-speed=MIN-SPEED
1187 This option sets the minimum encoding speed allowed when the
1188 speed option is set to automatic mode.
1189
1190 --auto-refresh-delay=DELAY
1191 This option sets a delay after which the windows are automati‐
1192 cally refreshed using a lossless frame. The delay is a float‐
1193 ing-point number and is in seconds. This option is enabled by
1194 default with a delay of 0.25 seconds. This option is only rele‐
1195 vant when using a lossy encoding.
1196
1197 --shortcut-modifiers=MODIFIERS
1198 Defines the default shortcut modifiers required by the key-
1199 shortcuts, these modifiers can then be referred to as #. The
1200 default value is 'auto' which evaluates to Meta+Shift on most
1201 platforms.
1202
1203 --key-shortcut=KEY:ACTION
1204 Can be specified multiple times to add multiple key shortcuts.
1205 These keys will be caught by the client and trigger the action
1206 specified and the key presses will not be passed on to the
1207 server.
1208
1209 The KEY specification may include keyboard modifiers in the form
1210 [modifier+]*key, for example: Shift+F10 or Shift+Control+B. You
1211 can refer to the shorcut-modifers option value using #, ie:
1212 #+F1.
1213
1214 If no shortcuts are defined on the command line, the default
1215 builtin list will be used.
1216
1217 Some of the actions may allow arguments (ie: the log action
1218 does), in which case they are specified in the usual programming
1219 style syntax: ACTION(ARG1, ARG2, etc)
1220 String arguments must be quoted (both single and double quotes
1221 are supported) and numeric arguments must not be quoted. Beware
1222 the the parenthesis and quotes must usually be escaped when used
1223 from a shell command line. Example: --key-short‐
1224 cut=Meta+Shift+F7:log\(\'hello\'\)
1225
1226 The following ACTIONs are currently defined:
1227
1228 quit Disconnect the xpra client.
1229
1230 log("MESSAGE")
1231 Sends MESSAGE to the log.
1232
1233 show_session_info[("TabName")]
1234 Shows the session information window. The optional Tab‐
1235 Name allows the information tab shown to be selected. Use
1236 the value help to get the list of options.
1237
1238 show_menu
1239 Shows the menu normally found in the system tray.
1240
1241 show_start_new_command
1242 Shows the start new command dialog.
1243
1244 magic_key
1245 Placeholder which can be used by some client toolkits.
1246
1247 void Does not do anything, and can therefore be used to pre‐
1248 vent certain key combinations from ever being sent to the
1249 server.
1250
1251 refresh_window
1252 Force the currently focused window to be refreshed.
1253
1254 refresh_all_windows
1255 Force all windows to be refreshed.
1256
1257 toggle_keyboard_grab
1258 The keyboard will be grabbed / ungrabbed by the current
1259 window.
1260
1261 toggle_pointer_grab
1262 The pointer will be grabbed and confined to the current
1263 window.
1264
1265 toggle_fullscreen
1266 Make the current window fullscreen / unfullscreen.
1267
1268 toggle_debug
1269 Turn debugging on or off.
1270
1271 scaleup
1272 Increase the current value of desktop-scaling.
1273
1274 scaledown
1275 Decrease the current value of desktop-scaling.
1276
1277 scalereset
1278 Reset the desktop-scaling to its original value.
1279
1280 scalingoff
1281 Turn off desktop-scaling.
1282
1283 increase_quality
1284 Increase the min-quality or quality setting (whichever
1285 one is currently in use).
1286
1287 decrease_quality
1288 Decrease the min-quality or quality setting (whichever
1289 one is currently in use).
1290
1291 increase_speed
1292 Increase the min-speed or speed setting (whichever one is
1293 currently in use).
1294
1295 decrease_speed
1296 Decrease the min-speed or speed setting (whichever one is
1297 currently in use).
1298
1299 --sharing=yes|no|auto
1300 Sharing allows more than one client to connect to the same ses‐
1301 sion. This must be enabled on both the server and all co-oper‐
1302 ating clients to function. When used server-side, the default
1303 value auto allows the clients to decide if they are willing to
1304 share the session. When used client-side, the default value
1305 auto evaluates to no. To allow sharing to work with unix domain
1306 sockets (either using local connections or via ssh), you should
1307 create at least one socket in a group accessible directory. On
1308 Posix with a default configuration, being a member of the xpra
1309 group should be enough to create a socket in /run/xpra. You must
1310 also ensure that the permissions of this socket file allow group
1311 access, see socket-permissions.
1312
1313 --lock=yes|no|auto
1314 Locking allows a client to refuse to hand over the session to a
1315 new client. The session may still be shared with multiple
1316 clients (see the sharing option), but otherwise the server will
1317 reject new clients. When used server-side, the default value
1318 auto allows the clients to decide if they want to lock the ses‐
1319 sion. When used client-side, the default value auto evaluates
1320 to no.
1321
1322 --keyboard-sync=yes|no
1323 Normally the key presses and key release events are sent to the
1324 server as they occur so that the server can maintain a consis‐
1325 tent keyboard state. Disabling synchronization can prevent keys
1326 from repeating unexpectedly on high latency links but it may
1327 also disrupt applications which access the keyboard directly
1328 (games, etc.).
1329
1330 --keyboard-raw=yes|no
1331 Tells the server to process all keyboard input untranslated.
1332 Both the client and the server must be using the same type of
1333 keyboard interface. (ie: both using X11)
1334
1335 --keyboard-layout=LAYOUTSTRING
1336 The keyboard layout is normally detected automatically. This
1337 option overrides it.
1338
1339 --keyboard-layouts=LAYOUTS
1340 The list of keyboard layouts to enable.
1341
1342 --keyboard-variant=VARIANT
1343 Override for the keyboard layout variant.
1344
1345 --keyboard-variants=VARIANTS
1346 Override for the keyboard layout variants.
1347
1348 --keyboard-options=OPTIONS
1349 Override for the keyboard options sent to the server.
1350
1351 --swap-keys=YES|NO
1352 This option only applies to MacOS clients, it swaps the command
1353 and control keys and is enabled by default.
1354
1355 --sound-source=PLUGIN
1356 Specifies the GStreamer sound plugin used for capturing the
1357 sound stream. This affects "speaker forwarding" on the server,
1358 and "microphone" forwarding on the client. To get a list of
1359 options use the special value 'help'. It is also possible to
1360 specify plugin options using the form: --sound-source= pulsede‐
1361 vice=device.alsa_input.pci-0000_00_14.2.analog-stereo
1362
1363 --speaker=on|off|disabled and --microphone=on|off|dis‐
1364 abled|on:DEVICE|off:DEVICE
1365 Sound input and output forwarding support: on will start the
1366 forwarding as soon as the connection is established, off will
1367 require the user to enable it via the menu, disabled will pre‐
1368 vent it from being used and the menu entry will be disabled.
1369 With microphone forwarding, you may also be able to specify
1370 which device to use.
1371
1372 --speaker-codec=CODEC and --microphone-codec=CODEC
1373 Specify the codec(s) to use for sound output (speaker) or input
1374 (microphone). This parameter can be specified multiple times
1375 and the order in which the codecs are specified defines the pre‐
1376 ferred codec order. Use the special value 'help' to get a list
1377 of options. When unspecified, all the available codecs are
1378 allowed and the first one is used.
1379
1380 --title=VALUE
1381 Sets the text shown as window title. The string supplied can
1382 make use of remote metadata placeholders which will be populated
1383 at runtime with the values from the remote server. The default
1384 value used is "@title@ on @client-machine@".
1385
1386 The following placeholders are defined:
1387
1388 @title@
1389 Will be replaced by the remote window's title.
1390
1391 @client-machine@
1392 Will be replaced by the hostname of the system where the
1393 application is running, if provided, the xpra server's
1394 hostname otherwise.
1395
1396 @server-machine@
1397 Will be replaced by the hostname of the xpra server.
1398
1399 @server-display@
1400 Will be replaced by the name of the display on which the
1401 application is running.
1402
1403 --border=BORDER
1404 Specifies the color and size of the border to draw inside every
1405 xpra window. This can be used to easily distinguish xpra win‐
1406 dows running on remote hosts from local windows. The BORDER can
1407 be specified using standard color names (ie: red, or orange) or
1408 using the web hexadecimal syntax (ie: #F00 or #FF8C00). The spe‐
1409 cial color name "auto" will derive the color from the server
1410 target address (the connection string) so that connecting to the
1411 same target should always give the same color. You may also
1412 specify the size of the border in pixels, ie: --border=yel‐
1413 low,10.
1414
1415 --window-icon=FILENAME
1416 Path to the default image which will be used for all windows.
1417 This icon may be shown in the window's bar, its iconified state
1418 or task switchers. This depends on the operating system, the
1419 window manage and the application may override this too.
1420
1421 --window-close=ACTION
1422 Choose what action to take when the window is closed by the
1423 client. The following actions can be used:
1424
1425 auto The client will figure out what is best based on the win‐
1426 dow type. This is the default. ie: it will use discon‐
1427 nect shadow sessions, Iforward for seamless windows.
1428
1429 forward
1430 The event will be forwarded to the server.
1431
1432 ignore Do nothing.
1433
1434 disconnect
1435 Disconnect from the server.
1436
1437 shutdown
1438 Shutdown the server.
1439
1440 --desktop-scaling=off|on|auto|VALUE
1441 Desktop scaling allows the windows to be scaled by the client.
1442 Downscaling will mostly waste bandwidth, upscaling allows the
1443 window's pixels to be sent over the wire at a lower resolution,
1444 saving bandwidth and CPU time. This option can also be used to
1445 request a specific scaling value. For best results, use opengl
1446 client rendering, the other display backends may show visual
1447 artifacts when scaling. Note: the scaling may also be adjusted
1448 at runtime through keyboard shortcuts if those are configured.
1449
1450 The desktop-scaling value can take the form:
1451
1452 off scaling will be disabled
1453
1454 on scaling will be allowed, but it will start unscaled
1455
1456 auto scaling will be allowed and a scaling value will be auto‐
1457 matically chosen if the client's desktop is large (bigger
1458 desktops will use higher scaling values)
1459
1460 scaling-value
1461 scaling will be enabled and use the given value, speci‐
1462 fied as a number, fraction or percentage. ie: 2, 3/2 or
1463 150%.
1464
1465 pair the scaling will be enabled and use a different value for
1466 the X and Y axis. ie: 3x2 or 3/2x4/3
1467
1468 desktop-size
1469 the scaling will be enabled and the server will render to
1470 the given size. ie: 1600x1200
1471
1472 --tray=yes|no Enable or disable the system tray. Not available on OSX
1473 since the dock icon is always shown.
1474
1475 --delay-tray
1476 Waits for the first window or notification to appear before
1477 showing the system tray. (posix only)
1478
1479 --tray-icon=FILENAME
1480 Specifies the icon shown in the dock/tray. By default it uses a
1481 simple default 'xpra' icon. (On Microsoft Windows, the icon
1482 must be in ico format.)
1483
1484 --enable-pings
1485 The client and server will exchange ping and echo packets which
1486 are used to gather latency statistics. Those statistics can be
1487 seen using the xpra info command.
1488
1489
1490
1491 Options for attach, stop, info, screenshot, version
1492 --ssh=CMD
1493 When you use an ssh: address to connect to a remote display,
1494 xpra runs ssh(1) to make the underlying connection. By default,
1495 it does this by running the command "ssh". If your ssh program
1496 is in an unusual location, has an unusual name, or you want to
1497 pass special options to change ssh's behavior, then you can use
1498 the --ssh switch to tell xpra how to run ssh.
1499
1500 For example, if you want to use arcfour encryption, then you
1501 should run
1502
1503 xpra attach --ssh="ssh -c arcfour" ssh://frodo/7
1504
1505 Note: Don't bother to enable ssh compression; this is redundant
1506 with xpra's own compression, and will just waste your CPU. See
1507 also xpra's --compress switch.
1508
1509 On MS Windows, where backslashes are used to separate path ele‐
1510 ments and where spaces are often used as part of paths, you need
1511 to add quotes around paths. (ie: ssh="C:\Program
1512 Files\Xpra\Plink.exe" -ssh -agent)
1513
1514
1515 --exit-ssh=yes|no
1516 Choose whether the SSH client process should be forcibly termi‐
1517 nated when xpra disconnects from the server. If you are using
1518 SSH connection sharing, you may want to avoid stopping the SSH
1519 master process instance spawned by xpra as it may be used by
1520 other SSH sessions. Note: the exit-ssh=no detaches the SSH
1521 process from the terminal which prevents the SSH process from
1522 interacting with the terminal input, this disables the keyboard
1523 interaction required for password input, host key verification,
1524 etc..
1525
1526 --remote-xpra=CMD
1527 When connecting to a remote server over ssh, xpra needs to be
1528 able to find and run the xpra executable on the remote host. If
1529 this executable is in a non-standard location, or requires spe‐
1530 cial environment variables to be set before it can run, then
1531 accomplishing this may be non-trivial. If running xpra attach
1532 ssh:something fails because it cannot find the remote xpra, then
1533 you can use this option to specify how to run xpra on the remote
1534 host.
1535
1536 That said, this option should not be needed in normal usage, as
1537 xpra tries quite hard to work around the above problems. If you
1538 find yourself needing it often, then that may indicate a bug
1539 that we would appreciate hearing about.
1540
1541
1542 SSL Options
1543 --ssl=on|auto|off|tcp|www
1544 Whether to enable SSL on TCP sockets and for what purpose. The
1545 TCP sockets will automatically be upgraded to SSL when SSL pack‐
1546 ets are received.
1547
1548 auto The server will try to guess what protocol to use for
1549 each new SSL connection: either xpra's native protocol or
1550 https / websocket (wss)
1551
1552 tcp The SSL sockets will only be used for xpra's native pro‐
1553 tocol
1554
1555 www The SSL sockets will only be used for https and websocket
1556 (wss)
1557 If SSL is enabled, then a ssl-cert is required. Authentication, if
1558 required, will use the ssl-auth module specified, and fallback to tcp-
1559 auth or auth unless the value none is specified.
1560
1561 The remaining options mirror the Python ssl module attributes. Please
1562 refer to that documentation and bear in mind that configuring SSL for
1563 security is not trivial, and definitely not just a matter of enabling
1564 SSL. See: https://docs.python.org/2/library/ssl.html Some options may
1565 not be available with older versions of Python.
1566
1567 Summary: --ssl-key=KEYFILE The key file to use.
1568
1569 --ssl-cert=ERTFILEORDIR
1570 Certificate file, required for server SSL support.
1571
1572 --ssl-protocol=PROTOCOLVERSION
1573 Specifies which version of the SSL protocol to use.
1574
1575 --ssl-ca-certs=CACERTSFILE
1576 The ca_certs file contains a set of concatenated 'certification
1577 authority' certificates. If a directory is specified, it should
1578 contain the certificates.
1579
1580 --ssl-ca-data=ERTDATA
1581 Certificate data.
1582
1583 --ssl-ciphers=CIPHERS
1584 Sets the available ciphers, it should be a string in the OpenSSL
1585 cipher list format.
1586
1587 --ssl-client-verify-mode=none|optional|required
1588 Whether to try to verify the client's certificates and how to
1589 behave if verification fails.
1590
1591 --ssl-server-verify-mode=none|optional|required
1592 Whether to try to verify the server's certificates and how to
1593 behave if verification fails.
1594
1595 --ssl-verify-flags=FLAGS
1596 The flags for certificate verification operations.
1597
1598 --ssl-check-hostname=yes|no
1599 Whether to match the peer cert's hostname.
1600
1601 --ssl-options=options
1602 Set of SSL options enabled on this context.
1603
1604
1605
1606 ENVIRONMENT
1607
1608 DISPLAY
1609 xpra start --start-child=... sets this variable in the environ‐
1610 ment of the child to point to the xpra display.
1611
1612 xpra attach, on the other hand, uses this variable to determine
1613 which display the remote applications should be shown on.
1614
1615 fIXPRA_PASSWORD may be used with xpra attach instead of the
1616 password-file option.
1617
1618
1620 xpra.conf stores default values for most options. There is a global
1621 configuration file in /etc or /usr/local/etc, and each user may over‐
1622 ride those defaults by creating the file .xpra/xpra.conf. You can also
1623 split the options into multiple files by placing them in a conf.d
1624 directory with the .conf extension. Depending on OS and version, xpra
1625 uses the directory ~/.xpra or /run/<uid>/xpra to store a number of
1626 files. (The examples below are given for the display :7.)
1627
1628 ~/.xpra/:7
1629 The unix domain socket that clients use to contact the xpra
1630 server, if the system configuration uses this directory.
1631
1632 ~/.xpra/:7.log
1633 When run in daemon mode (the default), the xpra server directs
1634 all output to this file. This includes all debugging output, if
1635 debugging is enabled.
1636
1637 ~/.xpra/run-xpra
1638 A shell script that, when run, starts up xpra with the correct
1639 python interpreter, PYTHONPATH, PATH, location of the main xpra
1640 script, etc. Automatically generated by xpra initenv, xpra
1641 start and used by xpra attach (see also the discussion of
1642 --remote-xpra).
1643
1645 Xpra has no test suite.
1646
1647 Xpra does not fully handle all aspects of the X protocol; for instance,
1648 fancy input features like pressure-sensitivity on tablets, some window
1649 manager hints, and probably other more obscure parts of the X protocol.
1650 It does, however, degrade gracefully, and patches for each feature
1651 would be gratefully accepted.
1652
1653 The xpra server allocates an over-large framebuffer when using Xvfb;
1654 this wastes memory. If the Xvfb does not support RandR this can also
1655 cause applications to misbehave (e.g. by letting menus go off-screen).
1656 This is not a problem when using Xdummy, see the --xvfb= switch for
1657 details. Conversely, if the framebuffer is ever insufficiently large,
1658 clients will misbehave in other ways (e.g., input events will be misdi‐
1659 rected).
1660
1662 Send any questions or bugs reports to http://xpra.org/trac/
1663
1665 screen(1), winswitch_applet(1)
1666
1667
1668
1669 XPRA(1)