nginx proxy issues and documentation

[totaam]

This is a tracker ticket for a number of issues that manifest themselves with proxy servers (Xpra-org/xpra-html5#317, Xpra-org/xpra-html5#328, Xpra-org/xpra-html5#299 (comment), #3958 (comment), #1349 (comment)) which highlights the need for better proxy setup documentation, specifically for nginx.

We already have documentation for apache: https://github.com/Xpra-org/xpra/blob/master/docs/Usage/Apache-Proxy.md

[totaam]

Starting with the most basic config:

• generate SSL certs sudo /usr/bin/xpra setup-ssl
• start xpra on tcp port 10000: xpra seamless xterm --bind-tcp=127.0.0.1:10000
• Use this very basic unauthenticated config (works with nginx 1.26.2):

events {
}

http {
	map $http_upgrade $connection_upgrade {
		default upgrade;
		''      close;
	}

	server {
		listen 443 ssl;
		listen 80; 

		root /usr/share/xpra/www;

		ssl_certificate /etc/xpra/ssl/ssl-cert.pem;
		ssl_certificate_key /etc/xpra/ssl/key.pem;

		location / {
			proxy_pass http://127.0.0.1:10000;
			
			proxy_http_version 1.1;
			proxy_buffering off;
			proxy_cache_bypass $http_upgrade;
		        proxy_set_header Upgrade $http_upgrade;
		        proxy_set_header Connection "Upgrade";
	        	proxy_set_header Host $host;
		}
	}
}

sudo nginx -c /usr/share/nginx/nginx-basic.conf  

And open: http://localhost/ or https://localhost/

[totaam]

Upstream documentation: https://nginx.org/en/docs/http/websocket.html

Settings that may be relevant or useful:

• proxy_connect_timeout could be set lower, an xpra server should never take 60 seconds to accept a connection - assuming that the server is already started and not too many hops away, then 10 seconds should be plenty - this is different from actual sending / receiving:
• proxy_read_timeout / proxy_send_timeout should be set higher than 60 seconds, just in case pings don't manage to keep the connection open - this does apply to websocket connections
• proxy_socket_keepalive should be enabled?
• keepalive_time and keepalive_timeout - should be irrelevant for websocket connections? see compared with tcp keepalive
• send_timeout - does this affect websockets?
• tcp_nodelay is already enabled for websockets
• tcp_nopush - irrelevant as we don't use sendfile
• proxy_buffer_size should be irrelevant since we have proxy_buffering off;
• proxy_pass - test with unix sockets?
• proxy_ignore_client_abort could be set to off explicitly to ensure this is never enabled, as it could cause problems / waste resources
• proxy_no_cache / proxy_cache_bypass: perhaps add proxy_cache_bypass $http_upgrade;? is this really useful? surely websocket upgrades can't be cached?
• proxy_set_header X-Forwarded-Ssl on; / X-Forwarded-Proto - maybe the xpra server could be told to accept that the connection is actually encrypted (as a socket option?) - albeit only between the proxy and the client, rather than end to end - which is acceptable for some configurations
• proxy_ssl_verify - for self signed certs in trusted zone instead of dealing with proxy_ssl_certificate*
• proxy_intercept_errors useful for diagnostics?
• client_max_body_size - needs to be increased to allow large file transfers? (surely this does not apply to websocket packets?)
• limit_except should be set, to protect the xpra server from unwanted requests
• limit_rate* could be useful for stress testing
• add an example setup with static html / css files served by nginx and only the websocket path forwarded to xpra
• a number of posts suggest adding proxy_set_header Connection ""; to prevent a Connection close header from being sent to the proxied server, but I doubt this would make any difference to an xpra server

---

QUIC with nginx #3376 : this won't use QUIC to the xpra server, and unlikely to support WebTransport either.

[totaam]

The new nginx documentation page can be found here:
https://github.com/Xpra-org/xpra/blob/master/docs/Usage/Nginx-Proxy.md