S6-FDHOLDER-DAEMON(8)

📦 version 2.15.1.0, in nixpkgs unstable

💖 s6-fdholder-daemon(8) — the fd-holding daemon, explained by your favorite Unix bestie 🎀

okay so bestie, welcome to the system manager's manual page for s6-fdholder-daemon, and honestly? it's giving "quiet little workhorse that holds your file descriptors so you don't have to" ✨ let's get into it.

🌸 NAME 🌸

s6-fdholder-daemon — the fd-holding daemon. yes that's literally it, she holds fds, that's her whole job, and she ate 💅

✨ SYNOPSIS ✨

s6-fdholder-daemon [-1] [-v verbosity] [-d | -D] [-c maxconn]
                   [-n maxfds] [-b backlog] [-G gidlist] [-g gid]
                   [-u uid] [-U] [-t clienttimeout] [-T lameducktimeout]
                   [-i rulesdir | -x rulesfile] path

🦋 DESCRIPTION 🦋

so s6-fdholder-daemon listens on a Unix domain socket, right, and then it accepts client connections. what does it do with those clients? it stores file descriptors on their behalf — and every fd it stores gets an identifier, and possibly an expiration date too (after that date the fd is just… forgotten, bestie, gone, no cap 🫶). it also lets clients come back and retrieve a file descriptor by its identifier. iconic behavior honestly.

here's the fun structural part: s6-fdholder-daemon parses the options and arguments it's given, and builds a new command line with them. then it executes into that new command line. it's a chain, a relay, main character energy all the way down 🌈

the first program it executes into is s6-ipcserver-socketbinder(8). that one 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). that one drops root privileges, then executes into the rest of the command line. slay 🎀

the last program in the chain is s6-fdholderd(8). it gets executed into by s6-applyuidgid(8), or directly by s6-ipcserver-socketbinder(8) if no privilege-dropping operation has been requested. s6-fdholderd(8) is the long-lived process — the actual daemon — the one doing the fd holding and accepting connections from clients. she's the one doing the real work fr fr 💜

lowkey important: s6-fdholder-daemon does not interpret its options itself. it just dispatches them to the appropriate program on the command line that it builds. so it's a delegator, not a micromanager. respect.

from the user's point of view, s6-fdholder-daemon behaves like a long-lived process, even if the long-lived process itself is called s6-fdholderd(8). every operational detail of s6-fdholderd(8) applies to s6-fdholder-daemon as well — and in particular, make sure to properly configure the clients' access rights, as described in s6-fdholderd(8). seriously. do it. 🙈

s6-fdholder-daemon is meant to be used in an s6 run script, as a supervised local service. it does not fork itself and it does not write to syslog. but that doesn't box it in — it can be run under any infrastructure, including other supervision infrastructures, OpenRC, systemd, or SysV scripts. versatile queen 👑

💅 OPTIONS 💅

  • -1 — writes a newline to stdout, before closing it, right after binding and listening to the Unix socket. if stdout is suitably redirected, monitoring programs can use this to check when the server is ready to accept connections. it's giving "i'm ready, come thru" ⭐
  • -v verbosity — be quiet, normally verbose, or more verbose, depending on whether verbosity is 0, 1, or more. default is 1.
  • -d — allow instant rebinding to the same path even if it's 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 👀
  • -D — disallow instant rebinding to the same path. the opposite vibe of -d, obviously.
  • -c maxconn — accept at most maxconn concurrent client connections. default is 16. it is impossible to set it higher than the value of the S6_FDHOLDER_MAX macro, which is 256. client connections to this server are short-lived, so this number needs not be too high — and every client connection eats up one available file descriptor, so it's best for maxconn to be as small as possible. tiny and efficient, we love her 🍓
  • -n maxfds — store at most maxfds file descriptors. default is 1000. it is impossible to set it higher than the number of files that can be opened by the s6-fdholder-daemon process minus a few descriptors needed for correct s6-fdholderd(8) operation. before running s6-fdholder-daemon, make sure to properly adjust, via s6-softlimit(8), the number of openable files[1] of the current process. (yes, the footnote is real, keep scrolling 🫶)
  • -b backlog — set a maximum of backlog backlog connections on the socket. extra connection attempts will be rejected by the kernel. the kernel said no 💀
  • -G gidlist — change s6-fdholder-daemon'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.
  • -g gid — change s6-fdholder-daemon's groupid to gid after binding the socket. this is only valid when run as root.
  • -u uid — change s6-fdholder-daemon's userid to uid after binding the socket. this is only valid when run as root.
  • -U — change s6-fdholder-daemon'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. bind high, drop low, that's the arc ✨
  • -t clienttimeout — disconnect a client if it's in the middle of an operation and it has not written or read any data in clienttimeout milliseconds. by default, clienttimeout is 0, which means infinite. no timeout, no pressure, live your truth 🌸
  • -T lameducktimeout — give clients lameducktimeout milliseconds to finish their current operation before exiting after s6-fdholderd(8) has received a SIGTERM. by default, lameducktimeout is 0, which means infinite. the lameduck era, we've all been there 😭
  • -x rulesfile — read access rights configuration from CDB file rulesfile.
  • -i rulesdir — read access rights configuration from the filesystem in directory rulesdir.
note that -i and -x are mutually exclusive — it's one or the other in that synopsis, bestie, pick a lane 🎀

🔥 SEE ALSO 🔥

[1] https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/sys_resource.h.html — that's the footnote link, go read it if you're curious, iykyk 🧚

this man page is ported from the authoritative documentation at: https://skarnet.org/software/s6/s6-fdholder-daemon.html 👑

👑 AUTHORS 👑

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

and that's the whole page, bestie 💖 shoutout to the Debian packaging, dated September 29, 2021 — that's the version/date energy for this one, and hey, s6-fdholder-daemon(8) really said "i'll hold your fds and i'll hold them with style" 🌟 bye ily 🫶

📦 where this page comes from