PROXY-SERVER(8)

NAME
proxy-server - read a line of text, or a block of binary data, following the PROXY protocol,[1] on stdin

SYNOPSIS
proxy-server [-1 | --only-v1 | -2 | --only-v2] [-t timeout] [-v verbosity] prog...

DESCRIPTION
proxy-server proxy-server 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(8) 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.

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

  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[2] 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(8) 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.

  Notes
proxy-server operates by writing UCSPI variables such as TCPREMOTEIP. These variables are normally set by programs dealing with the TCP connection such as s6-tcpserver(8) or s6-tcpserver-access(8). To take effect, it needs to run after these programs, to override the TCP-provided values with the proxy-provided values.

When used on a s6-tlsserver(8), command line, proxy-server runs after the TLS connection has been established, i.e. it expects the proxy header to be sent in the TLS tunnel.

If this is not the case and the proxy header is sent before the TLS connection is established, 1. it is probably an insecure setup (if you have a good reason to set up a TLS tunnel between your proxy and your server, then the PROXY information is worth protecting just as much as the rest of the data), 2. proxy-server needs to be run between s6-tcpserver(8) and s6-tlsd(8), which you can do by using the -L option to s6-tlsserver(8) rather than explicitly calling proxy-server on the command line.

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 or --only-v1
    Disable version 2 of the PROXY protocol, only expect v1, i.e. a line of text.

-2 or --only-v2
    Disable version 1 of the PROXY protocol, only expect v2, i.e. a binary structure.

If neither -1 or -2 is selected, proxy-server will default to supporting both versions of the protocol, at a tiny speed cost.

ENVIRONMENT
proxy-server sets client information into environment variables the same way that s6-tcpserver(8) 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

EXIT STATUS

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.

SEE ALSO
s6-tcpserver(8), s6-tcpserver-access(8), s6-tlsd(8), s6-tlsserver(8), tipideed(8)

[1] https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt

[2] https://skarnet.org/software/tipidee/

This man page is ported from the authoritative documentation at: https://skarnet.org/software/s6-networking/proxy-server.html

AUTHORS
Laurent Bercot Lennart Jablonka <humm@ljabl.com> (man page port)