root / xpra.1

.\" Man page for xpra
.\"
.\" Copyright (C) 2008 Nathaniel Smith <njs@pobox.com>
.\"
.\" You may distribute under the terms of the GNU General Public
.\" license, either version 2 or (at your option) any later version.
.\" See the file COPYING for details.
.\"
.TH XPRA 1
.SH NAME
xpra \- viewer for remote, persistent X applications
.\" --------------------------------------------------------------------
.SH SYNOPSIS
.PD 0
.HP \w'xpra\ 'u
\fBxpra\fP \fBstart\fP \fI:DISPLAY\fP [\fB\-\-start\-child=CHILD\fP]\fB .\|.\|.\fP [\fB\-\-exit\-with\-children\fP] [\fB\-\-no\-daemon\fP]
.HP
\fBxpra\fP \fBattach\fP [\fI:DISPLAY\fP | \fIssh:HOST:DISPLAY\fP] [\fB\-\-remote\-xpra=CMD\fP]
.HP
\fBxpra\fP \fBstop\fP [\fI:DISPLAY\fP | \fIssh:HOST:DISPLAY\fP] [\fB\-\-remote\-xpra=CMD\fP]
.HP
\fBxpra\fP \fBlist\fP
.HP
\fBxpra\fP \fBupgrade\fP \fI:DISPLAY\fP [\fB\-\-no\-daemon\fP]
.PD
.\" --------------------------------------------------------------------
.SH DESCRIPTION
Xpra is a tool which allows you to run X programs \(em usually on a
remote host \(em 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 \fIrootless\fP: 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 worse links than standard X.
.\" --------------------------------------------------------------------
.SH EXAMPLES
.TP \w'xpra\ 'u
\fBxpra start\fP \fI:7\fP
Start an xpra server using display number \fI:7\fP.
.TP
\fBDISPLAY=\fP\fI:7 firefox\fP
Start \fIfirefox\fP running inside the xpra server.  No window will
appear.
.TP
\fBxpra list\fP
Show a list of xpra servers you have running on the current host.
.TP
\fBxpra attach\fP \fI:7\fP
Attach to the xpra server that is using local display number \fI:7\fP.
Any apps running on that server will appear on your screen.
.TP
\fBxpra attach\fP \fIssh:frodo:7\fP
Use ssh to attach to the xpra server that is running on machine
\fIfrodo\fP and using display \fI:7\fP.  Any apps running on that
server will appear on your local screen.
.TP
\fBxpra start\fP \fI:7\fP \fB&& DISPLAY=\fP\fI:7\fP \fBscreen\fP
Start an xpra server and a \fBscreen\fP(1) session.  If any of the
applications inside screen attempt to use X, they will be directed to
the xpra server.
.\" --------------------------------------------------------------------
.SH 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 (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 \fB$DISPLAY\fP.

Xpra faces a similar problem \(em 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 \(em 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 \fBxpra attach\fP) 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 \(em :7, :12, :3117, etc., are all valid display names.
Just keep in mind that:
.IP \(bu
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.
.IP \(bu
The first few numbers (0, 1, 2) are commonly used by real X servers.
.IP \(bu
Everyone who connects to a given machine using \fBssh\fP(1) with X
forwarding enabled will also use a display number; ssh generally picks
numbers near ten (10, 11, 12, ...).
.PP
When specifying an xpra server to a client program like \fBxpra
attach\fP or \fBxpra stop\fP, then you can use a display of the form
\fB:\fP\fINUMBER\fP to refer to a server on the local host, or one of
the form \fBssh:\fP\fIHOST\fP\fB:\fP\fINUMBER\fP to refer to a server
on a remote host; xpra will automatically connect to the remote host
using \fBssh\fP(1).  Generally, if you have only one xpra server
running on a machine, then you can omit the number entirely; \fBxpra
attach\fP alone will attach to the lone xpra server on the current
machine regardless of its number, \fBxpra attach ssh:frodo\fP will
similarly attach to the lone xpra server on a remote machine.
.\" --------------------------------------------------------------------
.SH SUBCOMMANDS
.SS xpra start
This command starts a new xpra server, including any necessary setup.
.SS xpra attach
This command attachs to a running xpra server, and forwards any
applications using that server to appear on your current screen.
.SS 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.
.SS xpra list
This command finds all xpra servers that have been started by the
current user on the current machine, and lists them.
.SS 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 \fBxpra attach\fP
command will exit and need to be restarted.
.\" --------------------------------------------------------------------
.SH OPTIONS
.SS General options
.TP
\fB\-\-version\fP
Displays xpra's version number.
.TP
\fB\-h, \-\-help\fP
Displays a summary of command line usage.
.TP
\fB\-d\fP \fIFILTER1,FILTER2,...\fP, \fB\-\-debug=\fP\fIFILTER1,FILTER2,...\fP
Enable debug logging.  The special value \fBall\fP 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 \(em but they will
look something like \fBxpra.protocol.raw\fP or \fBwimpiggy\fP
(wimpiggy is the name of one of xpra's underlying libraries).  A
filter like \fBxpra.protocol.raw\fP is more specific than one like
\fBxpra.protocol\fP.
.SS Options for start, upgrade
.TP
\fB\-\-start\-child=\fP\fICMD\fP
After starting the server, runs the command \fICMD\fP 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.
.TP
\fB\-\-exit\-with\-children\fP
This option may only be used if \fB\-\-start\-child\fP is also
given.  If it is given, then the xpra server will monitor the status
of the children started by \fB\-\-start\-child\fP, and will
automatically terminate itself when the last of them has exited.
.TP
\fB\-\-no\-daemon\fP
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).
.SS Options for attach, stop
.TP
\fB\-\-remote\-xpra=\fP\fICMD\fP
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 \fBxpra attach ssh:something\fP
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.
.\" --------------------------------------------------------------------
.SH ENVIRONMENT
.TP
\fBDISPLAY\fP
\fBxpra start --with-child=...\fP sets this variable in the
environment of the child to point to the xpra display.

\fBxpra attach\fP, on the other hand, uses this variable to determine
which display the remote applications should be shown on.
.\" --------------------------------------------------------------------
.SH FILES
Xpra uses the directory \fI~/.xpra\fP to store a number of files.
.TP
\fI~/.xpra/:7\fP
The unix domain socket that clients use to contact the xpra server.
.TP
\fI~/.xpra/:7.log\fP
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.
.TP
\fI~/.xpra/run-xpra\fP
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 \fBxpra start\fP and used by \fBxpra
attach\fP (see also the discussion of \fB\-\-remote\-xpra\fP).
.\" --------------------------------------------------------------------
.SH BUGS
Xpra has no test suite.

Xpra does not fully handle all aspects of the X protocol; for
instance, as of September 2008 it does not yet forward window icons,
clipboards, 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.
.\" --------------------------------------------------------------------
.SH REPORTING BUGS
Send any questions or bugs reports to <parti-discuss@partiwm.org>.
.\" --------------------------------------------------------------------
.SH SEE ALSO
\fBscreen\fP(1)