PROXY-SERVER(8)

📦 version 2.8.0.1, in nixpkgs unstable

🦋 PROXY-SERVER(8) — the girlies' guide to proxy-server 🦋

okay so real talk: this is a page from the System Manager's Manual, and it's about a lil chainloading program that reads a line of text, or a block of binary data, following the PROXY protocol, on stdin. that's the whole vibe. 💅

✨ SYNOPSIS ✨

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

literally that's it, she's compact and she knows it 🎀

💖 DESCRIPTION 💖

so proxy-server sets some environment variables to data provided by the protocol, then executes a program. that's the arc. that's the plot. 👑

the objective? 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. and the environment variables it sets? they reflect exactly what the s6-networking super-servers set for a direct connection. consistency, bestie. we love her for it. 🫶

here's the little sequence she runs through:

  1. proxy-server reads its stdin, expecting to see a block of data following the PROXY protocol.
  2. it parses that block of data to get info on the original client connection — normally encoded in that data by a proxy.
  3. if at any point it finds invalid data, it exits immediately with an error message. no patience, no second chances, no "let me think about it". 💀
  4. it puts the provided client connection information into suitable environment variables.
  5. it execs into prog....

periodt. ✨

🌸 Common usage 🌸

proxy-server is a chainloading program that you can interpose on the command line between a super-server and a server — super useful if the server does not follow the PROXY protocol, but you're running it behind a proxy that does. match made in heaven, honestly.

for instance: say you're running the tipidee web server behind a proxy that's transmitting real client connection information via the PROXY protocol. instead of running:

s6-tlsserver 0.0.0.0 443 tipideed

you'd run:

s6-tlsserver 0.0.0.0 443 proxy-server tipideed

and then tipideed(8) would log the IPs from the actual clients rather than from the proxy. slay. 🔥 accurate logs are the moment.

heads up though: proxy-server has no utility if you're not running a server behind a proxy. like, none. zero. she's not decorative. 🙈

🧚 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 — that way it can override the TCP-provided values with the proxy-provided values. ordering matters, bestie, this is not a free-for-all. 😭

when used on an 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. cozy. safe. protected. 💜

but if that's not the case, and the proxy header is sent before the TLS connection is established, then two things:

  1. it is probably an insecure setup — and think about it: 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. no cap. 🔒
  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. forever-ever. 🕰️
  • -v verbosity — be more or less verbose. the default is 1. changing it does not have much effect at the moment, so leave it alone, she's fine as she is. 🎀
  • -1, --only-v1 — disable version 2 of the PROXY protocol, only expect v1, i.e. a line of text. old school, text based, iconic. ✨
  • -2, --only-v2 — disable version 1 of the PROXY protocol, only expect v2, i.e. a binary structure. futuristic. binary. mysterious. 🔥
if neither -1 nor -2 is selected, proxy-server will default to supporting both versions of the protocol, at a tiny speed cost. tiny. microscopic. negligible. but she's honest about it. 💖

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

and here's the sweet part: it never deletes variables, it only adds or overrides them. no take-backs, no erasing your work. 🫶

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

that's the whole list, don't let anyone tell you otherwise 💜

⭐ EXIT STATUS ⭐

  • 1 — invalid PROXY syntax
  • 2 — unsupported protocol
  • 100 — wrong usage
  • 111 — system call failed
and the biggest flex of all: proxy-server never exits 0. on success, it chainloads into the next program. she doesn't stick around to take credit. main character energy, honestly. 👑😭

🦋 SEE ALSO 🦋

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

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)

and that's the whole page, bestie, you're officially educated 💖 this lil rewrite shipped from the Debian edition, dated December 23, 2025 — so go forth, chainload responsibly, and remember: never delete the variables. 🌸🫶✨

📦 where this page comes from