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/index.html | 6 +++ doc/proxy-server.html | 141 ++++++++++++++++++++++++++++++++++++++++++++++++++ doc/upgrade.html | 1 + 3 files changed, 148 insertions(+) create mode 100644 doc/proxy-server.html diff --git a/doc/index.html b/doc/index.html index 260213e..3721936 100644 --- a/doc/index.html +++ b/doc/index.html @@ -168,6 +168,12 @@ relevant page.

PROXY protocol implementation

+ +

The proxy-server program

IDENT protocol implementation

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...
+

proxy-server reads its stdin, expecting to see a block of data +following the PROXY protocol.
It parses the block of data to get information on the original +client connection, normally encoded in that data by a proxy.
If at any point it finds invalid data, it exits immediately +with an error message.
It puts the provided client connection information into suitable +environment variables.
It execs into 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: +

PROTO
IPCREMOTEPATH
IPCLOCALPATH
TCPREMOTEIP
TCPLOCALIP
TCPREMOTEPORT
TCPLOCALPORT
SSL_PROTOCOL
SSL_CIPHER
SSL_PEER_CERT_CN
SSL_TLS_SNI_SERVERNAME

s6-dns dependency bumped to 2.4.1.1
New command: proxy-server

in 2.7.1.0

-- cgit v1.3.1