xpra icon
Bug tracker and wiki

This bug tracker and wiki are being discontinued
please use https://github.com/Xpra-org/xpra instead.

Version 12 (modified by Antoine Martin, 8 years ago) (diff)


Proxy Server


This new feature in version 0.11 (see #426) allows a single xpra server to provide access to many xpra sessions through a single entry point, without using SSH for transport/authentication.

This can be very useful for hosts that have a limited number of publicly accessible ports, or for clients accessing servers through firewalls with outbound port filtering. (ie: you can put the server on port 80 or 443) It can also be combined with the --tcp-proxy option to share the same TCP port with another server (ie: a web server): the non-xpra traffic will be forwarded to the destination of your choice.

Depending on the Authentication module configured, the proxy server can expose:

  • all local xpra sessions after user authentication
  • a custom list of sessions configured through the "file-auth" mechanism

Basic Usage

Beware: to simplify these instructions, we use the "allow" authentication module, which does no checking whatsoever!

To start the proxy server, simply run:

xpra proxy :20 --auth=allow --bind-tcp=

If only one session is accessible, users can connect as usual with:

xpra attach tcp:USERNAME@PROXYHOST:443

If there is more than one session accessible for this user, the client also needs to specify which display it wishes to connect to, using one of those two switches:

  • the "--display=:N" switch
  • the extended attach syntax: "tcp:USERNAME@SERVER:PORT:DISPLAY


xpra attach tcp:john@ --display=:100


  • if you run this command as root, all the user sessions will be exposed!
  • if you run it a normal user, only this user's session will be exposed
  • once authenticated, the proxy server spawns a new process and no longer runs as root
  • the display number chosen for the proxy server is only used for identifying the proxy server and interacting with it using the regular tools ("xpra info", etc)

File Authentication

When used with the proxy server, the password file (see Authentication Modules) should contain one user per line using the format:



  • USERNAME and PASSWORD are used for authentication
  • UID and GID are used for the new proxy process (and can be set to nobody)
  • SESSION_URI is the usual xpra connection string of the actual target session, ie:
  • ENV_VARS is an optional attribute which can contain ";" separated name-value pairs which will affect the environment of the new process spawned after authentication.
  • SESSION_OPTIONS is an optional attribute which can contain ";" separated name-value pairs which will override the client's connection settings and apply to the connection between the proxy and the real server only.

Detailed Example

  • Start a proxy server on port 443 using the "file" authentication module (we will call this server PROXYHOST):
    xpra proxy :100 --bind-tcp= --auth=file --password-file=./xpra-auth
  • Start the session we wish to access via the PROXYHOST (we call this TARGETHOST - for testing, this can be the same host as PROXYHOST):
    xpra start :10 --bind-tcp=
  • on PROXYHOST, add a user to the auth file pointing to TARGETHOST (ie: should be TARGETHOST's IP):
    echo "john|secretpassword|1000|1000|tcp:|EXAMPLE_ENV=VALUE|compression=0" >> ./xpra-auth
  • create the password file on the client:
    echo "secretpassword" >> password.txt
  • connect the client to the proxy server:
    xpra attach --username=myusername --password-file=./password.txt $PROXYHOST:443

What happens:

  • the client connects to the proxy server
  • the proxy server asks the client to authenticate and sends it a challenge
  • the client responds to the challenge (see wiki/Authentication)
  • the proxy server verifies the challenge (and disconnects the user if needed)
  • the proxy server identifies the session desired (ie: the one on TARGETHOST)
  • the proxy server creates a new connection to the real server (TARGETHOST), applying any options specified (ie: "compression=0" will disable compression between the proxy and server)
  • the proxy server spawns a new process
  • the new proxy process changes its uid and gid to non-root (if needed)
  • the packets should now flow through between the client and the real server

Attachments (1)

Download all attachments as: .zip