:DISPLAY[,OPTIONS]

Local displays: this is the simplest form and is only valid for the current local displays of the current user.

tcp://[[USERNAME][:PASSWORD]@]HOST:PORT[/DISPLAY][?OPTIONS]

TCP mode uses port numbers and not display numbers. If multiple displays are available through a single TCP port (ie: using a proxy server), then one can also specify the display number after the port number.

ssl://[[USERNAME][:PASSWORD]@]HOST:PORT[/DISPLAY][?OPTIONS]

SSL adds a secure socket layer on top of the TCP mode.

vsock://[[USERNAME][:PASSWORD]@]HOST:PORT[/?OPTIONS]

Almost identical to the TCP mode, but using AF_VSOCK for transport.

ws://[[USERNAME][:PASSWORD]@]HOST:PORT/[DISPLAY][?OPTIONS]

Connect using websocket protocol.

wss://[[USERNAME][:PASSWORD]@]HOST:PORT/[DISPLAY][?OPTIONS]

Connect using secure websocket protocol. (websocket with SSL)

ssh://[[USERNAME][:PASSWORD]@]HOST[:SSH_PORT]/[DISPLAY][?OPTIONS]

Connect using secure shell. (SSH)

Further SSH options can be specified using the --ssh command line option. The OPTIONS can be used to specify an ssh proxy: ?proxy=ssh://[USERNAME[:PASSWORD]@]HOST[:SSH_PORT] xpra will then establish an SSH connection to the specified "proxy" host, and from that host xpra will set up an SSH connection to the xpra server.

For backwards compatibility, SSH mode also supports the syntax: ssh:[USERNAME[:PASSWORD]@]HOST:DISPLAY but this form does not support specifying the SSH port number. Older versions also used the form protocol:host:port, but users are encouraged to move to a more standard URI format using :// as separator.

The password need only be specified when the server authentication module requires it.

vnc://[[USERNAME][:PASSWORD]@]HOST[:VNC_PORT]/

Connect using the RFB protocol. (aka VNC) This mode only works against VNC servers or an xpra server in desktop or shadow mode.

xpra start

