s6
Software
skarnet.org

The s6-fdholder-daemon program

s6-fdholder-daemon is a fd-holding daemon, i.e. a long-lived program. It listens on a Unix domain socket, then accepts client connections; it stores file descriptors on behalf of clients, along with an identifier for every file descriptor stored, and possibly an expiration date (after which the file descriptor will be forgotten). It also allows clients to retrieve a file descriptor by its identifier.

Interface

     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

• s6-fdholder-daemon 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-fdholder-daemon executes into is s6-ipcserver-socketbinder. 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 executes into is s6-applyuidgid. It will drop the root privileges, then execute into the rest of the command line.
• The last program in the chain is s6-fdholderd. It is executed into by s6-applyuidgid, or directly by s6-ipcserver-socketbinder if no privilege-dropping operation has been requested. s6-fdholderd is the long-lived process, the daemon itself, performing fd holding and accepting connections from clients.

Options

• -1 : write 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.
• -v verbosity : be quiet, normally verbose, or more verbose, depending on if verbosity is 0, 1, or more. The default is 1.
• -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() 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.
• -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. Every client connection eats up one available file descriptor, so it is best for maxconn to be as small as possible.
• -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 operation. Before running s6-fdholder-daemon, make sure to properly adjust the number of openable files of the current process.
• -b backlog : set a maximum of backlog backlog connections on the socket. Extra connection attempts will rejected by the kernel.
• -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 program to easily script a service that binds to a privileged socket then drops its privileges to those of a named non-root account.
• -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.
• -T lameducktimeout : give clients lameducktimeout milliseconds to finish their current operation before exiting after s6-fdholderd has received a SIGTERM. By default, lameducktimeout is 0, which means infinite.
• -x rulesfile : read access rights configuration from CDB file rulesfile.
• -i rulesdir : read access rights configuration from the filesystem in directory rulesdir.

Notes

• s6-fdholder-daemon does not interpret its options itself. It just dispatches them to the appropriate program on the command line that it builds.
• 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. Every operational detail of s6-fdholderd applies to s6-fdholder-daemon as well; in particular, make sure to properly configure the clients' access rights.
• s6-fdholder-daemon is meant to be used in an s6 run script, as a supervised local service. It does not fork itself or write to syslog. However, it can be run under any infrastructure, including other supervision infrastructures, OpenRC, systemd, or SysV scripts.