2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
9 <refentry id=
"systemd.socket">
11 <title>systemd.socket
</title>
12 <productname>systemd
</productname>
16 <refentrytitle>systemd.socket
</refentrytitle>
17 <manvolnum>5</manvolnum>
21 <refname>systemd.socket
</refname>
22 <refpurpose>Socket unit configuration
</refpurpose>
26 <para><filename><replaceable>socket
</replaceable>.socket
</filename></para>
30 <title>Description
</title>
32 <para>A unit configuration file whose name ends in
33 <literal>.socket
</literal> encodes information about an IPC or
34 network socket or a file system FIFO controlled and supervised by
35 systemd, for socket-based activation.
</para>
37 <para>This man page lists the configuration options specific to
39 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
40 for the common options of all unit configuration files. The common
41 configuration items are configured in the generic [Unit] and
42 [Install] sections. The socket specific configuration options are
43 configured in the [Socket] section.
</para>
45 <para>Additional options are listed in
46 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
47 which define the execution environment the
48 <option>ExecStartPre=
</option>,
<option>ExecStartPost=
</option>,
49 <option>ExecStopPre=
</option> and
<option>ExecStopPost=
</option>
50 commands are executed in, and in
51 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
52 which define the way the processes are terminated, and in
53 <citerefentry><refentrytitle>systemd.resource-control
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
54 which configure resource control settings for the processes of the
57 <para>For each socket file, a matching service file must exist,
58 describing the service to start on incoming traffic on the socket
60 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
61 for more information about .service files). The name of the
62 .service unit is by default the same as the name of the .socket
63 unit, but can be altered with the
<option>Service=
</option> option
64 described below. Depending on the setting of the
65 <option>Accept=
</option> option described below, this .service
66 unit must either be named like the .socket unit, but with the
67 suffix replaced, unless overridden with
<option>Service=
</option>;
68 or it must be a template unit named the same way. Example: a
69 socket file
<filename>foo.socket
</filename> needs a matching
70 service
<filename>foo.service
</filename> if
71 <option>Accept=no
</option> is set. If
72 <option>Accept=yes
</option> is set, a service template file
73 <filename>foo@.service
</filename> must exist from which services
74 are instantiated for each incoming connection.
</para>
76 <para>No implicit
<varname>WantedBy=
</varname> or
77 <varname>RequiredBy=
</varname> dependency from the socket to the
78 service is added. This means that the service may be started
79 without the socket, in which case it must be able to open sockets
80 by itself. To prevent this, an explicit
81 <varname>Requires=
</varname> dependency may be added.
</para>
83 <para>Socket units may be used to implement on-demand starting of
84 services, as well as parallelized starting of services. See the
85 blog stories linked at the end for an introduction.
</para>
87 <para>Note that the daemon software configured for socket
88 activation with socket units needs to be able to accept sockets
89 from systemd, either via systemd's native socket passing interface
91 <citerefentry><refentrytitle>sd_listen_fds
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
92 for details) or via the traditional
93 <citerefentry project='freebsd'
><refentrytitle>inetd
</refentrytitle><manvolnum>8</manvolnum></citerefentry>-style
94 socket passing (i.e. sockets passed in via standard input and
95 output, using
<varname>StandardInput=socket
</varname> in the
98 <para>All network sockets allocated through
<filename>.socket
</filename> units are allocated in the host's network
99 namespace (see
<citerefentry
100 project='man-pages'
><refentrytitle>network_namespaces
</refentrytitle><manvolnum>7</manvolnum></citerefentry>). This
101 does not mean however that the service activated by a configured socket unit has to be part of the host's network
102 namespace as well. It is supported and even good practice to run services in their own network namespace (for
103 example through
<varname>PrivateNetwork=
</varname>, see
104 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>), receiving only
105 the sockets configured through socket-activation from the host's namespace. In such a set-up communication within
106 the host's network namespace is only permitted through the activation sockets passed in while all sockets allocated
107 from the service code itself will be associated with the service's own namespace, and thus possibly subject to a a
108 much more restrictive configuration.
</para>
112 <title>Automatic Dependencies
</title>
115 <title>Implicit Dependencies
</title>
117 <para>The following dependencies are implicitly added:
</para>
120 <listitem><para>Socket units automatically gain a
<varname>Before=
</varname>
121 dependency on the service units they activate.
</para></listitem>
123 <listitem><para>Socket units referring to file system paths (such as AF_UNIX
124 sockets or FIFOs) implicitly gain
<varname>Requires=
</varname> and
125 <varname>After=
</varname> dependencies on all mount units
126 necessary to access those paths.
</para></listitem>
128 <listitem><para>Socket units using the
<varname>BindToDevice=
</varname>
129 setting automatically gain a
<varname>BindsTo=
</varname> and
130 <varname>After=
</varname> dependency on the device unit
131 encapsulating the specified network interface.
</para></listitem>
134 <para>Additional implicit dependencies may be added as result of
135 execution and resource control parameters as documented in
136 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
138 <citerefentry><refentrytitle>systemd.resource-control
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
142 <title>Default Dependencies
</title>
144 <para>The following dependencies are added unless
145 <varname>DefaultDependencies=no
</varname> is set:
</para>
148 <listitem><para>Socket units automatically gain a
149 <varname>Before=
</varname> dependency on
150 <filename>sockets.target
</filename>.
</para></listitem>
152 <listitem><para>Socket units automatically gain a pair of
153 <varname>After=
</varname> and
<varname>Requires=
</varname>
154 dependency on
<filename>sysinit.target
</filename>, and a pair of
155 <varname>Before=
</varname> and
<varname>Conflicts=
</varname>
156 dependencies on
<filename>shutdown.target
</filename>. These
157 dependencies ensure that the socket unit is started before normal
158 services at boot, and is stopped on shutdown. Only sockets
159 involved with early boot or late system shutdown should disable
160 <varname>DefaultDependencies=
</varname> option.
</para></listitem>
166 <title>Options
</title>
168 <para>Socket files must include a [Socket] section, which carries
169 information about the socket or FIFO it supervises. A number of
170 options that may be used in this section are shared with other
171 unit types. These options are documented in
172 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
174 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
175 The options specific to the [Socket] section of socket units are
176 the following:
</para>
178 <variablelist class='unit-directives'
>
180 <term><varname>ListenStream=
</varname></term>
181 <term><varname>ListenDatagram=
</varname></term>
182 <term><varname>ListenSequentialPacket=
</varname></term>
183 <listitem><para>Specifies an address to listen on for a stream
184 (
<constant>SOCK_STREAM
</constant>), datagram
185 (
<constant>SOCK_DGRAM
</constant>), or sequential packet
186 (
<constant>SOCK_SEQPACKET
</constant>) socket, respectively.
187 The address can be written in various formats:
</para>
189 <para>If the address starts with a slash
190 (
<literal>/
</literal>), it is read as file system socket in
191 the
<constant>AF_UNIX
</constant> socket family.
</para>
193 <para>If the address starts with an at symbol
194 (
<literal>@
</literal>), it is read as abstract namespace
195 socket in the
<constant>AF_UNIX
</constant> family. The
196 <literal>@
</literal> is replaced with a
197 <constant>NUL
</constant> character before binding. For
199 <citerefentry project='man-pages'
><refentrytitle>unix
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para>
201 <para>If the address string is a single number, it is read as
202 port number to listen on via IPv6. Depending on the value of
203 <varname>BindIPv6Only=
</varname> (see below) this might result
204 in the service being available via both IPv6 and IPv4
205 (default) or just via IPv6.
208 <para>If the address string is a string in the format
209 v.w.x.y:z, it is read as IPv4 specifier for listening on an
210 address v.w.x.y on a port z.
</para>
212 <para>If the address string is a string in the format [x]:y,
213 it is read as IPv6 address x on a port y. Note that this might
214 make the service available via IPv4, too, depending on the
215 <varname>BindIPv6Only=
</varname> setting (see below).
218 <para>If the address string is a string in the format
219 <literal>vsock:x:y
</literal>, it is read as CID
<literal>x
</literal> on
220 a port
<literal>y
</literal> address in the
221 <constant>AF_VSOCK
</constant> family. The CID is a unique
32-bit
222 integer identifier in
<constant>AF_VSOCK
</constant> analogous to an IP
223 address. Specifying the CID is optional, and may be set to the empty
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 to listen on.
261 This expects an absolute file system path as argument.
262 Behavior otherwise is very similar to the
263 <varname>ListenDatagram=
</varname> directive
264 above.
</para></listitem>
268 <term><varname>ListenSpecial=
</varname></term>
269 <listitem><para>Specifies a special file in the file system to
270 listen on. This expects an absolute file system path as
271 argument. Behavior otherwise is very similar to the
272 <varname>ListenFIFO=
</varname> directive above. Use this to
273 open character device nodes as well as special files in
274 <filename>/proc
</filename> and
275 <filename>/sys
</filename>.
</para></listitem>
279 <term><varname>ListenNetlink=
</varname></term>
280 <listitem><para>Specifies a Netlink family to create a socket
281 for to listen on. This expects a short string referring to the
282 <constant>AF_NETLINK
</constant> family name (such as
283 <varname>audit
</varname> or
<varname>kobject-uevent
</varname>)
284 as argument, optionally suffixed by a whitespace followed by a
285 multicast group integer. Behavior otherwise is very similar to
286 the
<varname>ListenDatagram=
</varname> directive
287 above.
</para></listitem>
291 <term><varname>ListenMessageQueue=
</varname></term>
292 <listitem><para>Specifies a POSIX message queue name to listen
293 on. This expects a valid message queue name (i.e. beginning
294 with /). Behavior otherwise is very similar to the
295 <varname>ListenFIFO=
</varname> directive above. On Linux
296 message queue descriptors are actually file descriptors and
297 can be inherited between processes.
</para></listitem>
301 <term><varname>ListenUSBFunction=
</varname></term>
302 <listitem><para>Specifies a
<ulink
303 url=
"https://www.kernel.org/doc/Documentation/usb/functionfs.txt">USB
304 FunctionFS
</ulink> endpoints location to listen on, for
305 implementation of USB gadget functions. This expects an
306 absolute file system path of functionfs mount point as the argument.
307 Behavior otherwise is very similar to the
<varname>ListenFIFO=
</varname>
308 directive above. Use this to open the FunctionFS endpoint
309 <filename>ep0
</filename>. When using this option, the
310 activated service has to have the
311 <varname>USBFunctionDescriptors=
</varname> and
312 <varname>USBFunctionStrings=
</varname> options set.
317 <term><varname>SocketProtocol=
</varname></term>
318 <listitem><para>Takes one of
<option>udplite
</option>
319 or
<option>sctp
</option>. Specifies a socket protocol
320 (
<constant>IPPROTO_UDPLITE
</constant>) UDP-Lite
321 (
<constant>IPPROTO_SCTP
</constant>) SCTP socket respectively.
</para>
326 <term><varname>BindIPv6Only=
</varname></term>
327 <listitem><para>Takes one of
<option>default
</option>,
328 <option>both
</option> or
<option>ipv6-only
</option>. Controls
329 the IPV6_V6ONLY socket option (see
330 <citerefentry project='die-net'
><refentrytitle>ipv6
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
331 for details). If
<option>both
</option>, IPv6 sockets bound
332 will be accessible via both IPv4 and IPv6. If
333 <option>ipv6-only
</option>, they will be accessible via IPv6
334 only. If
<option>default
</option> (which is the default,
335 surprise!), the system wide default setting is used, as
337 <filename>/proc/sys/net/ipv6/bindv6only
</filename>, which in
338 turn defaults to the equivalent of
339 <option>both
</option>.
</para>
344 <term><varname>Backlog=
</varname></term>
345 <listitem><para>Takes an unsigned integer argument. Specifies
346 the number of connections to queue that have not been accepted
347 yet. This setting matters only for stream and sequential
349 <citerefentry><refentrytitle>listen
</refentrytitle><manvolnum>2</manvolnum></citerefentry>
350 for details. Defaults to SOMAXCONN (
128).
</para></listitem>
354 <term><varname>BindToDevice=
</varname></term>
355 <listitem><para>Specifies a network interface name to bind
356 this socket to. If set, traffic will only be accepted from the
357 specified network interfaces. This controls the
358 SO_BINDTODEVICE socket option (see
<citerefentry
359 project='man-pages'
><refentrytitle>socket
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
360 for details). If this option is used, an implicit dependency
361 from this socket unit on the network interface device unit
362 (
<citerefentry><refentrytitle>systemd.device
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
363 is created. Note that setting this parameter might result in
364 additional dependencies to be added to the unit (see
365 above).
</para></listitem>
369 <term><varname>SocketUser=
</varname></term>
370 <term><varname>SocketGroup=
</varname></term>
372 <listitem><para>Takes a UNIX user/group name. When specified,
373 all AF_UNIX sockets and FIFO nodes in the file system are
374 owned by the specified user and group. If unset (the default),
375 the nodes are owned by the root user/group (if run in system
376 context) or the invoking user/group (if run in user context).
377 If only a user is specified but no group, then the group is
378 derived from the user's default group.
</para></listitem>
382 <term><varname>SocketMode=
</varname></term>
383 <listitem><para>If listening on a file system socket or FIFO,
384 this option specifies the file system access mode used when
385 creating the file node. Takes an access mode in octal
386 notation. Defaults to
0666.
</para></listitem>
390 <term><varname>DirectoryMode=
</varname></term>
391 <listitem><para>If listening on a file system socket or FIFO,
392 the parent directories are automatically created if needed.
393 This option specifies the file system access mode used when
394 creating these directories. Takes an access mode in octal
395 notation. Defaults to
0755.
</para></listitem>
399 <term><varname>Accept=
</varname></term>
400 <listitem><para>Takes a boolean argument. If true, a service
401 instance is spawned for each incoming connection and only the
402 connection socket is passed to it. If false, all listening
403 sockets themselves are passed to the started service unit, and
404 only one service unit is spawned for all connections (also see
405 above). This value is ignored for datagram sockets and FIFOs
406 where a single service unit unconditionally handles all
407 incoming traffic. Defaults to
<option>false
</option>. For
408 performance reasons, it is recommended to write new daemons
409 only in a way that is suitable for
410 <option>Accept=no
</option>. A daemon listening on an
411 <constant>AF_UNIX
</constant> socket may, but does not need to,
413 <citerefentry><refentrytitle>close
</refentrytitle><manvolnum>2</manvolnum></citerefentry>
414 on the received socket before exiting. However, it must not
415 unlink the socket from a file system. It should not invoke
416 <citerefentry><refentrytitle>shutdown
</refentrytitle><manvolnum>2</manvolnum></citerefentry>
417 on sockets it got with
<varname>Accept=no
</varname>, but it
418 may do so for sockets it got with
419 <varname>Accept=yes
</varname> set. Setting
420 <varname>Accept=yes
</varname> is mostly useful to allow
421 daemons designed for usage with
422 <citerefentry project='freebsd'
><refentrytitle>inetd
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
423 to work unmodified with systemd socket
426 <para>For IPv4 and IPv6 connections, the
<varname>REMOTE_ADDR
</varname>
427 environment variable will contain the remote IP address, and
<varname>REMOTE_PORT
</varname>
428 will contain the remote port. This is the same as the format used by CGI.
429 For SOCK_RAW, the port is the IP protocol.
</para></listitem>
433 <term><varname>Writable=
</varname></term>
434 <listitem><para>Takes a boolean argument. May only be used in
435 conjunction with
<varname>ListenSpecial=
</varname>. If true,
436 the specified special file is opened in read-write mode, if
437 false, in read-only mode. Defaults to false.
</para></listitem>
441 <term><varname>MaxConnections=
</varname></term>
442 <listitem><para>The maximum number of connections to
443 simultaneously run services instances for, when
444 <option>Accept=yes
</option> is set. If more concurrent
445 connections are coming in, they will be refused until at least
446 one existing connection is terminated. This setting has no
447 effect on sockets configured with
448 <option>Accept=no
</option> or datagram sockets. Defaults to
449 64.
</para></listitem>
453 <term><varname>MaxConnectionsPerSource=
</varname></term>
454 <listitem><para>The maximum number of connections for a service per source IP address.
455 This is very similar to the
<varname>MaxConnections=
</varname> directive
456 above. Disabled by default.
</para>
461 <term><varname>KeepAlive=
</varname></term>
462 <listitem><para>Takes a boolean argument. If true, the TCP/IP
463 stack will send a keep alive message after
2h (depending on
465 <filename>/proc/sys/net/ipv4/tcp_keepalive_time
</filename>)
466 for all TCP streams accepted on this socket. This controls the
467 SO_KEEPALIVE socket option (see
468 <citerefentry project='man-pages'
><refentrytitle>socket
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
470 url=
"http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
471 Keepalive HOWTO
</ulink> for details.) Defaults to
472 <option>false
</option>.
</para></listitem>
476 <term><varname>KeepAliveTimeSec=
</varname></term>
477 <listitem><para>Takes time (in seconds) as argument. The connection needs to remain
478 idle before TCP starts sending keepalive probes. This controls the TCP_KEEPIDLE
480 <citerefentry project='man-pages'
><refentrytitle>socket
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
482 url=
"http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
483 Keepalive HOWTO
</ulink> for details.)
484 Defaults value is
7200 seconds (
2 hours).
</para></listitem>
488 <term><varname>KeepAliveIntervalSec=
</varname></term>
489 <listitem><para>Takes time (in seconds) as argument between
490 individual keepalive probes, if the socket option SO_KEEPALIVE
491 has been set on this socket. This controls
492 the TCP_KEEPINTVL socket option (see
493 <citerefentry project='man-pages'
><refentrytitle>socket
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
495 url=
"http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
496 Keepalive HOWTO
</ulink> for details.) Defaults value is
75
497 seconds.
</para></listitem>
501 <term><varname>KeepAliveProbes=
</varname></term>
502 <listitem><para>Takes an integer as argument. It is the number of
503 unacknowledged probes to send before considering the
504 connection dead and notifying the application layer. This
505 controls the TCP_KEEPCNT socket option (see
506 <citerefentry project='man-pages'
><refentrytitle>socket
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
508 url=
"http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
509 Keepalive HOWTO
</ulink> for details.) Defaults value is
514 <term><varname>NoDelay=
</varname></term>
515 <listitem><para>Takes a boolean argument. TCP Nagle's
516 algorithm works by combining a number of small outgoing
517 messages, and sending them all at once. This controls the
518 TCP_NODELAY socket option (see
519 <citerefentry project='die-net'
><refentrytitle>tcp
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
520 Defaults to
<option>false
</option>.
</para></listitem>
524 <term><varname>Priority=
</varname></term>
525 <listitem><para>Takes an integer argument controlling the
526 priority for all traffic sent from this socket. This controls
527 the SO_PRIORITY socket option (see
528 <citerefentry project='man-pages'
><refentrytitle>socket
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
529 for details.).
</para></listitem>
533 <term><varname>DeferAcceptSec=
</varname></term>
535 <listitem><para>Takes time (in seconds) as argument. If set,
536 the listening process will be awakened only when data arrives
537 on the socket, and not immediately when connection is
538 established. When this option is set, the
539 <constant>TCP_DEFER_ACCEPT
</constant> socket option will be
541 <citerefentry project='die-net'
><refentrytitle>tcp
</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
542 and the kernel will ignore initial ACK packets without any
543 data. The argument specifies the approximate amount of time
544 the kernel should wait for incoming data before falling back
545 to the normal behavior of honoring empty ACK packets. This
546 option is beneficial for protocols where the client sends the
547 data first (e.g. HTTP, in contrast to SMTP), because the
548 server process will not be woken up unnecessarily before it
552 <para>If the client also uses the
553 <constant>TCP_DEFER_ACCEPT
</constant> option, the latency of
554 the initial connection may be reduced, because the kernel will
555 send data in the final packet establishing the connection (the
556 third packet in the
"three-way handshake").
</para>
558 <para>Disabled by default.
</para>
563 <term><varname>ReceiveBuffer=
</varname></term>
564 <term><varname>SendBuffer=
</varname></term>
565 <listitem><para>Takes an integer argument controlling the
566 receive or send buffer sizes of this socket, respectively.
567 This controls the SO_RCVBUF and SO_SNDBUF socket options (see
568 <citerefentry project='man-pages'
><refentrytitle>socket
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
569 for details.). The usual suffixes K, M, G are supported and
570 are understood to the base of
1024.
</para></listitem>
574 <term><varname>IPTOS=
</varname></term>
575 <listitem><para>Takes an integer argument controlling the IP
576 Type-Of-Service field for packets generated from this socket.
577 This controls the IP_TOS socket option (see
578 <citerefentry project='die-net'
><refentrytitle>ip
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
579 for details.). Either a numeric string or one of
580 <option>low-delay
</option>,
<option>throughput
</option>,
581 <option>reliability
</option> or
<option>low-cost
</option> may
582 be specified.
</para></listitem>
586 <term><varname>IPTTL=
</varname></term>
587 <listitem><para>Takes an integer argument controlling the IPv4
588 Time-To-Live/IPv6 Hop-Count field for packets generated from
589 this socket. This sets the IP_TTL/IPV6_UNICAST_HOPS socket
591 <citerefentry project='die-net'
><refentrytitle>ip
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
593 <citerefentry project='die-net'
><refentrytitle>ipv6
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
594 for details.)
</para></listitem>
598 <term><varname>Mark=
</varname></term>
599 <listitem><para>Takes an integer value. Controls the firewall
600 mark of packets generated by this socket. This can be used in
601 the firewall logic to filter packets from this socket. This
602 sets the SO_MARK socket option. See
603 <citerefentry project='die-net'
><refentrytitle>iptables
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
604 for details.
</para></listitem>
608 <term><varname>ReusePort=
</varname></term>
609 <listitem><para>Takes a boolean value. If true, allows
611 <citerefentry><refentrytitle>bind
</refentrytitle><manvolnum>2</manvolnum></citerefentry>s
612 to this TCP or UDP port. This controls the SO_REUSEPORT socket
614 <citerefentry project='man-pages'
><refentrytitle>socket
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
615 for details.
</para></listitem>
619 <term><varname>SmackLabel=
</varname></term>
620 <term><varname>SmackLabelIPIn=
</varname></term>
621 <term><varname>SmackLabelIPOut=
</varname></term>
622 <listitem><para>Takes a string value. Controls the extended
623 attributes
<literal>security.SMACK64
</literal>,
624 <literal>security.SMACK64IPIN
</literal> and
625 <literal>security.SMACK64IPOUT
</literal>, respectively, i.e.
626 the security label of the FIFO, or the security label for the
627 incoming or outgoing connections of the socket, respectively.
629 url=
"https://www.kernel.org/doc/Documentation/security/Smack.txt">Smack.txt
</ulink>
630 for details.
</para></listitem>
634 <term><varname>SELinuxContextFromNet=
</varname></term>
635 <listitem><para>Takes a boolean argument. When true, systemd
636 will attempt to figure out the SELinux label used for the
637 instantiated service from the information handed by the peer
638 over the network. Note that only the security level is used
639 from the information provided by the peer. Other parts of the
640 resulting SELinux context originate from either the target
641 binary that is effectively triggered by socket unit or from
642 the value of the
<varname>SELinuxContext=
</varname> option.
643 This configuration option only affects sockets with
644 <varname>Accept=
</varname> mode set to
645 <literal>true
</literal>. Also note that this option is useful
646 only when MLS/MCS SELinux policy is deployed. Defaults to
647 <literal>false
</literal>.
</para></listitem>
651 <term><varname>PipeSize=
</varname></term>
652 <listitem><para>Takes a size in bytes. Controls the pipe
653 buffer size of FIFOs configured in this socket unit. See
654 <citerefentry><refentrytitle>fcntl
</refentrytitle><manvolnum>2</manvolnum></citerefentry>
655 for details. The usual suffixes K, M, G are supported and are
656 understood to the base of
1024.
</para></listitem>
660 <term><varname>MessageQueueMaxMessages=
</varname>,
661 <varname>MessageQueueMessageSize=
</varname></term>
662 <listitem><para>These two settings take integer values and
663 control the mq_maxmsg field or the mq_msgsize field,
664 respectively, when creating the message queue. Note that
665 either none or both of these variables need to be set. See
666 <citerefentry project='die-net'
><refentrytitle>mq_setattr
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
667 for details.
</para></listitem>
671 <term><varname>FreeBind=
</varname></term>
672 <listitem><para>Takes a boolean value. Controls whether the
673 socket can be bound to non-local IP addresses. This is useful
674 to configure sockets listening on specific IP addresses before
675 those IP addresses are successfully configured on a network
676 interface. This sets the IP_FREEBIND socket option. For
677 robustness reasons it is recommended to use this option
678 whenever you bind a socket to a specific IP address. Defaults
679 to
<option>false
</option>.
</para></listitem>
683 <term><varname>Transparent=
</varname></term>
684 <listitem><para>Takes a boolean value. Controls the
685 IP_TRANSPARENT socket option. Defaults to
686 <option>false
</option>.
</para></listitem>
690 <term><varname>Broadcast=
</varname></term>
691 <listitem><para>Takes a boolean value. This controls the
692 SO_BROADCAST socket option, which allows broadcast datagrams
693 to be sent from this socket. Defaults to
694 <option>false
</option>.
</para></listitem>
698 <term><varname>PassCredentials=
</varname></term>
699 <listitem><para>Takes a boolean value. This controls the
700 SO_PASSCRED socket option, which allows
701 <constant>AF_UNIX
</constant> sockets to receive the
702 credentials of the sending process in an ancillary message.
703 Defaults to
<option>false
</option>.
</para></listitem>
707 <term><varname>PassSecurity=
</varname></term>
708 <listitem><para>Takes a boolean value. This controls the
709 SO_PASSSEC socket option, which allows
710 <constant>AF_UNIX
</constant> sockets to receive the security
711 context of the sending process in an ancillary message.
712 Defaults to
<option>false
</option>.
</para></listitem>
716 <term><varname>TCPCongestion=
</varname></term>
717 <listitem><para>Takes a string value. Controls the TCP
718 congestion algorithm used by this socket. Should be one of
719 "westwood",
"veno",
"cubic",
"lp" or any other available
720 algorithm supported by the IP stack. This setting applies only
721 to stream sockets.
</para></listitem>
725 <term><varname>ExecStartPre=
</varname></term>
726 <term><varname>ExecStartPost=
</varname></term>
727 <listitem><para>Takes one or more command lines, which are
728 executed before or after the listening sockets/FIFOs are
729 created and bound, respectively. The first token of the
730 command line must be an absolute filename, then followed by
731 arguments for the process. Multiple command lines may be
732 specified following the same scheme as used for
733 <varname>ExecStartPre=
</varname> of service unit
734 files.
</para></listitem>
738 <term><varname>ExecStopPre=
</varname></term>
739 <term><varname>ExecStopPost=
</varname></term>
740 <listitem><para>Additional commands that are executed before
741 or after the listening sockets/FIFOs are closed and removed,
742 respectively. Multiple command lines may be specified
743 following the same scheme as used for
744 <varname>ExecStartPre=
</varname> of service unit
745 files.
</para></listitem>
749 <term><varname>TimeoutSec=
</varname></term>
750 <listitem><para>Configures the time to wait for the commands
751 specified in
<varname>ExecStartPre=
</varname>,
752 <varname>ExecStartPost=
</varname>,
753 <varname>ExecStopPre=
</varname> and
754 <varname>ExecStopPost=
</varname> to finish. If a command does
755 not exit within the configured time, the socket will be
756 considered failed and be shut down again. All commands still
757 running will be terminated forcibly via
758 <constant>SIGTERM
</constant>, and after another delay of this
759 time with
<constant>SIGKILL
</constant>. (See
760 <option>KillMode=
</option> in
761 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
762 Takes a unit-less value in seconds, or a time span value such
763 as
"5min 20s". Pass
<literal>0</literal> to disable the
764 timeout logic. Defaults to
765 <varname>DefaultTimeoutStartSec=
</varname> from the manager
766 configuration file (see
767 <citerefentry><refentrytitle>systemd-system.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
772 <term><varname>Service=
</varname></term>
773 <listitem><para>Specifies the service unit name to activate on
774 incoming traffic. This setting is only allowed for sockets
775 with
<varname>Accept=no
</varname>. It defaults to the service
776 that bears the same name as the socket (with the suffix
777 replaced). In most cases, it should not be necessary to use
778 this option. Note that setting this parameter might result in
779 additional dependencies to be added to the unit (see
780 above).
</para></listitem>
784 <term><varname>RemoveOnStop=
</varname></term>
785 <listitem><para>Takes a boolean argument. If enabled, any file
786 nodes created by this socket unit are removed when it is
787 stopped. This applies to AF_UNIX sockets in the file system,
788 POSIX message queues, FIFOs, as well as any symlinks to them
789 configured with
<varname>Symlinks=
</varname>. Normally, it
790 should not be necessary to use this option, and is not
791 recommended as services might continue to run after the socket
792 unit has been terminated and it should still be possible to
793 communicate with them via their file system node. Defaults to
794 off.
</para></listitem>
798 <term><varname>Symlinks=
</varname></term>
799 <listitem><para>Takes a list of file system paths. The specified paths will be created as symlinks to the
800 <constant>AF_UNIX
</constant> socket path or FIFO path of this socket unit. If this setting is used, only one
801 <constant>AF_UNIX
</constant> socket in the file system or one FIFO may be configured for the socket unit. Use
802 this option to manage one or more symlinked alias names for a socket, binding their lifecycle together. Note
803 that if creation of a symlink fails this is not considered fatal for the socket unit, and the socket unit may
804 still start. If an empty string is assigned, the list of paths is reset. Defaults to an empty
805 list.
</para></listitem>
809 <term><varname>FileDescriptorName=
</varname></term>
810 <listitem><para>Assigns a name to all file descriptors this
811 socket unit encapsulates. This is useful to help activated
812 services identify specific file descriptors, if multiple fds
813 are passed. Services may use the
814 <citerefentry><refentrytitle>sd_listen_fds_with_names
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
815 call to acquire the names configured for the received file
816 descriptors. Names may contain any ASCII character, but must
817 exclude control characters and
<literal>:
</literal>, and must
818 be at most
255 characters in length. If this setting is not
819 used, the file descriptor name defaults to the name of the
820 socket unit, including its
<filename>.socket
</filename>
821 suffix.
</para></listitem>
825 <term><varname>TriggerLimitIntervalSec=
</varname></term>
826 <term><varname>TriggerLimitBurst=
</varname></term>
828 <listitem><para>Configures a limit on how often this socket unit my be activated within a specific time
829 interval. The
<varname>TriggerLimitIntervalSec=
</varname> may be used to configure the length of the time
830 interval in the usual time units
<literal>us
</literal>,
<literal>ms
</literal>,
<literal>s
</literal>,
831 <literal>min
</literal>,
<literal>h
</literal>, … and defaults to
2s (See
832 <citerefentry><refentrytitle>systemd.time
</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details on
833 the various time units understood). The
<varname>TriggerLimitBurst=
</varname> setting takes a positive integer
834 value and specifies the number of permitted activations per time interval, and defaults to
200 for
835 <varname>Accept=yes
</varname> sockets (thus by default permitting
200 activations per
2s), and
20 otherwise (
20
836 activations per
2s). Set either to
0 to disable any form of trigger rate limiting. If the limit is hit, the
837 socket unit is placed into a failure mode, and will not be connectible anymore until restarted. Note that this
838 limit is enforced before the service activation is enqueued.
</para></listitem>
844 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
846 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
847 for more settings.
</para>
852 <title>See Also
</title>
854 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
855 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
856 <citerefentry><refentrytitle>systemd-system.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
857 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
858 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
859 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
860 <citerefentry><refentrytitle>systemd.resource-control
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
861 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
862 <citerefentry><refentrytitle>systemd.directives
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
863 <citerefentry><refentrytitle>sd_listen_fds
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
864 <citerefentry><refentrytitle>sd_listen_fds_with_names
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
867 For more extensive descriptions see the
"systemd for Developers" series:
868 <ulink url=
"http://0pointer.de/blog/projects/socket-activation.html">Socket Activation
</ulink>,
869 <ulink url=
"http://0pointer.de/blog/projects/socket-activation2.html">Socket Activation, part II
</ulink>,
870 <ulink url=
"http://0pointer.de/blog/projects/inetd.html">Converting inetd Services
</ulink>,
871 <ulink url=
"http://0pointer.de/blog/projects/socket-activated-containers.html">Socket Activated Internet Services and OS Containers
</ulink>.