2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
6 <refentry id=
"systemd.socket" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
8 <title>systemd.socket
</title>
9 <productname>systemd
</productname>
13 <refentrytitle>systemd.socket
</refentrytitle>
14 <manvolnum>5</manvolnum>
18 <refname>systemd.socket
</refname>
19 <refpurpose>Socket unit configuration
</refpurpose>
23 <para><filename><replaceable>socket
</replaceable>.socket
</filename></para>
27 <title>Description
</title>
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>
34 <para>This man page lists the configuration options specific to
36 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
37 for the common options of all unit configuration files. The common
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>
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
54 <para>For each socket unit, a matching service unit must exist,
55 describing the service to start on incoming traffic on the socket
57 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
58 for more information about .service units). The name of the
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
68 <option>Accept=no
</option> is set. If
69 <option>Accept=yes
</option> is set, a service template
70 <filename>foo@.service
</filename> must exist from which services
71 are instantiated for each incoming connection.
</para>
73 <para>No implicit
<varname>WantedBy=
</varname> or
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>
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>
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>
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
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>
107 <title>Automatic Dependencies
</title>
110 <title>Implicit Dependencies
</title>
112 <para>The following dependencies are implicitly added:
</para>
115 <listitem><para>Socket units automatically gain a
<varname>Before=
</varname>
116 dependency on the service units they activate.
</para></listitem>
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>
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>
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>
132 <citerefentry><refentrytitle>systemd.resource-control
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
136 <title>Default Dependencies
</title>
138 <para>The following dependencies are added unless
139 <varname>DefaultDependencies=no
</varname> is set:
</para>
142 <listitem><para>Socket units automatically gain a
143 <varname>Before=
</varname> dependency on
144 <filename>sockets.target
</filename>.
</para></listitem>
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>
160 <title>Options
</title>
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>.
166 <para>Socket unit files must include a [Socket] section, which carries
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
170 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
172 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
173 The options specific to the [Socket] section of socket units are
174 the following:
</para>
176 <variablelist class='unit-directives'
>
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>
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>
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
197 <citerefentry project='man-pages'
><refentrytitle>unix
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para>
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.
206 <para>If the address string is a string in the format
207 <literal><replaceable>v.w.x.y
</replaceable>:
<replaceable>z
</replaceable></literal>, it is interpreted
208 as IPv4 address
<replaceable>v.w.x.y
</replaceable> and port
<replaceable>z
</replaceable>.
</para>
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
213 interface scope (interface name or number) may be specified after a
<literal>%
</literal> symbol:
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>
219 <para>If the address string is a string in the format
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
224 set to the empty string.
</para>
226 <para>Note that
<constant>SOCK_SEQPACKET
</constant> (i.e.
227 <varname>ListenSequentialPacket=
</varname>) is only available
228 for
<constant>AF_UNIX
</constant> sockets.
229 <constant>SOCK_STREAM
</constant> (i.e.
230 <varname>ListenStream=
</varname>) when used for IP sockets
231 refers to TCP sockets,
<constant>SOCK_DGRAM
</constant> (i.e.
232 <varname>ListenDatagram=
</varname>) to UDP.
</para>
234 <para>These options may be specified more than once, in which
235 case incoming traffic on any of the sockets will trigger
236 service activation, and all listed sockets will be passed to
237 the service, regardless of whether there is incoming traffic
238 on them or not. If the empty string is assigned to any of
239 these options, the list of addresses to listen on is reset,
240 all prior uses of any of these options will have no
243 <para>It is also possible to have more than one socket unit
244 for the same service when using
<varname>Service=
</varname>,
245 and the service will receive all the sockets configured in all
246 the socket units. Sockets configured in one unit are passed in
247 the order of configuration, but no ordering between socket
248 units is specified.
</para>
250 <para>If an IP address is used here, it is often desirable to
251 listen on it before the interface it is configured on is up
252 and running, and even regardless of whether it will be up and
253 running at any point. To deal with this, it is recommended to
254 set the
<varname>FreeBind=
</varname> option described
255 below.
</para></listitem>
259 <term><varname>ListenFIFO=
</varname></term>
260 <listitem><para>Specifies a file system FIFO (see
<citerefentry
261 project='man-pages'
><refentrytitle>fifo
</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
262 details) to listen on. This expects an absolute file system path as argument. Behavior otherwise is
263 very similar to the
<varname>ListenDatagram=
</varname> directive above.
</para></listitem>
267 <term><varname>ListenSpecial=
</varname></term>
268 <listitem><para>Specifies a special file in the file system to
269 listen on. This expects an absolute file system path as
270 argument. Behavior otherwise is very similar to the
271 <varname>ListenFIFO=
</varname> directive above. Use this to
272 open character device nodes as well as special files in
273 <filename>/proc/
</filename> and
274 <filename>/sys/
</filename>.
</para></listitem>
278 <term><varname>ListenNetlink=
</varname></term>
279 <listitem><para>Specifies a Netlink family to create a socket
280 for to listen on. This expects a short string referring to the
281 <constant>AF_NETLINK
</constant> family name (such as
282 <varname>audit
</varname> or
<varname>kobject-uevent
</varname>)
283 as argument, optionally suffixed by a whitespace followed by a
284 multicast group integer. Behavior otherwise is very similar to
285 the
<varname>ListenDatagram=
</varname> directive
286 above.
</para></listitem>
290 <term><varname>ListenMessageQueue=
</varname></term>
291 <listitem><para>Specifies a POSIX message queue name to listen on (see
<citerefentry
292 project='man-pages'
><refentrytitle>mq_overview
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
293 for details). This expects a valid message queue name (i.e. beginning with
294 <literal>/
</literal>). Behavior otherwise is very similar to the
<varname>ListenFIFO=
</varname>
295 directive above. On Linux message queue descriptors are actually file descriptors and can be
296 inherited between processes.
</para></listitem>
300 <term><varname>ListenUSBFunction=
</varname></term>
301 <listitem><para>Specifies a
<ulink
302 url=
"https://docs.kernel.org/usb/functionfs.html">USB
303 FunctionFS
</ulink> endpoints location to listen on, for
304 implementation of USB gadget functions. This expects an
305 absolute file system path of a FunctionFS mount point as the argument.
306 Behavior otherwise is very similar to the
<varname>ListenFIFO=
</varname>
307 directive above. Use this to open the FunctionFS endpoint
308 <filename>ep0
</filename>. When using this option, the
309 activated service has to have the
310 <varname>USBFunctionDescriptors=
</varname> and
311 <varname>USBFunctionStrings=
</varname> options set.
316 <term><varname>SocketProtocol=
</varname></term>
317 <listitem><para>Takes one of
<option>udplite
</option>
318 or
<option>sctp
</option>. The socket will use the UDP-Lite
319 (
<constant>IPPROTO_UDPLITE
</constant>) or SCTP
320 (
<constant>IPPROTO_SCTP
</constant>) protocol, respectively.
</para>
325 <term><varname>BindIPv6Only=
</varname></term>
326 <listitem><para>Takes one of
<option>default
</option>,
327 <option>both
</option> or
<option>ipv6-only
</option>. Controls
328 the IPV6_V6ONLY socket option (see
329 <citerefentry project='die-net'
><refentrytitle>ipv6
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
330 for details). If
<option>both
</option>, IPv6 sockets bound
331 will be accessible via both IPv4 and IPv6. If
332 <option>ipv6-only
</option>, they will be accessible via IPv6
333 only. If
<option>default
</option> (which is the default,
334 surprise!), the system wide default setting is used, as
336 <filename>/proc/sys/net/ipv6/bindv6only
</filename>, which in
337 turn defaults to the equivalent of
338 <option>both
</option>.
</para>
343 <term><varname>Backlog=
</varname></term>
344 <listitem><para>Takes an unsigned integer argument. Specifies
345 the number of connections to queue that have not been accepted
346 yet. This setting matters only for stream and sequential
348 <citerefentry><refentrytitle>listen
</refentrytitle><manvolnum>2</manvolnum></citerefentry>
349 for details. Defaults to SOMAXCONN (
128).
</para></listitem>
353 <term><varname>BindToDevice=
</varname></term>
354 <listitem><para>Specifies a network interface name to bind this socket to. If set, traffic will only
355 be accepted from the specified network interfaces. This controls the
356 <constant>SO_BINDTODEVICE
</constant> socket option (see
<citerefentry
357 project='man-pages'
><refentrytitle>socket
</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
358 details). If this option is used, an implicit dependency from this socket unit on the network
359 interface device unit is created
360 (see
<citerefentry><refentrytitle>systemd.device
</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
361 Note that setting this parameter might result in additional dependencies to be added to the unit (see
362 above).
</para></listitem>
366 <term><varname>SocketUser=
</varname></term>
367 <term><varname>SocketGroup=
</varname></term>
369 <listitem><para>Takes a UNIX user/group name. When specified, all
<constant>AF_UNIX
</constant>
370 sockets and FIFO nodes in the file system are owned by the specified user and group. If unset (the
371 default), the nodes are owned by the root user/group (if run in system context) or the invoking
372 user/group (if run in user context). If only a user is specified but no group, then the group is
373 derived from the user's default group.
</para></listitem>
377 <term><varname>SocketMode=
</varname></term>
378 <listitem><para>If listening on a file system socket or FIFO,
379 this option specifies the file system access mode used when
380 creating the file node. Takes an access mode in octal
381 notation. Defaults to
0666.
</para></listitem>
385 <term><varname>DirectoryMode=
</varname></term>
386 <listitem><para>If listening on a file system socket or FIFO,
387 the parent directories are automatically created if needed.
388 This option specifies the file system access mode used when
389 creating these directories. Takes an access mode in octal
390 notation. Defaults to
0755.
</para></listitem>
394 <term><varname>Accept=
</varname></term>
395 <listitem><para>Takes a boolean argument. If yes, a service instance is spawned for each incoming
396 connection and only the connection socket is passed to it. If no, all listening sockets themselves
397 are passed to the started service unit, and only one service unit is spawned for all connections
398 (also see above). This value is ignored for datagram sockets and FIFOs where a single service unit
399 unconditionally handles all incoming traffic. Defaults to
<option>no
</option>. For performance
400 reasons, it is recommended to write new daemons only in a way that is suitable for
401 <option>Accept=no
</option>. A daemon listening on an
<constant>AF_UNIX
</constant> socket may, but
402 does not need to, call
403 <citerefentry><refentrytitle>close
</refentrytitle><manvolnum>2</manvolnum></citerefentry> on the
404 received socket before exiting. However, it must not unlink the socket from a file system. It should
406 <citerefentry><refentrytitle>shutdown
</refentrytitle><manvolnum>2</manvolnum></citerefentry> on
407 sockets it got with
<varname>Accept=no
</varname>, but it may do so for sockets it got with
408 <varname>Accept=yes
</varname> set. Setting
<varname>Accept=yes
</varname> is mostly useful to allow
409 daemons designed for usage with
<citerefentry
410 project='freebsd'
><refentrytitle>inetd
</refentrytitle><manvolnum>8</manvolnum></citerefentry> to work
411 unmodified with systemd socket activation.
</para>
413 <para>For IPv4 and IPv6 connections, the
<varname>REMOTE_ADDR
</varname> environment variable will
414 contain the remote IP address, and
<varname>REMOTE_PORT
</varname> will contain the remote port. This
415 is the same as the format used by CGI. For
<constant>SOCK_RAW
</constant>, the port is the IP
418 <para>It is recommended to set
<varname>CollectMode=inactive-or-failed
</varname> for service
419 instances activated via
<varname>Accept=yes
</varname>, to ensure that failed connection services are
420 cleaned up and released from memory, and do not accumulate.
</para></listitem>
424 <term><varname>Writable=
</varname></term>
425 <listitem><para>Takes a boolean argument. May only be used in
426 conjunction with
<varname>ListenSpecial=
</varname>. If true,
427 the specified special file is opened in read-write mode, if
428 false, in read-only mode. Defaults to false.
</para></listitem>
432 <term><varname>FlushPending=
</varname></term>
433 <listitem><para>Takes a boolean argument. May only be used when
434 <option>Accept=no
</option>. If yes, the socket's buffers are cleared after the
435 triggered service exited. This causes any pending data to be
436 flushed and any pending incoming connections to be rejected. If no, the
437 socket's buffers won't be cleared, permitting the service to handle any
438 pending connections after restart, which is the usually expected behaviour.
439 Defaults to
<option>no
</option>.
444 <term><varname>MaxConnections=
</varname></term>
445 <listitem><para>The maximum number of connections to
446 simultaneously run services instances for, when
447 <option>Accept=yes
</option> is set. If more concurrent
448 connections are coming in, they will be refused until at least
449 one existing connection is terminated. This setting has no
450 effect on sockets configured with
451 <option>Accept=no
</option> or datagram sockets. Defaults to
452 64.
</para></listitem>
456 <term><varname>MaxConnectionsPerSource=
</varname></term>
457 <listitem><para>The maximum number of connections for a service per source IP address.
458 This is very similar to the
<varname>MaxConnections=
</varname> directive
459 above. Disabled by default.
</para>
464 <term><varname>KeepAlive=
</varname></term>
465 <listitem><para>Takes a boolean argument. If true, the TCP/IP stack will send a keep alive message
466 after
2h (depending on the configuration of
467 <filename>/proc/sys/net/ipv4/tcp_keepalive_time
</filename>) for all TCP streams accepted on this
468 socket. This controls the
<constant>SO_KEEPALIVE
</constant> socket option (see
<citerefentry
469 project='man-pages'
><refentrytitle>socket
</refentrytitle><manvolnum>7</manvolnum></citerefentry> and
470 the
<ulink url=
"http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP Keepalive
471 HOWTO
</ulink> for details.) Defaults to
<option>false
</option>.
</para></listitem>
475 <term><varname>KeepAliveTimeSec=
</varname></term>
476 <listitem><para>Takes time (in seconds) as argument. The connection needs to remain
477 idle before TCP starts sending keepalive probes. This controls the TCP_KEEPIDLE
479 <citerefentry project='man-pages'
><refentrytitle>socket
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
481 url=
"http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
482 Keepalive HOWTO
</ulink> for details.)
483 Defaults value is
7200 seconds (
2 hours).
</para></listitem>
487 <term><varname>KeepAliveIntervalSec=
</varname></term>
488 <listitem><para>Takes time (in seconds) as argument between individual keepalive probes, if the
489 socket option
<constant>SO_KEEPALIVE
</constant> has been set on this socket. This controls the
490 <constant>TCP_KEEPINTVL
</constant> socket option (see
<citerefentry
491 project='man-pages'
><refentrytitle>socket
</refentrytitle><manvolnum>7</manvolnum></citerefentry> and
492 the
<ulink url=
"http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP Keepalive
493 HOWTO
</ulink> for details.) Defaults value is
75 seconds.
</para></listitem>
497 <term><varname>KeepAliveProbes=
</varname></term>
498 <listitem><para>Takes an integer as argument. It is the number of
499 unacknowledged probes to send before considering the
500 connection dead and notifying the application layer. This
501 controls the TCP_KEEPCNT socket option (see
502 <citerefentry project='man-pages'
><refentrytitle>socket
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
504 url=
"http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
505 Keepalive HOWTO
</ulink> for details.) Defaults value is
510 <term><varname>NoDelay=
</varname></term>
511 <listitem><para>Takes a boolean argument. TCP Nagle's
512 algorithm works by combining a number of small outgoing
513 messages, and sending them all at once. This controls the
514 TCP_NODELAY socket option (see
515 <citerefentry project='die-net'
><refentrytitle>tcp
</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
516 Defaults to
<option>false
</option>.
</para></listitem>
520 <term><varname>Priority=
</varname></term>
521 <listitem><para>Takes an integer argument controlling the priority for all traffic sent from this
522 socket. This controls the
<constant>SO_PRIORITY
</constant> socket option (see
<citerefentry
523 project='man-pages'
><refentrytitle>socket
</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
524 details.).
</para></listitem>
528 <term><varname>DeferAcceptSec=
</varname></term>
530 <listitem><para>Takes time (in seconds) as argument. If set,
531 the listening process will be awakened only when data arrives
532 on the socket, and not immediately when connection is
533 established. When this option is set, the
534 <constant>TCP_DEFER_ACCEPT
</constant> socket option will be
536 <citerefentry project='die-net'
><refentrytitle>tcp
</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
537 and the kernel will ignore initial ACK packets without any
538 data. The argument specifies the approximate amount of time
539 the kernel should wait for incoming data before falling back
540 to the normal behavior of honoring empty ACK packets. This
541 option is beneficial for protocols where the client sends the
542 data first (e.g. HTTP, in contrast to SMTP), because the
543 server process will not be woken up unnecessarily before it
547 <para>If the client also uses the
548 <constant>TCP_DEFER_ACCEPT
</constant> option, the latency of
549 the initial connection may be reduced, because the kernel will
550 send data in the final packet establishing the connection (the
551 third packet in the
"three-way handshake").
</para>
553 <para>Disabled by default.
</para>
558 <term><varname>ReceiveBuffer=
</varname></term>
559 <term><varname>SendBuffer=
</varname></term>
560 <listitem><para>Takes an integer argument controlling the receive or send buffer sizes of this
561 socket, respectively. This controls the
<constant>SO_RCVBUF
</constant> and
562 <constant>SO_SNDBUF
</constant> socket options (see
<citerefentry
563 project='man-pages'
><refentrytitle>socket
</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
564 details.). The usual suffixes K, M, G are supported and are understood to the base of
565 1024.
</para></listitem>
569 <term><varname>IPTOS=
</varname></term>
570 <listitem><para>Takes an integer argument controlling the IP Type-Of-Service field for packets
571 generated from this socket. This controls the
<constant>IP_TOS
</constant> socket option (see
573 project='die-net'
><refentrytitle>ip
</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
574 details.). Either a numeric string or one of
<option>low-delay
</option>,
<option>throughput
</option>,
575 <option>reliability
</option> or
<option>low-cost
</option> may be specified.
</para></listitem>
579 <term><varname>IPTTL=
</varname></term>
580 <listitem><para>Takes an integer argument controlling the IPv4 Time-To-Live/IPv6 Hop-Count field for
581 packets generated from this socket. This sets the
582 <constant>IP_TTL
</constant>/
<constant>IPV6_UNICAST_HOPS
</constant> socket options (see
<citerefentry
583 project='die-net'
><refentrytitle>ip
</refentrytitle><manvolnum>7</manvolnum></citerefentry> and
585 project='die-net'
><refentrytitle>ipv6
</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
586 details.)
</para></listitem>
590 <term><varname>Mark=
</varname></term>
591 <listitem><para>Takes an integer value. Controls the firewall mark of packets generated by this
592 socket. This can be used in the firewall logic to filter packets from this socket. This sets the
593 <constant>SO_MARK
</constant> socket option. See
<citerefentry
594 project='die-net'
><refentrytitle>iptables
</refentrytitle><manvolnum>8</manvolnum></citerefentry> for
595 details.
</para></listitem>
599 <term><varname>ReusePort=
</varname></term>
600 <listitem><para>Takes a boolean value. If true, allows multiple
601 <citerefentry><refentrytitle>bind
</refentrytitle><manvolnum>2</manvolnum></citerefentry>s to this TCP
602 or UDP port. This controls the
<constant>SO_REUSEPORT
</constant> socket option. See
<citerefentry
603 project='man-pages'
><refentrytitle>socket
</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
604 details.
</para></listitem>
608 <term><varname>SmackLabel=
</varname></term>
609 <term><varname>SmackLabelIPIn=
</varname></term>
610 <term><varname>SmackLabelIPOut=
</varname></term>
611 <listitem><para>Takes a string value. Controls the extended
612 attributes
<literal>security.SMACK64
</literal>,
613 <literal>security.SMACK64IPIN
</literal> and
614 <literal>security.SMACK64IPOUT
</literal>, respectively, i.e.
615 the security label of the FIFO, or the security label for the
616 incoming or outgoing connections of the socket, respectively.
618 url=
"https://docs.kernel.org/admin-guide/LSM/Smack.html">Smack
</ulink>
619 for details.
</para></listitem>
623 <term><varname>SELinuxContextFromNet=
</varname></term>
624 <listitem><para>Takes a boolean argument. When true, systemd
625 will attempt to figure out the SELinux label used for the
626 instantiated service from the information handed by the peer
627 over the network. Note that only the security level is used
628 from the information provided by the peer. Other parts of the
629 resulting SELinux context originate from either the target
630 binary that is effectively triggered by socket unit or from
631 the value of the
<varname>SELinuxContext=
</varname> option.
632 This configuration option applies only when activated service
633 is passed in single socket file descriptor, i.e. service
634 instances that have standard input connected to a socket or
635 services triggered by exactly one socket unit. Also note
636 that this option is useful only when MLS/MCS SELinux policy
637 is deployed. Defaults to
638 <literal>false
</literal>.
</para></listitem>
642 <term><varname>PipeSize=
</varname></term>
643 <listitem><para>Takes a size in bytes. Controls the pipe
644 buffer size of FIFOs configured in this socket unit. See
645 <citerefentry><refentrytitle>fcntl
</refentrytitle><manvolnum>2</manvolnum></citerefentry>
646 for details. The usual suffixes K, M, G are supported and are
647 understood to the base of
1024.
</para></listitem>
651 <term><varname>MessageQueueMaxMessages=
</varname>,
652 <varname>MessageQueueMessageSize=
</varname></term>
653 <listitem><para>These two settings take integer values and
654 control the mq_maxmsg field or the mq_msgsize field,
655 respectively, when creating the message queue. Note that
656 either none or both of these variables need to be set. See
657 <citerefentry project='die-net'
><refentrytitle>mq_setattr
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
658 for details.
</para></listitem>
662 <term><varname>FreeBind=
</varname></term>
663 <listitem><para>Takes a boolean value. Controls whether the socket can be bound to non-local IP
664 addresses. This is useful to configure sockets listening on specific IP addresses before those IP
665 addresses are successfully configured on a network interface. This sets the
666 <constant>IP_FREEBIND
</constant>/
<constant>IPV6_FREEBIND
</constant> socket option. For robustness
667 reasons it is recommended to use this option whenever you bind a socket to a specific IP
668 address. Defaults to
<option>false
</option>.
</para></listitem>
672 <term><varname>Transparent=
</varname></term>
673 <listitem><para>Takes a boolean value. Controls the
674 <constant>IP_TRANSPARENT
</constant>/
<constant>IPV6_TRANSPARENT
</constant> socket option. Defaults to
675 <option>false
</option>.
</para></listitem>
679 <term><varname>Broadcast=
</varname></term>
680 <listitem><para>Takes a boolean value. This controls the
<constant>SO_BROADCAST
</constant> socket
681 option, which allows broadcast datagrams to be sent from this socket. Defaults to
682 <option>false
</option>.
</para></listitem>
686 <term><varname>PassCredentials=
</varname></term>
687 <listitem><para>Takes a boolean value. This controls the
<constant>SO_PASSCRED
</constant> socket
688 option, which allows
<constant>AF_UNIX
</constant> sockets to receive the credentials of the sending
689 process in an ancillary message. Defaults to
<option>false
</option>.
</para></listitem>
693 <term><varname>PassSecurity=
</varname></term>
694 <listitem><para>Takes a boolean value. This controls the
<constant>SO_PASSSEC
</constant> socket
695 option, which allows
<constant>AF_UNIX
</constant> sockets to receive the security context of the
696 sending process in an ancillary message. Defaults to
<option>false
</option>.
</para></listitem>
700 <term><varname>PassPacketInfo=
</varname></term>
701 <listitem><para>Takes a boolean value. This controls the
<constant>IP_PKTINFO
</constant>,
702 <constant>IPV6_RECVPKTINFO
</constant>,
<constant>NETLINK_PKTINFO
</constant> or
703 <constant>PACKET_AUXDATA
</constant> socket options, which enable reception of additional per-packet
704 metadata as ancillary message, on
<constant>AF_INET
</constant>,
<constant>AF_INET6
</constant>,
705 <constant>AF_UNIX
</constant> and
<constant>AF_PACKET
</constant> sockets. Defaults to
706 <option>false
</option>.
</para></listitem>
710 <term><varname>Timestamping=
</varname></term>
711 <listitem><para>Takes one of
<literal>off
</literal>,
<literal>us
</literal> (alias:
712 <literal>usec
</literal>,
<literal>µs
</literal>) or
<literal>ns
</literal> (alias:
713 <literal>nsec
</literal>). This controls the
<constant>SO_TIMESTAMP
</constant> or
714 <constant>SO_TIMESTAMPNS
</constant> socket options, and enables whether ingress network traffic shall
715 carry timestamping metadata. Defaults to
<option>off
</option>.
</para></listitem>
719 <term><varname>TCPCongestion=
</varname></term>
720 <listitem><para>Takes a string value. Controls the TCP congestion algorithm used by this
721 socket. Should be one of
<literal>westwood
</literal>,
<literal>veno
</literal>,
722 <literal>cubic
</literal>,
<literal>lp
</literal> or any other available algorithm supported by the IP
723 stack. This setting applies only to stream sockets.
</para></listitem>
727 <term><varname>ExecStartPre=
</varname></term>
728 <term><varname>ExecStartPost=
</varname></term>
729 <listitem><para>Takes one or more command lines, which are
730 executed before or after the listening sockets/FIFOs are
731 created and bound, respectively. The first token of the
732 command line must be an absolute filename, then followed by
733 arguments for the process. Multiple command lines may be
734 specified following the same scheme as used for
735 <varname>ExecStartPre=
</varname> of service unit
736 files.
</para></listitem>
740 <term><varname>ExecStopPre=
</varname></term>
741 <term><varname>ExecStopPost=
</varname></term>
742 <listitem><para>Additional commands that are executed before
743 or after the listening sockets/FIFOs are closed and removed,
744 respectively. Multiple command lines may be specified
745 following the same scheme as used for
746 <varname>ExecStartPre=
</varname> of service unit
747 files.
</para></listitem>
751 <term><varname>TimeoutSec=
</varname></term>
752 <listitem><para>Configures the time to wait for the commands
753 specified in
<varname>ExecStartPre=
</varname>,
754 <varname>ExecStartPost=
</varname>,
755 <varname>ExecStopPre=
</varname> and
756 <varname>ExecStopPost=
</varname> to finish. If a command does
757 not exit within the configured time, the socket will be
758 considered failed and be shut down again. All commands still
759 running will be terminated forcibly via
760 <constant>SIGTERM
</constant>, and after another delay of this
761 time with
<constant>SIGKILL
</constant>. (See
762 <option>KillMode=
</option> in
763 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
764 Takes a unit-less value in seconds, or a time span value such
765 as
"5min 20s". Pass
<literal>0</literal> to disable the
766 timeout logic. Defaults to
767 <varname>DefaultTimeoutStartSec=
</varname> from the manager
768 configuration file (see
769 <citerefentry><refentrytitle>systemd-system.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
774 <term><varname>Service=
</varname></term>
775 <listitem><para>Specifies the service unit name to activate on
776 incoming traffic. This setting is only allowed for sockets
777 with
<varname>Accept=no
</varname>. It defaults to the service
778 that bears the same name as the socket (with the suffix
779 replaced). In most cases, it should not be necessary to use
780 this option. Note that setting this parameter might result in
781 additional dependencies to be added to the unit (see
782 above).
</para></listitem>
786 <term><varname>RemoveOnStop=
</varname></term>
787 <listitem><para>Takes a boolean argument. If enabled, any file nodes created by this socket unit are
788 removed when it is stopped. This applies to
<constant>AF_UNIX
</constant> sockets in the file system,
789 POSIX message queues, FIFOs, as well as any symlinks to them configured with
790 <varname>Symlinks=
</varname>. Normally, it should not be necessary to use this option, and is not
791 recommended as services might continue to run after the socket unit has been terminated and it should
792 still be possible to communicate with them via their file system node. Defaults to
793 off.
</para></listitem>
797 <term><varname>Symlinks=
</varname></term>
798 <listitem><para>Takes a list of file system paths. The specified paths will be created as symlinks to the
799 <constant>AF_UNIX
</constant> socket path or FIFO path of this socket unit. If this setting is used, only one
800 <constant>AF_UNIX
</constant> socket in the file system or one FIFO may be configured for the socket unit. Use
801 this option to manage one or more symlinked alias names for a socket, binding their lifecycle together. Note
802 that if creation of a symlink fails this is not considered fatal for the socket unit, and the socket unit may
803 still start. If an empty string is assigned, the list of paths is reset. Defaults to an empty
804 list.
</para></listitem>
808 <term><varname>FileDescriptorName=
</varname></term>
809 <listitem><para>Assigns a name to all file descriptors this
810 socket unit encapsulates. This is useful to help activated
811 services identify specific file descriptors, if multiple fds
812 are passed. Services may use the
813 <citerefentry><refentrytitle>sd_listen_fds_with_names
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
814 call to acquire the names configured for the received file
815 descriptors. Names may contain any ASCII character, but must
816 exclude control characters and
<literal>:
</literal>, and must
817 be at most
255 characters in length. If this setting is not
818 used, the file descriptor name defaults to the name of the
819 socket unit, including its
<filename>.socket
</filename>
820 suffix.
</para></listitem>
824 <term><varname>TriggerLimitIntervalSec=
</varname></term>
825 <term><varname>TriggerLimitBurst=
</varname></term>
827 <listitem><para>Configures a limit on how often this socket unit may be activated within a specific time
828 interval. The
<varname>TriggerLimitIntervalSec=
</varname> may be used to configure the length of the time
829 interval in the usual time units
<literal>us
</literal>,
<literal>ms
</literal>,
<literal>s
</literal>,
830 <literal>min
</literal>,
<literal>h
</literal>, … and defaults to
2s (See
831 <citerefentry><refentrytitle>systemd.time
</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details on
832 the various time units understood). The
<varname>TriggerLimitBurst=
</varname> setting takes a positive integer
833 value and specifies the number of permitted activations per time interval, and defaults to
200 for
834 <varname>Accept=yes
</varname> sockets (thus by default permitting
200 activations per
2s), and
20 otherwise (
20
835 activations per
2s). Set either to
0 to disable any form of trigger rate limiting. If the limit is hit, the
836 socket unit is placed into a failure mode, and will not be connectible anymore until restarted. Note that this
837 limit is enforced before the service activation is enqueued.
</para></listitem>
842 <xi:include href=
"systemd.service.xml" xpointer=
"shared-unit-options" />
846 <title>See Also
</title>
848 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
849 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
850 <citerefentry><refentrytitle>systemd-system.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
851 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
852 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
853 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
854 <citerefentry><refentrytitle>systemd.resource-control
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
855 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
856 <citerefentry><refentrytitle>systemd.directives
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
857 <citerefentry><refentrytitle>sd_listen_fds
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
858 <citerefentry><refentrytitle>sd_listen_fds_with_names
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
861 For more extensive descriptions see the
"systemd for Developers" series:
862 <ulink url=
"http://0pointer.de/blog/projects/socket-activation.html">Socket Activation
</ulink>,
863 <ulink url=
"http://0pointer.de/blog/projects/socket-activation2.html">Socket Activation, part II
</ulink>,
864 <ulink url=
"http://0pointer.de/blog/projects/inetd.html">Converting inetd Services
</ulink>,
865 <ulink url=
"http://0pointer.de/blog/projects/socket-activated-containers.html">Socket Activated Internet Services and OS Containers
</ulink>.