S6-TLSSERVER(8)

📦 version 2.8.0.1, in nixpkgs unstable

✨ S6-TLSSERVER(8) ✨

okay bestie, buckle up — this is S6-TLSSERVER(8) and she is here to make TLS super-server stuff make sense 💅

🎀 NAME 🎀

s6-tlsserver — UCSPI server tool[1] for TLS/SSL connections over INET domain sockets 🦋

🌸 SYNOPSIS 🌸

s6-tlsserver [options] [--] ip port prog...

💖 DESCRIPTION 💖

s6-tlsserver is a TCP super-server: it listens for connections, accepts them, and for each connection it establishes a TLS transport over it, then executes into a program. Iconic behavior, genuinely 🫶

s6-tlsserver rewrites itself into a command line involving:

  • s6-tcpserver(8), which listens to TCP connections on IP address ip port port and forks a command line for every connection. Heads up: s6-tcpserver(8) also rewrites itself into a more complex command line (the final long-lived process being s6-tcpserverd(8)), so your end command line may look a lot longer in ps(1) than what you originally wrote. This is normal and healthy. no cap ✨
  • (If applicable) s6-tcpserver-access(8), which performs TCP access control and various operations on the TCP connection.
  • s6-tlsd(8), which establishes a TLS transport (server-side) over a connection, via an s6-tlsd-io(8) child process.
  • (If applicable) s6-applyuidgid(8), which drops root privileges.
  • prog..., your client program, which is run with the s6-tlsd(8).

It runs until it is killed by a signal. 💀

prog is expected to read from its peer on its standard input and write to its peer on its standard output. Since there will be an s6-tlsd-io(8) program between prog and the network to perform the SSL encryption/decryption, those descriptors will not be a network socket — they will be pipes. lowkey important 🧚

📡 Signals 📡

s6-tlsserver reacts to the same signals as s6-tcpserverd(8), which is the long-lived process hanging around. main character energy, honestly 👑

🌈 OPTIONS 🌈

s6-tlsserver accepts a myriad of options, most of which are passed as is to the correct executable. Not giving any options will generally work, but unless you're running a very public server (such as a Web server) or base your access control on client certificates, you probably still want TCP access rules. fr fr 🎀

💅 Options informing s6-tlsserver behaviour 💅

  • -L — if this option is given, s6-tlsserver will add an invocation of proxy-server(8) so that a PROXY line or binary block is read in cleartext before the TLS tunnel is established. If the proxy uses the v2 version of the PROXY protocol and transmits SSL information from the client connection, this information will be reflected in the SSL environment variables transmitted to prog. 🦋

🛠️ Options passed as-is to s6-tcpserver(8) 🛠️

🔐 Options passed as-is to s6-tcpserver-access(8) 🔐

  • -v0, -v2 — the verbosity level.
  • -w, -W — be strict or tolerant with DNS or IDENT resolution errors.
  • -d, -D — enable or disable Nagle's algorithm.
  • -r, -R — enable or disable IDENT lookups.
  • -p, -P — enable or disable paranoid DNS cross-checking.
  • -H — disable DNS lookups.
  • -h — consult /etc/hosts before DNS.
  • -l localname — get the local name from the command line, don't look it up.
  • -B banner — initial server-side banner.
  • -t timeout — set a timeout for all the lookups.
  • -i rulesdir, -x rulesfile — TCP access control.

🔥 Options passed as-is to s6-tlsd(8) 🔥

  • -Z, -z — keep or remove the s6-tlsd-io(8)-specific variables from the application's environment.
  • -S, -s — use ‘close_notify’ or EOF to signal the end of a TLS connection.
  • -J, -j — exit nonzero with an error message when the peer fails to ‘close_notify’, or ignore it.
  • -Y, -y — request an optional or a mandatory client certificate.
  • -K kimeout — set a timeout for the TLS handshake.
  • -k snilevel — support SNI-based certificate chains.

👑 Options passed to s6-applyuidgid 👑

  • -u uid, -g gid, -G gidlist — set uid, gid, or supplementary group list.
  • -U (passed as -Uz) — get the uid, gid and supplementary group list from the UID, GID and GIDLIST variables, and remove these variables from the application's environment.

🦋 ENVIRONMENT 🦋

📖 Read 📖

The following variables should be set before invoking s6-tlsserver, because they will be used by every s6-tlsd(8) invocation:

  • KEYFILE
  • CERTFILE
  • TLS_UID and TLS_GI — if you run s6-tlsserver as root.
  • CADIR — if you want client certificates.
  • CAFILE — if you want client certificates, alternative to CADIR.

Setting both KEYFILE and CERTFILE is mandatory. periodt 💅

✍️ Written ✍️

prog... is run with the following variables added to, or removed from, its environment by s6-tcpserverd(8) and possibly by s6-tcpserver-access(8):

  • PROTO
  • TCPREMOTEIP
  • TCPREMOTEPORT
  • TCPCONNNUM
  • TCPLOCALIP
  • TCPLOCALPORT
  • TCPREMOTEHOST
  • TCPLOCALHOST
  • TCPREMOTEINFO

Depending on TCP access rules (if the -i or -x option has been given), it is possible that prog's environment undergoes more modifications. Also, since s6-tlsd(8) is always run after s6-tcpserver-access(8), it is possible to set different TLS/SSL parameters (typically a different KEYFILE and CERTFILE) depending on the client connection, by writing the correct set of TCP access rules. iykyk ✨

Unless the -Z option is given to s6-tlsserver, the CADIR, CAFILE, KEYFILE, CERTFILE, TLS_UID and TLS_GID variables will not appear in prog's environment. 🫶

🧪 EXAMPLES 🧪

As root:

env KEYFILE=/etc/ssl/private/mykey.der CERTFILE=/etc/ssl/public/mycert.pem \
TLS_UID=65534 TLS_GID=65534 \
s6-envuidgid www \
s6-tlsserver -U -- 1.2.3.4 443 httpd

This will start a server listening to 1.2.3.4 on TCP port 443, and for every connection, spawn the ‘httpd’ program reading queries on stdin and replying on stdout, as user ‘www’, with a TLS layer protecting the connection, the TLS engine running as user ‘nobody’ (‘65534:65534’). The server is authenticated by the certificate in /etc/ssl/public/mycert.pem that it sends to the client, and the private key in /etc/ssl/private/mykey.der that it keeps to itself. ate and left no crumbs 🔥

🌟 SEE ALSO 🌟

💜 AUTHORS 💜

  • Laurent Bercot
  • Alexis <flexibeast@gmail.com> (man page port)

mwah 💋 this little rewrite is serving Debian's S6-TLSSERVER(8) manual, dated November 20, 2023 — bye bestie, go secure those sockets 🫶✨

📦 where this page comes from