Linux Certif

Toute la documentation sur la certification Linux LPI

xpra

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)