Provided by: xpra_0.0.7.36+dfsg-1_amd64 bug

NAME

       xpra - viewer for remote, persistent X applications

SYNOPSIS

       xpra   start  :DISPLAY  [--start-child=CHILD]  ...   [--exit-with-children]  [--no-daemon]
            [--use-display]   [--xvfb=CMD]   [--no-randr]   [--no-clipboard]    [--no-pulseaudio]
            [--bind-tcp=[HOST]:PORT] [--password-file=filename]
       xpra  attach  [:DISPLAY  |  ssh:HOST:DISPLAY | tcp:HOST:PORT] [-zLEVEL | --compress=LEVEL]
            [--no-mmap] [--disable-mmap] [--no-clipboard] [--no-pulseaudio]  [--no-keyboard-sync]
            [--no-tray] [--encoding=ENCODING] [--jpeg-quality=VALUE] [--auto-refresh-delay=DELAY]
            [--max-bandwidth=BW] [--key-shortcut=key:action] [--readonly]  [--title-suffix=VALUE]
            [--title=VALUE]     [--window-icon=FILENAME]    [--tray-icon=filename]    [--ssh=CMD]
            [--remote-xpra=CMD] [--password-file=filename]
       xpra stop [:DISPLAY | ssh:HOST:DISPLAY | tcp:HOST:PORT] [--ssh=CMD] [--remote-xpra=CMD]
       xpra detach [:DISPLAY | ssh:HOST:DISPLAY | tcp:HOST:PORT] [--ssh=CMD] [--remote-xpra=CMD]
       xpra  screenshot  filename  [:DISPLAY  |  ssh:HOST:DISPLAY  |  tcp:HOST:PORT]  [--ssh=CMD]
            [--remote-xpra=CMD]
       xpra version [:DISPLAY | ssh:HOST:DISPLAY | tcp:HOST:PORT] [--ssh=CMD] [--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 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 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.  --disable-mmap Deprecated, please use  --no-mmap
              instead.

       --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 3 options: jpeg, png and rgb24.
              The  default  is  rgb24.  jpeg  can  be  useful  for  graphical  applications  (see
              --jpeg-quality  below).  png  is  compressed  but  also  lossless so it can be used
              instead of rgb24  (which  is  inefficent  without  the  --compress  option).   When
              specifying  this  option  on the server, it will act as default for clients that do
              not specify which encoding they want to be using.  jpeg and png require the  Python
              Imaging Library.

   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 -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. Over local 100Mbs+ networks  the  CPU  can  easily
              become the bottleneck on xpra's speed, and -z0 is therefore recommended.

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

              quit   disconnects the xpra client

              void   does  not  do  anything,  and  can  therefore be used to prevent certain key
                     combinations from ever being sent to the server.

              refresh_window
                     forces the currently focused window to be refreshed.

              refresh_all_windows
                     forces all windows to be refreshed.

       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 This options applies to Mac OS X and  Microsoft
              Windows  only  and  it  allows the icon shown in the dock/tray to be specified.  By
              default it uses a simple default 'xpra' icon if it finds it.  (on Windows, the icon
              must be in ico format)

   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

                     xpra attach --ssh="ssh -c arcfour" ssh:frodo:7

              (Note: don't bother to enable ssh compression; this is redundant  with  xpra's  own
              compression, and will just waste your CPU. See also xpra's --compress switch.)

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

                                                                                          XPRA(1)