]> git.ipfire.org Git - thirdparty/systemd.git/blame - man/systemd.socket.xml
man/systemd-sysext: list ephemeral/ephemeral-import in the list of options
[thirdparty/systemd.git] / man / systemd.socket.xml
CommitLineData
514094f9 1<?xml version='1.0'?>
3a54a157 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
eea10b26 3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
db9ecf05 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
1f812fea 5
d8e1613e 6<refentry id="systemd.socket" xmlns:xi="http://www.w3.org/2001/XInclude">
798d3a52
ZJS
7 <refentryinfo>
8 <title>systemd.socket</title>
9 <productname>systemd</productname>
798d3a52
ZJS
10 </refentryinfo>
11
12 <refmeta>
13 <refentrytitle>systemd.socket</refentrytitle>
14 <manvolnum>5</manvolnum>
15 </refmeta>
16
17 <refnamediv>
18 <refname>systemd.socket</refname>
19 <refpurpose>Socket unit configuration</refpurpose>
20 </refnamediv>
21
22 <refsynopsisdiv>
23 <para><filename><replaceable>socket</replaceable>.socket</filename></para>
24 </refsynopsisdiv>
25
26 <refsect1>
27 <title>Description</title>
28
29 <para>A unit configuration file whose name ends in
30 <literal>.socket</literal> encodes information about an IPC or
31 network socket or a file system FIFO controlled and supervised by
32 systemd, for socket-based activation.</para>
33
34 <para>This man page lists the configuration options specific to
35 this unit type. See
36 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
37 for the common options of all unit configuration files. The common
bdac5608
ZJS
38 configuration items are configured in the generic [Unit] and
39 [Install] sections. The socket specific configuration options are
40 configured in the [Socket] section.</para>
798d3a52
ZJS
41
42 <para>Additional options are listed in
43 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
44 which define the execution environment the
45 <option>ExecStartPre=</option>, <option>ExecStartPost=</option>,
46 <option>ExecStopPre=</option> and <option>ExecStopPost=</option>
47 commands are executed in, and in
48 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
49 which define the way the processes are terminated, and in
50 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
51 which configure resource control settings for the processes of the
52 socket.</para>
53
847af199 54 <para>For each socket unit, a matching service unit must exist,
798d3a52
ZJS
55 describing the service to start on incoming traffic on the socket
56 (see
57 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
847af199 58 for more information about .service units). The name of the
798d3a52
ZJS
59 .service unit is by default the same as the name of the .socket
60 unit, but can be altered with the <option>Service=</option> option
61 described below. Depending on the setting of the
62 <option>Accept=</option> option described below, this .service
63 unit must either be named like the .socket unit, but with the
64 suffix replaced, unless overridden with <option>Service=</option>;
65 or it must be a template unit named the same way. Example: a
66 socket file <filename>foo.socket</filename> needs a matching
67 service <filename>foo.service</filename> if
964c4eda 68 <option>Accept=no</option> is set. If
847af199 69 <option>Accept=yes</option> is set, a service template
798d3a52
ZJS
70 <filename>foo@.service</filename> must exist from which services
71 are instantiated for each incoming connection.</para>
72
45f09f93 73 <para>No implicit <varname>WantedBy=</varname> or
798d3a52
ZJS
74 <varname>RequiredBy=</varname> dependency from the socket to the
75 service is added. This means that the service may be started
76 without the socket, in which case it must be able to open sockets
77 by itself. To prevent this, an explicit
78 <varname>Requires=</varname> dependency may be added.</para>
79
80 <para>Socket units may be used to implement on-demand starting of
81 services, as well as parallelized starting of services. See the
82 blog stories linked at the end for an introduction.</para>
83
df2f5817
LP
84 <para>Note that the daemon software configured for socket activation with socket units needs to be able
85 to accept sockets from systemd, either via systemd's native socket passing interface (see
86 <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> for
87 details about the precise protocol used and the order in which the file descriptors are passed) or via
88 traditional <citerefentry
89 project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>-style
90 socket passing (i.e. sockets passed in via standard input and output, using
91 <varname>StandardInput=socket</varname> in the service file).</para>
48e6dd37
LP
92
93 <para>All network sockets allocated through <filename>.socket</filename> units are allocated in the host's network
94 namespace (see <citerefentry
95 project='man-pages'><refentrytitle>network_namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry>). This
96 does not mean however that the service activated by a configured socket unit has to be part of the host's network
97 namespace as well. It is supported and even good practice to run services in their own network namespace (for
98 example through <varname>PrivateNetwork=</varname>, see
99 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>), receiving only
100 the sockets configured through socket-activation from the host's namespace. In such a set-up communication within
101 the host's network namespace is only permitted through the activation sockets passed in while all sockets allocated
3d62af7d
YW
102 from the service code itself will be associated with the service's own namespace, and thus possibly subject to a
103 restrictive configuration.</para>
798d3a52
ZJS
104 </refsect1>
105
c129bd5d 106 <refsect1>
aed5cb03
ZJS
107 <title>Automatic Dependencies</title>
108
109 <refsect2>
110 <title>Implicit Dependencies</title>
111
112 <para>The following dependencies are implicitly added:</para>
113
114 <itemizedlist>
115 <listitem><para>Socket units automatically gain a <varname>Before=</varname>
116 dependency on the service units they activate.</para></listitem>
117
e9dd6984
ZJS
118 <listitem><para>Socket units referring to file system paths (such as <constant>AF_UNIX</constant>
119 sockets or FIFOs) implicitly gain <varname>Requires=</varname> and <varname>After=</varname>
120 dependencies on all mount units necessary to access those paths.</para></listitem>
aed5cb03
ZJS
121
122 <listitem><para>Socket units using the <varname>BindToDevice=</varname>
123 setting automatically gain a <varname>BindsTo=</varname> and
124 <varname>After=</varname> dependency on the device unit
125 encapsulating the specified network interface.</para></listitem>
126 </itemizedlist>
127
128 <para>Additional implicit dependencies may be added as result of
129 execution and resource control parameters as documented in
130 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
131 and
132 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
133 </refsect2>
134
135 <refsect2>
136 <title>Default Dependencies</title>
137
138 <para>The following dependencies are added unless
139 <varname>DefaultDependencies=no</varname> is set:</para>
140
141 <itemizedlist>
142 <listitem><para>Socket units automatically gain a
143 <varname>Before=</varname> dependency on
144 <filename>sockets.target</filename>.</para></listitem>
145
146 <listitem><para>Socket units automatically gain a pair of
147 <varname>After=</varname> and <varname>Requires=</varname>
148 dependency on <filename>sysinit.target</filename>, and a pair of
149 <varname>Before=</varname> and <varname>Conflicts=</varname>
150 dependencies on <filename>shutdown.target</filename>. These
151 dependencies ensure that the socket unit is started before normal
152 services at boot, and is stopped on shutdown. Only sockets
153 involved with early boot or late system shutdown should disable
154 <varname>DefaultDependencies=</varname> option.</para></listitem>
155 </itemizedlist>
156 </refsect2>
45f09f93
JL
157 </refsect1>
158
798d3a52
ZJS
159 <refsect1>
160 <title>Options</title>
161
d8e1613e
ZJS
162 <para>Socket unit files may include [Unit] and [Install] sections, which are described in
163 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
164 </para>
165
166 <para>Socket unit files must include a [Socket] section, which carries
798d3a52
ZJS
167 information about the socket or FIFO it supervises. A number of
168 options that may be used in this section are shared with other
169 unit types. These options are documented in
78a529ca 170 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
171 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> and
172 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
798d3a52
ZJS
173 The options specific to the [Socket] section of socket units are
174 the following:</para>
175
176 <variablelist class='unit-directives'>
177 <varlistentry>
178 <term><varname>ListenStream=</varname></term>
179 <term><varname>ListenDatagram=</varname></term>
180 <term><varname>ListenSequentialPacket=</varname></term>
181 <listitem><para>Specifies an address to listen on for a stream
182 (<constant>SOCK_STREAM</constant>), datagram
183 (<constant>SOCK_DGRAM</constant>), or sequential packet
184 (<constant>SOCK_SEQPACKET</constant>) socket, respectively.
185 The address can be written in various formats:</para>
186
187 <para>If the address starts with a slash
188 (<literal>/</literal>), it is read as file system socket in
189 the <constant>AF_UNIX</constant> socket family.</para>
190
191 <para>If the address starts with an at symbol
192 (<literal>@</literal>), it is read as abstract namespace
193 socket in the <constant>AF_UNIX</constant> family. The
194 <literal>@</literal> is replaced with a
195 <constant>NUL</constant> character before binding. For
196 details, see
197 <citerefentry project='man-pages'><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
198
199 <para>If the address string is a single number, it is read as
200 port number to listen on via IPv6. Depending on the value of
201 <varname>BindIPv6Only=</varname> (see below) this might result
202 in the service being available via both IPv6 and IPv4
203 (default) or just via IPv6.
204 </para>
205
206 <para>If the address string is a string in the format
69e3234d 207 <literal><replaceable>v.w.x.y</replaceable>:<replaceable>z</replaceable></literal>, it is interpreted
a07ab56a 208 as IPv4 address <replaceable>v.w.x.y</replaceable> and port <replaceable>z</replaceable>.</para>
798d3a52 209
a07ab56a
ZJS
210 <para>If the address string is a string in the format
211 <literal>[<replaceable>x</replaceable>]:<replaceable>y</replaceable></literal>, it is interpreted as
212 IPv6 address <replaceable>x</replaceable> and port <replaceable>y</replaceable>. An optional
69e3234d 213 interface scope (interface name or number) may be specified after a <literal>%</literal> symbol:
a07ab56a
ZJS
214 <literal>[<replaceable>x</replaceable>]:<replaceable>y</replaceable>%<replaceable>dev</replaceable></literal>.
215 Interface scopes are only useful with link-local addresses, because the kernel ignores them in other
216 cases. Note that if an address is specified as IPv6, it might still make the service available via
217 IPv4 too, depending on the <varname>BindIPv6Only=</varname> setting (see below).</para>
798d3a52 218
359a5bcf 219 <para>If the address string is a string in the format
a07ab56a
ZJS
220 <literal>vsock:<replaceable>x</replaceable>:<replaceable>y</replaceable></literal>, it is read as CID
221 <replaceable>x</replaceable> on a port <replaceable>y</replaceable> address in the
222 <constant>AF_VSOCK</constant> family. The CID is a unique 32-bit integer identifier in
223 <constant>AF_VSOCK</constant> analogous to an IP address. Specifying the CID is optional, and may be
db7374e1
DDM
224 set to the empty string. <literal>vsock</literal> may be replaced with
225 <literal>vsock-stream</literal>, <literal>vsock-dgram</literal> or <literal>vsock-seqpacket</literal>
226 to force usage of the corresponding socket type.</para>
359a5bcf 227
798d3a52
ZJS
228 <para>Note that <constant>SOCK_SEQPACKET</constant> (i.e.
229 <varname>ListenSequentialPacket=</varname>) is only available
230 for <constant>AF_UNIX</constant> sockets.
231 <constant>SOCK_STREAM</constant> (i.e.
232 <varname>ListenStream=</varname>) when used for IP sockets
233 refers to TCP sockets, <constant>SOCK_DGRAM</constant> (i.e.
234 <varname>ListenDatagram=</varname>) to UDP.</para>
235
b938cb90 236 <para>These options may be specified more than once, in which
798d3a52
ZJS
237 case incoming traffic on any of the sockets will trigger
238 service activation, and all listed sockets will be passed to
239 the service, regardless of whether there is incoming traffic
240 on them or not. If the empty string is assigned to any of
241 these options, the list of addresses to listen on is reset,
242 all prior uses of any of these options will have no
243 effect.</para>
244
245 <para>It is also possible to have more than one socket unit
246 for the same service when using <varname>Service=</varname>,
247 and the service will receive all the sockets configured in all
248 the socket units. Sockets configured in one unit are passed in
249 the order of configuration, but no ordering between socket
250 units is specified.</para>
251
252 <para>If an IP address is used here, it is often desirable to
253 listen on it before the interface it is configured on is up
254 and running, and even regardless of whether it will be up and
255 running at any point. To deal with this, it is recommended to
256 set the <varname>FreeBind=</varname> option described
257 below.</para></listitem>
258 </varlistentry>
259
260 <varlistentry>
261 <term><varname>ListenFIFO=</varname></term>
c758bea7
LP
262 <listitem><para>Specifies a file system FIFO (see <citerefentry
263 project='man-pages'><refentrytitle>fifo</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
264 details) to listen on. This expects an absolute file system path as argument. Behavior otherwise is
265 very similar to the <varname>ListenDatagram=</varname> directive above.</para></listitem>
798d3a52
ZJS
266 </varlistentry>
267
268 <varlistentry>
269 <term><varname>ListenSpecial=</varname></term>
270 <listitem><para>Specifies a special file in the file system to
271 listen on. This expects an absolute file system path as
272 argument. Behavior otherwise is very similar to the
273 <varname>ListenFIFO=</varname> directive above. Use this to
274 open character device nodes as well as special files in
3b121157
ZJS
275 <filename>/proc/</filename> and
276 <filename>/sys/</filename>.</para></listitem>
798d3a52
ZJS
277 </varlistentry>
278
279 <varlistentry>
280 <term><varname>ListenNetlink=</varname></term>
281 <listitem><para>Specifies a Netlink family to create a socket
282 for to listen on. This expects a short string referring to the
283 <constant>AF_NETLINK</constant> family name (such as
284 <varname>audit</varname> or <varname>kobject-uevent</varname>)
285 as argument, optionally suffixed by a whitespace followed by a
286 multicast group integer. Behavior otherwise is very similar to
287 the <varname>ListenDatagram=</varname> directive
288 above.</para></listitem>
289 </varlistentry>
290
291 <varlistentry>
292 <term><varname>ListenMessageQueue=</varname></term>
c758bea7
LP
293 <listitem><para>Specifies a POSIX message queue name to listen on (see <citerefentry
294 project='man-pages'><refentrytitle>mq_overview</refentrytitle><manvolnum>7</manvolnum></citerefentry>
295 for details). This expects a valid message queue name (i.e. beginning with
296 <literal>/</literal>). Behavior otherwise is very similar to the <varname>ListenFIFO=</varname>
297 directive above. On Linux message queue descriptors are actually file descriptors and can be
298 inherited between processes.</para></listitem>
798d3a52
ZJS
299 </varlistentry>
300
8c7c9839
PS
301 <varlistentry>
302 <term><varname>ListenUSBFunction=</varname></term>
3d314510 303 <listitem><para>Specifies a <ulink
0e685823 304 url="https://docs.kernel.org/usb/functionfs.html">USB
00bb64ec 305 FunctionFS</ulink> endpoints location to listen on, for
3d314510 306 implementation of USB gadget functions. This expects an
885a4e6c 307 absolute file system path of a FunctionFS mount point as the argument.
00bb64ec 308 Behavior otherwise is very similar to the <varname>ListenFIFO=</varname>
a8eaaee7 309 directive above. Use this to open the FunctionFS endpoint
3d314510
LP
310 <filename>ep0</filename>. When using this option, the
311 activated service has to have the
22065311
ZJS
312 <varname>USBFunctionDescriptors=</varname> and
313 <varname>USBFunctionStrings=</varname> options set.
ec07c3c8
AK
314 </para>
315
316 <xi:include href="version-info.xml" xpointer="v227"/></listitem>
8c7c9839
PS
317 </varlistentry>
318
74bb646e
SS
319 <varlistentry>
320 <term><varname>SocketProtocol=</varname></term>
3f690705
MBN
321 <listitem><para>Takes one of <option>udplite</option>,
322 <option>sctp</option> or <option>mptcp</option>. The socket will use
323 the UDP-Lite (<constant>IPPROTO_UDPLITE</constant>), SCTP
324 (<constant>IPPROTO_SCTP</constant>) or MPTCP
325 (<constant>IPPROTO_MPTCP</constant>) protocol, respectively.</para>
ec07c3c8
AK
326
327 <xi:include href="version-info.xml" xpointer="v229"/>
74bb646e
SS
328 </listitem>
329 </varlistentry>
330
798d3a52
ZJS
331 <varlistentry>
332 <term><varname>BindIPv6Only=</varname></term>
a7c64e14 333 <listitem><para>Takes one of <option>default</option>,
798d3a52
ZJS
334 <option>both</option> or <option>ipv6-only</option>. Controls
335 the IPV6_V6ONLY socket option (see
3ba3a79d 336 <citerefentry project='die-net'><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
798d3a52
ZJS
337 for details). If <option>both</option>, IPv6 sockets bound
338 will be accessible via both IPv4 and IPv6. If
339 <option>ipv6-only</option>, they will be accessible via IPv6
340 only. If <option>default</option> (which is the default,
341 surprise!), the system wide default setting is used, as
342 controlled by
343 <filename>/proc/sys/net/ipv6/bindv6only</filename>, which in
344 turn defaults to the equivalent of
345 <option>both</option>.</para>
346 </listitem>
347 </varlistentry>
348
349 <varlistentry>
350 <term><varname>Backlog=</varname></term>
da890466 351 <listitem><para>Takes an unsigned 32-bit integer argument. Specifies the number of connections to
768fcd77
LP
352 queue that have not been accepted yet. This setting matters only for stream and sequential packet
353 sockets. See
354 <citerefentry><refentrytitle>listen</refentrytitle><manvolnum>2</manvolnum></citerefentry> for
bf63dadb
ZJS
355 details. Defaults to 4294967295. Note that this value is silently capped by the
356 <literal>net.core.somaxconn</literal> sysctl, which typically defaults to 4096, so typically
357 the sysctl is the setting that actually matters.</para></listitem>
798d3a52
ZJS
358 </varlistentry>
359
360 <varlistentry>
361 <term><varname>BindToDevice=</varname></term>
e9dd6984
ZJS
362 <listitem><para>Specifies a network interface name to bind this socket to. If set, traffic will only
363 be accepted from the specified network interfaces. This controls the
364 <constant>SO_BINDTODEVICE</constant> socket option (see <citerefentry
365 project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
366 details). If this option is used, an implicit dependency from this socket unit on the network
367 interface device unit is created
368 (see <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
369 Note that setting this parameter might result in additional dependencies to be added to the unit (see
c129bd5d 370 above).</para></listitem>
798d3a52
ZJS
371 </varlistentry>
372
373 <varlistentry>
374 <term><varname>SocketUser=</varname></term>
375 <term><varname>SocketGroup=</varname></term>
376
e9dd6984 377 <listitem><para>Takes a UNIX user/group name. When specified, all <constant>AF_UNIX</constant>
3eec82f6 378 sockets, FIFO nodes, and message queues are owned by the specified user and group. If unset (the
e9dd6984
ZJS
379 default), the nodes are owned by the root user/group (if run in system context) or the invoking
380 user/group (if run in user context). If only a user is specified but no group, then the group is
ec07c3c8
AK
381 derived from the user's default group.</para>
382
383 <xi:include href="version-info.xml" xpointer="v214"/></listitem>
798d3a52
ZJS
384 </varlistentry>
385
386 <varlistentry>
387 <term><varname>SocketMode=</varname></term>
3eec82f6
DM
388 <listitem><para>If listening on a file system socket, FIFO, or message queue, this option specifies
389 the file system access mode used when creating the file node. Takes an access mode in octal notation.
390 Defaults to 0666.</para></listitem>
798d3a52
ZJS
391 </varlistentry>
392
393 <varlistentry>
394 <term><varname>DirectoryMode=</varname></term>
395 <listitem><para>If listening on a file system socket or FIFO,
396 the parent directories are automatically created if needed.
397 This option specifies the file system access mode used when
398 creating these directories. Takes an access mode in octal
399 notation. Defaults to 0755.</para></listitem>
400 </varlistentry>
401
402 <varlistentry>
403 <term><varname>Accept=</varname></term>
c91d2b43
LP
404 <listitem><para>Takes a boolean argument. If yes, a service instance is spawned for each incoming
405 connection and only the connection socket is passed to it. If no, all listening sockets themselves
406 are passed to the started service unit, and only one service unit is spawned for all connections
407 (also see above). This value is ignored for datagram sockets and FIFOs where a single service unit
fbf43297
LP
408 unconditionally handles all incoming traffic. Defaults to <option>no</option>.</para>
409
410 <para>Typically, for performance sensitive services, a choice of <option>Accept=no</option> is
411 preferable, since that way only the first connection will have to pay the activation resource
412 cost. On the other hand, for sporadically used services <option>Accept=yes</option> can be preferable
413 as it simplifies the implementation (as the service program code only has to process a single
414 connection instead of handling multiple) and enables stronger security (since the various sandboxing
415 options can be used to isolate parallel connections from each other, as each is serviced by a
416 separate service instance and process).</para>
417
418 <para>A service listening on an <constant>AF_UNIX</constant> socket may, but does not need to, call
c91d2b43
LP
419 <citerefentry><refentrytitle>close</refentrytitle><manvolnum>2</manvolnum></citerefentry> on the
420 received socket before exiting. However, it must not unlink the socket from a file system. It should
421 not invoke
422 <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>2</manvolnum></citerefentry> on
423 sockets it got with <varname>Accept=no</varname>, but it may do so for sockets it got with
fbf43297
LP
424 <varname>Accept=yes</varname> set.</para>
425
426 <para>Setting <varname>Accept=yes</varname> is in particular useful for allowing daemons designed for
427 usage with <citerefentry
c91d2b43
LP
428 project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry> to work
429 unmodified with systemd socket activation.</para>
3b1c5241 430
dbbf0618
LP
431 <para>Note that depending on this setting the services activated by units of this type are either
432 regular services (in case of <varname>Accept=</varname><option>no</option>) or instances of templated
433 services (in case of <varname>Accept=</varname><option>yes</option>). See the Description section
434 above for a more detailed discussion of the naming rules of triggered services.</para>
435
608bfe76 436 <para>For IPv4 and IPv6 connections, the <varname>$REMOTE_ADDR</varname> environment variable will
bfb1f9e2
LP
437 contain the remote IP address, and <varname>$REMOTE_PORT</varname> will contain the remote port
438 number. These two variables correspond to those defined by the CGI interface for web services (see
439 <ulink url="https://datatracker.ietf.org/doc/html/rfc3875">RFC 3875</ulink>).</para>
c91d2b43 440
608bfe76
KS
441 <para>For <constant>AF_UNIX</constant> socket connections, the <varname>$REMOTE_ADDR</varname>
442 environment variable will contain either the remote socket's file system path starting with a slash
443 (<literal>/</literal>) or its address in the abstract namespace starting with an at symbol
bfb1f9e2
LP
444 (<literal>@</literal>). If the socket is unnamed, <varname>$REMOTE_ADDR</varname> will not be
445 set.</para>
446
fbf43297
LP
447 <para>If <varname>Accept=yes</varname> is used, the activated service process will have set the
448 <varname>$SO_COOKIE</varname> environment variable to the Linux socket cookie, formatted as decimal
449 integer. The socket cookie can otherwise be acquired via <citerefentry
bfb1f9e2 450 project='man-pages'><refentrytitle>getsockopt</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
608bfe76 451
c91d2b43
LP
452 <para>It is recommended to set <varname>CollectMode=inactive-or-failed</varname> for service
453 instances activated via <varname>Accept=yes</varname>, to ensure that failed connection services are
454 cleaned up and released from memory, and do not accumulate.</para></listitem>
798d3a52
ZJS
455 </varlistentry>
456
55301ec0
LP
457 <varlistentry>
458 <term><varname>Writable=</varname></term>
459 <listitem><para>Takes a boolean argument. May only be used in
460 conjunction with <varname>ListenSpecial=</varname>. If true,
461 the specified special file is opened in read-write mode, if
ec07c3c8
AK
462 false, in read-only mode. Defaults to false.</para>
463
464 <xi:include href="version-info.xml" xpointer="v227"/></listitem>
55301ec0
LP
465 </varlistentry>
466
3e5f04bf
RM
467 <varlistentry>
468 <term><varname>FlushPending=</varname></term>
469 <listitem><para>Takes a boolean argument. May only be used when
470 <option>Accept=no</option>. If yes, the socket's buffers are cleared after the
471 triggered service exited. This causes any pending data to be
472 flushed and any pending incoming connections to be rejected. If no, the
44855c77 473 socket's buffers will not be cleared, permitting the service to handle any
3e5f04bf
RM
474 pending connections after restart, which is the usually expected behaviour.
475 Defaults to <option>no</option>.
ec07c3c8
AK
476 </para>
477
478 <xi:include href="version-info.xml" xpointer="v247"/></listitem>
3e5f04bf
RM
479 </varlistentry>
480
798d3a52
ZJS
481 <varlistentry>
482 <term><varname>MaxConnections=</varname></term>
6b014a2a
MY
483 <listitem><para>The maximum number of connections to simultaneously run services instances for, when
484 <option>Accept=yes</option> is set. If more concurrent connections are coming in, they will be refused
485 until at least one existing connection is terminated. This setting has no effect on sockets configured
486 with <option>Accept=no</option> or datagram sockets. Defaults to 64.</para></listitem>
798d3a52
ZJS
487 </varlistentry>
488
489 <varlistentry>
9d565427 490 <term><varname>MaxConnectionsPerSource=</varname></term>
48930a5d
LP
491 <listitem><para>The maximum number of connections for a service per source IP address (in case of
492 IPv4/IPv6), per source CID (in case of <constant>AF_VSOCK</constant>), or source UID (in case of
493 <constant>AF_UNIX</constant>). This is very similar to the <varname>MaxConnections=</varname>
6b014a2a 494 directive above. Defaults to 0, i.e. disabled.</para>
ec07c3c8
AK
495
496 <xi:include href="version-info.xml" xpointer="v232"/>
9d565427
SS
497 </listitem>
498 </varlistentry>
499
500 <varlistentry>
798d3a52 501 <term><varname>KeepAlive=</varname></term>
e9dd6984
ZJS
502 <listitem><para>Takes a boolean argument. If true, the TCP/IP stack will send a keep alive message
503 after 2h (depending on the configuration of
504 <filename>/proc/sys/net/ipv4/tcp_keepalive_time</filename>) for all TCP streams accepted on this
505 socket. This controls the <constant>SO_KEEPALIVE</constant> socket option (see <citerefentry
506 project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> and
507 the <ulink url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP Keepalive
508 HOWTO</ulink> for details.) Defaults to <option>false</option>.</para></listitem>
798d3a52
ZJS
509 </varlistentry>
510
511 <varlistentry>
512 <term><varname>KeepAliveTimeSec=</varname></term>
b938cb90 513 <listitem><para>Takes time (in seconds) as argument. The connection needs to remain
798d3a52
ZJS
514 idle before TCP starts sending keepalive probes. This controls the TCP_KEEPIDLE
515 socket option (see
3ba3a79d 516 <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
798d3a52
ZJS
517 and the <ulink
518 url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
519 Keepalive HOWTO</ulink> for details.)
ec07c3c8
AK
520 Default value is 7200 seconds (2 hours).</para>
521
522 <xi:include href="version-info.xml" xpointer="v216"/></listitem>
798d3a52
ZJS
523 </varlistentry>
524
525 <varlistentry>
526 <term><varname>KeepAliveIntervalSec=</varname></term>
e9dd6984
ZJS
527 <listitem><para>Takes time (in seconds) as argument between individual keepalive probes, if the
528 socket option <constant>SO_KEEPALIVE</constant> has been set on this socket. This controls the
529 <constant>TCP_KEEPINTVL</constant> socket option (see <citerefentry
530 project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> and
531 the <ulink url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP Keepalive
ec07c3c8
AK
532 HOWTO</ulink> for details.) Default value is 75 seconds.</para>
533
534 <xi:include href="version-info.xml" xpointer="v216"/></listitem>
798d3a52
ZJS
535 </varlistentry>
536
537 <varlistentry>
538 <term><varname>KeepAliveProbes=</varname></term>
7ca41557 539 <listitem><para>Takes an integer as argument. It is the number of
798d3a52
ZJS
540 unacknowledged probes to send before considering the
541 connection dead and notifying the application layer. This
542 controls the TCP_KEEPCNT socket option (see
3ba3a79d 543 <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
798d3a52
ZJS
544 and the <ulink
545 url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
6870daff 546 Keepalive HOWTO</ulink> for details.) Default value is
ec07c3c8
AK
547 9.</para>
548
549 <xi:include href="version-info.xml" xpointer="v216"/></listitem>
798d3a52
ZJS
550 </varlistentry>
551
552 <varlistentry>
553 <term><varname>NoDelay=</varname></term>
554 <listitem><para>Takes a boolean argument. TCP Nagle's
555 algorithm works by combining a number of small outgoing
556 messages, and sending them all at once. This controls the
557 TCP_NODELAY socket option (see
e9dd6984 558 <citerefentry project='die-net'><refentrytitle>tcp</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
ec07c3c8
AK
559 Defaults to <option>false</option>.</para>
560
561 <xi:include href="version-info.xml" xpointer="v216"/></listitem>
798d3a52
ZJS
562 </varlistentry>
563
564 <varlistentry>
565 <term><varname>Priority=</varname></term>
e9dd6984
ZJS
566 <listitem><para>Takes an integer argument controlling the priority for all traffic sent from this
567 socket. This controls the <constant>SO_PRIORITY</constant> socket option (see <citerefentry
568 project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
569 details.).</para></listitem>
798d3a52
ZJS
570 </varlistentry>
571
572 <varlistentry>
573 <term><varname>DeferAcceptSec=</varname></term>
574
575 <listitem><para>Takes time (in seconds) as argument. If set,
576 the listening process will be awakened only when data arrives
577 on the socket, and not immediately when connection is
578 established. When this option is set, the
579 <constant>TCP_DEFER_ACCEPT</constant> socket option will be
580 used (see
3ba3a79d 581 <citerefentry project='die-net'><refentrytitle>tcp</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
798d3a52
ZJS
582 and the kernel will ignore initial ACK packets without any
583 data. The argument specifies the approximate amount of time
584 the kernel should wait for incoming data before falling back
2dd67817 585 to the normal behavior of honoring empty ACK packets. This
798d3a52
ZJS
586 option is beneficial for protocols where the client sends the
587 data first (e.g. HTTP, in contrast to SMTP), because the
588 server process will not be woken up unnecessarily before it
589 can take any action.
590 </para>
591
592 <para>If the client also uses the
593 <constant>TCP_DEFER_ACCEPT</constant> option, the latency of
594 the initial connection may be reduced, because the kernel will
595 send data in the final packet establishing the connection (the
596 third packet in the "three-way handshake").</para>
597
598 <para>Disabled by default.</para>
ec07c3c8
AK
599
600 <xi:include href="version-info.xml" xpointer="v216"/>
798d3a52
ZJS
601 </listitem>
602 </varlistentry>
603
604 <varlistentry>
605 <term><varname>ReceiveBuffer=</varname></term>
606 <term><varname>SendBuffer=</varname></term>
e9dd6984
ZJS
607 <listitem><para>Takes an integer argument controlling the receive or send buffer sizes of this
608 socket, respectively. This controls the <constant>SO_RCVBUF</constant> and
609 <constant>SO_SNDBUF</constant> socket options (see <citerefentry
610 project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
611 details.). The usual suffixes K, M, G are supported and are understood to the base of
612 1024.</para></listitem>
798d3a52
ZJS
613 </varlistentry>
614
615 <varlistentry>
616 <term><varname>IPTOS=</varname></term>
c6a79245
LP
617 <listitem><para>Takes an integer argument controlling the IP Type-Of-Service field for packets
618 generated from this socket. This controls the <constant>IP_TOS</constant> socket option (see
619 <citerefentry
620 project='die-net'><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
621 details.). Either a numeric string or one of <option>low-delay</option>, <option>throughput</option>,
622 <option>reliability</option> or <option>low-cost</option> may be specified.</para></listitem>
798d3a52
ZJS
623 </varlistentry>
624
625 <varlistentry>
626 <term><varname>IPTTL=</varname></term>
c6a79245
LP
627 <listitem><para>Takes an integer argument controlling the IPv4 Time-To-Live/IPv6 Hop-Count field for
628 packets generated from this socket. This sets the
629 <constant>IP_TTL</constant>/<constant>IPV6_UNICAST_HOPS</constant> socket options (see <citerefentry
630 project='die-net'><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry> and
631 <citerefentry
632 project='die-net'><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
633 details.)</para></listitem>
798d3a52
ZJS
634 </varlistentry>
635
636 <varlistentry>
637 <term><varname>Mark=</varname></term>
e9dd6984
ZJS
638 <listitem><para>Takes an integer value. Controls the firewall mark of packets generated by this
639 socket. This can be used in the firewall logic to filter packets from this socket. This sets the
640 <constant>SO_MARK</constant> socket option. See <citerefentry
641 project='die-net'><refentrytitle>iptables</refentrytitle><manvolnum>8</manvolnum></citerefentry> for
642 details.</para></listitem>
798d3a52
ZJS
643 </varlistentry>
644
645 <varlistentry>
646 <term><varname>ReusePort=</varname></term>
e9dd6984
ZJS
647 <listitem><para>Takes a boolean value. If true, allows multiple
648 <citerefentry><refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum></citerefentry>s to this TCP
649 or UDP port. This controls the <constant>SO_REUSEPORT</constant> socket option. See <citerefentry
650 project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
ec07c3c8
AK
651 details.</para>
652
653 <xi:include href="version-info.xml" xpointer="v206"/></listitem>
798d3a52
ZJS
654 </varlistentry>
655
656 <varlistentry>
657 <term><varname>SmackLabel=</varname></term>
658 <term><varname>SmackLabelIPIn=</varname></term>
659 <term><varname>SmackLabelIPOut=</varname></term>
660 <listitem><para>Takes a string value. Controls the extended
661 attributes <literal>security.SMACK64</literal>,
662 <literal>security.SMACK64IPIN</literal> and
663 <literal>security.SMACK64IPOUT</literal>, respectively, i.e.
664 the security label of the FIFO, or the security label for the
665 incoming or outgoing connections of the socket, respectively.
666 See <ulink
0e685823 667 url="https://docs.kernel.org/admin-guide/LSM/Smack.html">Smack</ulink>
ec07c3c8
AK
668 for details.</para>
669
670 <xi:include href="version-info.xml" xpointer="v196"/></listitem>
798d3a52
ZJS
671 </varlistentry>
672
673 <varlistentry>
674 <term><varname>SELinuxContextFromNet=</varname></term>
675 <listitem><para>Takes a boolean argument. When true, systemd
676 will attempt to figure out the SELinux label used for the
677 instantiated service from the information handed by the peer
678 over the network. Note that only the security level is used
679 from the information provided by the peer. Other parts of the
680 resulting SELinux context originate from either the target
681 binary that is effectively triggered by socket unit or from
682 the value of the <varname>SELinuxContext=</varname> option.
49590d67
MS
683 This configuration option applies only when activated service
684 is passed in single socket file descriptor, i.e. service
685 instances that have standard input connected to a socket or
686 services triggered by exactly one socket unit. Also note
687 that this option is useful only when MLS/MCS SELinux policy
688 is deployed. Defaults to
ec07c3c8
AK
689 <literal>false</literal>. </para>
690
691 <xi:include href="version-info.xml" xpointer="v217"/></listitem>
798d3a52
ZJS
692 </varlistentry>
693
694 <varlistentry>
695 <term><varname>PipeSize=</varname></term>
696 <listitem><para>Takes a size in bytes. Controls the pipe
697 buffer size of FIFOs configured in this socket unit. See
698 <citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
699 for details. The usual suffixes K, M, G are supported and are
700 understood to the base of 1024.</para></listitem>
701 </varlistentry>
702
703 <varlistentry>
704 <term><varname>MessageQueueMaxMessages=</varname>,
705 <varname>MessageQueueMessageSize=</varname></term>
706 <listitem><para>These two settings take integer values and
707 control the mq_maxmsg field or the mq_msgsize field,
708 respectively, when creating the message queue. Note that
709 either none or both of these variables need to be set. See
3ba3a79d 710 <citerefentry project='die-net'><refentrytitle>mq_setattr</refentrytitle><manvolnum>3</manvolnum></citerefentry>
798d3a52
ZJS
711 for details.</para></listitem>
712 </varlistentry>
713
714 <varlistentry>
715 <term><varname>FreeBind=</varname></term>
c6a79245
LP
716 <listitem><para>Takes a boolean value. Controls whether the socket can be bound to non-local IP
717 addresses. This is useful to configure sockets listening on specific IP addresses before those IP
718 addresses are successfully configured on a network interface. This sets the
719 <constant>IP_FREEBIND</constant>/<constant>IPV6_FREEBIND</constant> socket option. For robustness
720 reasons it is recommended to use this option whenever you bind a socket to a specific IP
721 address. Defaults to <option>false</option>.</para></listitem>
798d3a52
ZJS
722 </varlistentry>
723
724 <varlistentry>
725 <term><varname>Transparent=</varname></term>
726 <listitem><para>Takes a boolean value. Controls the
c6a79245 727 <constant>IP_TRANSPARENT</constant>/<constant>IPV6_TRANSPARENT</constant> socket option. Defaults to
798d3a52
ZJS
728 <option>false</option>.</para></listitem>
729 </varlistentry>
730
731 <varlistentry>
732 <term><varname>Broadcast=</varname></term>
e9dd6984
ZJS
733 <listitem><para>Takes a boolean value. This controls the <constant>SO_BROADCAST</constant> socket
734 option, which allows broadcast datagrams to be sent from this socket. Defaults to
798d3a52
ZJS
735 <option>false</option>.</para></listitem>
736 </varlistentry>
737
738 <varlistentry>
739 <term><varname>PassCredentials=</varname></term>
e9dd6984
ZJS
740 <listitem><para>Takes a boolean value. This controls the <constant>SO_PASSCRED</constant> socket
741 option, which allows <constant>AF_UNIX</constant> sockets to receive the credentials of the sending
742 process in an ancillary message. Defaults to <option>false</option>.</para></listitem>
798d3a52
ZJS
743 </varlistentry>
744
35462aa1
MY
745 <varlistentry>
746 <term><varname>PassPIDFD=</varname></term>
747
748 <listitem><para>Takes a boolean value. This controls the <constant>SO_PASSPIDFD</constant> socket
749 option, which allows <constant>AF_UNIX</constant> sockets to receive the pidfd of the sending
750 process in an ancillary message. Defaults to <option>false</option>.</para>
751
752 <xi:include href="version-info.xml" xpointer="v258"/></listitem>
753 </varlistentry>
754
798d3a52
ZJS
755 <varlistentry>
756 <term><varname>PassSecurity=</varname></term>
e9dd6984
ZJS
757 <listitem><para>Takes a boolean value. This controls the <constant>SO_PASSSEC</constant> socket
758 option, which allows <constant>AF_UNIX</constant> sockets to receive the security context of the
759 sending process in an ancillary message. Defaults to <option>false</option>.</para></listitem>
798d3a52
ZJS
760 </varlistentry>
761
a3d19f5d
LP
762 <varlistentry>
763 <term><varname>PassPacketInfo=</varname></term>
764 <listitem><para>Takes a boolean value. This controls the <constant>IP_PKTINFO</constant>,
2d6d4136
LP
765 <constant>IPV6_RECVPKTINFO</constant>, <constant>NETLINK_PKTINFO</constant> or
766 <constant>PACKET_AUXDATA</constant> socket options, which enable reception of additional per-packet
767 metadata as ancillary message, on <constant>AF_INET</constant>, <constant>AF_INET6</constant>,
768 <constant>AF_UNIX</constant> and <constant>AF_PACKET</constant> sockets. Defaults to
ec07c3c8
AK
769 <option>false</option>.</para>
770
771 <xi:include href="version-info.xml" xpointer="v246"/></listitem>
a3d19f5d
LP
772 </varlistentry>
773
5c12797f
MY
774 <varlistentry>
775 <term><varname>AcceptFileDescriptors=</varname></term>
776
777 <listitem><para>Takes a boolean value. This controls the <constant>SO_PASSRIGHTS</constant> socket
778 option, which when disabled prohibits the peer from sending <constant>SCM_RIGHTS</constant>
779 ancillary messages (aka file descriptors) via <constant>AF_UNIX</constant> sockets. Defaults to
780 <option>true</option>.</para>
781
782 <xi:include href="version-info.xml" xpointer="v258"/></listitem>
783 </varlistentry>
784
95923d7e
LP
785 <varlistentry>
786 <term><varname>Timestamping=</varname></term>
787 <listitem><para>Takes one of <literal>off</literal>, <literal>us</literal> (alias:
e503019b 788 <literal>usec</literal>, <literal>μs</literal>) or <literal>ns</literal> (alias:
95923d7e
LP
789 <literal>nsec</literal>). This controls the <constant>SO_TIMESTAMP</constant> or
790 <constant>SO_TIMESTAMPNS</constant> socket options, and enables whether ingress network traffic shall
ec07c3c8
AK
791 carry timestamping metadata. Defaults to <option>off</option>.</para>
792
793 <xi:include href="version-info.xml" xpointer="v247"/></listitem>
95923d7e
LP
794 </varlistentry>
795
798d3a52
ZJS
796 <varlistentry>
797 <term><varname>TCPCongestion=</varname></term>
e9dd6984 798 <listitem><para>Takes a string value. Controls the TCP congestion algorithm used by this
a7d8cacc 799 socket. Should be one of <literal>westwood</literal>, <literal>reno</literal>,
e9dd6984
ZJS
800 <literal>cubic</literal>, <literal>lp</literal> or any other available algorithm supported by the IP
801 stack. This setting applies only to stream sockets.</para></listitem>
798d3a52
ZJS
802 </varlistentry>
803
804 <varlistentry>
805 <term><varname>ExecStartPre=</varname></term>
806 <term><varname>ExecStartPost=</varname></term>
807 <listitem><para>Takes one or more command lines, which are
808 executed before or after the listening sockets/FIFOs are
809 created and bound, respectively. The first token of the
810 command line must be an absolute filename, then followed by
811 arguments for the process. Multiple command lines may be
812 specified following the same scheme as used for
813 <varname>ExecStartPre=</varname> of service unit
814 files.</para></listitem>
815 </varlistentry>
816
817 <varlistentry>
818 <term><varname>ExecStopPre=</varname></term>
819 <term><varname>ExecStopPost=</varname></term>
820 <listitem><para>Additional commands that are executed before
821 or after the listening sockets/FIFOs are closed and removed,
822 respectively. Multiple command lines may be specified
823 following the same scheme as used for
824 <varname>ExecStartPre=</varname> of service unit
825 files.</para></listitem>
826 </varlistentry>
827
828 <varlistentry>
829 <term><varname>TimeoutSec=</varname></term>
830 <listitem><para>Configures the time to wait for the commands
831 specified in <varname>ExecStartPre=</varname>,
832 <varname>ExecStartPost=</varname>,
833 <varname>ExecStopPre=</varname> and
834 <varname>ExecStopPost=</varname> to finish. If a command does
835 not exit within the configured time, the socket will be
836 considered failed and be shut down again. All commands still
837 running will be terminated forcibly via
838 <constant>SIGTERM</constant>, and after another delay of this
839 time with <constant>SIGKILL</constant>. (See
840 <option>KillMode=</option> in
841 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
842 Takes a unit-less value in seconds, or a time span value such
843 as "5min 20s". Pass <literal>0</literal> to disable the
844 timeout logic. Defaults to
845 <varname>DefaultTimeoutStartSec=</varname> from the manager
846 configuration file (see
847 <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
848 </para></listitem>
849 </varlistentry>
850
851 <varlistentry>
852 <term><varname>Service=</varname></term>
853 <listitem><para>Specifies the service unit name to activate on
854 incoming traffic. This setting is only allowed for sockets
855 with <varname>Accept=no</varname>. It defaults to the service
856 that bears the same name as the socket (with the suffix
857 replaced). In most cases, it should not be necessary to use
c129bd5d
LP
858 this option. Note that setting this parameter might result in
859 additional dependencies to be added to the unit (see
860 above).</para></listitem>
798d3a52
ZJS
861 </varlistentry>
862
863 <varlistentry>
864 <term><varname>RemoveOnStop=</varname></term>
e9dd6984
ZJS
865 <listitem><para>Takes a boolean argument. If enabled, any file nodes created by this socket unit are
866 removed when it is stopped. This applies to <constant>AF_UNIX</constant> sockets in the file system,
867 POSIX message queues, FIFOs, as well as any symlinks to them configured with
868 <varname>Symlinks=</varname>. Normally, it should not be necessary to use this option, and is not
869 recommended as services might continue to run after the socket unit has been terminated and it should
870 still be possible to communicate with them via their file system node. Defaults to
ec07c3c8
AK
871 off.</para>
872
873 <xi:include href="version-info.xml" xpointer="v214"/></listitem>
798d3a52
ZJS
874 </varlistentry>
875
876 <varlistentry>
877 <term><varname>Symlinks=</varname></term>
3ecc7fc3
LP
878 <listitem><para>Takes a list of file system paths. The specified paths will be created as symlinks to the
879 <constant>AF_UNIX</constant> socket path or FIFO path of this socket unit. If this setting is used, only one
880 <constant>AF_UNIX</constant> socket in the file system or one FIFO may be configured for the socket unit. Use
881 this option to manage one or more symlinked alias names for a socket, binding their lifecycle together. Note
882 that if creation of a symlink fails this is not considered fatal for the socket unit, and the socket unit may
883 still start. If an empty string is assigned, the list of paths is reset. Defaults to an empty
ec07c3c8
AK
884 list.</para>
885
886 <xi:include href="version-info.xml" xpointer="v214"/></listitem>
798d3a52
ZJS
887 </varlistentry>
888
8dd4c05b
LP
889 <varlistentry>
890 <term><varname>FileDescriptorName=</varname></term>
daa78907
MY
891 <listitem><para>Assigns a name to all file descriptors this socket unit encapsulates.
892 This is useful to help activated services identify specific file descriptors, if multiple fds are passed.
893 Services may use the
8dd4c05b 894 <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>
daa78907
MY
895 call to acquire the names configured for the received file descriptors. Names may contain any ASCII character,
896 but must exclude control characters and <literal>:</literal>, and must be at most 255 characters in length.
897 If this setting is not used, the file descriptor name defaults to the name of the socket unit
898 (including its <filename>.socket</filename> suffix) when <varname>Accept=no</varname>,
899 <literal>connection</literal> otherwise.</para>
ec07c3c8
AK
900
901 <xi:include href="version-info.xml" xpointer="v227"/></listitem>
8dd4c05b
LP
902 </varlistentry>
903
8b26cdbd
LP
904 <varlistentry>
905 <term><varname>TriggerLimitIntervalSec=</varname></term>
db985064 906 <term><varname>TriggerLimitBurst=</varname></term>
8b26cdbd 907
9373fce6
LP
908 <listitem><para>Configures a limit on how often this socket unit may be activated within a specific
909 time interval. The <varname>TriggerLimitIntervalSec=</varname> setting may be used to configure the
910 length of the time interval in the usual time units <literal>us</literal>, <literal>ms</literal>,
911 <literal>s</literal>, <literal>min</literal>, <literal>h</literal>, … and defaults to 2s (See
912 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
913 details on the various time units understood). The <varname>TriggerLimitBurst=</varname> setting
914 takes a positive integer value and specifies the number of permitted activations per time interval,
915 and defaults to 200 for <varname>Accept=yes</varname> sockets (thus by default permitting 200
916 activations per 2s), and 20 otherwise (20 activations per 2s). Set either to 0 to disable any form of
917 trigger rate limiting.</para>
918
919 <para>If the limit is hit, the socket unit is placed into a failure mode, and will not be connectible
920 anymore until restarted. Note that this limit is enforced before the service activation is
921 enqueued.</para>
922
923 <para>Compare with <varname>PollLimitIntervalSec=</varname>/<varname>PollLimitBurst=</varname>
924 described below, which implements a temporary slowdown if a socket unit is flooded with incoming
925 traffic, as opposed to the permanent failure state
926 <varname>TriggerLimitIntervalSec=</varname>/<varname>TriggerLimitBurst=</varname> results in.</para>
ec07c3c8
AK
927
928 <xi:include href="version-info.xml" xpointer="v230"/></listitem>
8b26cdbd
LP
929 </varlistentry>
930
9373fce6
LP
931 <varlistentry>
932 <term><varname>PollLimitIntervalSec=</varname></term>
933 <term><varname>PollLimitBurst=</varname></term>
934
935 <listitem><para>Configures a limit on how often polling events on the file descriptors backing this
936 socket unit will be considered. This pair of settings is similar to
937 <varname>TriggerLimitIntervalSec=</varname>/<varname>TriggerLimitBurst=</varname> but instead of
938 putting a (fatal) limit on the activation frequency puts a (transient) limit on the polling
939 frequency. The expected parameter syntax and range are identical to that of the aforementioned
940 options, and can be disabled the same way.</para>
941
942 <para>If the polling limit is hit polling is temporarily disabled on it until the specified time
943 window passes. The polling limit hence slows down connection attempts if hit, but unlike the trigger
44855c77 944 limit will not cause permanent failures. It's the recommended mechanism to deal with DoS attempts
9373fce6
LP
945 through packet flooding.</para>
946
947 <para>The polling limit is enforced per file descriptor to listen on, as opposed to the trigger limit
948 which is enforced for the entire socket unit. This distinction matters for socket units that listen
949 on multiple file descriptors (i.e. have multiple <varname>ListenXYZ=</varname> stanzas).</para>
950
951 <para>These setting defaults to 150 (in case of <varname>Accept=yes</varname>) and 15 (otherwise)
952 polling events per 2s. This is considerably lower than the default values for the trigger limit (see
953 above) and means that the polling limit should typically ensure the trigger limit is never hit,
954 unless one of them is reconfigured or disabled.</para>
955
956 <xi:include href="version-info.xml" xpointer="v255"/></listitem>
957 </varlistentry>
958
97df75d7
JS
959 <varlistentry>
960 <term><varname>PassFileDescriptorsToExec=</varname></term>
961
962 <listitem><para>Takes a boolean argument. Defaults to off. If enabled, file descriptors created by
963 the socket unit are passed to <varname>ExecStartPost=</varname>, <varname>ExecStopPre=</varname>, and
964 <varname>ExecStopPost=</varname> commands from the socket unit. The passed file descriptors can be
965 accessed with
966 <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> as
967 if the commands were invoked from the associated service units. Note that
968 <varname>ExecStartPre=</varname> command cannot access socket file descriptors.</para>
969
970 <xi:include href="version-info.xml" xpointer="v256"/></listitem>
971 </varlistentry>
972
798d3a52
ZJS
973 </variablelist>
974
d8e1613e 975 <xi:include href="systemd.service.xml" xpointer="shared-unit-options" />
798d3a52
ZJS
976 </refsect1>
977
978 <refsect1>
979 <title>See Also</title>
13a69c12
DT
980 <para><simplelist type="inline">
981 <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
982 <member><citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
983 <member><citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
984 <member><citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
985 <member><citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
986 <member><citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
987 <member><citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
988 <member><citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
989 <member><citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
990 <member><citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
991 <member><citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
992 </simplelist></para>
798d3a52
ZJS
993 <para>
994 For more extensive descriptions see the "systemd for Developers" series:
13a69c12
DT
995 <simplelist type="inline">
996 <member><ulink url="https://0pointer.de/blog/projects/socket-activation.html">Socket Activation</ulink></member>
997 <member><ulink url="https://0pointer.de/blog/projects/socket-activation2.html">Socket Activation, part II</ulink></member>
998 <member><ulink url="https://0pointer.de/blog/projects/inetd.html">Converting inetd Services</ulink></member>
999 <member><ulink url="https://0pointer.de/blog/projects/socket-activated-containers.html">Socket Activated Internet Services and OS Containers</ulink></member>
1000 </simplelist>.
798d3a52
ZJS
1001 </para>
1002 </refsect1>
1f812fea
LP
1003
1004</refentry>