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: