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