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