s6-fdholder-daemon.html (7416B)
1 <html> 2 <head> 3 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 5 <meta http-equiv="Content-Language" content="en" /> 6 <title>s6: the s6-fdholder-daemon program</title> 7 <meta name="Description" content="s6: the s6-fdholder-daemon program" /> 8 <meta name="Keywords" content="s6 s6-fdholder fd-holding fd-holder fd unix socket activation server daemon" /> 9 <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> 10 </head> 11 <body> 12 13 <p> 14 <a href="index.html">s6</a><br /> 15 <a href="//skarnet.org/software/">Software</a><br /> 16 <a href="//skarnet.org/">skarnet.org</a> 17 </p> 18 19 <h1> The <tt>s6-fdholder-daemon</tt> program </h1> 20 21 <p> 22 <tt>s6-fdholder-daemon</tt> is a fd-holding <em>daemon</em>, i.e. a 23 long-lived program. 24 It listens on a Unix domain socket, then 25 accepts client connections; 26 it stores file descriptors on behalf of clients, along with an identifier 27 for every file descriptor stored, and possibly an expiration date (after 28 which the file descriptor will be forgotten). It also allows clients to 29 retrieve a file descriptor by its identifier. 30 </p> 31 32 <h2> Interface </h2> 33 34 <pre> 35 s6-fdholder-daemon [ -1 ] [ -v <em>verbosity</em> ] [ -d | -D ] [ -c <em>maxconn</em> ] [ -n <em>maxfds</em> ] [ -b <em>backlog</em> ] [ -G <em>gidlist</em> ] [ -g <em>gid</em> ] [ -u <em>uid</em> ] [ -U ] [ -t <em>clienttimeout</em> ] [ -T <em>lameducktimeout</em> ] [ -i <em>rulesdir</em> | -x <em>rulesfile</em> ] <em>path</em> 36 </pre> 37 38 <ul> 39 <li> s6-fdholder-daemon parses the options and arguments it is given, and 40 builds a new command line with them. It then executes into that new 41 command line. </li> 42 <li> The first program s6-fdholder-daemon executes into is 43 <a href="s6-ipcserver-socketbinder.html">s6-ipcserver-socketbinder</a>. 44 It will create and bind a Unix domain socket to <em>path</em>, then 45 execute into the rest of the command line. </li> 46 <li> If a privilege-dropping operation has been requested, the 47 program that s6-ipcserver-socketbinder executes into is 48 <a href="s6-applyuidgid.html">s6-applyuidgid</a>. 49 It will drop the root privileges, then execute into the rest of the 50 command line. </li> 51 <li> The last program in the chain is 52 <a href="s6-fdholderd.html">s6-fdholderd</a>. It is executed into 53 by s6-applyuidgid, or directly by s6-ipcserver-socketbinder if no 54 privilege-dropping operation has been requested. s6-fdholderd is 55 the long-lived process, the daemon itself, performing fd holding and 56 accepting connections from clients. </li> 57 </ul> 58 59 60 <h2> Options </h2> 61 62 <ul> 63 <li> <tt>-1</tt> : write a newline to stdout, before 64 closing it, right after binding and listening to the Unix socket. 65 If stdout is suitably redirected, this can be used by monitoring 66 programs to check when the server is ready to accept connections. </li> 67 <li> <tt>-v <em>verbosity</em></tt> : be quiet, normally 68 verbose, or more verbose, depending on if <em>verbosity</em> is 0, 69 1, or more. The default is 1. </li> 70 <li> <tt>-d</tt> : allow instant rebinding to the same path 71 even if it has been used not long ago - this is the SO_REUSEADDR flag to 72 <a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/setsockopt.html">setsockopt()</a> 73 and is generally used with server programs. This is the default. Note that 74 <em>path</em> will be deleted if it already exists at program start time. </li> 75 <li> <tt>-D</tt> : disallow instant rebinding to the same path. </li> 76 <li> <tt>-c <em>maxconn</em></tt> : accept at most 77 <em>maxconn</em> concurrent client connections. Default is 16. It is 78 impossible to set it higher than the value of the S6_FDHOLDER_MAX macro, 79 which is 256. Client connections to this server are short-lived, so this 80 number needs not be too high. Every client connection eats up 81 one available file descriptor, so it is best for <em>maxconn</em> to be 82 as small as possible. </li> 83 <li> <tt>-n <em>maxfds</em></tt> : store at most 84 <em>maxfds</em> file descriptors. Default is 1000. 85 It is impossible to set it higher than the number of files that can 86 be opened by the s6-fdholder-daemon process minus a few descriptors 87 needed for correct <a href="s6-fdholderd.html">s6-fdholderd</a> 88 operation. Before running s6-fdholder-daemon, make sure to 89 <a href="s6-softlimit.html">properly adjust</a> the 90 <a href="https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_resource.h.html">number 91 of openable files</a> of the current process. </li> 92 <li> <tt>-b <em>backlog</em></tt> : set a maximum of 93 <em>backlog</em> backlog connections on the socket. Extra 94 connection attempts will rejected by the kernel. </li> 95 <li> <tt>-G <em>gidlist</em></tt> : change s6-fdholder-daemon's 96 supplementary group list to <em>gidlist</em> after binding the socket. 97 This is only valid when run as root. <em>gidlist</em> must be a 98 comma-separated list of numerical group IDs. </li> 99 <li> <tt>-g <em>gid</em></tt> : change s6-fdholder-daemon's groupid 100 to <em>gid</em> after binding the socket. This is only valid when run 101 as root. </li> 102 <li> <tt>-u <em>uid</em></tt> : change s6-fdholder-daemon's userid 103 to <em>uid</em> after binding the socket. This is only valid when run 104 as root. </li> 105 <li> <tt>-U</tt> : change s6-fdholder-daemon's user id, group id and 106 supplementary group list 107 according to the values of the UID, GID and GIDLIST environment variables 108 after binding the socket. This is only valid when run as root. 109 This can be used with the 110 <a href="s6-envuidgid.html">s6-envuidgid</a> 111 program to easily script a service that binds to a privileged socket 112 then drops its privileges to those of a named non-root account. </li> 113 <li> <tt>-t <em>clienttimeout</em></tt> : disconnect a client 114 if it's in the middle of an operation and it has not written or read any 115 data in <em>clienttimeout</em> milliseconds. By default, <em>clienttimeout</em> 116 is 0, which means infinite. </li> 117 <li> <tt>-T <em>lameducktimeout</em></tt> : give clients 118 <em>lameducktimeout</em> milliseconds to finish their current operation 119 before exiting after s6-fdholderd has received a SIGTERM. By default, 120 <em>lameducktimeout</em> is 0, which means infinite. </li> 121 <li> <tt>-x <em>rulesfile</em></tt> : read access rights 122 configuration from CDB file <em>rulesfile</em>. </li> 123 <li> <tt>-i <em>rulesdir</em></tt> : read access rights 124 configuration from the filesystem in directory <em>rulesdir</em>. </li> 125 </ul> 126 127 <h2> Notes </h2> 128 129 <ul> 130 <li> s6-fdholder-daemon does not interpret its options itself. It just 131 dispatches them to the appropriate program on the command line that 132 it builds. </li> 133 <li> From the user's point of view, s6-fdholder-daemon behaves like a 134 long-lived process, even if the long-lived process itself is called 135 <a href="s6-fdholderd.html">s6-fdholderd</a>. Every operational detail 136 of s6-fdholderd applies to s6-fdholder-daemon as well; in particular, 137 make sure to properly 138 <a href="s6-fdholderd.html#configuration">configure the clients' 139 access rights</a>. </li> 140 <li> s6-fdholder-daemon is meant to be used in an s6 run script, as 141 a supervised local service. It does not fork itself or write to syslog. 142 However, it can be run under any infrastructure, including other 143 supervision infrastructures, OpenRC, systemd, or SysV scripts. </li> 144 </ul> 145 146 </body> 147 </html>