From 8bffa1c19fd05f4f04dad4b5b98f85b94f23113c Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Mon, 26 Jan 2015 22:26:57 +0000 Subject: - added s6-fdholder-delete(c) - small s6-fdholder-* fixes - s6-fdholder documentation (in review) - s6_svstatus_* bugfix (thanks Olivier Brunel) --- doc/s6-fdholder-daemon.html | 147 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 doc/s6-fdholder-daemon.html (limited to 'doc/s6-fdholder-daemon.html') diff --git a/doc/s6-fdholder-daemon.html b/doc/s6-fdholder-daemon.html new file mode 100644 index 0000000..90adea0 --- /dev/null +++ b/doc/s6-fdholder-daemon.html @@ -0,0 +1,147 @@ + + + + + s6: the s6-fdholder-daemon program + + + + + + +

+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 path, followed by 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 a 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.

+ + + -- cgit v1.2.3

The s6-fdholder-daemon program

Interface

Options

Notes

The `s6-fdholder-daemon` program