S6-FDHOLDER-DAEMON(8)

NAME
s6-fdholder-daemon - fd-holding daemon

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
s6-fdholder-daemon 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.

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(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 root privileges, then execute into the rest of the command line.

The last program in the chain is s6-fdholderd(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-fdholderd(8) is the long-lived process, the daemon itself, performing fd holding and accepting connections from clients.

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(8). Every operational detail of s6-fdholderd(8) applies to s6-fdholder-daemon as well; in particular, make sure to properly configure the clients' access rights, as described in s6-fdholderd(8).

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.

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(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.

-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(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.

-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(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.

-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(8) 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.

SEE ALSO
s6-fdholder-delete(8), s6-fdholder-getdump(8), s6-fdholder-list(8), s6-fdholder-retrieve(8), s6-fdholder-setdump(8), s6-fdholder-store(8), s6-fdholder-transferdump(8), s6-fdholderd(8)

[1] https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/sys_resource.h.html

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)