S6-IPCSERVER(8)

📦 version 2.15.1.0, in nixpkgs unstable

💅 s6-ipcserver — the UCSPI server tool<sup>[1]</sup> for Unix domain sockets ✨

okay so bestie, picture this: a super-server. It accepts connections from clients on a Unix domain socket, and then forks a little program to handle each and every connection. That's the whole vibe. This is the s6-ipcserver page from the System Manager's Manual, and yes we're gonna get through all of it together 🫶

🌸 SYNOPSIS 🌸

s6-ipcserver [-1] [-q | -Q | -v] [-d | -D] [-P | -p] [-a perms]
             [-c maxconn] [-C localmaxconn] [-b backlog] [-G gidlist]
             [-g gid] [-u uid] [-U] path prog...

Like, look at her. Gorgeous. Iconic. All those flags are about to get explained one by one, don't panic 💖

🦋 DESCRIPTION 🦋

So s6-ipcserver binds a Unix domain socket to path. Simple as that.

It can drop its root privileges. Slay, we love a humble queen 👑

It closes its stdin and stdout. Bye bestie, we don't need those anymore.

For every client connection to this socket, it forks. The child sets some environment variables, then executes prog... with stdin reading from the socket and stdout writing to it. Like a little handoff, very main character energy.

Depending on the verbosity level, it logs what it does to stderr.

It runs until it gets killed by a signal. And depending on the received signal, it may kill its children before exiting. Not a fun vibe but like, necessary 💀

Here's the tea though: s6-ipcserver actually doesn't do any of this itself. It is a wrapper, rewriting the command line and executing into a chain of programs that perform those duties. It's giving project manager. It delegates, it's fabulous, it takes zero credit ✨

Previous versions of s6-ipcserver were monolithic: it did the work of s6-ipcserver-socketbinder(8), s6-applyuidgid(8) and s6-ipcserverd(8) itself. The functionality has now been split into several different programs because some service startup schemes require the daemon to get its socket from an external program instead of creating and binding it itself. The most obvious application of this is upgrading a long-lived process without losing existing connections. Which is honestly so valid of them 🎀

✨ OPTIONS ✨

  • -1 — Writes a newline to stdout, before closing it, right after binding and listening to the Unix socket. If stdout is suitably redirected, this can be used by monitoring programs to check when the server is ready to accept connections. It's the "hey bestie I'm ready" signal 🎀
  • -q — Be quiet. Shhh. 🤫
  • -Q — Be normally verbose. This is the default, iykyk.
  • -v — Be verbose. Tell me everything, I'm listening 👀
  • -d — Allow instant rebinding to the same path even if it has been used not long ago — this is the SO_REUSEADDR flag to setsockopt(2) and is generally used with server programs. This is the default. Note that path will be deleted if it already exists at program start time. Lowkey destructive but she's the default so 🌈
  • -D — Disallow instant rebinding to the same path. The cautious option 🦋
  • -P — Disable client credentials lookups. The IPCREMOTEEUID and IPCREMOTEEGID environment variables will be unset in every instance of prog.... This is the portable option, because not every system supports credential lookup across Unix domain sockets; but it is not as secure. So like, tradeoff: it works everywhere but it's less safe 🙈
  • -p — Enable client credentials lookups. This is the default; it works at least on Linux, Solaris, and *BSD systems. On systems that do not support it, every connection attempt will fail with a warning message. Not a vibe check you wanna fail 💀
  • -c maxconn — Accept at most maxconn concurrent connections. Default is 40. It is impossible to set it higher than 1000. That's the ceiling, periodt.
  • -C localmaxconn — Accept at most localmaxconn connections from the same user ID. Default is 40. It is impossible to set it higher than maxconn. So if you try to be slick, the math says no 💅
  • -b backlog — Set a maximum of backlog backlog connections on the socket. Extra connection attempts will rejected by the kernel. (Yes, it says "will rejected", we're quoting the energy, not fixing it 😭)
  • -a perms — Create the socket with permissions perms, which is an octal number from 0000 to 0777. Default is 0777, meaning everyone can connect to it. 0700 means only processes having the same uid as the s6-ipcserver process can connect to it. Choose your fighter 🎀
  • -G gidlist — Change s6-ipcserver's supplementary group list to gidlist after binding the socket. This is only valid when run as root. gidlist must be a comma-separated list of numerical group IDs. Commas, bestie, not spaces ✨
  • -g gid — Change s6-ipcserver's groupid to gid after binding the socket. This is only valid when run as root.
  • -u uid — Change s6-ipcserver's userid to uid after binding the socket. This is only valid when run as root.
  • -U — Change s6-ipcserver's user id, group id and supplementary group list according to the values of the UID, GID and GIDLIST environment variables after binding the socket. This is only valid when run as root. This can be used with the s6-envuidgid(8) program to easily script a service that binds to a privileged socket then drops its privileges to those of a named non-root account. Literally the glow-up-from-root pipeline 👑

🧚 IMPLEMENTATION NOTES 🧚

s6-ipcserver parses the options and arguments it is given, and builds a new command line with them. It then executes into that new command line.

The first program s6-ipcserver executes into is s6-ipcserver-socketbinder(8). It will create and bind a Unix domain socket to path, then execute into the rest of the command line.

If a privilege-dropping operation has been requested, the program that s6-ipcserver-socketbinder(8) executes into is s6-applyuidgid(8). It will drop the root privileges, then execute into the rest of the command line.

The next program in the chain is s6-ipcserverd(8). It is executed into by s6-applyuidgid(8), or directly by s6-ipcserver-socketbinder(8) if no privilege-dropping operation has been requested. s6-ipcserverd(8) is the long-lived process, the "daemon" itself, accepting connections from clients. She's the one who stays. Main character energy, fr fr 💜

For every client, s6-ipcserverd(8) will spawn an instance of prog..., the remainder of the command line.

ngl this whole chain is giving relay race and every runner slays their leg and hands off the baton. No cap 🏃‍♀️✨

👑 SEE ALSO 👑

[1] https://cr.yp.to/proto/ucspi.txt

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

💖 AUTHORS 💖

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

and that's the whole page bestie!! 🎀 written by the icons above, ported over on the Debian side, dated September 29, 2021, from System Manager's Manual — S6-IPCSERVER(8) — mwah, go bind some sockets responsibly 💅✨

📦 where this page comes from