This feature allows a single xpra server to provide access to many xpra sessions through a single entry point, without using SSH for transport/authentication. (see #426 for details)
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)
You can also configure your proxy server to start new sessions on demand, see #1319 for details.
Another important use-case is servers with hardware accelerated encoding devices (via NVENC), the proxy server can be used to share this device with many servers: the proxy does encoding, the real servers just forward raw RGB data to it. (see #504)
Depending on the Authentication module configured, the proxy server can:
- expose all local xpra sessions after user authentication
- provide access to a custom list of sessions configured through the "multifile" auth mechanism
- start new sessions on demand (#1319)
(see also wiki/DataFlow)
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=0.0.0.0:443
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 the extended attach syntax: "
tcp/USERNAME@SERVER:PORT/DISPLAY or the display command line option:
xpra attach tcp:email@example.com:443 --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)
When used with the proxy server, the password multifile (see Authentication Modules) should contain one user per line using the format:
PASSWORDare used for authentication
GIDare used for the new proxy process (and can be set to
SESSION_URIis the usual xpra connection string of the actual target session, ie:
ENV_VARSis an optional attribute which can contain ";" separated name-value pairs which will affect the environment of the new process spawned after authentication.
SESSION_OPTIONSis 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.
Info and Control
When the client requests information from the server (ie: for the session info dialog or for internal use), the requests are passed through the proxy instance to the real server just like other packets, but the response is augmented with some extra information from the proxy server. (it is prefixed to prevent any interference)
Just like any other xpra server instance, a proxy instance can be also be queried directly. Since proxy instances do not have their own display number, each proxy instance will create a socket using the process ID instead (ie:
:proxy-15452), you can find their names using
You can stop the proxy server just like any other servers with
xpra stop :$PROXYDISPLAY.
If you want to stop an individual proxy connection instead, you must identify the proxy instance that you want to stop then use
xpra stop :proxy-$PROXYPID.
You can identify proxy instances in a number of ways:
- using system network tools that list processes and the hosts they are connected to (ie: lsof, netstat)
- using "xpra info" on a specific proxy instance
- from the proxy server log file
- from the proxy instance log file
- Start a proxy server on port 443 using the "
multifile" authentication module (we will call this server
xpra proxy :100 --bind-tcp=0.0.0.0:443 --auth=multifile:filename=./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
xpra start :10 --bind-tcp=0.0.0.0:10000
PROXYHOST, add a user to the auth file pointing to
echo "john|secretpassword|1000|1000|tcp:192.168.1.200:10000|EXAMPLE_ENV=VALUE|compression=0" >> ./xpra-auth
- create the password file on the client:
echo -n "secretpassword" > password.txt
- connect the client to the proxy server:
xpra attach --username=myusername --password-file=./password.txt $PROXYHOST:443
- 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
- 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
- see also 1264#comment:3 for authentication between proxy and server
- in version 1.0 with multifile, you can omit the uid and gid and the special user / group "nobody" will be used (posix servers only)
- in version 1.0 with multifile, you can specify the uid and gid using their names (ie: uid="joe", gid="users", posix servers only)
- see #1319 for starting new sessions via the proxy (posix servers only)