S6-TCPSERVER-SOCKETBINDER(8)

📦 version 2.8.0.1, in nixpkgs unstable

💅 S6-TCPSERVER-SOCKETBINDER — the manual page, but make it make sense

okay so bestie, you found s6-tcpserver-socketbinder, from the System Manager's Manual section 8 (that's the "system administration / daemons" section, iykyk). this one's a little building block, not the whole show, and honestly? it's iconic in a quiet way. let's get into it 🌸

✨ NAME ✨

s6-tcpserver-socketbinder — she binds an INET domain socket to an IPv4 or IPv6 address and port, and then executes a program. that's it, that's her job, and she does it flawlessly 💅

🎀 SYNOPSIS 🎀

s6-tcpserver-socketbinder [-d | -D] [-b backlog] [-M | -m] [-B] ip port
                          prog...

like, look at that flow. ip, port, then prog... — she's gonna hand off to your program and let it cook. 🔥

🦋 DESCRIPTION 🦋

so what she actually does: s6-tcpserver-socketbinder creates a TCP socket and binds it to the IP address ip and the port port. simple, clean, no cap.

then she gets that socket ready to accept connections by calling listen(2). yes bestie, she's setting up the whole vibe.

after that? she exec(3)s into prog... with the open socket as its standard input. that socket is literally the main character now — it gets handed straight to your program as stdin.

and heads up: the socket is provided non-blocking by default. ⭐

s6-tcpserver-socketbinder is part of a set of basic blocks used to build a flexible TCP/IP super-server. she's a lego brick, not the whole castle. normally you'd give her a command line crafted to make her execute into s6-tcpserverd(8) so it can accept connections from clients, or into a program like s6-applyuidgid(8) to drop privileges before doing so. 🫶

and the s6-tcpserver(8) program does exactly this — full transparency. it implements a full TCP/IP super-server by building a command line that starts with s6-tcpserver-socketbinder and ends with s6-tcpserverd(8) followed by the application program, and then executes into it. she's the first domino. 👑

okay now the address tea, because this trips people up: for s6-tcpserver-socketbinder, '::' means "all IPv6 addresses", and '0.0.0.0' means "all IPv4 addresses". but she does not provide a way to bind a socket to all addresses regardless of protocol — no single magic "everything" address, sorry bestie. instead you should use two sockets, one for IPv4 and one for IPv6. two icons, one job each. 🌈

💖 OPTIONS 💖

  • -d — allow instant rebinding to the same IP and port even if it's been used not long ago. this is the SO_REUSEADDR flag to setsockopt(2), and it's generally used with server programs. and guess what — this is the default. she's already doing it, you don't even have to ask. ✨
  • -D — disallow instant rebinding to the same path. the opposite of -d, if you're feeling strict.
  • -b backlog — set a maximum of backlog backlog connections on the socket — extra connection attempts will get rejected by the kernel. rude but efficient 💀. the default is the maximum number allowed by the system. and here's the little detail that matters: if backlog is 0, then the socket will be created, but it will not be listening. she exists, she's just not answering the door. 🚪
  • -M — create a TCP socket. this is the default, so if you say nothing, this is what you get. 🎀
  • -m — create a UDP socket. ⚠️ heads up bestie: by default UDP sockets are not connection-mode, and listen(2) will fail — so you should always give the 'b0' option to s6-tcpserver-socketbinder along with -m. no cap, that pairing is mandatory or it's not gonna go well. 😭
  • -B — create a blocking socket. default is non-blocking, so this is you opting into the patient lifestyle.

👀 SEE ALSO 👀

the whole friend group:

this man page is ported from the authoritative documentation at: https://skarnet.org/software/s6-networking/s6-tcpserver-socketbinder.html — go read the source if you want the OG vibes. 🧚

🌸 AUTHORS 🌸

  • Laurent Bercot
  • Alexis <flexibeast@gmail.com> (man page port) — thank you for your service 🫡

alright bestie, that's the whole page, every flag and every detail intact, no facts harmed in the making of this rewrite 💜 this one's from the Debian packaging, dated November 11, 2023, for S6-TCPSERVER-SOCKETBINDER(8). go bind something cute. 🍓

📦 where this page comes from