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