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 docs
29 xpra html5
30 xpra upgrade [:DISPLAY] [...any options accepted by xpra start...]
31 xpra upgrade-desktop [:DISPLAY] [...any options accepted by xpra start-
32 desktop...]
33 xpra recover [:DISPLAY] [...any options accepted by xpra start...]
34
36 Xpra is a tool which allows you to run X programs — usually on a remote
37 host — and then direct their display to your local machine, disconnect
38 from these programs, and reconnect from the same or another machine,
39 all without losing any state. It differs from standard X forwarding in
40 that it allows disconnection and reconnection without disrupting the
41 forwarded application; it differs from VNC and similar remote display
42 technologies in that xpra can run rootless: i.e., applications for‐
43 warded by xpra appear on your desktop as normal windows managed by your
44 window manager, rather than being all "trapped in a box together".
45 Xpra also uses a custom protocol that is self-tuning and relatively la‐
46 tency-insensitive, and thus is usable over network connections that are
47 too slow or unreliable for standard X forwarding. Xpra can also be
48 used to shadow an existing X11 display, or in desktop mode where it be‐
49 haves more like VNC.
50 By default the Xpra server announces available sessions (username and
52 display number) via mDNS to the local network. Use mdns=no to disable
53 it.
54
56 Xpra supports many types of connection strings (some may require extra
57 packages to be installed):
58 :DISPLAY[,OPTIONS]
60 Local displays: this is the simplest form and is only valid for the
61 current local displays of the current user.
62 tcp://[[USERNAME][:PASSWORD]@]HOST:PORT[/DISPLAY][?OPTIONS]
64 TCP mode uses port numbers and not display numbers. If multiple dis‐
65 plays are available through a single TCP port (ie: using a proxy
66 server), then one can also specify the display number after the port
67 number.
68 ssl://[[USERNAME][:PASSWORD]@]HOST:PORT[/DISPLAY][?OPTIONS]
70 SSL adds a secure socket layer on top of the TCP mode.
71 vsock://[[USERNAME][:PASSWORD]@]HOST:PORT[/?OPTIONS]
73 Almost identical to the TCP mode, but using AF_VSOCK for transport.
74 ws://[[USERNAME][:PASSWORD]@]HOST:PORT/[DISPLAY][?OPTIONS]
76 Connect using websocket protocol.
77 wss://[[USERNAME][:PASSWORD]@]HOST:PORT/[DISPLAY][?OPTIONS]
79 Connect using secure websocket protocol. (websocket with SSL)
80 ssh://[[USERNAME][:PASSWORD]@]HOST[:SSH_PORT]/[DISPLAY][?OPTIONS]
82 Connect using secure shell. (SSH)
83 Further SSH options can be specified using the --ssh command line op‐
85 tion. The OPTIONS can be used to specify an ssh proxy:
86 ?proxy=ssh://[USERNAME[:PASSWORD]@]HOST[:SSH_PORT] xpra will then es‐
87 tablish an SSH connection to the specified "proxy" host, and from that
88 host xpra will set up an SSH connection to the xpra server.
89 For backwards compatibility, SSH mode also supports the syntax:
92 ssh:[USERNAME[:PASSWORD]@]HOST:DISPLAY but this form does not support
93 specifying the SSH port number. Older versions also used the form pro‐
94 tocol:host:port, but users are encouraged to move to a more standard
95 URI format using :// as separator.
96 The password need only be specified when the server authentication mod‐
98 ule requires it.
99 vnc://[[USERNAME][:PASSWORD]@]HOST[:VNC_PORT]/
101 Connect using ther RFB protocol. (aka VNC) This mode only works against
102 VNC servers or an xpra server in desktop or shadow mode.
103
105 xpra start :7
106 Start an xpra server using display number :7. Note: using DIS‐
107 PLAY=:7 xterm to start applications against a specific display is
108 not recommended. Always prefer using xpra's --start= command line
109 option instead. See this next example:
110 xpra start --start=firefox
112 Start an xpra server, choosing a display automatically and start
113 firefox on that virtual display. No window will appear until you
114 attach with xpra attach. The start child commands will inherit an
115 environment tailored for running under xpra.
116 xpra start ssh://bigbox/7 --start=xterm
118 Start an xpra server on bigbox with an xterm in it, and connect to
119 it.
120 xpra start-desktop --start=xfce4-session
122 Start an xfce session in a nested X11 server on an automatically
123 assigned display number.
124 xpra displays
126 Lists all the displays currently running on the system. This in‐
127 cludes interactive desktop sessions as well as any virtual display
128 (xvfb) whether or not they are being used by an xpra server. The
129 displays in DEAD state can be recovered using xpra recover.
130 xpra clean-displays
132 Terminate any displays left in DEAD state.
133 xpra clean-sockets
135 Delete any server sockets belonging to dead servers.
136 xpra list
138 Show a list of xpra servers you have running on the current host.
139 This will also run clean-sockets.
140 xpra list-sessions
142 Show a list of xpra servers, with extra information about each
143 session if it can be collected.
144 xpra list-windows
146 Show a list of xpra servers you have running on the current host,
147 including the session name and a list of windows. (only if the
148 session can be queried using xpra info)
149 xpra list-mdns
151 Show a list of xpra servers found via mDNS. (local network)
152 xpra docs
154 Open the documentation in a web browser.
155 xpra html5
157 Open the html5 client in a web browser.
158 xpra shell
160 Start an interactive debug shell.
161 xpra showconfig
163 Shows the configuration that would be used with other sub-com‐
164 mands, taking into account the command line arguments.
165 xpra showsetting [SETTING1..]
167 Shows the value of a specific configuration setting and which con‐
168 figuration directory set this value.
169 xpra attach :7
171 Attach to the xpra server that is using local display number :7.
172 Any apps running on that server will appear on your screen.
173 xpra attach ssh://foo@frodo/7
175 Use ssh to attach to the xpra server that is running on machine
176 frodo as user foo and using display :7. Any apps running on that
177 server will appear on your local screen.
178 xpra start :7 --start=screen
180 Start an xpra server and a screen(1) session. If any of the ap‐
181 plications inside screen attempt to use X, they will be directed
182 to the xpra server.
183
185 Understanding the basic idea of displays is critical to using xpra suc‐
186 cessfully.
187 The idea comes from standard X. If you have multiple X servers running
189 on the same host, then there has to be some way to distinguish them. X
190 does this by assigning each server a small, unique integer called (per‐
191 haps confusingly) its "display". In the common case of a desktop ma‐
192 chine that has only one X server running, that server uses display ":0"
193 (or sometimes you'll see ":0.0", which is effectively the same). When
194 an application starts under X, it needs to know how to find the right X
195 server to use; it does this by checking the environment variable $DIS‐
196 PLAY.
197 Xpra faces a similar problem — there may be multiple xpra servers run‐
199 ning on the same host, as well as multiple X servers. It solves this
200 problem by re-using X's solution — each xpra server has a display asso‐
201 ciated with it. This display functions as both an X display (for when
202 xpra is talking to X applications) and as an identifier by which xpra
203 clients (like xpra attach) can locate the xpra server.
204 You may omit the display number when using xpra start: a display will
206 be chosen for you automatically. The display number chosen will be
207 shown in the log output, you should also be able to see it with xpra
208 list. On Microsoft Windows and Mac OSX, the display number should be
209 omitted.
210 Otherwise, when starting an xpra server, you may want to specify the
212 name of the display to use. To do this, simply pick any number you
213 like and stick a colon in front of it. For instance :7, :12, and :3117
214 are all valid display names. Just keep in mind that:
215 • Every X or xpra server that is running on a single machine must
217 use a different display name. If you pick a number that is al‐
218 ready in use then xpra will not work.
219 • The first few numbers (0, 1, 2) are commonly used by real X
221 servers.
222 • Everyone who connects to a given machine using ssh(1) with X
224 forwarding enabled will also use a display number; ssh generally
225 picks numbers near ten (10, 11, 12, ...).
226 When specifying an xpra server to a client program like xpra attach,
228 xpra detach, xpra stop, xpra exit, xpra version, xpra info, xpra list
229 or xpra screenshot then you can use a display of the form :DISPLAY to
230 refer to a server on the local host, or one of the form
231 ssh://[USER@]HOST/DISPLAY to refer to a server on a remote host; xpra
232 will automatically connect to the remote host using ssh(1). Generally,
233 if you have only one xpra session running on a machine (which you can
234 verify by running xpra list on that machine), then you can omit the
235 number entirely; xpra attach alone will attach to the lone xpra server
236 on the current machine regardless of its number, xpra attach
237 ssh://frodo will similarly attach to the lone xpra session on a remote
238 machine.
239 Connecting using the display number assumes that the client and server
241 use the same configuration for socket directories, or at least that the
242 client can find at least one of the directories used by the unix domain
243 sockets (see bind, socket-dir and socket-dirs).
244 If the xpra server was given the --bind-tcp=[HOST]:PORT (or --bind-ssl,
246 --bind-ws, --bind-wss, --bind-vsock) option when started then you can
247 also connect to it using a display of the form tcp://HOST:PORT[/DIS‐
248 PLAY], ssl://HOST:PORT[/DISPLAY], ws://HOST:PORT[/DISPLAY],
249 wss://HOST:PORT[/DISPLAY] or vsock://HOST:PORT[/DISPLAY].
250
252 xpra start
253 This command starts a new xpra server, including any necessary setup.
254 (When starting a remote server with the ssh://HOST/DISPLAY syntax, the
255 new session will also be attached.)
256 xpra start-desktop
258 Starts a nested X11 server, all child commands will be started in the
259 nested X11 server.
260 xpra attach
262 This command attaches to a running xpra server, and forwards any appli‐
263 cations using that server to appear on your current screen.
264 xpra detach
266 Detaches the given xpra display.
267 xpra screenshot
269 Takes a screenshot and saves it to the filename specified. Note:
270 screenshots can only be taken when a client is attached.
271 xpra version
273 Queries the server version and prints it out. Note: older servers may
274 not support this feature.
275 xpra info
277 Queries the server for version, status and statistics.
278 xpra top
280 Shows the server's key health attributes.
281 xpra control
283 Modify the server at runtime by issuing commands. The list of commands
284 can be obtained by specifying "help" as command. Some of those com‐
285 mands may support a "help" mode themselves.
286 xpra initenv
288 This internal command creates the run-xpra script used with ssh connec‐
289 tions.
290 xpra stop
292 This command attaches to a running xpra server, and requests that it
293 terminates immediately. This generally causes any applications using
294 that server to terminate as well.
295 xpra exit
297 This command attaches to a running xpra server, and requests that it
298 terminates immediately. Unlike xpra stop, the Xvfb process and its X11
299 clients (if any) will be left running.
300 xpra showconfig
302 This commands shows the configuration which would be used given the ar‐
303 guments provided. You can also specify as extra arguments the specific
304 options that should be displayed, or use the special value all to dis‐
305 play all the options including the ones which are normally not dis‐
306 played because they are not relevant on the given system.
307 xpra list
309 This command finds all xpra servers that have been started by the cur‐
310 rent user on the current machine, and lists them.
311 xpra upgrade
313 This command starts a new xpra server, but instead of creating it from
314 scratch, it attaches to another existing server, tells it to exit, and
315 takes over managing the applications that it was managing before. As
316 the name suggests, the main use case is to replace a server running
317 against an older version of xpra with a newer version, without having
318 to restart your session. Any currently-running xpra attach command
319 will exit and need to be restarted.
320 xpra upgrade-desktop
322 Same as upgrade but for servers started using start-desktop. It is
323 possible to upgrade seamless server into a desktop server and vice
324 versa.
325 xpra recover
327 Similar to upgrade and upgrade-desktop: but without needing to specify
328 if the server to recover is a seamless server or a desktop server. Un‐
329 like the upgrade subcommands, recover can also detect which displays
330 need recovering. That is, displays which were previously used by an
331 xpra server but this server has gone missing.
332 xpra shadow
334 This command shadows an existing display and is supported on X11, MacOS
335 and MS Windows platforms. (this is not supported on Wayland yet)
336 If there is only one X11 display active and its number is below 10, it
338 can be auto-detected and the display may be omitted.
339 Note that this mode of operation uses screenscraping which is not very
341 efficient. Video encoders partially mitigate this drawback.
342 By default, shadow mode will expose all the monitors connected as indi‐
344 vidual windows. But it is also possible to only shadow a specific re‐
345 gion or monitor, or to group all monitors as a single window by speci‐
346 fying display options. Here are some examples:
347 To expose all monitors connected to display :1 as a single window,
349 use the multi-window option:
350 xpra shadow :1,multi-window=no
351 To shadow a specific output using its name (ie: DP-1):
353 xpra shadow :1,DP-1
354 or more explicitly:
355 xpra shadow :1,plug=DP-1
356 To expose a rectangular area of size 1920x1080 as a single window, use:
358 xpra shadow :1,1920x1080
359 You may also want to specify the position of this rectangle (ie:
360 1280x0):
361 xpra shadow :1,1920x1080@1280x0
362 or using the more explicit syntax:
363 xpra shadow :1,geometry=1920x1080@1280x0
364 Multiple areas can be specified using / as separator, each one
365 will be exposed as a separate window:
366 xpra shadow :1,1920x1080@1280x0/1280x600@0x400
367 xpra proxy
370 This command allows a single server to proxy connections for multiple
371 others, potentially serving as a load balancing or authentication entry
372 point for many sessions. The proxy server will spawn a new process for
373 each proxy connection, this proxy process will create an unauthenti‐
374 cated new unix domain socket which can be used with the subcommands
375 info, version and stop.
376 Important Note
379 Some platforms and package managers may choose to only build the client
380 and not the server. In this case, only the attach subcommand will be
381 available.
382
385 General options
386 --version
387 Displays xpra's version number.
388 -h, --help
390 Displays a summary of command line usage.
391 -d FILTER1,FILTER2,..., --debug=FILTER1,FILTER2,...
393 Enable debug logging. The special value all enables all debug‐
394 ging. To get the full list of logging categories, run xpra -d
395 help. To target loggers that use more than one logging category
396 (as some categories can be quite broad), join them with a '+'.
397 For example, to enable logging for server and keyboard, use
398 --debug server+keyboard. You can also exclude a category with
399 the '-' prefix. For example, to enable shadow debugging but not
400 clipboard, use: --debug shadow,-clipboard.
401 --mmap=yes|no|ABSOLUTEFILENAME|DIRECTORY
403 Enable or disable memory mapped pixel data transfer. By default
404 it is normally enabled automatically if the server and the
405 client reside on the same filesystem namespace. This method of
406 data transfer offers much lower overheads and reduces both CPU
407 consumption and local network traffic. When attaching, you can
408 also specify an absolute path where the mmap file will be cre‐
409 ated. When used on the server, one can specify the exact file‐
410 name that the client will create, or just the directory where
411 the file will be created so that multiple clients may connect
412 and use mmap concurrently.
413 --mmap-group=GROUP
415 Sets the mmap file's gid to the group specified, and sets the
416 permissions to 660. This is necessary to share the mmap file
417 across user accounts. You can also use the special GROUP val‐
418 ues:
419 no Disable the functionality, the mmap file will use the de‐
421 fault file permissions and default group ownership.
422 SOCKET The group used will be the same one as found on the unix
424 domain socket file the client connects to. Obviously,
425 this can only work when connecting to unix domain sock‐
426 ets.
427 auto Will use the 'xpra' group if the user is a member, other‐
429 wise it will fallback to the same behaviour as SOCKET.
430 --windows=yes|no
433 Enable or disable the forwarding of windows. This is usually the
434 primary use for xpra and should be enabled.
435 --min-size=WIDTHxHEIGHT
437 Sets the minimum size for all decorated windows.
438 --max-size=WIDTHxHEIGHT
440 Sets the maximum size for all windows.
441 --readonly=yes|no
443 Read only mode ignores all keyboard and mouse activity.
444 --clipboard=yes|no|clipboard-type
447 Enable or disable clipboard synchronization. If disabled on the
448 server, no clients will be able to use clipboard synchronization
449 at all. If turned off on the client, only this particular con‐
450 nection will ignore clipboard data from the server. This can
451 also be used to specify a different clipboard implementation.
452 The clipboard types available will vary from platform to plat‐
453 form and also depend on build time environment and options so
454 this is best left on auto. Other clipboard types available may
455 include:
456 translated
458 Clipboard which can translate from one type of selection
459 to another
460 GDK The most complete clipboard implementation, includes full
462 X11 support
463 default
465 Fallback clipboard, with limited X11 support
466 OSX OSX specific clipboard
468 --clipboard-direction=to-server|to-client|both|disabled
471 Choose the direction of the clipboard synchronization.
472 --pulseaudio=yes|no
474 Enable or disable the starting of a pulseaudio server with the
475 session.
476 --pulseaudio-command=SERVER-START-COMMAND
478 Specifies the pulseaudio command to use to start the pulseaudio
479 server, unless disabled with pulseaudio=no.
480 --session-name=VALUE
482 Sets the name of this session. This value may be used in notifi‐
483 cations, utilities, tray menu, etc. Setting this value on the
484 server provides a default value which may be overridden on the
485 client.
486 --encoding=ENCODING
488 Sets the preferred encoding to use. To see the list of encod‐
489 ings available, use --encoding=help. This can be used to select
490 grayscale or 8-bit modes like png/P. On local connections or
491 with extremelly fast network links, plain rgb is also a viable
492 option. For everything else, the default value auto will select
493 the best encoding automatically and you should use the min-speed
494 and min-quality options instead for tuning.
495 --encodings=ENCODING
497 This specifies the image encodings enabled. This is the most
498 misused command line option and should be left alone. The
499 server engine needs to have multiple encodings available to work
500 effectively.
501 --video-scaling=on|off|SCALING
504 How much automatic video downscaling should be used, from 1
505 (rarely) to 100 (aggressively), 0 to disable. Video scaling is
506 normally used with video regions or very large windows (espe‐
507 cially full screen windows) to try to maintain a decent framer‐
508 ate. Video downscaling negatively affects visual quality and
509 will cause automatic refreshes (if enabled), it is most useful
510 on video content where it saves a considerable amount of band‐
511 width.
512 --socket-dir=DIR
515 Location where to write and look for the Xpra socket files. The
516 default location varies from platform to platform ("~/.xpra" and
517 "$XDG_RUNTIME_DIR/xpra" on most Posix systems). If unspecified,
518 the first value from socket-dirs will be used. It may also be
519 specified using the XPRA_SOCKET_DIR environment variable.
520 When using the socket-dir option, it is generally necessary to
522 specify socket-dir or socket-dirs on all following commands, for
523 xpra to work with the open sessions.
524 By specifying a shared directory this can be coupled with the
526 mmap-group and socket-permissions option to connect Xpra ses‐
527 sions across user accounts with shared memory acceleration.
528 --socket-dirs=DIR
531 Specifies the directories where to look for existing sockets if
532 a specific one was not set using socket-dir. You may specify
533 each directory using a new --socket-dirs command line argument,
534 or joined together by the path separator (: on Posix). The
535 paths will be expanded. (ie: --socket-dirs=~/.xpra:/tmp)
536 --file-transfer=on|off
539 Enable file transfers.
540 --open-files=on|off
542 This option may be used to allow the remote end to automatically
543 open files after they have been uploaded. This may be a secu‐
544 rity risk if you are using xpra to constrain what the clients
545 can execute on the server.
546 --forward-xdg-open=on|off|auto
549 Intercept execution of xdg-open and forward the request to the
550 client.
551 --open-command=COMMAND
554 The command to use for opening files and URLs.
555 --bandwidth-limit=BITSPERSECOND
558 Restrict bandwidth usage to below the limit given. The client's
559 value cannot raise the limit of the server. The value may be
560 specified using standard units, ie: 1Mbps or 500K. In auto
561 mode, the client will set the bandwidth limit value to 80% of
562 the maximum speed of the network interface it is using to con‐
563 nect to the server.
564 --splash=yes|no|auto Show a splash screen during client or
566 server startup. With the default value of auto, the splash
567 screen is only shown if there is a GUI available - ie: no at‐
568 tempt will be made to show the splash screen when xpra is
569 launched from an SSH session.
570 Options for start, start-desktop, upgrade, proxy and shadow
574 --daemon=yes|no
575 By default, the xpra server puts itself into the background,
576 i.e. 'daemonizes', and redirects its output to a log file. This
577 can be used to prevent that behavior (useful mostly for debug‐
578 ging).
579 --resize-display=yes|no|WIDTHxHEIGHT
582 Resize the virtual display to match the resolution of the client
583 currently connected. This only applies to the start and start-
584 desktop subcommands. If a resolution is given, this will be the
585 initial resolution of the display and the display will be resiz‐
586 able. A small set of pre-defined aliases can also be used:
587 QVGA, VGA, SVGA, XGA, 1080p, FHD, 4K.
588 --fake-xinerama=PATH|auto|no
591 Specify the path to the libfakeXinerama.so library which will be
592 injected into all the child processes the server starts using
593 LD_PRELOAD. This can also be disabled or set to auto: the
594 server will then try to locate the library itself. This only
595 applies to the start subcommand.
596 --chdir=DIR
599 Change to this directory after daemonizing.
600 --uid=UID and --gid=GID
603 When launching the server as root, these options can be used to
604 drop privileges to the given UID / GID.
605 --pidfile=FILENAME
608 Writes the server process ID to this file on startup. If the
609 file has not been replaced, it will be deleted when the server
610 exits.
611 --challenge-handlers=MODULE:options
614 Configures which challenge handlers are used by the client and
615 in which order. This option may be repeated to specify multiple
616 handlers, which can be useful if the server sends more than one
617 authentication challenge. The default value is: all which cor‐
618 responds to: uri,file,env,kerberos,gss,u2f,prompt.
619 uri Use the password specified on the connection string, if
621 any.
622 file The filename used to store the password can be specified
624 using the filename option. If this option is not speci‐
625 fied, it will fallback to using the password filename
626 specified with the password-file switch.
627 env Use the password specified using the environment variable
629 specified using the name option, which defaults to
630 XPRA_PASSWORD if unspecified.
631 kerberos
633 Requests a kerberos token for the service specified.
634 gss Requests a gss token for the service specified.
636 u2f Requests a token from a U2F device.
638 prompt Prompt the user for the value. Terminal clients prompt
640 using text input, GUI clients use a dialog.
641 --min-port=PORT
643 The minimum port number allowed when creating TCP sockets. You
644 can use a lower value to allow unprivileged users to bind to
645 privileged ports when starting sessions via the system wide
646 proxy server. The default value is 1024 which is the standard
647 value for privileged ports.
648 --mdns=yes|no
650 Enable or disable the publication of new sessions via mDNS.
651 --dbus-launch=COMMAND|no
653 Start the session within a dbus-launch context, you can specify
654 the dbus launch command to use, or turn it off completely. Some
655 features may not be available without a dbus context.
656 --dbus-proxy=yes|no
658 Allows the client to forward dbus calls to the server.
659 --dbus-control=yes|no
661 Start a dbus server which can be used to interact with the
662 server process.
663 Options for start, start-desktop, upgrade and listen:
667 In previous versions, the authentication for each connection type was
668 configured using a separate command line option which would apply to
669 all connections of the same type. ie: tcp-auth for bind-tcp. Although
670 this is still supported as a fallback, the recommended way is to spec‐
671 ify authentication options using bind properties. ie: bind-
672 tcp=0.0.0.0:14500,auth=file:filename=password.txt. The properties can
673 also define extra socket configuration options.
674 --bind=BIND_LOCATION[,PROPERTIES] Create a local Unix domain socket (on
676 Unix) or named-pipe (on MS Windows) for each bind option specified.
677 This option can be specified multiple times to specify multiple socket
679 locations. These sockets support local connections with the :7-style
680 display address, and remote connections with the ssh://frodo/7-style
681 display address.
682 Local sockets may also process HTTP / Websocket connections if the html
684 switch is enabled.
685 The location can take the form:
687 none do not create a socket
689 auto backwards compatible default which uses the current
691 socket-dir
692 DIRECTORY/
694 create a socket in the directory specified, if the direc‐
695 tory does not exist then it will be created - you should
696 include the trailing slash to prevent the confusion with
697 the PATH form:
698 PATH create the socket using the path specified
700 --bind-tcp=[HOST]:PORT[,PROPERTIES]
702 Create a TCP socket for each --bind-tcp option specified. If
703 the host portion is omitted, then 127.0.0.1 (localhost) will be
704 used. If you wish to accept connections on all interfaces, pass
705 0.0.0.0 for the host portion.
706 Using this switch without setting the auth option is not recom‐
708 mended, and is a major security risk (especially when passing
709 0.0.0.0)! Anyone at all may connect to this port and access
710 your session.
711 TCP sockets may also process HTTP / Websocket connections if the
713 html switch is enabled. TCP sockets may also be upgraded to SSL
714 sockets if the ssl switch is enabled.
715 --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). Depre‐
860 cated, use per-socket authentication options.
861 --ws-auth=MODULE
863 Just like the auth switch, except this one only applies to ws
864 sockets: sockets defined using the bind-ws switch, or TCP sock‐
865 ets upgraded to websockets. (if the html option is enabled).
866 Deprecated, use per-socket authentication options.
867 --wss-auth=MODULE
869 Just like the auth switch, except this one only applies to wss
870 sockets: sockets defined using the bind-wss switch, ws sockets
871 upgraded to SSL (if the ssl option is enabled) or TCP sockets
872 upgraded to SSL and then to wss. (if both the ssl and html op‐
873 tions are enabled). Deprecated, use per-socket authentication
874 options.
875 --ssl-auth=MODULE
877 Just like the auth switch, except this one only applies to SSL
878 sockets: sockets defined using the bind-ssl switch, or TCP sock‐
879 ets upgraded by ssl=auto or ssl=on. Deprecated, use per-socket
880 authentication options.
881 --rfb-auth=MODULE
883 Authentication module to use for the bind-rfb sockets. Depre‐
884 cated, use per-socket authentication options.
885 --vsock-auth=MODULE
887 Just like the auth switch, except this one only applies to VSOCK
888 sockets (sockets defined using the bind-vsock switch). Depre‐
889 cated, use per-socket authentication options.
890 Options for start, start-desktop, upgrade
894 --exec-wrapper=CMD
895 A wrapper command which is prepended to all start commands.
896 Typically, this is used for starting all sub-commands via Virtu‐
897 alGL.
898 --start=CMD
900 After starting the server, runs the command CMD using the de‐
901 fault shell. The command is run with its $DISPLAY set to point
902 to the newly-started server. This option may be given multiple
903 times to start multiple commands.
904 --start-child=CMD
906 Identical to --start, except that the commands are taken into
907 account by --exit-with-children.
908 --start-after-connect=CMD
910 Wait for the first client to connect before starting the com‐
911 mand.
912 --start-child-after-connect=CMD
914 Wait for the first client to connect before starting the child
915 command. See start-child.
916 --start-on-connect=CMD
918 Execute this command every time a client connects.
919 --start-child-on-connect=CMD
921 Execute this child command every time a client connects. See
922 start-child.
923 --start-on-last-client-exit=CMD
925 Execute this command every time a client disconnects and there
926 are no other clients left.
927 --start-child-on-last-client-exit=CMD
929 Execute this child command every time a client disconnects and
930 there are no other clients left. See start-child.
931 --terminate-children=yes|no
933 On server stop, terminate all the child commands that have been
934 started by the server. This does not affect server exit. Most
935 child commands are tied to the display so they are normally
936 forced to shutdown anyway, but this gives them more time to
937 cleanup properly and can be used to stop background commands
938 that aren't tied to a display.
939 --exit-with-children=yes|no
941 This option may only be used if --start-child is also given. If
942 it is given, then the xpra server will monitor the status of the
943 children started by --start-child, and will automatically termi‐
944 nate itself when the last of them has exited.
945 --exit-with-windows=yes|no
947 The server will terminate automatically when there are no more
948 windows or system trays being forwarded. This option is only
949 relevant for seamless servers.
950 --exit-with-client=yes|no
952 The server will terminate when the last client disconnects.
953 --env=KEY=VALUE
955 Extra environment variables which will only affect commands
956 started using --start or --start-child.
957 --start-new-commands=yes|no
959 Allow clients to ask the server to execute new commands. (this
960 can also be used via the control channel)
961 --start-via-proxy=yes|no|auto
963 If enabled, the start and start-desktop subcommands will be del‐
964 egated to the system wide proxy server instance. With auto
965 mode, this delegation will only occur if the system wide proxy
966 server is found.
967 --systemd-run=yes|no|auto
969 Wrap server start commands with systemd-run.
970 --systemd-run-args=ARGS
972 Command line arguments passed to systemd-run.
973 --use-display=yes|no|auto
975 Use an existing display rather than starting one with xvfb. You
976 are responsible for starting the display yourself. This can
977 also be used to rescue an existing display whose xpra server in‐
978 stance crashed or for running xpra against an accelerated X11
979 server. With auto, xpra will use the existing display if it is
980 found.
981 --displayfd=FD
983 The xpra server will write the display number back on this file
984 descriptor as a newline-terminated string. This is most useful
985 when the display number is not specified with the xpra start or
986 start-desktop subcommands.
987 --xvfb=CMD
989 When starting a seamless server, xpra starts a virtual X server
990 to run the clients on. If your Xvfb is installed in a funny lo‐
991 cation, or you want to use some other virtual X server, then
992 this switch allows you to specify how to run your preferred X
993 server executable. The default value used depends on your plat‐
994 form. The recommended command to use here is Xorg with the
995 dummy driver, also known as Xdummy. See:
996 https://github.com/Xpra-org/xpra/blob/master/docs/Us‐
997 age/Xdummy.md Some distributions are unable to configure it
998 properly and will use Xvfb instead.
999 --sync-xvfb=DELAY
1001 The windows are normally only displayed on the client(s), they
1002 are not painted on the virtual display. Some applications like
1003 screen recorders may want to capture the window contents, you
1004 can use this option to enable painting with a configurable delay
1005 (in milliseconds). Warning: this extra painting is expensive
1006 and quite slow, which is why it is not enabled by default.
1007 --attach=yes|no|auto
1009 Once the server has started, immediately connect a client to it.
1010 With the value auto, a client is started for remote servers
1011 only. (servers specified via a network URI) If a display is
1012 specified and a server is already running, xpra will not try to
1013 start a new one and it will just attach to it.
1014 Options for start, start-desktop, upgrade, shadow
1017 --html=on|off|auto|webrootpath
1020 Respond to HTTP requests on the TCP port(s) and local sockets.
1021 This requires at least one TCP or local socket to be configured
1022 using the matching bind option. The auto mode will enable sup‐
1023 port if possible. By default the server will provide access to
1024 the HTML5 client. You can also specify your own web root path
1025 as argument.
1026 --http-scripts=off|all|SCRIPTS
1028 Enable the builtin web server scripts that expose the server
1029 status, current active sessions and displays, the list of appli‐
1030 cations and desktop sessions installed. This can be used by the
1031 client's user interface.
1032 --rfb-upgrade=DELAY
1035 Allows RFB clients (ie: VNC) to connect to a plain TCP socket.
1036 If no data is received after DELAY seconds, the server will send
1037 a RFB handshake. This option is only applicable to servers
1038 started in start-desktop or shadow modes.
1039 --video-encoders=ENCODERS
1042 Specifies the video encoders to try to load. By default, all of
1043 them are loaded, but one may want to specify a more restrictive
1044 list of encoders. Use the special value 'help' to get a list of
1045 options. Use the value 'none' to not load any video encoders.
1046 --csc-modules=MODULES
1049 Specifies the colourspace conversion modules to try to load. By
1050 default, all of them are loaded, but one may want to specify a
1051 more restrictive list of modules. Use the special value 'help'
1052 to get a list of options. Use the value 'none' to not load any
1053 colourspace conversion modules.
1054 --socket-permissions=ACCESS-MODE
1057 Specifies the file permissions on the server's unix domain sock‐
1058 ets. Defaults to 600. This is ignored when mmap-group is en‐
1059 abled.
1060 Options for start, start-desktop, upgrade and attach
1064 --encryption=CIPHER
1065 Specifies the cipher to use for securing the connection from
1066 prying eyes. This option requires the use of the --encryption-
1067 keyfile option. The only ciphers supported at present are:
1068 AES For servers, this allows the client to choose any of the
1070 modes it wants to use. For clients, this is an alias for
1071 AES-CBC and using a more specific mode should be pre‐
1072 ferred.
1073 AES-CBC
1075 AES in cipher block chaining mode
1076 AES-GCM
1078 AES in galois/counter mode
1079 AES-CFB
1081 AES in cipher feedback mode
1082 AES-CTR
1084 AES in counter mode
1085 If the client requests encryption it will be used by both the client
1087 and server for all communication after the initial password verifica‐
1088 tion, but only if the server supports this feature too. Note: this
1089 feature has not been extensively reviewed and as it is it should not be
1090 considered safe from determined attackers.
1091 --tcp-encryption=CIPHER
1093 Just like the encryption switch, except this one only applies to
1094 TCP sockets (sockets defined using the bind-tcp switch).
1095 --encryption-keyfile=FILENAME
1097 Specifies the key to use with the encryption cipher specified
1098 with --encryption. The client and server must use the same key‐
1099 file contents.
1100 --tcp-encryption-keyfile=FILENAME
1102 Just like the encryption-keyfile switch, except this one only
1103 applies to TCP sockets (sockets defined using the bind-tcp
1104 switch).
1105 --idle-timeout=IDLETIMEOUT
1107 The connection will be terminated if there is no user activity
1108 (mouse clicks or key presses) for the given amount of time (in
1109 seconds). Use the value 0 to disable this timeout.
1110 --server-idle-timeout=IDLETIMEOUT
1112 The server will exit if there are no active connections for the
1113 given amount of time (in seconds). Use the value 0 to disable
1114 this timeout.
1115 --clipboard-filter-file=FILENAME
1117 Name of a file containing regular expressions, any clipboard
1118 data that matches one of these regular expressions will be
1119 dropped. Note: at present this only applies to copying from the
1120 machine where this option is used, not to it.
1121 --dpi=VALUE
1123 The 'dots per inch' value that client applications should try to
1124 honour. This numeric value should be in the range 10 to 500 to
1125 be useful. Many applications will only read this value when
1126 starting up, so connecting to an existing session started with a
1127 different DPI value may not have the desired effect.
1128 --pixel-depth=VALUE
1130 When starting a server, this switch controls the bits per pixel
1131 of the virtual framebuffer. Possible values: 0 (auto), 16, 24,
1132 30. When starting a client, this switch controls the picture
1133 rendering with the opengl backend: values higher than 24 will
1134 enable deep color, the value 24 enables regular true color ren‐
1135 dering. Use the value 0 to let the client decide if the render‐
1136 ing will benefit from using deep color. (this is only supported
1137 on some Posix clients) Other values should not be used.
1138 --cursors=yes|no
1140 Enable or disable forwarding of custom application mouse cur‐
1141 sors. Client applications may change the mouse cursor at any
1142 time, which will cause the new cursor's pixels to be sent to the
1143 client each time. This disables the feature.
1144 --notifications=yes|no
1146 Enable or disable forwarding of system notifications. System
1147 notifications require the xpra server to have its own instance
1148 of a dbus daemon, if it is missing a warning will be printed on
1149 startup. This switch disables the feature entirely, and avoids
1150 the warning.
1151 --input-method=METHOD
1153 Specify which input method to configure. This sets a number of
1154 environment variables which should be honoured by applications
1155 started with the start-child option.
1156 The following METHODs are currently supported:
1158 none Disable input methods completely and prevent it from in‐
1160 terfering with keyboard input. This is the default.
1161 keep Keeps the environment unchanged. You are responsible for
1163 ensuring it is correct.
1164 xim Enables the X Input Method.
1166 IBus Enables the Intelligent Input Bus.
1168 SCIM Enables the Smart Common Input Method.
1170 uim Enables the Universal Input Method.
1172 Any other value will also be set up, but will trigger a warning.
1174 --xsettings=auto|yes|no
1177 Enable or disable xsettings synchronization. Xsettings are only
1178 forwarded from posix clients connecting to real posix servers
1179 (not shadows). In 'auto' mode, only seamless servers enable
1180 xsettings synchronization.
1181 --system-tray=yes|no
1183 Enable or disable forwarding of system tray icons. This feature
1184 requires client support and may not be available on all plat‐
1185 forms.
1186 --bell=yes|no
1188 Enable or disable forwarding of the system bell.
1189 --webcam=yes|no
1191 Enable or disable webcam forwarding.
1192 --mousewheel=on|off|invert|invert-x|invert-y|invert-z
1194 Mouse wheel handling: can be used to disable mouse wheel for‐
1195 warding using the value no, or to invert some or all axes: in‐
1196 vert-all, invert-x, invert-y, invert-z.
1197 --remote-logging=both|all|send|receive|no
1200 Remote logging is always initiated by the client, but the server
1201 can restrict which direction log messages are allowed to flow.
1202 both The log output is both forwarded and sent locally (to
1204 stdout, stderr or a log file).
1205 allow Used by the server to allow both send and receive, when
1207 sending the log output it will no longer be recorded lo‐
1208 cally.
1209 send Used by the client to send its log output to the server.
1211 Used by the server to allow clients to request log for‐
1212 warding.
1213 receive
1215 Used by the client to request that the server sends its
1216 log output to the client. Used by the server to allow
1217 clients to forward their logging.
1218 no Remote logging is disabled.
1220 --av-sync=yes|no
1222 Enable or disable audio-video synchronization. The video data
1223 will be delayed so that it is displayed in sync with the audio.
1224 Note: this only applies to video regions, either auto-detected
1225 via the builtin heuristics or specified using the dbus inter‐
1226 face.
1227 Options for attach
1231 --modal-windows=yes|no
1232 Honour modal windows. This may have undesirable side effects
1233 when multiple applications are forwarded through the same xpra
1234 server: modal windows will be made modal for all the applica‐
1235 tions forwarded by xpra rather than just the one application
1236 which owns that window.
1237 --headerbar=auto|no|force
1239 Replaces the window's standard title bar with a custom one which
1240 is used to give access to xpra specific window controls. This
1241 feature can have side effects and it is incompatible with OpenGL
1242 acceleration on MS Windows.
1243 --password-file=FILENAME
1245 Supply the password to be used for connecting to a server that
1246 uses authentication. Deprecated, use per-socket authentication
1247 options.
1248 --opengl=(yes|no|auto)[:backend]
1250 Use OpenGL accelerated rendering on the client. The default is
1251 to detect if the graphics card and drivers are supported (auto
1252 mode), but one can also disable OpenGL (no) or force it enabled
1253 (yes). On some platforms, it is also possible to specify which
1254 backends should be used, only gtk and native are currently sup‐
1255 ported and only on X11 platforms. ie: opengl=yes:native, or
1256 opengl=auto:gtk,native.
1257 --webcam=yes|no|/dev/deviceXXX|DEVICEID
1259 Enable or disable webcam forwarding. The webcam device to use
1260 can also be specified.
1261 -zLEVEL, --compress=LEVEL
1264 Select the level of compression xpra will use when transmitting
1265 data over the network. With the lz4 and lzo compressors, there
1266 are only two possible values: 0 (meaning no compression) and 1
1267 (compression enabled). The zlib compressor supports values be‐
1268 tween 0 (meaning no compression) and 9, inclusive. It should
1269 only be used when lz4 and lzo are not available.
1270 This compression is not used on pixel data (except when using
1272 the rgb encoding).
1273 --quality=VALUE
1275 This option sets a fixed image compression quality for lossy en‐
1276 codings (jpeg, webp, h264/h265 and vp8/vp9). First, one of
1277 those lossy encodings must be enabled with --encoding or when
1278 using the default auto mode. Values range from 1 (lowest qual‐
1279 ity, high compression - generally unusable) to 100 (highest
1280 quality, low compression). Specify a value of zero to let the
1281 system tune the quality dynamically to achieve the best band‐
1282 width usage possible. It is usually best not to use this option
1283 and use min-quality instead.
1284 --min-quality=MIN-QUALITY
1286 This option sets the minimum encoding quality allowed when the
1287 quality option is set to automatic mode. See quality above.
1288 --speed=SPEED
1290 This option sets the encoding speed, from 1 (slowest) to 100
1291 (fastest). Slower compresses better and will use less band‐
1292 width, faster will give better latency as long as there is suf‐
1293 ficient bandwidth. The system normally uses a variable speed,
1294 this option forces a fixed speed setting to be used instead. It
1295 is usually best not to use this option and use min-speed in‐
1296 stead.
1297 --min-speed=MIN-SPEED
1299 This option sets the minimum encoding speed allowed when the
1300 speed option is set to automatic mode. See speed above.
1301 --auto-refresh-delay=DELAY
1303 This option sets a delay after which the windows are automati‐
1304 cally refreshed using a lossless frame if their contents had
1305 been updated using a lossy encoding previously. The delay is a
1306 floating-point number and is in seconds. This option is enabled
1307 by default with a delay of 0.25 seconds. This option is only
1308 relevant when using a lossy encoding.
1309 --shortcut-modifiers=MODIFIERS
1311 Defines the default shortcut modifiers required by the key-
1312 shortcuts, these modifiers can then be referred to as #. The
1313 default value is 'auto' which evaluates to Meta+Shift on most
1314 platforms.
1315 --key-shortcut=KEY:ACTION
1317 Can be specified multiple times to add multiple key shortcuts.
1318 These keys will be caught by the client and trigger the action
1319 specified and the key presses will not be passed on to the
1320 server.
1321 The KEY specification may include keyboard modifiers in the form
1323 [modifier+]*key, for example: Shift+F10 or Shift+Control+B. You
1324 can refer to the shorcut-modifers option value using #, ie:
1325 #+F1.
1326 Shortcuts defined on the command line are added to the builtin
1328 default shortcuts. To clear the list of shortcuts, use key-
1329 shortcut=clear and define your shortcuts after this one.
1330 Some of the actions may allow arguments (ie: the log action
1332 does), in which case they are specified in the usual programming
1333 style syntax: ACTION(ARG1, ARG2, etc)
1334 String arguments must be quoted (both single and double quotes
1335 are supported) and numeric arguments must not be quoted. Beware
1336 the the parenthesis and quotes must usually be escaped when used
1337 from a shell command line. Example: --key-short‐
1338 cut=Meta+Shift+F7:log\(\'hello\'\)
1339 The following ACTIONs are currently defined:
1341 quit Disconnect the xpra client.
1343 log("MESSAGE")
1345 Sends MESSAGE to the log.
1346 show_session_info[("TabName")]
1348 Shows the session information window. The optional Tab‐
1349 Name allows the information tab shown to be selected. Use
1350 the value help to get the list of options.
1351 show_menu
1353 Shows the menu normally found in the system tray.
1354 show_start_new_command
1356 Shows the start new command dialog.
1357 show_shortcuts
1359 Shows the list of shortcuts.
1360 show_docs
1362 Shows the documentation in a browser window.
1363 magic_key
1365 Placeholder which can be used by some client toolkits.
1366 void Does not do anything, and can therefore be used to pre‐
1368 vent certain key combinations from ever being sent to the
1369 server.
1370 pass Does not do anything. However, unlike void the key event
1372 is forwarded to the server.
1373 - Removes an existing key shortcut if one exists.
1375 refresh_window
1377 Force the currently focused window to be refreshed.
1378 refresh_all_windows
1380 Force all windows to be refreshed.
1381 toggle_keyboard_grab
1383 The keyboard will be grabbed / ungrabbed by the current
1384 window.
1385 toggle_pointer_grab
1387 The pointer will be grabbed and confined to the current
1388 window.
1389 toggle_fullscreen
1391 Make the current window fullscreen / unfullscreen.
1392 toggle_debug
1394 Turn debugging on or off.
1395 scaleup
1397 Increase the current value of desktop-scaling.
1398 scaledown
1400 Decrease the current value of desktop-scaling.
1401 scalereset
1403 Reset the desktop-scaling to its original value.
1404 scalingoff
1406 Turn off desktop-scaling.
1407 increase_quality
1409 Increase the min-quality or quality setting (whichever
1410 one is currently in use).
1411 decrease_quality
1413 Decrease the min-quality or quality setting (whichever
1414 one is currently in use).
1415 increase_speed
1417 Increase the min-speed or speed setting (whichever one is
1418 currently in use).
1419 decrease_speed
1421 Decrease the min-speed or speed setting (whichever one is
1422 currently in use).
1423 --sharing=yes|no|auto
1425 Sharing allows more than one client to connect to the same ses‐
1426 sion. This must be enabled on both the server and all co-oper‐
1427 ating clients to function. When used server-side, the default
1428 value auto allows the clients to decide if they are willing to
1429 share the session. When used client-side, the default value
1430 auto evaluates to no. To allow sharing to work with unix domain
1431 sockets (either using local connections or via ssh), you should
1432 create at least one socket in a group accessible directory. On
1433 Posix with a default configuration, being a member of the xpra
1434 group should be enough to create a socket in /run/xpra. You must
1435 also ensure that the permissions of this socket file allow group
1436 access, see socket-permissions.
1437 --lock=yes|no|auto
1439 Locking allows a client to refuse to hand over the session to a
1440 new client. The session may still be shared with multiple
1441 clients (see the sharing option), but otherwise the server will
1442 reject new clients. When used server-side, the default value
1443 auto allows the clients to decide if they want to lock the ses‐
1444 sion. When used client-side, the default value auto evaluates
1445 to no.
1446 --keyboard-sync=yes|no
1448 Normally the key presses and key release events are sent to the
1449 server as they occur so that the server can maintain a consis‐
1450 tent keyboard state. Disabling synchronization can prevent keys
1451 from repeating unexpectedly on high latency links but it may
1452 also disrupt applications which access the keyboard directly
1453 (games, etc.).
1454 --keyboard-raw=yes|no
1456 Tells the server to process all keyboard input untranslated.
1457 Both the client and the server must be using the same type of
1458 keyboard interface. (ie: both using X11)
1459 --keyboard-layout=LAYOUTSTRING
1461 The keyboard layout is normally detected automatically. This
1462 option overrides it.
1463 --keyboard-layouts=LAYOUTS
1465 The list of keyboard layouts to enable.
1466 --keyboard-variant=VARIANT
1468 Override for the keyboard layout variant.
1469 --keyboard-variants=VARIANTS
1471 Override for the keyboard layout variants.
1472 --keyboard-options=OPTIONS
1474 Override for the keyboard options sent to the server.
1475 --swap-keys=YES|NO
1477 This option only applies to MacOS clients, it swaps the command
1478 and control keys and is enabled by default.
1479 --audio-source=PLUGIN
1481 Specifies the GStreamer audio plugin used for capturing the au‐
1482 dio stream. This affects "speaker forwarding" on the server,
1483 and "microphone" forwarding on the client. To get a list of op‐
1484 tions use the special value 'help'. It is also possible to
1485 specify plugin options using the form: --audio-source= pulsede‐
1486 vice=device.alsa_input.pci-0000_00_14.2.analog-stereo
1487 --speaker=on|off|disabled and --microphone=on|off|disabled|on:DE‐
1489 VICE|off:DEVICE
1490 Sound input and output forwarding support: on will start the
1491 forwarding as soon as the connection is established, off will
1492 require the user to enable it via the menu, disabled will pre‐
1493 vent it from being used and the menu entry will be disabled.
1494 With microphone forwarding, you may also be able to specify
1495 which device to use.
1496 --speaker-codec=CODEC and --microphone-codec=CODEC
1498 Specify the codec(s) to use for audio output (speaker) or input
1499 (microphone). This parameter can be specified multiple times
1500 and the order in which the codecs are specified defines the pre‐
1501 ferred codec order. Use the special value 'help' to get a list
1502 of options. When unspecified, all the available codecs are al‐
1503 lowed and the first one is used.
1504 --title=VALUE
1506 Sets the text shown as window title. The string supplied can
1507 make use of remote metadata placeholders which will be populated
1508 at runtime with the values from the remote server. The default
1509 value used is "@title@ on @client-machine@".
1510 The following placeholders are defined:
1512 @title@
1514 Will be replaced by the remote window's title.
1515 @client-machine@
1517 Will be replaced by the hostname of the system where the
1518 application is running, if provided, the xpra server's
1519 hostname otherwise.
1520 @server-machine@
1522 Will be replaced by the hostname of the xpra server.
1523 @server-display@
1525 Will be replaced by the name of the display on which the
1526 application is running.
1527 --border=BORDER
1529 Specifies the color and size of the border to draw inside every
1530 xpra window. This can be used to easily distinguish xpra win‐
1531 dows running on remote hosts from local windows. The BORDER can
1532 be specified using standard color names (ie: red, or orange) or
1533 using the web hexadecimal syntax (ie: #F00 or #FF8C00). The spe‐
1534 cial color name "auto" will derive the color from the server
1535 target address (the connection string) so that connecting to the
1536 same target should always give the same color. You may also
1537 specify the size of the border in pixels, ie: --border=yel‐
1538 low,10.
1539 --window-icon=FILENAME
1541 Path to the default image which will be used for all windows.
1542 This icon may be shown in the window's bar, its iconified state
1543 or task switchers. This depends on the operating system, the
1544 window manage and the application may override this too.
1545 --window-close=ACTION
1547 Choose what action to take when the window is closed by the
1548 client. The following actions can be used:
1549 auto The client will figure out what is best based on the win‐
1551 dow type. This is the default. ie: it will use discon‐
1552 nect shadow sessions, Iforward for seamless windows.
1553 forward
1555 The event will be forwarded to the server.
1556 ignore Do nothing.
1558 disconnect
1560 Disconnect from the server.
1561 shutdown
1563 Shutdown the server.
1564 --desktop-scaling=off|on|auto|VALUE
1566 Desktop scaling allows the windows to be scaled by the client.
1567 Downscaling will mostly waste bandwidth, upscaling allows the
1568 window's pixels to be sent over the wire at a lower resolution,
1569 saving bandwidth and CPU time. This option can also be used to
1570 request a specific scaling value. For best results, use opengl
1571 client rendering, the other display backends may show visual ar‐
1572 tifacts when scaling. Note: the scaling may also be adjusted at
1573 runtime through keyboard shortcuts if those are configured.
1574 The desktop-scaling value can take the form:
1576 off scaling will be disabled
1578 on scaling will be allowed, but it will start unscaled
1580 auto scaling will be allowed and a scaling value will be auto‐
1582 matically chosen if the client's desktop is large (bigger
1583 desktops will use higher scaling values)
1584 scaling-value
1586 scaling will be enabled and use the given value, speci‐
1587 fied as a number, fraction or percentage. ie: 2, 3/2 or
1588 150%.
1589 pair the scaling will be enabled and use a different value for
1591 the X and Y axis. ie: 3x2 or 3/2x4/3
1592 desktop-size
1594 the scaling will be enabled and the server will render to
1595 the given size. ie: 1600x1200
1596 --tray=yes|no Enable or disable the xpra's own tray menu. On MacOS,
1598 the dock icon cannot be disabled.
1599 --delay-tray
1601 Waits for the first window or notification to appear before
1602 showing the system tray. (posix only)
1603 --tray-icon=FILENAME
1605 Specifies the icon shown in the dock/tray. By default it uses a
1606 simple default 'xpra' icon. (On Microsoft Windows, the icon
1607 must be in ico format.)
1608 --enable-pings
1610 The client and server will exchange ping and echo packets which
1611 are used to gather latency statistics. Those statistics can be
1612 seen using the xpra info command.
1613 Options for attach, stop, info, screenshot, version
1617 --ssh=CMD
1618 When you use an ssh: address to connect to a remote display,
1619 xpra runs ssh(1) to make the underlying connection. Most in‐
1620 stallations should now be using paramiko as default backend com‐
1621 mand. Another common value for CMD is ssh or plink on Microsoft
1622 Windows. If your ssh program is in an unusual location, has an
1623 unusual name, or you want to pass special options to change
1624 ssh's behavior, then you can use the --ssh switch to tell xpra
1625 how to run ssh.
1626 For example, if you want to use arcfour encryption, then you
1628 should run
1629 xpra attach --ssh="ssh -c arcfour" ssh://frodo/7
1631 Note: Don't bother to enable ssh compression; this is redundant
1633 with xpra's own compression, and will just waste your CPU.
1634 On MS Windows, where backslashes are used to separate path ele‐
1636 ments and where spaces are often used as part of paths, you need
1637 to add quotes around paths. (ie: ssh="C:\Program
1638 Files\Xpra\Plink.exe" -ssh -agent)
1639 --exit-ssh=yes|no
1642 Choose whether the SSH client process should be forcibly termi‐
1643 nated when xpra disconnects from the server. If you are using
1644 SSH connection sharing, you may want to avoid stopping the SSH
1645 master process instance spawned by xpra as it may be used by
1646 other SSH sessions. Note: the exit-ssh=no detaches the SSH
1647 process from the terminal which prevents the SSH process from
1648 interacting with the terminal input, this disables the keyboard
1649 interaction required for password input, host key verification,
1650 etc..
1651 --remote-xpra=CMD
1653 When connecting to a remote server over ssh, xpra needs to be
1654 able to find and run the xpra executable on the remote host. If
1655 this executable is in a non-standard location, or requires spe‐
1656 cial environment variables to be set before it can run, then ac‐
1657 complishing this may be non-trivial. If running xpra attach
1658 ssh:something fails because it cannot find the remote xpra, then
1659 you can use this option to specify how to run xpra on the remote
1660 host.
1661 That said, this option should not be needed in normal usage, as
1663 xpra tries quite hard to work around the above problems. If you
1664 find yourself needing it often, then that may indicate a bug
1665 that we would appreciate hearing about.
1666 SSL Options
1669 --ssl=on|auto|off|tcp|www
1670 Whether to enable SSL on TCP sockets and for what purpose. The
1671 TCP sockets will automatically be upgraded to SSL when SSL pack‐
1672 ets are received.
1673 auto The server will try to guess what protocol to use for
1675 each new SSL connection: either xpra's native protocol or
1676 https / websocket (wss)
1677 tcp The SSL sockets will only be used for xpra's native pro‐
1679 tocol
1680 www The SSL sockets will only be used for https and websocket
1682 (wss)
1683 If SSL is enabled, then a ssl-cert is required.
1684 The remaining options mirror the Python ssl module attributes. Please
1686 refer to that documentation and bear in mind that configuring SSL for
1687 security is not trivial, and definitely not just a matter of enabling
1688 SSL. See: https://docs.python.org/2/library/ssl.html Some options may
1689 not be available with older versions of Python.
1690 Summary: --ssl-key=KEYFILE The key file to use.
1692 --ssl-cert=ERTFILEORDIR
1694 Certificate file, required for server SSL support.
1695 --ssl-protocol=PROTOCOLVERSION
1697 Specifies which version of the SSL protocol to use.
1698 --ssl-ca-certs=CACERTSFILE
1700 The ca_certs file contains a set of concatenated 'certification
1701 authority' certificates. If a directory is specified, it should
1702 contain the certificates.
1703 --ssl-ca-data=ERTDATA
1705 Certificate data.
1706 --ssl-ciphers=CIPHERS
1708 Sets the available ciphers, it should be a string in the OpenSSL
1709 cipher list format.
1710 --ssl-client-verify-mode=none|optional|required
1712 Whether to try to verify the client's certificates and how to
1713 behave if verification fails.
1714 --ssl-server-verify-mode=none|optional|required
1716 Whether to try to verify the server's certificates and how to
1717 behave if verification fails.
1718 --ssl-verify-flags=FLAGS
1720 The flags for certificate verification operations.
1721 --ssl-check-hostname=yes|no
1723 Whether to match the peer cert's hostname.
1724 --ssl-options=options
1726 Set of SSL options enabled on this context.
1727 ENVIRONMENT
1731 DISPLAY
1733 xpra start --start-child=... sets this variable in the environ‐
1734 ment of the child to point to the xpra display.
1735 xpra attach, on the other hand, uses this variable to determine
1737 which display the remote applications should be shown on.
1738 XPRA_PASSWORD may be used with xpra attach instead of the pass‐
1740 word-file option.
1741
1744 xpra.conf stores default values for most options. There is a global
1745 configuration file in /etc or /usr/local/etc, and each user may over‐
1746 ride those defaults by creating the file .xpra/xpra.conf. You can also
1747 split the options into multiple files by placing them in a conf.d di‐
1748 rectory with the .conf extension. Depending on OS and version, xpra
1749 uses the directory ~/.xpra or /run/<uid>/xpra to store a number of
1750 files. (The examples below are given for the display :7.)
1751 ~/.xpra/:7
1753 The unix domain socket that clients use to contact the xpra
1754 server, if the system configuration uses this directory.
1755 ~/.xpra/:7.log
1757 When run in daemon mode (the default), the xpra server directs
1758 all output to this file. This includes all debugging output, if
1759 debugging is enabled.
1760 ~/.xpra/run-xpra
1762 A shell script that, when run, starts up xpra with the correct
1763 python interpreter, PYTHONPATH, PATH, location of the main xpra
1764 script, etc. Automatically generated by xpra initenv, xpra
1765 start and used by xpra attach (see also the discussion of --re‐
1766 mote-xpra).
1767
1769 Xpra has no test suite.
1770 Xpra does not fully handle all aspects of the X protocol; for instance,
1772 fancy input features like pressure-sensitivity on tablets, some window
1773 manager hints, and probably other more obscure parts of the X protocol.
1774 It does, however, degrade gracefully, and patches for each feature
1775 would be gratefully accepted.
1776 The xpra server allocates an over-large framebuffer when using Xvfb;
1778 this wastes memory. If the Xvfb does not support RandR this can also
1779 cause applications to misbehave (e.g. by letting menus go off-screen).
1780 This is not a problem when using Xdummy, see the --xvfb= switch for de‐
1781 tails. Conversely, if the framebuffer is ever insufficiently large,
1782 clients will misbehave in other ways (e.g., input events will be misdi‐
1783 rected).
1784
1786 Send any questions or bugs reports to https://github.com/Xpra-
1787 org/xpra/issues
1788
1790 screen(1),
1791 XPRA(1)