xpra

XPRA(1)                                                                XPRA(1)



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 suc‐
       cessfully.

       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 (per‐
       haps  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 vari‐
       able $DISPLAY.

       Xpra faces a similar problem — there may be multiple xpra servers  run‐
       ning  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 dis‐
       play (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 con‐
       nect 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 num‐
       ber.)

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 appli‐
       cations 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  cur‐
       rent 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 debug‐
              ging; alternatively, debugging logs for particular  systems  can
              be  enabled by specifying one or more filters (separated by com‐
              mas).  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 termi‐
              nate 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 lis‐
              ten 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 spe‐
              cial 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 environ‐
              ment 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 man‐
       ager 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 char‐
       acters outside of the standard US keyboard range.

       The  xpra  server allocates an over-large framebuffer; this wastes mem‐
       ory, 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 .

SEE ALSO
       screen(1)



                                                                       XPRA(1)