DragonFly On-Line Manual Pages
XPRA(1) DragonFly General Commands Manual XPRA(1)
NAME
xpra - viewer for remote, persistent X applications
SYNOPSIS
xpra start [:DISPLAY] | xpra start ssh:HOST:DISPLAY
[--start-child=CHILD] ... [--env=KEY=VALUE] [--exit-with-children]
[--daemon=yes|no] [--use-display] [--xvfb=CMD]
[--video-encoders=ENCODERS] [--csc-modules=MODULES]
[--pulseaudio=yes|no] [--pulseaudio-command=SERVER START COMMAND]
[--clipboard=yes|no] [--cursors=yes|no] [--notifications=yes|no]
[--xsettings=yes|no] [--system-tray=yes|no] [--bell=yes|no]
[--remote-logging=yes|no] [--sound-source=PLUGIN]
[--speaker=yes|no] [--speaker-codec=CODEC] [--microphone=yes|no]
[--microphone-codec=CODEC] [--sharing=yes|no]
[--bind-tcp=[HOST]:PORT] [--encryption=CIPHER]
[--encryption-keyfile=FILENAME] [--auth=MODULE]
[--tcp-auth=MODULE] [--password-file=FILENAME]
[--idle-timeout=IDLETIMEOUT] [--clipboard-filter-file=FILENAME]
[--dpi=VALUE] [--input-method=METHOD] [--socket-dir=DIR]
[--socket-permissions=ACCESS-MODE] [--mmap-group]
[--tcp-proxy=HOST:PORT] [--html=on|off|[HOST]:PORT]
xpra attach [:DISPLAY | ssh:[USER@]HOST:DISPLAY |
tcp:[USER@]HOST:PORT[:DISPLAY]] [-zLEVEL | --compress=LEVEL]
[--mmap=yes|no] [--windows=yes|no] [--clipboard=yes|no]
[--cursors=yes|no] [--notifications=yes|no] [--xsettings=yes|no]
[--system-tray=yes|no] [--bell=yes|no] [--remote-logging=yes|no]
[--keyboard-sync=yes|no] [--tray=yes|no] [--sound-source=PLUGIN]
[--speaker=on|off|disabled] [--speaker-codec=CODEC]
[--microphone=on|off|disabled] [--microphone-codec=CODEC]
[--delay-tray] [--encoding=ENCODING] [--scaling=on|offSCALING]
[--opengl=yes|no|auto] [--quality=QUALITY]
[--min-quality=MIN-QUALITY] [--speed=SPEED] [--min-speed=MIN-
SPEED] [--auto-refresh-delay=DELAY] [--key-shortcut=KEY:ACTION]
[--readonly=yes|no] [--sharing=yes|no] [--title=VALUE]
[--client-toolkit=TOOLKIT] [--border=BORDER]
[--window-layout=LAYOUT] [--window-icon=FILENAME]
[--tray-icon=FILENAME] [--ssh=CMD] [--exit-ssh=yes|no]
[--remote-xpra=CMD] [--password-file=FILENAME] [--dpi=VALUE]
[--mouse-polling=VALUE] [--socket-dir=DIR] [--pings=yes|no]
[--encryption=CIPHER] [--encryption-keyfile=FILENAME]
xpra shadow [:DISPLAY] | ssh:[USER@]HOST[:DISPLAY] [--start=CMD] ...
[--start-child=CHILD] ... [--env=KEY=VALUE] ...
[--exit-with-children] [--daemon=yes|no] [--clipboard=yes|no]
[--notifications=yes|no] [--bell=yes|no] [--sound-source=PLUGIN]
[--speaker=on|off|disabled] [--speaker-codec=CODEC]
[--microphone=on|off|disabled] [--microphone-codec=CODEC]
[--bind-tcp=[HOST]:PORT] [--auth=MODULE] [--tcp-auth=MODULE]
[--password-file=FILENAME] [--idle-timeout=IDLETIMEOUT]
[--socket-dir=DIR] [--socket-permissions=ACCESS-MODE]
[--mmap-group] [--tcp-proxy=HOST:PORT] [--html=on|off|[HOST]:PORT]
xpra proxy :DISPLAY
xpra stop [:DISPLAY | ssh:[USER@]HOST:DISPLAY | tcp:[USER@]HOST:PORT]
[--ssh=CMD] [--remote-xpra=CMD] [--socket-dir=DIR]
xpra exit [:DISPLAY | ssh:[USER@]HOST:DISPLAY | tcp:[USER@]HOST:PORT]
[--ssh=CMD] [--remote-xpra=CMD] [--socket-dir=DIR]
xpra detach [:DISPLAY | ssh:[USER@]HOST:DISPLAY | tcp:HOST:PORT]
[--ssh=CMD] [--remote-xpra=CMD] [--socket-dir=DIR]
xpra screenshot filename [:DISPLAY | ssh:[USER@]HOST:DISPLAY |
tcp:HOST:PORT] [--ssh=CMD] [--remote-xpra=CMD] [--socket-dir=DIR]
xpra version [:DISPLAY | ssh:[USER@]HOST:DISPLAY | tcp:HOST:PORT]
[--ssh=CMD] [--remote-xpra=CMD] [--socket-dir=DIR]
xpra info [:DISPLAY | ssh:[USER@]HOST:DISPLAY | tcp:HOST:PORT]
[--ssh=CMD] [--remote-xpra=CMD] [--socket-dir=DIR]
xpra control (:DISPLAY | ssh:[USER@]HOST:DISPLAY | tcp:HOST:PORT)
command [arguments..] [--ssh=CMD] [--remote-xpra=CMD]
[--socket-dir=DIR]
xpra initenv [--socket-dir=DIR]
xpra list [--socket-dir=DIR]
xpra upgrade :[DISPLAY] [...any options accepted by xpra start...]
DESCRIPTION
Xpra is a tool which allows you to run X programs -- usually on a
remote host -- and then direct their display to your local machine,
disconnect from these programs, and reconnect from the same or another
machine, all without losing any state. It differs from standard X
forwarding in that it allows disconnection and reconnection without
disrupting the forwarded application; it differs from VNC and similar
remote display technologies in that xpra is rootless: i.e.,
applications forwarded by xpra appear on your desktop as normal windows
managed by your window manager, rather than being all "trapped in a box
together". Xpra also uses a custom protocol that is self-tuning and
relatively latency-insensitive, and thus is usable over network
connections that are too slow or unreliable for standard X forwarding.
Xpra can also be used to shadow an existing X11 display.
By default the Xpra server announces available sessions (username and
display number) via mDNS to the local network. Use mdns=no to disable
it.
CONNECTION STRINGS
Xpra supports 3 types of connection strings:
:DISPLAY
Local displays: this is the simplest form and is only valid for the
current local displays of the current user.
tcp:[USERNAME@]HOST:PORT[:DISPLAY]
TCP mode uses port numbers and not display numbers. If multiple
displays are available through a single TCP port (using a proxy
server), then one can also specify the display number.
ssh/[USERNAME[:PASSWORD]@]HOST[:SSH_PORT]/DISPLAY
SSH mode allows most common connection options to be specified using
the connection string. Further options can be specified using the --ssh
command line option.
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.
The password is only actually used on Microsoft Windows.
EXAMPLES
xpra start :7
Start an xpra server using display number :7.
xpra start ssh:bigbox:7 --start=xterm
Start an xpra server on bigbox with an xterm in it, and connect to
it.
DISPLAY=:7 firefox
Start firefox running inside the xpra server. Run this on the
host where xpra was started or in terminal forwarded by xpra. No
window will appear until you attach with xpra attach.
xpra list
Show a list of xpra servers you have running on the current host.
xpra attach :7
Attach to the xpra server that is using local display number :7.
Any apps running on that server will appear on your screen.
xpra attach ssh:foo@frodo:7
Use ssh to attach to the xpra server that is running on machine
frodo as user foo and using display :7. Any apps running on that
server will appear on your local screen.
xpra start :7 && DISPLAY=:7 screen
Start an xpra server and a screen(1) session. If any of the
applications inside screen attempt to use X, they will be directed
to the xpra server.
DISPLAYS
Understanding the basic idea of displays is critical to using xpra
successfully.
The idea comes from standard X. If you have multiple X servers running
on the same host, then there has to be some way to distinguish them. X
does this by assigning each server a small, unique integer called
(perhaps confusingly) its "display". In the common case of a desktop
machine that has only one X server running, that server uses display
":0" (or sometimes you'll see ":0.0", which is effectively the same).
When an application starts under X, it needs to know how to find the
right X server to use; it does this by checking the environment
variable $DISPLAY.
Xpra faces a similar problem -- there may be multiple xpra servers
running on the same host, as well as multiple X servers. It solves
this problem by re-using X's solution -- each xpra server has a display
associated with it. This display functions as both an X display (for
when xpra is talking to X applications) and as an identifier by which
xpra clients (like xpra attach) can locate the xpra server.
If your xvfb command supports the -displayfd argument, you may set the
displayfd option to true in your /etc/xpra/xpra.conf file (or your
user's ~/.xpra/xpra.conf) and then you may omit the display number when
using xpra start: a display will be chosen for you automatically. The
display number chosen will be shown in the log output, you should also
be able to see it with xpra list.
Otherwise, when starting an xpra server, you must specify the name of
the display to use. To do this, simply pick any number you like and
stick a colon in front of it. For instance :7, :12, and :3117 are all
valid display names. Just keep in mind that:
o Every X or xpra server that is running on a single machine must
use a different display name. If you pick a number that is
already in use then xpra will not work.
o The first few numbers (0, 1, 2) are commonly used by real X
servers.
o Everyone who connects to a given machine using ssh(1) with X
forwarding enabled will also use a display number; ssh generally
picks numbers near ten (10, 11, 12, ...).
When specifying an xpra server to a client program like xpra attach,
xpra detach, xpra stop, xpra exit, xpra version, xpra info, xpra list
or xpra screenshot then you can use a display of the form :DISPLAY to
refer to a server on the local host, or one of the form
ssh:[USER@]HOST:DISPLAY to refer to a server on a remote host; xpra
will automatically connect to the remote host using ssh(1). Generally,
if you have only one xpra session running on a machine (which you can
verify by running xpra list on that machine), then you can omit the
number entirely; xpra attach alone will attach to the lone xpra server
on the current machine regardless of its number, xpra attach ssh:frodo
will similarly attach to the lone xpra session on a remote machine.
If the xpra server was given the --bind-tcp option when started then
you can also connect to it using a display of the form tcp:HOST:PORT.
(Notice that ssh: takes an optional display number, while tcp: takes a
required port number.)
SUBCOMMANDS
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 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. Note: older
servers may not support this feature.
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 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 shadow
This command shadows an existing X11 display. If there is only one X11
display active and its number is below 10, it can be auto-detected.
Note that this mode of operation uses screenscraping which is far less
efficient. Using a video encoder (h264 or vp8) is highly recommended
for this mode of operation.
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.
OPTIONS
General options
--version
Displays xpra's version number.
-h, --help
Displays a summary of command line usage.
-d FILTER1,FILTER2,..., --debug=FILTER1,FILTER2,...
Enable debug logging. The special value all enables all
debugging.
--mmap=yes|no
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.
--windows=yes|no
Enable or disable the forwarding of windows. This is usually the
primary use for xpra and should be enabled.
--clipboard=yes|no
Enable or disable clipboard synchronization. If used on the
server, no clients will be able to use clipboard synchronization
at all. If used on the client, only this particular connection
will ignore clipboard data from the server.
--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
This specifies the image encoding to use, there are a number of
encodings supported: jpeg, png, png/P, png/L, webp, rgb, vp8,
vp9, h264 and h265 (some may not be available in your
environment).
png compressed and lossless, can be quite slow.
png/P compressed and lossy: it uses a colour palette, which
means better compression but still slow.
png/L compressed and lossy: grayscale only using a palette.
rgb a raw pixel format (lossless) compressed with zlib or
lz4, the compression ratio is lower, but it is by far the
fastest encoding available.
webp can be used in lossy or lossless mode, useful for
graphical applications, it compresses better than jpeg
and is reasonably fast except at high resolutions.
jpeg can be useful for graphical applications, it is lossy and
usually very fast.
vp8 lossy video encoding which always uses colour
subsampling. Fast at encoding and decoding.
vp9 Far too slow at encoding, avoid.
h264 Currently the best encoding available: it is fast,
efficient and tunable via the quality and speed options.
h265 Far too slow at encoding, avoid.
The default encoding which is automatically selected if you do not
specify one will depend on what options are available on both the
server and the client: rgb is always available (builtin), jpeg and png
require the Python Imaging Library, vp8, vp9, webp, h264 and h265 all
require their respective shared libraries, as well as the xpra codec
that uses them.
Note: when selecting a video encoding (usually h264 or vp8), some of
the smaller screen updates will be sent using one of the other non-
video encodings.
--scaling=on|offSCALING
How much automatic window downscaling should be used, from 1
(rarely) to 100 (aggressively), 0 to disable. Window scaling is
normally used with large windows (especially full screen
windows) to try to maintain a decent framerate. Window
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.
--opengl=yes|no|auto
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).
--socket-dir=DIR
Location where to write and look for the Xpra socket files.
Defaults to "~/.xpra". 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 on all following commands, for xpra to work
with the open sessions. Mixing different socket-dir options is
not recommended.
By specifying a shared directory this can be coupled with the
mmap-group or socket-permissions option to connect Xpra sessions
across user accounts.
Options for start, 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
prevents that behavior (useful mostly for debugging).
--mdns=yes|no
Enable or disable the publication of new sessions via mDNS.
--auth=MODULE
Specifies the authentication module to use. This can be used to
secure sockets in a different way from the --encryption switch:
authentication modules can validate a username and password
against a variety of backend modules:
allow always allows authentication - this is dangerous and
should only be used for testing
fail always fails authentication, useful for testing
file checks the password against the file specified using
password-file switch or data provided via the
XPRA_PASSWORD environment variable. They can either
contain a single password, in which case it will be used
for all usernames, or a list of user credentials of the
form (one per line):
username|password|uid|gid|displays|env_opts|session_opts
pam validates the username and password using the PAM system
win32 validates the username and password using Microsoft
Windows authentication
sys chooses the most appropriate system authentication module
automatically (either pam or win32)
--tcp-auth=MODULE
Just like the auth switch, except this one only applies to TCP
sockets (sockets defined using the bind-tcp switch).
Options for start, upgrade
--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 children. --start-child=CMD
Identical to --start, except the commands are taken into account
by --exit-with-children.
--env=KEY=VALUE
Extra environment variables which will only affect commands
started using fB--start or fB--start-child.
--exit-with-children
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.
--use-display
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.
--xvfb=CMD
When starting the server, xpra starts a virtual X server to run
the clients on. By default, this is 'Xvfb'. 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
is: Xvfb +extension Composite -screen 0 3840x2560x24+32
-nolisten tcp -noreset -auth $XAUTHORITY
This can also be used to specify Xdummy as an alternative to
Xvfb, this requires Xorg server version 1.12 or later and the
dummy driver version 0.3.5 or later. For more information, see:
https://xpra.org/Xdummy.html
Options for start, upgrade, shadow
--bind-tcp=[HOST]:PORT
The xpra server always listens for connections on a local Unix
domain socket, and supports local connections with the :7-style
display address, and remote connections with the
ssh:frodo:7-style display address. If you want, it can also
listen for connections on a raw TCP socket. This behavior is
enabled with --bind--tcp. 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 using 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. Use it only if you have special needs, and
understand the consequences of your actions.
--tcp-proxy=HOST:PORT
Specifies the address to which non-xpra packets will be
forwarded. This can be used to share the same TCP port with
another TCP servers, usually a web server. xpra clients will
connect as usual, but any client that does not speak the xpra
protocol will be forwarded to the alternative server.
--html=on|off|[HOST]:PORT
Takes care of setting up a web server for the html5 client.
This automatically configures a tcp-proxy pointing to the web
server it starts. If the port is not specified, one is chosen
automatically. You may want to specify a port number or at
least ensure that firewall restrictions are in place, though web
servers are usually public. This requires websockify to be
installed and a single tcp port to be configured using bind-tcp.
--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.
--mmap-group Sets the mmap file's gid to match the socket file's
gid and sets the mmap file's permissions to 660. This is
necessary to share the mmap file across user accounts.
--socket-permissions=ACCESS-MODE
Specifies the permissions on the server socket. Defaults to
600. This is ignored when mmap-group is enabled.
Options for start, upgrade and attach
--password-file=FILENAME
This allows sessions to be secured with a password stored in a
text file. You should use this if you use the --bind-tcp
option. If this is used on the server, it will reject any
client connections that do not provide the same password value.
Instead of using this option, password itself can be provided
via the XPRA_PASSWORD environment variable.
--encryption=CIPHER
Specifies the cipher to use for securing the connection from
prying eyes. This is only really useful with the --bind-tcp
option. This option requires the use of the
--encryption-keyfile option or the XPRA_ENCRYPTION_KEY
environment variable. The only cipher supported at present is
AES, 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.
--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. Instead of using this option, the key can be
provided via the XPRA_ENCRYPTION_KEY environment variable.
--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 the 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.
--mouse-polling=VALUE
How often to poll the mouse position when the cursor is not
hovering over one of our windows, this is measured in seconds.
If you do not wish the server to be able to have a rough
overview of your mouse movements, or if you simply wish to
disable the feature, use the special value '0'.
--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:
none Disable input methods completely and prevent it from
interfering with keyboard input. This is the default.
keep Keeps the environment unchanged. You are responsible for
ensuring it is correct.
xim Enables the X Input Method.
IBus Enables the Intelligent Input Bus.
SCIM Enables the Smart Common Input Method.
uim Enables the Universal Input Method.
Any other value will also be set up, but will trigger a warning.
--xsettings=yes|no
Enable or disable xsettings synchronization. Xsettings are only
forwarded from posix clients connecting to real posix servers
(not shadows).
--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.
--remote-logging=yes|no
Allow the client to forward its log output to the server.
Options for attach
-zLEVEL, --compress=LEVEL
Select the level of zlib compression xpra will use when
transmitting data over the network. Higher levels of
compression transmit less data over the network, but use more
CPU power. Valid options are between 0 (meaning no compression)
and 9, inclusive. Higher levels take progressively more CPU
while giving diminishing returns in terms of actual compression
achieved; the default is 3, which gives a reasonable trade-off
in general. If lz4 compression is available, it will be enabled
when the level is set to 1, lz4 compresses a lot less than zlib
but it is also much faster.
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. 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.
--min-quality=MIN-QUALITY
This option sets the minimum encoding quality allowed when the
quality option is set to automatic mode.
--speed=SPEED
This option sets the encoding speed. Slower compresses more,
faster will give better latency. The system normally uses a
variable speed, this option forces a fixed speed setting to be
used instead.
--min-speed=MIN-SPEED
This option sets the minimum encoding speed allowed when the
speed option is set to automatic mode.
--auto-refresh-delay=DELAY
This option sets a delay after which the windows are
automatically refreshed using a lossless frame. The delay is a
floating-point number and is in seconds. This option is enabled
by default with a delay of 1 second. This option is only
relevant when using a lossy encoding with a quality lower than
95%.
--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 to the server.
The KEY specification may include keyboard modifiers in the form
[modifier+]*key, for example: Shift+F10 or Shift+Control+B
If no shortcuts are defined on the command line, the following
default one will be used: Meta+Shift+F4:quit
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 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:
quit Disconnect the xpra client.
log("MESSAGE")
Sends MESSAGE to the log.
show_session_info[("TabName")]
Shows the session information window. The optional
TabName allows the information tab shown to be selected.
Use the value help to get the list of options.
show_start_new_command
Shows the start new command dialog.
magic_key
Placeholder which can be used by some window layouts.
void Does not do anything, and can therefore be used to
prevent certain key combinations from ever being sent to
the server.
refresh_window
Force the currently focused window to be refreshed.
refresh_all_windows
Force all windows to be refreshed.
--readonly=yes|no
Read only mode prevents all keyboard and mouse activity from
being sent to the server.
--sharing=yes|no
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.
--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.).
--sound-source=LUGIN
Specifies the GStreamer sound plugin used for capturing the
sound 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: --sound-source=pulse
device=device.alsa_input.pci-0000_00_14.2.analog-stereo
--speaker=on|off|disabled and --microphone=on|off|disabled
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.
--speaker-codec=CODEC and --microphone-codec=CODEC
Specify the codec(s) to use for sound 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:
@title@
Will be replaced by the remote window's title.
@client-machine@
Will be replaced by the remote server's hostname.
--client-toolkit=TOOLKIT
Specifies the client toolkit to use. This changes the user
interface toolkit used to draw the windows and may affect the
availability of other features. The 'gtk2' toolkit is the one
with the most features. Use the special value 'help' to get a
list of options.
--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-layout=LAYOUT
Specifies how main windows are drawn, this can be used to add
widgets or use custom code. Use the special value 'help' to get
a list of options. Each client toolkit may or may not provide
different window layouts.
--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.
--tray=yes|no
Enable or disable the system tray. Not available on OSX since
the dock icon is always shown.
--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. By default,
it does this by running the command "ssh". 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
xpra attach --ssh="ssh -c arcfour" ssh:frodo:7
Note: Don't bother to enable ssh compression; this is redundant
with xpra's own compression, and will just waste your CPU. See
also xpra's --compress switch.
On MS Windows, where backslashes are used to separate path
elements and where spaces are often used as part of paths, you
need to add quotes around paths. (ie: ssh="C:\Program
Files\Xpra\Plink.exe" -ssh -agent)
--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.
ENVIRONMENT
DISPLAY
xpra start --start-child=... sets this variable in the
environment of the child to point to the xpra display.
xpra attach, on the other hand, uses this variable to determine
which display the remote applications should be shown on.
XPRA_PASSWORD Can be used to specify the password (or user and
password list) as an alternative to a password file. If
--password-file is also specified, this environment variable is
ignored.
XPRA_ENCRYPTION_KEY Can be used to specify the encryption key to
use if encryption is enabled. Specifying the key on its own
does not enable encryption. If --encryption-keyfile is also
specified, this environment variable is ignored.
FILES
xpra.conf stores default values for most options. There is a global
config file in /etc or /usr/local/etc, and each user may override it
using .xpra/xpra.conf. Xpra uses the directory ~/.xpra to store a
number of files. (The examples below are given for the display :7.)
~/.xpra/:7
The unix domain socket that clients use to contact the xpra
server.
~/.xpra/:7.log
When run in daemon mode (the default), the xpra server directs
all output to this file. This includes all debugging output, if
debugging is enabled.
~/.xpra/run-xpra
A shell script that, when run, starts up xpra with the correct
python interpreter, PYTHONPATH, PATH, location of the main xpra
script, etc. Automatically generated by xpra start and used by
xpra attach (see also the discussion of --remote-xpra).
BUGS
Xpra has no test suite.
Xpra does not fully handle all aspects of the X protocol; for instance,
fancy input features like pressure-sensitivity on tablets, some window
manager hints, and probably other more obscure parts of the X protocol.
It does, however, degrade gracefully, and patches for each feature
would be gratefully accepted.
The xpra server allocates an over-large framebuffer when using Xvfb;
this wastes memory, and can cause applications to misbehave (e.g., by
letting menus go off-screen). Conversely, if the framebuffer is ever
insufficiently large, clients will misbehave in other ways (e.g., input
events will be misdirected). This is not a problem when using Xdummy,
see the --xvfb= switch for details.
REPORTING BUGS
Send any questions or bugs reports to <antoine@devloop.org.uk>.
SEE ALSO
screen(1) winswitch_applet(1)
XPRA(1)