This command starts a new xpra server, including any necessary setup. (When starting a remote server with the ssh://HOST/DISPLAY syntax, the new session will also be attached.)

xpra start-desktop

Starts a nested X11 server, all child commands will be started in the nested X11 server.

xpra attach

This command attaches to a running xpra server, and forwards any applications using that server to appear on your current screen.

xpra detach

Detaches the given xpra display.

xpra screenshot

Takes a screenshot and saves it to the filename specified. Note: screenshots can only be taken when a client is attached.

xpra version

Queries the server version and prints it out. Note: older servers may not support this feature.

xpra info

Queries the server for version, status and statistics.

xpra top

Shows the server's key health attributes.

xpra control

Modify the server at runtime by issuing commands. The list of commands can be obtained by specifying "help" as command. Some of those commands may support a "help" mode themselves.

xpra initenv

This internal command creates the run-xpra script used with ssh connections.

xpra stop

This command attaches to a running xpra server, and requests that it terminates immediately. This generally causes any applications using that server to terminate as well.

xpra exit

This command attaches to a running xpra server, and requests that it terminates immediately. Unlike xpra stop, the Xvfb process and its X11 clients (if any) will be left running.

xpra showconfig

This commands shows the configuration which would be used given the arguments provided. You can also specify as extra arguments the specific options that should be displayed, or use the special value all to display all the options including the ones which are normally not displayed because they are not relevant on the given system.

xpra list

This command finds all xpra servers that have been started by the current user on the current machine, and lists them.

xpra upgrade

This command starts a new xpra server, but instead of creating it from scratch, it attaches to another existing server, tells it to exit, and takes over managing the applications that it was managing before. As the name suggests, the main use case is to replace a server running against an older version of xpra with a newer version, without having to restart your session. Any currently-running xpra attach command will exit and need to be restarted.

xpra upgrade-desktop

Same as upgrade but for servers started using start-desktop. It is possible to upgrade seamless server into a desktop server and vice versa.

xpra recover

Similar to upgrade and upgrade-desktop: but without needing to specify if the server to recover is a seamless server or a desktop server. Unlike the upgrade subcommands, recover can also detect which displays need recovering. That is, displays which were previously used by an xpra server but this server has gone missing.

xpra shadow

This command shadows an existing display and is supported on X11, MacOS and MS Windows platforms. (this is not supported on Wayland yet)

If there is only one X11 display active and its number is below 10, it can be auto-detected and the display may be omitted.

Note that this mode of operation uses screenscraping which is not very efficient. Video encoders partially mitigate this drawback.

By default, shadow mode will expose all the monitors connected as individual windows. But it is also possible to only shadow a specific region or monitor, or to group all monitors as a single window by specifying display options. Here are some examples:

To expose all monitors connected to display :1 as a single window,

use the multi-window option:
xpra shadow :1,multi-window=no

To shadow a specific output using its name (ie: DP-1):

xpra shadow :1,DP-1
or more explicitly:
xpra shadow :1,plug=DP-1

To expose a rectangular area of size 1920x1080 as a single window, use:

xpra shadow :1,1920x1080
You may also want to specify the position of this rectangle (ie: 1280x0):
xpra shadow :1,1920x1080@1280x0
or using the more explicit syntax:
xpra shadow :1,geometry=1920x1080@1280x0
Multiple areas can be specified using / as separator, each one will be exposed as a separate window:
xpra shadow :1,1920x1080@1280x0/1280x600@0x400

xpra proxy

This command allows a single server to proxy connections for multiple others, potentially serving as a load balancing or authentication entry point for many sessions. The proxy server will spawn a new process for each proxy connection, this proxy process will create an unauthenticated new unix domain socket which can be used with the subcommands info, version and stop.

Important Note

Some platforms and package managers may choose to only build the client and not the server. In this case, only the attach subcommand will be available.

General options

--version

Displays xpra's version number.

-h, --help

Displays a summary of command line usage.

--minimal

Disables all non-essential features.

-d FILTER1,FILTER2,..., --debug=FILTER1,FILTER2,...

Enable debug logging. The special value all enables all debugging. To get the full list of logging categories, run xpra -d help. To target loggers that use more than one logging category (as some categories can be quite broad), join them with a '+'. For example, to enable logging for server and keyboard, use --debug server+keyboard. You can also exclude a category with the '-' prefix. For example, to enable shadow debugging but not clipboard, use: --debug shadow,-clipboard.

--commands=yes|no

Enable or disable the ability to run commands on the server. Generally, clients expect to be able to request new commands to be executed by the server, but this can be turned off to securely lock down the server.

--shell=yes|no

Enable or disable the ability to connect to an xpra socket with the shell subcommand. This is useful for debugging and is not enabled by default. When disabled, it can still be enable on a per-socket basis using bind options.

--control=yes|no

Enable or disable the control channel of xpra sockets. This channel is accessed using the control subcommand to interact with an xpra process.

--mmap=yes|no|ABSOLUTEFILENAME|DIRECTORY

Enable or disable memory mapped pixel data transfer. By default it is normally enabled automatically if the server and the client reside on the same filesystem namespace. This method of data transfer offers much lower overheads and reduces both CPU consumption and local network traffic. When attaching, you can also specify an absolute path where the mmap file will be created. When used on the server, one can specify the exact filename that the client will create, or just the directory where the file will be created so that multiple clients may connect and use mmap concurrently.

--mmap-group=GROUP

Sets the mmap file's gid to the group specified, and sets the permissions to 660. This is necessary to share the mmap file across user accounts. You can also use the special GROUP values:

--windows=yes|no

Enable or disable the forwarding of windows. This is usually the primary use for xpra and should be enabled.

--min-size=WIDTHxHEIGHT

Sets the minimum size for all decorated windows.

--max-size=WIDTHxHEIGHT

Sets the maximum size for all windows.

--readonly=yes|no

Read only mode ignores all keyboard and mouse activity.

--clipboard=yes|no|clipboard-type

Enable or disable clipboard synchronization. If disabled on the server, no clients will be able to use clipboard synchronization at all. If turned off on the client, only this particular connection will ignore clipboard data from the server. This can also be used to specify a different clipboard implementation. The clipboard types available will vary from platform to platform and also depend on build time environment and options so this is best left on auto. Other clipboard types available may include:

--clipboard-direction=to-server|to-client|both|disabled

Choose the direction of the clipboard synchronization.

--pulseaudio=yes|no

Enable or disable the starting of a pulseaudio server with the session.

--pulseaudio-command=SERVER-START-COMMAND

Specifies the pulseaudio command to use to start the pulseaudio server, unless disabled with pulseaudio=no.

--session-name=VALUE

Sets the name of this session. This value may be used in notifications, utilities, tray menu, etc. Setting this value on the server provides a default value which may be overridden on the client.

--encoding=ENCODING

Sets the preferred encoding to use. To see the list of encodings available, use --encoding=help. This can be used to select grayscale or 8-bit modes like png/P. On local connections or with extremelly fast network links, plain rgb is also a viable option. For everything else, the default value auto will select the best encoding automatically and you should use the min-speed and min-quality options instead for tuning.

--encodings=ENCODING

This specifies the image encodings enabled. This is the most misused command line option and should be left alone. The server engine needs to have multiple encodings available to work effectively.

--video-scaling=on|off|SCALING

How much automatic video downscaling should be used, from 1 (rarely) to 100 (aggressively), 0 to disable. Video scaling is normally used with video regions or very large windows (especially full screen windows) to try to maintain a decent framerate. Video downscaling negatively affects visual quality and will cause automatic refreshes (if enabled), it is most useful on video content where it saves a considerable amount of bandwidth.

--socket-dir=DIR

Location where to write and look for the Xpra socket files. The default location varies from platform to platform ("~/.xpra" and "$XDG_RUNTIME_DIR/xpra" on most Posix systems). If unspecified, the first value from socket-dirs will be used. It may also be specified using the XPRA_SOCKET_DIR environment variable.

When using the socket-dir option, it is generally necessary to specify socket-dir or socket-dirs on all following commands, for xpra to work with the open sessions.

By specifying a shared directory this can be coupled with the mmap-group and socket-permissions option to connect Xpra sessions across user accounts with shared memory acceleration.

--socket-dirs=DIR

Specifies the directories where to look for existing sockets if a specific one was not set using socket-dir. You may specify each directory using a new --socket-dirs command line argument, or joined together by the path separator (: on Posix). The paths will be expanded. (ie: --socket-dirs=~/.xpra:/tmp)

--file-transfer=on|off

Enable file transfers.

--open-files=on|off

This option may be used to allow the remote end to automatically open files after they have been uploaded. This may be a security risk if you are using xpra to constrain what the clients can execute on the server.

--forward-xdg-open=on|off|auto

Intercept execution of xdg-open and forward the request to the client.

--open-command=COMMAND

The command to use for opening files and URLs.

--bandwidth-limit=BITSPERSECOND

Restrict bandwidth usage to below the limit given. The client's value cannot raise the limit of the server. The value may be specified using standard units, ie: 1Mbps or 500K. In auto mode, the client will set the bandwidth limit value to 80% of the maximum speed of the network interface it is using to connect to the server.

--splash=yes|no|auto Show a splash screen during client or server startup. With the default value of auto, the splash screen is only shown if there is a GUI available - ie: no attempt will be made to show the splash screen when xpra is launched from an SSH session.

Options for start, start-desktop, upgrade, proxy and shadow

--daemon=yes|no

By default, the xpra server puts itself into the background, i.e. 'daemonizes', and redirects its output to a log file. This can be used to prevent that behavior (useful mostly for debugging).

--resize-display=yes|no|WIDTHxHEIGHT

Resize the virtual display to match the resolution of the client currently connected. This only applies to the start and start-desktop subcommands. If a resolution is given, this will be the initial resolution of the display and the display will be resizable. A small set of pre-defined aliases can also be used: QVGA, VGA, SVGA, XGA, 1080p, FHD, 4K.

--chdir=DIR

Change to this directory after daemonizing.

--uid=UID and --gid=GID

When launching the server as root, these options can be used to drop privileges to the given UID / GID.

--pidfile=FILENAME

Writes the server process ID to this file on startup. If the file has not been replaced, it will be deleted when the server exits.

--challenge-handlers=MODULE:options

Configures which challenge handlers are used by the client and in which order. This option may be repeated to specify multiple handlers, which can be useful if the server sends more than one authentication challenge. The default value is: all which corresponds to: uri,file,env,kerberos,gss,u2f,prompt.

--min-port=PORT

The minimum port number allowed when creating TCP sockets. You can use a lower value to allow unprivileged users to bind to privileged ports when starting sessions via the system wide proxy server. The default value is 1024 which is the standard value for privileged ports.

--mdns=yes|no

Enable or disable the publication of new sessions via mDNS.

--dbus-launch=COMMAND|no

Start the session within a dbus-launch context, you can specify the dbus launch command to use, or turn it off completely. Some features may not be available without a dbus context.

--dbus-control=yes|no

Start a dbus server which can be used to interact with the server process.

Options for start, start-desktop, upgrade and listen:

In previous versions, the authentication for each connection type was configured using a separate command line option which would apply to all connections of the same type. ie: tcp-auth for bind-tcp. Although this is still supported as a fallback, the recommended way is to specify authentication options using bind properties. ie: bind-tcp=0.0.0.0:14500,auth=file:filename=password.txt. The properties can also define extra socket configuration options.

--bind=BIND_LOCATION[,PROPERTIES] Create a local Unix domain socket (on Unix) or named-pipe (on MS Windows) for each bind option specified.

This option can be specified multiple times to specify multiple socket locations. These sockets support local connections with the :7-style display address, and remote connections with the ssh://frodo/7-style display address.

Local sockets may also process HTTP / Websocket connections if the html switch is enabled.

The location can take the form:

--bind-tcp=[HOST]:PORT[,PROPERTIES]

Create a TCP socket for each --bind-tcp option specified. If the host portion is omitted, then 127.0.0.1 (localhost) will be used. If you wish to accept connections on all interfaces, pass 0.0.0.0 for the host portion.

Using this switch without setting the auth option is not recommended, and is a major security risk (especially when passing 0.0.0.0)! Anyone at all may connect to this port and access your session.

TCP sockets may also process HTTP / Websocket connections if the html switch is enabled. TCP sockets may also be upgraded to SSL sockets if the ssl switch is enabled.

--bind-ws=[HOST]:PORT[,PROPERTIES]

Create an HTTP / Websocket listener. See bind-tcp for host restrictions, you should use the auth-ws to secure access.

--bind-wss=[HOST]:PORT[,PROPERTIES]

Create an HTTPS / Secure Websocket listener. See bind-tcp for host restrictions, you should use the auth-wss to secure access.

--bind-ssl=[HOST]:PORT[,PROPERTIES]

Just like --bind-tcp but for SSL sockets. See ssl-auth and the other SSL options.

--bind-rfb=[HOST]:PORT[,PROPERTIES]

Listens for RFB connections on the given port. These sockets are only supported with the start-desktop and shadow modes.

--bind-vsock=CID:PORT[,PROPERTIES]

Create a VSOCK socket for each --bind-vsock option specified.

--auth=MODULE[:OPTION=VALUE]

Specifies the authentication module to use for all unix domain sockets created using the bind switch. Authentication modules can validate a username and password against a variety of backend modules:

--tcp-auth=MODULE

Just like the auth switch, except this one only applies to TCP sockets (sockets defined using the bind-tcp switch). Deprecated, use per-socket authentication options.

--ws-auth=MODULE

Just like the auth switch, except this one only applies to ws sockets: sockets defined using the bind-ws switch, or TCP sockets upgraded to websockets. (if the html option is enabled). Deprecated, use per-socket authentication options.

--wss-auth=MODULE

Just like the auth switch, except this one only applies to wss sockets: sockets defined using the bind-wss switch, ws sockets upgraded to SSL (if the ssl option is enabled) or TCP sockets upgraded to SSL and then to wss. (if both the ssl and html options are enabled). Deprecated, use per-socket authentication options.

--ssl-auth=MODULE

Just like the auth switch, except this one only applies to SSL sockets: sockets defined using the bind-ssl switch, or TCP sockets upgraded by ssl=auto or ssl=on. Deprecated, use per-socket authentication options.

--rfb-auth=MODULE

Authentication module to use for the bind-rfb sockets. Deprecated, use per-socket authentication options.

--vsock-auth=MODULE

Just like the auth switch, except this one only applies to VSOCK sockets (sockets defined using the bind-vsock switch). Deprecated, use per-socket authentication options.

Options for start, start-desktop, upgrade

--exec-wrapper=CMD

A wrapper command which is prepended to all start commands. Typically, this is used for starting all sub-commands via VirtualGL.

--start=CMD

After starting the server, runs the command CMD using the default shell. The command is run with its $DISPLAY set to point to the newly-started server. This option may be given multiple times to start multiple commands.

--start-child=CMD

Identical to --start, except that the commands are taken into account by --exit-with-children.

--start-after-connect=CMD

Wait for the first client to connect before starting the command.

--start-child-after-connect=CMD

Wait for the first client to connect before starting the child command. See start-child.

--start-on-connect=CMD

Execute this command every time a client connects.

--start-child-on-connect=CMD

Execute this child command every time a client connects. See start-child.

--start-on-last-client-exit=CMD

Execute this command every time a client disconnects and there are no other clients left.

--start-child-on-last-client-exit=CMD

Execute this child command every time a client disconnects and there are no other clients left. See start-child.

--terminate-children=yes|no

On server stop, terminate all the child commands that have been started by the server. This does not affect server exit. Most child commands are tied to the display so they are normally forced to shutdown anyway, but this gives them more time to cleanup properly and can be used to stop background commands that aren't tied to a display.

--exit-with-children=yes|no

This option may only be used if --start-child is also given. If it is given, then the xpra server will monitor the status of the children started by --start-child, and will automatically terminate itself when the last of them has exited.

--exit-with-windows=yes|no

The server will terminate automatically when there are no more windows or system trays being forwarded. This option is only relevant for seamless servers.

--exit-with-client=yes|no

The server will terminate when the last client disconnects.

--env=KEY=VALUE

Extra environment variables which will only affect commands started using --start or --start-child.

--start-new-commands=yes|no

Allow clients to ask the server to execute new commands. (this can also be used via the control channel)

--start-via-proxy=yes|no|auto

If enabled, the start and start-desktop subcommands will be delegated to the system wide proxy server instance. With auto mode, this delegation will only occur if the system wide proxy server is found.

--systemd-run=yes|no|auto

Wrap server start commands with systemd-run.

--systemd-run-args=ARGS

Command line arguments passed to systemd-run.

--use-display=yes|no|auto

Use an existing display rather than starting one with xvfb. You are responsible for starting the display yourself. This can also be used to rescue an existing display whose xpra server instance crashed or for running xpra against an accelerated X11 server. With auto, xpra will use the existing display if it is found.

--displayfd=FD

The xpra server will write the display number back on this file descriptor as a newline-terminated string. This is most useful when the display number is not specified with the xpra start or start-desktop subcommands.

--xvfb=CMD

When starting a seamless server, xpra starts a virtual X server to run the clients on. If your Xvfb is installed in a funny location, or you want to use some other virtual X server, then this switch allows you to specify how to run your preferred X server executable. The default value used depends on your platform. The recommended command to use here is Xorg with the dummy driver, also known as Xdummy. See: https://github.com/Xpra-org/xpra/blob/master/docs/Usage/Xdummy.md Some distributions are unable to configure it properly and will use Xvfb instead.

--sync-xvfb=DELAY

The windows are normally only displayed on the client(s), they are not painted on the virtual display. Some applications like screen recorders may want to capture the window contents, you can use this option to enable painting with a configurable delay (in milliseconds). Warning: this extra painting is expensive and quite slow, which is why it is not enabled by default.

--attach=yes|no|auto

Once the server has started, immediately connect a client to it. With the value auto, a client is started for remote servers only. (servers specified via a network URI) If a display is specified and a server is already running, xpra will not try to start a new one and it will just attach to it.

Options for start, start-desktop, upgrade, shadow

--http=on|off

Respond to HTTP requests on the TCP port(s) and local sockets. This requires at least one TCP or local socket to be configured using the matching bind option.

--html=on|off|auto|webrootpath

This enables access to the html5 client via http. The auto mode will enable support if it is found. You can also specify your own web root path as argument.

--http-scripts=off|all|SCRIPTS

Enable the builtin web server scripts that expose the server status, current active sessions and displays, the list of applications and desktop sessions installed. This can be used by the client's user interface.

--rfb-upgrade=DELAY

Allows RFB clients (ie: VNC) to connect to a plain TCP socket. If no data is received after DELAY seconds, the server will send a RFB handshake. This option is only applicable to servers started in start-desktop or shadow modes.

--video-encoders=ENCODERS

Specifies the video encoders to try to load. By default, all of them are loaded, but one may want to specify a more restrictive list of encoders. Use the special value 'help' to get a list of options. Use the value 'none' to not load any video encoders.

--csc-modules=MODULES

Specifies the colourspace conversion modules to try to load. By default, all of them are loaded, but one may want to specify a more restrictive list of modules. Use the special value 'help' to get a list of options. Use the value 'none' to not load any colourspace conversion modules.

--socket-permissions=ACCESS-MODE

Specifies the file permissions on the server's unix domain sockets. Defaults to 600. This is ignored when mmap-group is enabled.

Options for start, start-desktop, upgrade and attach

--encryption=CIPHER

Specifies the cipher to use for securing the connection from prying eyes. This option requires the use of the --encryption-keyfile option. The only ciphers supported at present are:

If the client requests encryption it will be used by both the client and server for all communication after the initial password verification, but only if the server supports this feature too. Note: this feature has not been extensively reviewed and as it is it should not be considered safe from determined attackers.

--tcp-encryption=CIPHER

Just like the encryption switch, except this one only applies to TCP sockets (sockets defined using the bind-tcp switch).

--encryption-keyfile=FILENAME

Specifies the key to use with the encryption cipher specified with --encryption. The client and server must use the same keyfile contents.

--tcp-encryption-keyfile=FILENAME

Just like the encryption-keyfile switch, except this one only applies to TCP sockets (sockets defined using the bind-tcp switch).

--idle-timeout=IDLETIMEOUT

The connection will be terminated if there is no user activity (mouse clicks or key presses) for the given amount of time (in seconds). Use the value 0 to disable this timeout.

--server-idle-timeout=IDLETIMEOUT

The server will exit if there are no active connections for the given amount of time (in seconds). Use the value 0 to disable this timeout.

--clipboard-filter-file=FILENAME

Name of a file containing regular expressions, any clipboard data that matches one of these regular expressions will be dropped. Note: at present this only applies to copying from the machine where this option is used, not to it.

--dpi=VALUE

The 'dots per inch' value that client applications should try to honour. This numeric value should be in the range 10 to 500 to be useful. Many applications will only read this value when starting up, so connecting to an existing session started with a different DPI value may not have the desired effect.

--pixel-depth=VALUE

When starting a server, this switch controls the bits per pixel of the virtual framebuffer. Possible values: 0 (auto), 16, 24, 30. When starting a client, this switch controls the picture rendering with the opengl backend: values higher than 24 will enable deep color, the value 24 enables regular true color rendering. Use the value 0 to let the client decide if the rendering will benefit from using deep color. (this is only supported on some Posix clients) Other values should not be used.

--cursors=yes|no

Enable or disable forwarding of custom application mouse cursors. Client applications may change the mouse cursor at any time, which will cause the new cursor's pixels to be sent to the client each time. This disables the feature.

--notifications=yes|no

Enable or disable forwarding of system notifications. System notifications require the xpra server to have its own instance of a dbus daemon, if it is missing a warning will be printed on startup. This switch disables the feature entirely, and avoids the warning.

--input-method=METHOD

Specify which input method to configure. This sets a number of environment variables which should be honoured by applications started with the start-child option.

The following METHODs are currently supported:

Any other value will also be set up, but will trigger a warning.

--xsettings=auto|yes|no

Enable or disable xsettings synchronization. Xsettings are only forwarded from posix clients connecting to real posix servers (not shadows). In 'auto' mode, only seamless servers enable xsettings synchronization.

--system-tray=yes|no

Enable or disable forwarding of system tray icons. This feature requires client support and may not be available on all platforms.

--bell=yes|no

Enable or disable forwarding of the system bell.

--webcam=yes|no

Enable or disable webcam forwarding.

--mousewheel=on|off|invert|invert-x|invert-y|invert-z

Mouse wheel handling: can be used to disable mouse wheel forwarding using the value no, or to invert some or all axes: invert-all, invert-x, invert-y, invert-z.

--remote-logging=both|all|send|receive|no

--av-sync=yes|no

Enable or disable audio-video synchronization. The video data will be delayed so that it is displayed in sync with the audio. Note: this only applies to video regions, either auto-detected via the builtin heuristics or specified using the dbus interface.

Options for attach

--modal-windows=yes|no

Honour modal windows. This may have undesirable side effects when multiple applications are forwarded through the same xpra server: modal windows will be made modal for all the applications forwarded by xpra rather than just the one application which owns that window.

--headerbar=auto|no|force

Replaces the window's standard title bar with a custom one which is used to give access to xpra specific window controls. This feature can have side effects and it is incompatible with OpenGL acceleration on MS Windows.

--password-file=FILENAME

Supply the password to be used for connecting to a server that uses authentication. Deprecated, use per-socket authentication options.

--opengl=(yes|no|auto)[:backend]

Use OpenGL accelerated rendering on the client. The default is to detect if the graphics card and drivers are supported (auto mode), but one can also disable OpenGL (no) or force it enabled (yes). On some platforms, it is also possible to specify which backends should be used, only gtk and native are currently supported and only on X11 platforms. ie: opengl=yes:native, or opengl=auto:gtk,native.

--webcam=yes|no|/dev/deviceXXX|DEVICEID

Enable or disable webcam forwarding. The webcam device to use can also be specified.

-zLEVEL, --compress=LEVEL

Select the level of compression xpra will use when transmitting data over the network. There are only two possible values: 0 (meaning no compression) and 1 (compression enabled).

This compression is not used on pixel data (except when using the rgb encoding).

--quality=VALUE

This option sets a fixed image compression quality for lossy encodings (jpeg, webp, h264/h265 and vp8/vp9). First, one of those lossy encodings must be enabled with --encoding or when using the default auto mode. Values range from 1 (lowest quality, high compression - generally unusable) to 100 (highest quality, low compression). Specify a value of zero to let the system tune the quality dynamically to achieve the best bandwidth usage possible. It is usually best not to use this option and use min-quality instead.

--min-quality=MIN-QUALITY

This option sets the minimum encoding quality allowed when the quality option is set to automatic mode. See quality above.

--speed=SPEED

This option sets the encoding speed, from 1 (slowest) to 100 (fastest). Slower compresses better and will use less bandwidth, faster will give better latency as long as there is sufficient bandwidth. The system normally uses a variable speed, this option forces a fixed speed setting to be used instead. It is usually best not to use this option and use min-speed instead.

--min-speed=MIN-SPEED

This option sets the minimum encoding speed allowed when the speed option is set to automatic mode. See speed above.

--auto-refresh-delay=DELAY

This option sets a delay after which the windows are automatically refreshed using a lossless frame if their contents had been updated using a lossy encoding previously. The delay is a floating-point number and is in seconds. This option is enabled by default with a delay of 0.25 seconds. This option is only relevant when using a lossy encoding.

--shortcut-modifiers=MODIFIERS

Defines the default shortcut modifiers required by the key-shortcuts, these modifiers can then be referred to as #. The default value is 'auto' which evaluates to Meta+Shift on most platforms.

--key-shortcut=KEY:ACTION

Can be specified multiple times to add multiple key shortcuts. These keys will be caught by the client and trigger the action specified and the key presses will not be passed on to the server.

The KEY specification may include keyboard modifiers in the form [modifier+]*key, for example: Shift+F10 or Shift+Control+B. You can refer to the shorcut-modifers option value using #, ie: #+F1.

Shortcuts defined on the command line are added to the builtin default shortcuts. To clear the list of shortcuts, use key-shortcut=clear and define your shortcuts after this one.

Some of the actions may allow arguments (ie: the log action does), in which case they are specified in the usual programming style syntax: ACTION(ARG1, ARG2, etc)
String arguments must be quoted (both single and double quotes are supported) and numeric arguments must not be quoted. Beware the parenthesis and quotes must usually be escaped when used from a shell command line. Example: --key-shortcut=Meta+Shift+F7:log\(\'hello\'\)

The following ACTIONs are currently defined:

--sharing=yes|no|auto

Sharing allows more than one client to connect to the same session. This must be enabled on both the server and all co-operating clients to function. When used server-side, the default value auto allows the clients to decide if they are willing to share the session. When used client-side, the default value auto evaluates to no. To allow sharing to work with unix domain sockets (either using local connections or via ssh), you should create at least one socket in a group accessible directory. On Posix with a default configuration, being a member of the xpra group should be enough to create a socket in /run/xpra. You must also ensure that the permissions of this socket file allow group access, see socket-permissions.

--lock=yes|no|auto

Locking allows a client to refuse to hand over the session to a new client. The session may still be shared with multiple clients (see the sharing option), but otherwise the server will reject new clients. When used server-side, the default value auto allows the clients to decide if they want to lock the session. When used client-side, the default value auto evaluates to no.

--keyboard-sync=yes|no

Normally the key presses and key release events are sent to the server as they occur so that the server can maintain a consistent keyboard state. Disabling synchronization can prevent keys from repeating unexpectedly on high latency links but it may also disrupt applications which access the keyboard directly (games, etc.).

--keyboard-raw=yes|no

Tells the server to process all keyboard input untranslated. Both the client and the server must be using the same type of keyboard interface. (ie: both using X11)

--keyboard-backend=BACKEND

The keyboard backend is normally detected automatically. This option overrides it.

--keyboard-layout=LAYOUTSTRING

The keyboard layout is normally detected automatically. This option overrides it.

--keyboard-layouts=LAYOUTS

The list of keyboard layouts to enable.

--keyboard-variant=VARIANT

Override for the keyboard layout variant.

--keyboard-variants=VARIANTS

Override for the keyboard layout variants.

--keyboard-options=OPTIONS

Override for the keyboard options sent to the server.

--swap-keys=YES|NO

This option only applies to MacOS clients, it swaps the command and control keys and is enabled by default.

--audio-source=PLUGIN

Specifies the GStreamer audio plugin used for capturing the audio stream. This affects "speaker forwarding" on the server, and "microphone" forwarding on the client. To get a list of options use the special value 'help'. It is also possible to specify plugin options using the form: --audio-source= pulsedevice=device.alsa_input.pci-0000_00_14.2.analog-stereo

--speaker=on|off|disabled and --microphone=on|off|disabled|on:DEVICE|off:DEVICE

Sound input and output forwarding support: on will start the forwarding as soon as the connection is established, off will require the user to enable it via the menu, disabled will prevent it from being used and the menu entry will be disabled. With microphone forwarding, you may also be able to specify which device to use.

--speaker-codec=CODEC and --microphone-codec=CODEC

Specify the codec(s) to use for audio output (speaker) or input (microphone). This parameter can be specified multiple times and the order in which the codecs are specified defines the preferred codec order. Use the special value 'help' to get a list of options. When unspecified, all the available codecs are allowed and the first one is used.

--title=VALUE

Sets the text shown as window title. The string supplied can make use of remote metadata placeholders which will be populated at runtime with the values from the remote server. The default value used is "@title@ on @client-machine@".

The following placeholders are defined:

--border=BORDER

Specifies the color and size of the border to draw inside every xpra window. This can be used to easily distinguish xpra windows running on remote hosts from local windows. The BORDER can be specified using standard color names (ie: red, or orange) or using the web hexadecimal syntax (ie: #F00 or #FF8C00). The special color name "auto" will derive the color from the server target address (the connection string) so that connecting to the same target should always give the same color. You may also specify the size of the border in pixels, ie: --border=yellow,10.

--window-icon=FILENAME

Path to the default image which will be used for all windows. This icon may be shown in the window's bar, its iconified state or task switchers. This depends on the operating system, the window manage and the application may override this too.

--window-close=ACTION

Choose what action to take when the window is closed by the client. The following actions can be used:

--desktop-scaling=off|on|auto|VALUE

Desktop scaling allows the windows to be scaled by the client. Downscaling will mostly waste bandwidth, upscaling allows the window's pixels to be sent over the wire at a lower resolution, saving bandwidth and CPU time. This option can also be used to request a specific scaling value. For best results, use opengl client rendering, the other display backends may show visual artifacts when scaling. Note: the scaling may also be adjusted at runtime through keyboard shortcuts if those are configured.

The desktop-scaling value can take the form:

--tray=yes|no Enable or disable the xpra's own tray menu. On MacOS, the dock icon cannot be disabled.

--delay-tray

Waits for the first window or notification to appear before showing the system tray. (posix only)

--tray-icon=FILENAME

Specifies the icon shown in the dock/tray. By default it uses a simple default 'xpra' icon. (On Microsoft Windows, the icon must be in ico format.)

--enable-pings

The client and server will exchange ping and echo packets which are used to gather latency statistics. Those statistics can be seen using the xpra info command.

Options for attach, stop, info, screenshot, version

--ssh=CMD

When you use an ssh: address to connect to a remote display, xpra runs ssh(1) to make the underlying connection. Most installations should now be using paramiko as default backend command. Another common value for CMD is ssh or plink on Microsoft Windows. If your ssh program is in an unusual location, has an unusual name, or you want to pass special options to change ssh's behavior, then you can use the --ssh switch to tell xpra how to run ssh.

For example, if you want to use arcfour encryption, then you should run

--exit-ssh=yes|no

Choose whether the SSH client process should be forcibly terminated when xpra disconnects from the server. If you are using SSH connection sharing, you may want to avoid stopping the SSH master process instance spawned by xpra as it may be used by other SSH sessions. Note: the exit-ssh=no detaches the SSH process from the terminal which prevents the SSH process from interacting with the terminal input, this disables the keyboard interaction required for password input, host key verification, etc..

--remote-xpra=CMD

When connecting to a remote server over ssh, xpra needs to be able to find and run the xpra executable on the remote host. If this executable is in a non-standard location, or requires special environment variables to be set before it can run, then accomplishing this may be non-trivial. If running xpra attach ssh:something fails because it cannot find the remote xpra, then you can use this option to specify how to run xpra on the remote host.

That said, this option should not be needed in normal usage, as xpra tries quite hard to work around the above problems. If you find yourself needing it often, then that may indicate a bug that we would appreciate hearing about.

SSL Options

--ssl=on|auto|off|tcp|www

Whether to enable SSL on TCP sockets and for what purpose. The TCP sockets will automatically be upgraded to SSL when SSL packets are received.

If SSL is enabled, then a ssl-cert is required.

The remaining options mirror the Python ssl module attributes. Please refer to that documentation and bear in mind that configuring SSL for security is not trivial, and definitely not just a matter of enabling SSL. See: https://docs.python.org/2/library/ssl.html Some options may not be available with older versions of Python.

Summary: --ssl-key=KEYFILE The key file to use.

--ssl-cert=CERTFILEORDIR

Certificate file, required for server SSL support.

--ssl-protocol=PROTOCOLVERSION

Specifies which version of the SSL protocol to use.

--ssl-ca-certs=CACERTSFILE

The ca_certs file contains a set of concatenated 'certification authority' certificates. If a directory is specified, it should contain the certificates.

--ssl-ca-data=CERTDATA

Certificate data.

--ssl-ciphers=CIPHERS

Sets the available ciphers, it should be a string in the OpenSSL cipher list format.

--ssl-client-verify-mode=none|optional|required

Whether to try to verify the client's certificates and how to behave if verification fails.

--ssl-server-verify-mode=none|optional|required

Whether to try to verify the server's certificates and how to behave if verification fails.

--ssl-verify-flags=FLAGS

The flags for certificate verification operations.

--ssl-check-hostname=yes|no

Whether to match the peer cert's hostname.

--ssl-options=options

Set of SSL options enabled on this context.