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