From bffe71501a9be468cb0e31d8e607bd02ace3cc81 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Tue, 3 Jun 2025 23:01:48 +0000 Subject: Add proxy-server documentation Signed-off-by: Laurent Bercot --- doc/proxy-server.html | 141 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 doc/proxy-server.html (limited to 'doc/proxy-server.html') diff --git a/doc/proxy-server.html b/doc/proxy-server.html new file mode 100644 index 0000000..8363b86 --- /dev/null +++ b/doc/proxy-server.html @@ -0,0 +1,141 @@ + + + + + + s6-networking: the proxy-server program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The proxy-server program

+ +

+proxy-server reads a line of text, or a block of binary data, following +the PROXY +protocol, on its stdin. It sets some environment variables to +data provided by the protocol, then executes a program. +

+ +

+ The objective is to make servers running under the +s6-tcpserver superserver work behind a proxy +with client connection data provided by the proxy via the PROXY protocol. +The environment variables reflect what the s6-networking super-servers set +for a direct connection. +

+ +

Interface

+ +
+     proxy-server [ -1 | -2 ] [ -t timeout ] [ -v verbosity ] prog...
+
+ + + +

Exit codes

+ +
+
1
invalid PROXY syntax
+
2
unsupported protocol
+
100
wrong usage
+
111
system call failed
+
+ +

+ proxy-server never exits 0: on success, it chainloads into the next program. +

+ +

Options

+ +
+
-t timeout
+
If no data is received after timeout milliseconds, exit 111. +By default, timeout is 0, meaning infinite: proxy-server will wait +forever for data.
+
-v verbosity
+
Be more or less verbose. The default is 1. Changing it does not +have much effect at the moment, leave it alone.
+
-1
+
Expect version 1 of the PROXY protocol: a line of text.
+
-2
+
Expect version 2 of the PROXY protocol: a binary structure.
+
+ +

+ If neither -1 or -2 is selected, proxy-server will default +to expecting version 2. If you pass both options, proxy-server will support +both versions of the protocol. +

+ +

Common usage

+ +

+ proxy-server is a chainloading program that you can interpose on the command +line between a super-server and a server, if the server does not follow the +PROXY protocol but you are running it behind a proxy that does. +

+ +

+ For instance, if you are running the +tipidee web server behind a proxy +transmitting real client connection information via the PROXY protocol, +instead of running s6-tlsserver 0.0.0.0 443 tipideed, you would run +s6-tlsserver 0.0.0.0 443 proxy-server tipideed, and +tipideed would log +the IPs from the clients rather than from the proxy. +

+ +

+ proxy-server has no utility if you are not running a server behind a proxy. +

+ +

Environment variables

+ +

+ proxy-server sets client information into environment variables the same +way that s6-tcpserver and similar programs do. +It tries to map the information provided by the proxy to the same variables, as +closely as possible. It never deletes variables, it only adds or overrides +them. +

+ +

+ Depending on the version of the protocol and the information transmitted by +the proxy, proxy-server may modify the following variables: +

+ + + + + -- cgit v1.3.1