Context Navigation

Proxy Server

Introduction

For information on the "system wide proxy server", please see wiki/Service.

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.

This proxy server can also be used as a system-wide proxy server so that sessions are started with enough privileges to register as logind sessions (#1105), allowing them to outlive the user's session. (KillUserProcesses=yes)

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 the video encoding, the real servers just forward raw uncompressed pixel data to it. (see #504)

It can also be combined with the TCP Socket Sharing option to share the same TCP port with another server (ie: a web server), it can also use SSL encryption (see wiki/Encryption/SSL). The proxy server can also provide access to the HTML5 client, for all sessions.

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 sqlite and multifile authentication modules

Diagram

Here is an example architecture using the proxy server to provide access to a number of servers through a single port, also showing where NVENC hardware encoders and TCP proxying (apache, nginx, thttp,..) can all hook into:

Basic Usage

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

start a session on display :100 with an xterm, this session is not exposed via tcp (there is no bind-tcp option):

xpra start :100 --start=xterm

start a proxy server available on tcp port 14501:

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

if only one session exists for this user, you can connect via the proxy with:

xpra attach tcp://:foo@PROXYHOST:14501/

If there is more than one existing 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:PASSWORD@SERVER:PORT/DISPLAY":

xpra attach tcp://:foo@PROXYHOST:14501/100

Notes:

this example uses tcp, but the proxy works equally well with all other transports (ssl, wss etc)

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)

Authentication

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

Stopping

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

etc..

Remote Hosts

This example uses a sqlite database to expose two remote server instances accessible from the proxy server via tcp.

Start two sessions we wish to access via the PROXYHOST (we call this TARGETHOST - for testing, this can be the same host as PROXYHOST):