NAME¶

xpra - viewer for remote, persistent X applications

SYNOPSIS¶

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 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 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.

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; alternatively, debugging logs for particular subsystems 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. Additionally, logging can be disabled for a specific subsystem by prefixing a minus sign to its name, like so: --debug=all,-wimpiggy.

--no-mmap

Disables 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 context switches.

--no-clipboard

Disables 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.

--no-pulseaudio

Disables pulseaudio information echange. If used on the server, no clients will be able to set the pulseaudio cookies seen by the application running within xpra. If used on the client, only this particular connection will avoid sending pulseaudio cookies and information to the server.

 

Note: what the application does with this information is beyond the scope of this document.

--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, rgb24, vpx and x264 (some may not be available in your environment). The default is generally png, if available. png is compressed and lossless, it is more efficient than rgb24 (rather inefficient, it is compressed with zlib, see the --compress option). jpeg can be useful for graphical applications (see --jpeg-quality below). vpx and x264 are both lossy and are very efficient with graphics or high framerate applications, x264 is also very usable with text.

 

When specifying this option on the server, it will act as default for clients that do not specify which encoding they want to use.

 

jpeg and png require the Python Imaging Library. vpx and x264 require their respective shared libraries.

--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 option to connect Xpra sessions across user accounts.

 

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).

--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

--no-randr

Disables X11 randr support. The X11 randr extensions allows the virtual display to be resized to match the client's screen dimensions. The default xvfb command (Xvfb) does not support randr, so using this switch will have no effect unless a different xvfb is used (like Xdummy).

--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 password 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.

--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.

 

Options for attach¶

-zLEVEL, --compress=LEVEL

Select the level of 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. You generally do not need to use this option, the default value should be adequate in almost all cases.

 

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

--jpeg-quality=VALUE

This option sets the JPEG compression quality of pixel data sent by the server, jpeg must first be enabled with --encoding=jpeg. The valid values range from 0 (lowest quality, high compression - generally unusable) to 100 (highest quality, low compression - not particularly useful). (requires jpeg encoding)

--auto-refresh-delay=DELAY

This option sets a delay after which the windows are automatically refreshed. The delay is a floating-point number and is in seconds. This option is disabled by default. If using the jpeg encoding, for which this switch was designed, the refresh will override the current jpeg quality encoding and it will use an almost lossless quality setting of 95%.

--max-bandwidth=BW

Specify the link's maximal receive bandwidth. Xpra will adjust the JPEG quality to match this bandwidth. Specify 0.0 (default) to disable. (requires jpeg encoding)

--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

 

The following actions are currently defined:

If no shortcuts are defined on the command line, the following default one will be used: Meta+Shift+F4:quit

--readonly

Read only mode prevents all keyboard and mouse activity from being sent to the server.

--no-keyboard-sync

Disables keyboard state synchronization. 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. Using this option can prevent keys from repeating unexpectedly on high latency links but it may also disrupt applications which access the keyboard directly (games, etc).

--title-suffix=VALUE

Sets the portion of text which is appended to the windows' title. This option is deprecated and --title should be used instead.

--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. ie:
@title@ will be replaced by the remote window's title,
@client-machine@ will be replaced by the remote server's hostname.

 

The default value used is "@title@ on @client-machine@".

--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. --no-tray Disables the system tray. Not available on OSX since the dock icon is always shown. --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)

--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. --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¶

--ssh=fICMD

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

 

--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.

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 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. The need to choose display numbers by hand is annoying.

REPORTING BUGS¶

Send any questions or bugs reports to <antoine@nagafix.co.uk>.

SEE ALSO¶

screen(1) winswitch_applet(1)