1 <?xml version='
1.0'
?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
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+
8 Copyright 2010 Lennart Poettering
11 <refentry id=
"systemd.socket">
13 <title>systemd.socket
</title>
14 <productname>systemd
</productname>
18 <contrib>Developer
</contrib>
19 <firstname>Lennart
</firstname>
20 <surname>Poettering
</surname>
21 <email>lennart@poettering.net
</email>
27 <refentrytitle>systemd.socket
</refentrytitle>
28 <manvolnum>5</manvolnum>
32 <refname>systemd.socket
</refname>
33 <refpurpose>Socket unit configuration
</refpurpose>
37 <para><filename><replaceable>socket
</replaceable>.socket
</filename></para>
41 <title>Description
</title>
43 <para>A unit configuration file whose name ends in
44 <literal>.socket
</literal> encodes information about an IPC or
45 network socket or a file system FIFO controlled and supervised by
46 systemd, for socket-based activation.
</para>
48 <para>This man page lists the configuration options specific to
50 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
51 for the common options of all unit configuration files. The common
52 configuration items are configured in the generic [Unit] and
53 [Install] sections. The socket specific configuration options are
54 configured in the [Socket] section.
</para>
56 <para>Additional options are listed in
57 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
58 which define the execution environment the
59 <option>ExecStartPre=
</option>,
<option>ExecStartPost=
</option>,
60 <option>ExecStopPre=
</option> and
<option>ExecStopPost=
</option>
61 commands are executed in, and in
62 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
63 which define the way the processes are terminated, and in
64 <citerefentry><refentrytitle>systemd.resource-control
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
65 which configure resource control settings for the processes of the
68 <para>For each socket file, a matching service file must exist,
69 describing the service to start on incoming traffic on the socket
71 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
72 for more information about .service files). The name of the
73 .service unit is by default the same as the name of the .socket
74 unit, but can be altered with the
<option>Service=
</option> option
75 described below. Depending on the setting of the
76 <option>Accept=
</option> option described below, this .service
77 unit must either be named like the .socket unit, but with the
78 suffix replaced, unless overridden with
<option>Service=
</option>;
79 or it must be a template unit named the same way. Example: a
80 socket file
<filename>foo.socket
</filename> needs a matching
81 service
<filename>foo.service
</filename> if
82 <option>Accept=false
</option> is set. If
83 <option>Accept=true
</option> is set, a service template file
84 <filename>foo@.service
</filename> must exist from which services
85 are instantiated for each incoming connection.
</para>
87 <para>No implicit
<varname>WantedBy=
</varname> or
88 <varname>RequiredBy=
</varname> dependency from the socket to the
89 service is added. This means that the service may be started
90 without the socket, in which case it must be able to open sockets
91 by itself. To prevent this, an explicit
92 <varname>Requires=
</varname> dependency may be added.
</para>
94 <para>Socket units may be used to implement on-demand starting of
95 services, as well as parallelized starting of services. See the
96 blog stories linked at the end for an introduction.
</para>
98 <para>Note that the daemon software configured for socket
99 activation with socket units needs to be able to accept sockets
100 from systemd, either via systemd's native socket passing interface
102 <citerefentry><refentrytitle>sd_listen_fds
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
103 for details) or via the traditional
104 <citerefentry project='freebsd'
><refentrytitle>inetd
</refentrytitle><manvolnum>8</manvolnum></citerefentry>-style
105 socket passing (i.e. sockets passed in via standard input and
106 output, using
<varname>StandardInput=socket
</varname> in the
107 service file).
</para>
111 <title>Automatic Dependencies
</title>
114 <title>Implicit Dependencies
</title>
116 <para>The following dependencies are implicitly added:
</para>
119 <listitem><para>Socket units automatically gain a
<varname>Before=
</varname>
120 dependency on the service units they activate.
</para></listitem>
122 <listitem><para>Socket units referring to file system paths (such as AF_UNIX
123 sockets or FIFOs) implicitly gain
<varname>Requires=
</varname> and
124 <varname>After=
</varname> dependencies on all mount units
125 necessary to access those paths.
</para></listitem>
127 <listitem><para>Socket units using the
<varname>BindToDevice=
</varname>
128 setting automatically gain a
<varname>BindsTo=
</varname> and
129 <varname>After=
</varname> dependency on the device unit
130 encapsulating the specified network interface.
</para></listitem>
133 <para>Additional implicit dependencies may be added as result of
134 execution and resource control parameters as documented in
135 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
137 <citerefentry><refentrytitle>systemd.resource-control
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
141 <title>Default Dependencies
</title>
143 <para>The following dependencies are added unless
144 <varname>DefaultDependencies=no
</varname> is set:
</para>
147 <listitem><para>Socket units automatically gain a
148 <varname>Before=
</varname> dependency on
149 <filename>sockets.target
</filename>.
</para></listitem>
151 <listitem><para>Socket units automatically gain a pair of
152 <varname>After=
</varname> and
<varname>Requires=
</varname>
153 dependency on
<filename>sysinit.target
</filename>, and a pair of
154 <varname>Before=
</varname> and
<varname>Conflicts=
</varname>
155 dependencies on
<filename>shutdown.target
</filename>. These
156 dependencies ensure that the socket unit is started before normal
157 services at boot, and is stopped on shutdown. Only sockets
158 involved with early boot or late system shutdown should disable
159 <varname>DefaultDependencies=
</varname> option.
</para></listitem>
165 <title>Options
</title>
167 <para>Socket files must include a [Socket] section, which carries
168 information about the socket or FIFO it supervises. A number of
169 options that may be used in this section are shared with other
170 unit types. These options are documented in
171 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
173 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
174 The options specific to the [Socket] section of socket units are
175 the following:
</para>
177 <variablelist class='unit-directives'
>
179 <term><varname>ListenStream=
</varname></term>
180 <term><varname>ListenDatagram=
</varname></term>
181 <term><varname>ListenSequentialPacket=
</varname></term>
182 <listitem><para>Specifies an address to listen on for a stream
183 (
<constant>SOCK_STREAM
</constant>), datagram
184 (
<constant>SOCK_DGRAM
</constant>), or sequential packet
185 (
<constant>SOCK_SEQPACKET
</constant>) socket, respectively.
186 The address can be written in various formats:
</para>
188 <para>If the address starts with a slash
189 (
<literal>/
</literal>), it is read as file system socket in
190 the
<constant>AF_UNIX
</constant> socket family.
</para>
192 <para>If the address starts with an at symbol
193 (
<literal>@
</literal>), it is read as abstract namespace
194 socket in the
<constant>AF_UNIX
</constant> family. The
195 <literal>@
</literal> is replaced with a
196 <constant>NUL
</constant> character before binding. For
198 <citerefentry project='man-pages'
><refentrytitle>unix
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para>
200 <para>If the address string is a single number, it is read as
201 port number to listen on via IPv6. Depending on the value of
202 <varname>BindIPv6Only=
</varname> (see below) this might result
203 in the service being available via both IPv6 and IPv4
204 (default) or just via IPv6.
207 <para>If the address string is a string in the format
208 v.w.x.y:z, it is read as IPv4 specifier for listening on an
209 address v.w.x.y on a port z.
</para>
211 <para>If the address string is a string in the format [x]:y,
212 it is read as IPv6 address x on a port y. Note that this might
213 make the service available via IPv4, too, depending on the
214 <varname>BindIPv6Only=
</varname> setting (see below).
217 <para>If the address string is a string in the format
218 <literal>vsock:x:y
</literal>, it is read as CID
<literal>x
</literal> on
219 a port
<literal>y
</literal> address in the
220 <constant>AF_VSOCK
</constant> family. The CID is a unique
32-bit
221 integer identifier in
<constant>AF_VSOCK
</constant> analogous to an IP
222 address. Specifying the CID is optional, and may be set to the empty
225 <para>Note that
<constant>SOCK_SEQPACKET
</constant> (i.e.
226 <varname>ListenSequentialPacket=
</varname>) is only available
227 for
<constant>AF_UNIX
</constant> sockets.
228 <constant>SOCK_STREAM
</constant> (i.e.
229 <varname>ListenStream=
</varname>) when used for IP sockets
230 refers to TCP sockets,
<constant>SOCK_DGRAM
</constant> (i.e.
231 <varname>ListenDatagram=
</varname>) to UDP.
</para>
233 <para>These options may be specified more than once, in which
234 case incoming traffic on any of the sockets will trigger
235 service activation, and all listed sockets will be passed to
236 the service, regardless of whether there is incoming traffic
237 on them or not. If the empty string is assigned to any of
238 these options, the list of addresses to listen on is reset,
239 all prior uses of any of these options will have no
242 <para>It is also possible to have more than one socket unit
243 for the same service when using
<varname>Service=
</varname>,
244 and the service will receive all the sockets configured in all
245 the socket units. Sockets configured in one unit are passed in
246 the order of configuration, but no ordering between socket
247 units is specified.
</para>
249 <para>If an IP address is used here, it is often desirable to
250 listen on it before the interface it is configured on is up
251 and running, and even regardless of whether it will be up and
252 running at any point. To deal with this, it is recommended to
253 set the
<varname>FreeBind=
</varname> option described
254 below.
</para></listitem>
258 <term><varname>ListenFIFO=
</varname></term>
259 <listitem><para>Specifies a file system FIFO to listen on.
260 This expects an absolute file system path as argument.
261 Behavior otherwise is very similar to the
262 <varname>ListenDatagram=
</varname> directive
263 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
292 on. This expects a valid message queue name (i.e. beginning
293 with /). Behavior otherwise is very similar to the
294 <varname>ListenFIFO=
</varname> directive above. On Linux
295 message queue descriptors are actually file descriptors and
296 can be inherited between processes.
</para></listitem>
300 <term><varname>ListenUSBFunction=
</varname></term>
301 <listitem><para>Specifies a
<ulink
302 url=
"https://www.kernel.org/doc/Documentation/usb/functionfs.txt">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 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 a one of
<option>udplite
</option>
318 or
<option>sctp
</option>. Specifies a socket protocol
319 (
<constant>IPPROTO_UDPLITE
</constant>) UDP-Lite
320 (
<constant>IPPROTO_SCTP
</constant>) SCTP socket respectively.
</para>
325 <term><varname>BindIPv6Only=
</varname></term>
326 <listitem><para>Takes a 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
355 this socket to. If set, traffic will only be accepted from the
356 specified network interfaces. This controls the
357 SO_BINDTODEVICE socket option (see
<citerefentry
358 project='man-pages'
><refentrytitle>socket
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
359 for details). If this option is used, an implicit dependency
360 from this socket unit on the network interface device unit
361 (
<citerefentry><refentrytitle>systemd.device
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
362 is created. Note that setting this parameter might result in
363 additional dependencies to be added to the unit (see
364 above).
</para></listitem>
368 <term><varname>SocketUser=
</varname></term>
369 <term><varname>SocketGroup=
</varname></term>
371 <listitem><para>Takes a UNIX user/group name. When specified,
372 all AF_UNIX sockets and FIFO nodes in the file system are
373 owned by the specified user and group. If unset (the default),
374 the nodes are owned by the root user/group (if run in system
375 context) or the invoking user/group (if run in user context).
376 If only a user is specified but no group, then the group is
377 derived from the user's default group.
</para></listitem>
381 <term><varname>SocketMode=
</varname></term>
382 <listitem><para>If listening on a file system socket or FIFO,
383 this option specifies the file system access mode used when
384 creating the file node. Takes an access mode in octal
385 notation. Defaults to
0666.
</para></listitem>
389 <term><varname>DirectoryMode=
</varname></term>
390 <listitem><para>If listening on a file system socket or FIFO,
391 the parent directories are automatically created if needed.
392 This option specifies the file system access mode used when
393 creating these directories. Takes an access mode in octal
394 notation. Defaults to
0755.
</para></listitem>
398 <term><varname>Accept=
</varname></term>
399 <listitem><para>Takes a boolean argument. If true, a service
400 instance is spawned for each incoming connection and only the
401 connection socket is passed to it. If false, all listening
402 sockets themselves are passed to the started service unit, and
403 only one service unit is spawned for all connections (also see
404 above). This value is ignored for datagram sockets and FIFOs
405 where a single service unit unconditionally handles all
406 incoming traffic. Defaults to
<option>false
</option>. For
407 performance reasons, it is recommended to write new daemons
408 only in a way that is suitable for
409 <option>Accept=false
</option>. A daemon listening on an
410 <constant>AF_UNIX
</constant> socket may, but does not need to,
412 <citerefentry><refentrytitle>close
</refentrytitle><manvolnum>2</manvolnum></citerefentry>
413 on the received socket before exiting. However, it must not
414 unlink the socket from a file system. It should not invoke
415 <citerefentry><refentrytitle>shutdown
</refentrytitle><manvolnum>2</manvolnum></citerefentry>
416 on sockets it got with
<varname>Accept=false
</varname>, but it
417 may do so for sockets it got with
418 <varname>Accept=true
</varname> set. Setting
419 <varname>Accept=true
</varname> is mostly useful to allow
420 daemons designed for usage with
421 <citerefentry project='freebsd'
><refentrytitle>inetd
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
422 to work unmodified with systemd socket
425 <para>For IPv4 and IPv6 connections, the
<varname>REMOTE_ADDR
</varname>
426 environment variable will contain the remote IP address, and
<varname>REMOTE_PORT
</varname>
427 will contain the remote port. This is the same as the format used by CGI.
428 For SOCK_RAW, the port is the IP protocol.
</para></listitem>
432 <term><varname>Writable=
</varname></term>
433 <listitem><para>Takes a boolean argument. May only be used in
434 conjunction with
<varname>ListenSpecial=
</varname>. If true,
435 the specified special file is opened in read-write mode, if
436 false, in read-only mode. Defaults to false.
</para></listitem>
440 <term><varname>MaxConnections=
</varname></term>
441 <listitem><para>The maximum number of connections to
442 simultaneously run services instances for, when
443 <option>Accept=true
</option> is set. If more concurrent
444 connections are coming in, they will be refused until at least
445 one existing connection is terminated. This setting has no
446 effect on sockets configured with
447 <option>Accept=false
</option> or datagram sockets. Defaults to
448 64.
</para></listitem>
452 <term><varname>MaxConnectionsPerSource=
</varname></term>
453 <listitem><para>The maximum number of connections for a service per source IP address.
454 This is very similar to the
<varname>MaxConnections=
</varname> directive
455 above. Disabled by default.
</para>
460 <term><varname>KeepAlive=
</varname></term>
461 <listitem><para>Takes a boolean argument. If true, the TCP/IP
462 stack will send a keep alive message after
2h (depending on
464 <filename>/proc/sys/net/ipv4/tcp_keepalive_time
</filename>)
465 for all TCP streams accepted on this socket. This controls the
466 SO_KEEPALIVE socket option (see
467 <citerefentry project='man-pages'
><refentrytitle>socket
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
469 url=
"http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
470 Keepalive HOWTO
</ulink> for details.) Defaults to
471 <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
489 individual keepalive probes, if the socket option SO_KEEPALIVE
490 has been set on this socket. This controls
491 the TCP_KEEPINTVL socket option (see
492 <citerefentry project='man-pages'
><refentrytitle>socket
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
494 url=
"http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
495 Keepalive HOWTO
</ulink> for details.) Defaults value is
75
496 seconds.
</para></listitem>
500 <term><varname>KeepAliveProbes=
</varname></term>
501 <listitem><para>Takes an integer as argument. It is the number of
502 unacknowledged probes to send before considering the
503 connection dead and notifying the application layer. This
504 controls the TCP_KEEPCNT socket option (see
505 <citerefentry project='man-pages'
><refentrytitle>socket
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
507 url=
"http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
508 Keepalive HOWTO
</ulink> for details.) Defaults value is
513 <term><varname>NoDelay=
</varname></term>
514 <listitem><para>Takes a boolean argument. TCP Nagle's
515 algorithm works by combining a number of small outgoing
516 messages, and sending them all at once. This controls the
517 TCP_NODELAY socket option (see
518 <citerefentry project='die-net'
><refentrytitle>tcp
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
519 Defaults to
<option>false
</option>.
</para></listitem>
523 <term><varname>Priority=
</varname></term>
524 <listitem><para>Takes an integer argument controlling the
525 priority for all traffic sent from this socket. This controls
526 the SO_PRIORITY socket option (see
527 <citerefentry project='man-pages'
><refentrytitle>socket
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
528 for details.).
</para></listitem>
532 <term><varname>DeferAcceptSec=
</varname></term>
534 <listitem><para>Takes time (in seconds) as argument. If set,
535 the listening process will be awakened only when data arrives
536 on the socket, and not immediately when connection is
537 established. When this option is set, the
538 <constant>TCP_DEFER_ACCEPT
</constant> socket option will be
540 <citerefentry project='die-net'
><refentrytitle>tcp
</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
541 and the kernel will ignore initial ACK packets without any
542 data. The argument specifies the approximate amount of time
543 the kernel should wait for incoming data before falling back
544 to the normal behavior of honoring empty ACK packets. This
545 option is beneficial for protocols where the client sends the
546 data first (e.g. HTTP, in contrast to SMTP), because the
547 server process will not be woken up unnecessarily before it
551 <para>If the client also uses the
552 <constant>TCP_DEFER_ACCEPT
</constant> option, the latency of
553 the initial connection may be reduced, because the kernel will
554 send data in the final packet establishing the connection (the
555 third packet in the
"three-way handshake").
</para>
557 <para>Disabled by default.
</para>
562 <term><varname>ReceiveBuffer=
</varname></term>
563 <term><varname>SendBuffer=
</varname></term>
564 <listitem><para>Takes an integer argument controlling the
565 receive or send buffer sizes of this socket, respectively.
566 This controls the SO_RCVBUF and SO_SNDBUF socket options (see
567 <citerefentry project='man-pages'
><refentrytitle>socket
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
568 for details.). The usual suffixes K, M, G are supported and
569 are understood to the base of
1024.
</para></listitem>
573 <term><varname>IPTOS=
</varname></term>
574 <listitem><para>Takes an integer argument controlling the IP
575 Type-Of-Service field for packets generated from this socket.
576 This controls the IP_TOS socket option (see
577 <citerefentry project='die-net'
><refentrytitle>ip
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
578 for details.). Either a numeric string or one of
579 <option>low-delay
</option>,
<option>throughput
</option>,
580 <option>reliability
</option> or
<option>low-cost
</option> may
581 be specified.
</para></listitem>
585 <term><varname>IPTTL=
</varname></term>
586 <listitem><para>Takes an integer argument controlling the IPv4
587 Time-To-Live/IPv6 Hop-Count field for packets generated from
588 this socket. This sets the IP_TTL/IPV6_UNICAST_HOPS socket
590 <citerefentry project='die-net'
><refentrytitle>ip
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
592 <citerefentry project='die-net'
><refentrytitle>ipv6
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
593 for details.)
</para></listitem>
597 <term><varname>Mark=
</varname></term>
598 <listitem><para>Takes an integer value. Controls the firewall
599 mark of packets generated by this socket. This can be used in
600 the firewall logic to filter packets from this socket. This
601 sets the SO_MARK socket option. See
602 <citerefentry project='die-net'
><refentrytitle>iptables
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
603 for details.
</para></listitem>
607 <term><varname>ReusePort=
</varname></term>
608 <listitem><para>Takes a boolean value. If true, allows
610 <citerefentry><refentrytitle>bind
</refentrytitle><manvolnum>2</manvolnum></citerefentry>s
611 to this TCP or UDP port. This controls the SO_REUSEPORT socket
613 <citerefentry project='man-pages'
><refentrytitle>socket
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
614 for details.
</para></listitem>
618 <term><varname>SmackLabel=
</varname></term>
619 <term><varname>SmackLabelIPIn=
</varname></term>
620 <term><varname>SmackLabelIPOut=
</varname></term>
621 <listitem><para>Takes a string value. Controls the extended
622 attributes
<literal>security.SMACK64
</literal>,
623 <literal>security.SMACK64IPIN
</literal> and
624 <literal>security.SMACK64IPOUT
</literal>, respectively, i.e.
625 the security label of the FIFO, or the security label for the
626 incoming or outgoing connections of the socket, respectively.
628 url=
"https://www.kernel.org/doc/Documentation/security/Smack.txt">Smack.txt
</ulink>
629 for details.
</para></listitem>
633 <term><varname>SELinuxContextFromNet=
</varname></term>
634 <listitem><para>Takes a boolean argument. When true, systemd
635 will attempt to figure out the SELinux label used for the
636 instantiated service from the information handed by the peer
637 over the network. Note that only the security level is used
638 from the information provided by the peer. Other parts of the
639 resulting SELinux context originate from either the target
640 binary that is effectively triggered by socket unit or from
641 the value of the
<varname>SELinuxContext=
</varname> option.
642 This configuration option only affects sockets with
643 <varname>Accept=
</varname> mode set to
644 <literal>true
</literal>. Also note that this option is useful
645 only when MLS/MCS SELinux policy is deployed. Defaults to
646 <literal>false
</literal>.
</para></listitem>
650 <term><varname>PipeSize=
</varname></term>
651 <listitem><para>Takes a size in bytes. Controls the pipe
652 buffer size of FIFOs configured in this socket unit. See
653 <citerefentry><refentrytitle>fcntl
</refentrytitle><manvolnum>2</manvolnum></citerefentry>
654 for details. The usual suffixes K, M, G are supported and are
655 understood to the base of
1024.
</para></listitem>
659 <term><varname>MessageQueueMaxMessages=
</varname>,
660 <varname>MessageQueueMessageSize=
</varname></term>
661 <listitem><para>These two settings take integer values and
662 control the mq_maxmsg field or the mq_msgsize field,
663 respectively, when creating the message queue. Note that
664 either none or both of these variables need to be set. See
665 <citerefentry project='die-net'
><refentrytitle>mq_setattr
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
666 for details.
</para></listitem>
670 <term><varname>FreeBind=
</varname></term>
671 <listitem><para>Takes a boolean value. Controls whether the
672 socket can be bound to non-local IP addresses. This is useful
673 to configure sockets listening on specific IP addresses before
674 those IP addresses are successfully configured on a network
675 interface. This sets the IP_FREEBIND socket option. For
676 robustness reasons it is recommended to use this option
677 whenever you bind a socket to a specific IP address. Defaults
678 to
<option>false
</option>.
</para></listitem>
682 <term><varname>Transparent=
</varname></term>
683 <listitem><para>Takes a boolean value. Controls the
684 IP_TRANSPARENT socket option. Defaults to
685 <option>false
</option>.
</para></listitem>
689 <term><varname>Broadcast=
</varname></term>
690 <listitem><para>Takes a boolean value. This controls the
691 SO_BROADCAST socket option, which allows broadcast datagrams
692 to be sent from this socket. Defaults to
693 <option>false
</option>.
</para></listitem>
697 <term><varname>PassCredentials=
</varname></term>
698 <listitem><para>Takes a boolean value. This controls the
699 SO_PASSCRED socket option, which allows
700 <constant>AF_UNIX
</constant> sockets to receive the
701 credentials of the sending process in an ancillary message.
702 Defaults to
<option>false
</option>.
</para></listitem>
706 <term><varname>PassSecurity=
</varname></term>
707 <listitem><para>Takes a boolean value. This controls the
708 SO_PASSSEC socket option, which allows
709 <constant>AF_UNIX
</constant> sockets to receive the security
710 context of the sending process in an ancillary message.
711 Defaults to
<option>false
</option>.
</para></listitem>
715 <term><varname>TCPCongestion=
</varname></term>
716 <listitem><para>Takes a string value. Controls the TCP
717 congestion algorithm used by this socket. Should be one of
718 "westwood",
"veno",
"cubic",
"lp" or any other available
719 algorithm supported by the IP stack. This setting applies only
720 to stream sockets.
</para></listitem>
724 <term><varname>ExecStartPre=
</varname></term>
725 <term><varname>ExecStartPost=
</varname></term>
726 <listitem><para>Takes one or more command lines, which are
727 executed before or after the listening sockets/FIFOs are
728 created and bound, respectively. The first token of the
729 command line must be an absolute filename, then followed by
730 arguments for the process. Multiple command lines may be
731 specified following the same scheme as used for
732 <varname>ExecStartPre=
</varname> of service unit
733 files.
</para></listitem>
737 <term><varname>ExecStopPre=
</varname></term>
738 <term><varname>ExecStopPost=
</varname></term>
739 <listitem><para>Additional commands that are executed before
740 or after the listening sockets/FIFOs are closed and removed,
741 respectively. Multiple command lines may be specified
742 following the same scheme as used for
743 <varname>ExecStartPre=
</varname> of service unit
744 files.
</para></listitem>
748 <term><varname>TimeoutSec=
</varname></term>
749 <listitem><para>Configures the time to wait for the commands
750 specified in
<varname>ExecStartPre=
</varname>,
751 <varname>ExecStartPost=
</varname>,
752 <varname>ExecStopPre=
</varname> and
753 <varname>ExecStopPost=
</varname> to finish. If a command does
754 not exit within the configured time, the socket will be
755 considered failed and be shut down again. All commands still
756 running will be terminated forcibly via
757 <constant>SIGTERM
</constant>, and after another delay of this
758 time with
<constant>SIGKILL
</constant>. (See
759 <option>KillMode=
</option> in
760 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
761 Takes a unit-less value in seconds, or a time span value such
762 as
"5min 20s". Pass
<literal>0</literal> to disable the
763 timeout logic. Defaults to
764 <varname>DefaultTimeoutStartSec=
</varname> from the manager
765 configuration file (see
766 <citerefentry><refentrytitle>systemd-system.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
771 <term><varname>Service=
</varname></term>
772 <listitem><para>Specifies the service unit name to activate on
773 incoming traffic. This setting is only allowed for sockets
774 with
<varname>Accept=no
</varname>. It defaults to the service
775 that bears the same name as the socket (with the suffix
776 replaced). In most cases, it should not be necessary to use
777 this option. Note that setting this parameter might result in
778 additional dependencies to be added to the unit (see
779 above).
</para></listitem>
783 <term><varname>RemoveOnStop=
</varname></term>
784 <listitem><para>Takes a boolean argument. If enabled, any file
785 nodes created by this socket unit are removed when it is
786 stopped. This applies to AF_UNIX sockets in the file system,
787 POSIX message queues, FIFOs, as well as any symlinks to them
788 configured with
<varname>Symlinks=
</varname>. Normally, it
789 should not be necessary to use this option, and is not
790 recommended as services might continue to run after the socket
791 unit has been terminated and it should still be possible to
792 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 my 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>
843 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
845 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
846 for more settings.
</para>
851 <title>See Also
</title>
853 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
854 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
855 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
856 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
857 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
858 <citerefentry><refentrytitle>systemd.resource-control
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
859 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
860 <citerefentry><refentrytitle>systemd.directives
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
861 <citerefentry><refentrytitle>sd_listen_fds
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
862 <citerefentry><refentrytitle>sd_listen_fds_with_names
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
865 For more extensive descriptions see the
"systemd for Developers" series:
866 <ulink url=
"http://0pointer.de/blog/projects/socket-activation.html">Socket Activation
</ulink>,
867 <ulink url=
"http://0pointer.de/blog/projects/socket-activation2.html">Socket Activation, part II
</ulink>,
868 <ulink url=
"http://0pointer.de/blog/projects/inetd.html">Converting inetd Services
</ulink>,
869 <ulink url=
"http://0pointer.de/blog/projects/socket-activated-containers.html">Socket Activated Internet Services and OS Containers
</ulink>.