NAME
xpra - viewer for remote, persistent X applications
SYNOPSIS
xpra start :DISPLAY [--start-child=CHILD] ... [--exit-with-children]
[--no-daemon] [--bind-tcp=[HOST]:PORT]
xpra attach [:DISPLAY | ssh:HOST:DISPLAY | tcp:HOST:DISPLAY]
[--remote-xpra=CMD]
xpra stop [:DISPLAY | ssh:HOST:DISPLAY | tcp:HOST:DISPLAY]
[--remote-xpra=CMD]
xpra list
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.
EXAMPLES
xpra start :7
Start an xpra server using display number :7.
DISPLAY=:7 firefox
Start firefox running inside the xpra server. No window will
appear.
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:frodo:7
Use ssh to attach to the xpra server that is running on machine
frodo 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 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.
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:
· 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.
· The first few numbers (0, 1, 2) are commonly used by real X
servers.
· 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 or
xpra stop, then you can use a display of the form :NUMBER to refer to a
server on the local host, or one of the form ssh:HOST:NUMBER 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 server
running on a 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 server on a remote machine.
If the xpra server was given the --bind-tcp option when started (which
is a major security risk, and not recommended!), 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.
xpra attach
This command attachs to a running xpra server, and forwards any
applications using that server to appear on your current screen.
xpra stop
This command attachs to a running xpra server, and requests that it
terminate immediately. This generally causes any applications using
that server to terminate as well.
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.
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; alternatively, debugging logs for particular systems
can be enabled by specifying one or more filters (separated by
commas). In general, check the source to determine filter names
— but they will look something like xpra.protocol.raw or
wimpiggy (wimpiggy is the name of one of xpra’s underlying
libraries). A filter like xpra.protocol.raw is more specific
than one like xpra.protocol.
Options for start, upgrade
--start-child=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.
--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.
--no-daemon
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).
Options for attach, stop
--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.
Using this switch is NOT RECOMMENDED, and is a major security risk!
Xpra does not do any checking on incoming connections; anyone at
all may connect to this port and access your desktop. Use it
only if you have special needs (e.g., certain virtualization
environments), and understand the consequences of your actions.
Options for start
--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 --with-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.
FILES
Xpra uses the directory ~/.xpra to store a number of files.
~/.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,
as of March 2009 it does not yet forward custom cursors, beeps, 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 mapping between local and remote keyboard events is not very
robust; in particular, it is possible in some situations for modifier
keys to get "stuck" in xpra, and it is usually impossible to type
characters outside of the standard US keyboard range.
The xpra server allocates an over-large framebuffer; 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).
The need to choose display numbers by hand is annoying.
REPORTING BUGS
Send any questions or bugs reports to <parti-discuss@partiwm.org>.
SEE ALSO
screen(1)