man/systemd.socket.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="systemd.socket">
  10   <refentryinfo>
  11     <title>systemd.socket</title>
  12     <productname>systemd</productname>
  13   </refentryinfo>
  14
  15   <refmeta>
  16     <refentrytitle>systemd.socket</refentrytitle>
  17     <manvolnum>5</manvolnum>
  18   </refmeta>
  19
  20   <refnamediv>
  21     <refname>systemd.socket</refname>
  22     <refpurpose>Socket unit configuration</refpurpose>
  23   </refnamediv>
  24
  25   <refsynopsisdiv>
  26     <para><filename><replaceable>socket</replaceable>.socket</filename></para>
  27   </refsynopsisdiv>
  28
  29   <refsect1>
  30     <title>Description</title>
  31
  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>
  36
  37     <para>This man page lists the configuration options specific to
  38     this unit type. See
  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>
  44
  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
  55     socket.</para>
  56
  57     <para>For each socket file, a matching service file must exist,
  58     describing the service to start on incoming traffic on the socket
  59     (see
  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=false</option> is set. If
  72     <option>Accept=true</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>
  75
  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>
  82
  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>
  86
  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
  90     (see
  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
  96     service file).</para>
  97   </refsect1>
  98
  99   <refsect1>
 100     <title>Automatic Dependencies</title>
 101
 102     <refsect2>
 103       <title>Implicit Dependencies</title>
 104
 105       <para>The following dependencies are implicitly added:</para>
 106
 107       <itemizedlist>
 108         <listitem><para>Socket units automatically gain a <varname>Before=</varname>
 109         dependency on the service units they activate.</para></listitem>
 110
 111         <listitem><para>Socket units referring to file system paths (such as AF_UNIX
 112         sockets or FIFOs) implicitly gain <varname>Requires=</varname> and
 113         <varname>After=</varname> dependencies on all mount units
 114         necessary to access those paths.</para></listitem>
 115
 116         <listitem><para>Socket units using the <varname>BindToDevice=</varname>
 117         setting automatically gain a <varname>BindsTo=</varname> and
 118         <varname>After=</varname> dependency on the device unit
 119         encapsulating the specified network interface.</para></listitem>
 120       </itemizedlist>
 121
 122       <para>Additional implicit dependencies may be added as result of
 123       execution and resource control parameters as documented in
 124       <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 125       and
 126       <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 127     </refsect2>
 128
 129     <refsect2>
 130       <title>Default Dependencies</title>
 131
 132       <para>The following dependencies are added unless
 133       <varname>DefaultDependencies=no</varname> is set:</para>
 134
 135       <itemizedlist>
 136         <listitem><para>Socket units automatically gain a
 137         <varname>Before=</varname> dependency on
 138         <filename>sockets.target</filename>.</para></listitem>
 139
 140         <listitem><para>Socket units automatically gain a pair of
 141         <varname>After=</varname> and <varname>Requires=</varname>
 142         dependency on <filename>sysinit.target</filename>, and a pair of
 143         <varname>Before=</varname> and <varname>Conflicts=</varname>
 144         dependencies on <filename>shutdown.target</filename>. These
 145         dependencies ensure that the socket unit is started before normal
 146         services at boot, and is stopped on shutdown. Only sockets
 147         involved with early boot or late system shutdown should disable
 148         <varname>DefaultDependencies=</varname> option.</para></listitem>
 149       </itemizedlist>
 150     </refsect2>
 151   </refsect1>
 152
 153   <refsect1>
 154     <title>Options</title>
 155
 156     <para>Socket files must include a [Socket] section, which carries
 157     information about the socket or FIFO it supervises. A number of
 158     options that may be used in this section are shared with other
 159     unit types. These options are documented in
 160     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 161     and
 162     <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 163     The options specific to the [Socket] section of socket units are
 164     the following:</para>
 165
 166     <variablelist class='unit-directives'>
 167       <varlistentry>
 168         <term><varname>ListenStream=</varname></term>
 169         <term><varname>ListenDatagram=</varname></term>
 170         <term><varname>ListenSequentialPacket=</varname></term>
 171         <listitem><para>Specifies an address to listen on for a stream
 172         (<constant>SOCK_STREAM</constant>), datagram
 173         (<constant>SOCK_DGRAM</constant>), or sequential packet
 174         (<constant>SOCK_SEQPACKET</constant>) socket, respectively.
 175         The address can be written in various formats:</para>
 176
 177         <para>If the address starts with a slash
 178         (<literal>/</literal>), it is read as file system socket in
 179         the <constant>AF_UNIX</constant> socket family.</para>
 180
 181         <para>If the address starts with an at symbol
 182         (<literal>@</literal>), it is read as abstract namespace
 183         socket in the <constant>AF_UNIX</constant> family. The
 184         <literal>@</literal> is replaced with a
 185         <constant>NUL</constant> character before binding. For
 186         details, see
 187         <citerefentry project='man-pages'><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
 188
 189         <para>If the address string is a single number, it is read as
 190         port number to listen on via IPv6. Depending on the value of
 191         <varname>BindIPv6Only=</varname> (see below) this might result
 192         in the service being available via both IPv6 and IPv4
 193         (default) or just via IPv6.
 194         </para>
 195
 196         <para>If the address string is a string in the format
 197         v.w.x.y:z, it is read as IPv4 specifier for listening on an
 198         address v.w.x.y on a port z.</para>
 199
 200         <para>If the address string is a string in the format [x]:y,
 201         it is read as IPv6 address x on a port y. Note that this might
 202         make the service available via IPv4, too, depending on the
 203         <varname>BindIPv6Only=</varname> setting (see below).
 204         </para>
 205
 206         <para>If the address string is a string in the format
 207         <literal>vsock:x:y</literal>, it is read as CID <literal>x</literal> on
 208         a port <literal>y</literal> address in the
 209         <constant>AF_VSOCK</constant> family.  The CID is a unique 32-bit
 210         integer identifier in <constant>AF_VSOCK</constant> analogous to an IP
 211         address.  Specifying the CID is optional, and may be set to the empty
 212         string.</para>
 213
 214         <para>Note that <constant>SOCK_SEQPACKET</constant> (i.e.
 215         <varname>ListenSequentialPacket=</varname>) is only available
 216         for <constant>AF_UNIX</constant> sockets.
 217         <constant>SOCK_STREAM</constant> (i.e.
 218         <varname>ListenStream=</varname>) when used for IP sockets
 219         refers to TCP sockets, <constant>SOCK_DGRAM</constant> (i.e.
 220         <varname>ListenDatagram=</varname>) to UDP.</para>
 221
 222         <para>These options may be specified more than once, in which
 223         case incoming traffic on any of the sockets will trigger
 224         service activation, and all listed sockets will be passed to
 225         the service, regardless of whether there is incoming traffic
 226         on them or not. If the empty string is assigned to any of
 227         these options, the list of addresses to listen on is reset,
 228         all prior uses of any of these options will have no
 229         effect.</para>
 230
 231         <para>It is also possible to have more than one socket unit
 232         for the same service when using <varname>Service=</varname>,
 233         and the service will receive all the sockets configured in all
 234         the socket units. Sockets configured in one unit are passed in
 235         the order of configuration, but no ordering between socket
 236         units is specified.</para>
 237
 238         <para>If an IP address is used here, it is often desirable to
 239         listen on it before the interface it is configured on is up
 240         and running, and even regardless of whether it will be up and
 241         running at any point. To deal with this, it is recommended to
 242         set the <varname>FreeBind=</varname> option described
 243         below.</para></listitem>
 244       </varlistentry>
 245
 246       <varlistentry>
 247         <term><varname>ListenFIFO=</varname></term>
 248         <listitem><para>Specifies a file system FIFO to listen on.
 249         This expects an absolute file system path as argument.
 250         Behavior otherwise is very similar to the
 251         <varname>ListenDatagram=</varname> directive
 252         above.</para></listitem>
 253       </varlistentry>
 254
 255       <varlistentry>
 256         <term><varname>ListenSpecial=</varname></term>
 257         <listitem><para>Specifies a special file in the file system to
 258         listen on. This expects an absolute file system path as
 259         argument. Behavior otherwise is very similar to the
 260         <varname>ListenFIFO=</varname> directive above. Use this to
 261         open character device nodes as well as special files in
 262         <filename>/proc</filename> and
 263         <filename>/sys</filename>.</para></listitem>
 264       </varlistentry>
 265
 266       <varlistentry>
 267         <term><varname>ListenNetlink=</varname></term>
 268         <listitem><para>Specifies a Netlink family to create a socket
 269         for to listen on. This expects a short string referring to the
 270         <constant>AF_NETLINK</constant> family name (such as
 271         <varname>audit</varname> or <varname>kobject-uevent</varname>)
 272         as argument, optionally suffixed by a whitespace followed by a
 273         multicast group integer. Behavior otherwise is very similar to
 274         the <varname>ListenDatagram=</varname> directive
 275         above.</para></listitem>
 276       </varlistentry>
 277
 278       <varlistentry>
 279         <term><varname>ListenMessageQueue=</varname></term>
 280         <listitem><para>Specifies a POSIX message queue name to listen
 281         on. This expects a valid message queue name (i.e. beginning
 282         with /). Behavior otherwise is very similar to the
 283         <varname>ListenFIFO=</varname> directive above. On Linux
 284         message queue descriptors are actually file descriptors and
 285         can be inherited between processes.</para></listitem>
 286       </varlistentry>
 287
 288       <varlistentry>
 289         <term><varname>ListenUSBFunction=</varname></term>
 290         <listitem><para>Specifies a <ulink
 291         url="https://www.kernel.org/doc/Documentation/usb/functionfs.txt">USB
 292         FunctionFS</ulink> endpoints location to listen on, for
 293         implementation of USB gadget functions. This expects an
 294         absolute file system path of functionfs mount point as the argument.
 295         Behavior otherwise is very similar to the <varname>ListenFIFO=</varname>
 296         directive above. Use this to open the FunctionFS endpoint
 297         <filename>ep0</filename>. When using this option, the
 298         activated service has to have the
 299         <varname>USBFunctionDescriptors=</varname> and
 300         <varname>USBFunctionStrings=</varname> options set.
 301         </para></listitem>
 302       </varlistentry>
 303
 304       <varlistentry>
 305         <term><varname>SocketProtocol=</varname></term>
 306         <listitem><para>Takes one of <option>udplite</option>
 307         or <option>sctp</option>. Specifies a socket protocol
 308         (<constant>IPPROTO_UDPLITE</constant>) UDP-Lite
 309         (<constant>IPPROTO_SCTP</constant>) SCTP socket respectively. </para>
 310         </listitem>
 311       </varlistentry>
 312
 313       <varlistentry>
 314         <term><varname>BindIPv6Only=</varname></term>
 315         <listitem><para>Takes one of <option>default</option>,
 316         <option>both</option> or <option>ipv6-only</option>. Controls
 317         the IPV6_V6ONLY socket option (see
 318         <citerefentry project='die-net'><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 319         for details). If <option>both</option>, IPv6 sockets bound
 320         will be accessible via both IPv4 and IPv6. If
 321         <option>ipv6-only</option>, they will be accessible via IPv6
 322         only. If <option>default</option> (which is the default,
 323         surprise!), the system wide default setting is used, as
 324         controlled by
 325         <filename>/proc/sys/net/ipv6/bindv6only</filename>, which in
 326         turn defaults to the equivalent of
 327         <option>both</option>.</para>
 328         </listitem>
 329       </varlistentry>
 330
 331       <varlistentry>
 332         <term><varname>Backlog=</varname></term>
 333         <listitem><para>Takes an unsigned integer argument. Specifies
 334         the number of connections to queue that have not been accepted
 335         yet. This setting matters only for stream and sequential
 336         packet sockets. See
 337         <citerefentry><refentrytitle>listen</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 338         for details. Defaults to SOMAXCONN (128).</para></listitem>
 339       </varlistentry>
 340
 341       <varlistentry>
 342         <term><varname>BindToDevice=</varname></term>
 343         <listitem><para>Specifies a network interface name to bind
 344         this socket to. If set, traffic will only be accepted from the
 345         specified network interfaces. This controls the
 346         SO_BINDTODEVICE socket option (see <citerefentry
 347         project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 348         for details). If this option is used, an implicit dependency
 349         from this socket unit on the network interface device unit
 350         (<citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 351         is created. Note that setting this parameter might result in
 352         additional dependencies to be added to the unit (see
 353         above).</para></listitem>
 354       </varlistentry>
 355
 356       <varlistentry>
 357         <term><varname>SocketUser=</varname></term>
 358         <term><varname>SocketGroup=</varname></term>
 359
 360         <listitem><para>Takes a UNIX user/group name. When specified,
 361         all AF_UNIX sockets and FIFO nodes in the file system are
 362         owned by the specified user and group. If unset (the default),
 363         the nodes are owned by the root user/group (if run in system
 364         context) or the invoking user/group (if run in user context).
 365         If only a user is specified but no group, then the group is
 366         derived from the user's default group.</para></listitem>
 367       </varlistentry>
 368
 369       <varlistentry>
 370         <term><varname>SocketMode=</varname></term>
 371         <listitem><para>If listening on a file system socket or FIFO,
 372         this option specifies the file system access mode used when
 373         creating the file node. Takes an access mode in octal
 374         notation. Defaults to 0666.</para></listitem>
 375       </varlistentry>
 376
 377       <varlistentry>
 378         <term><varname>DirectoryMode=</varname></term>
 379         <listitem><para>If listening on a file system socket or FIFO,
 380         the parent directories are automatically created if needed.
 381         This option specifies the file system access mode used when
 382         creating these directories. Takes an access mode in octal
 383         notation. Defaults to 0755.</para></listitem>
 384       </varlistentry>
 385
 386       <varlistentry>
 387         <term><varname>Accept=</varname></term>
 388         <listitem><para>Takes a boolean argument. If true, a service
 389         instance is spawned for each incoming connection and only the
 390         connection socket is passed to it. If false, all listening
 391         sockets themselves are passed to the started service unit, and
 392         only one service unit is spawned for all connections (also see
 393         above). This value is ignored for datagram sockets and FIFOs
 394         where a single service unit unconditionally handles all
 395         incoming traffic. Defaults to <option>false</option>. For
 396         performance reasons, it is recommended to write new daemons
 397         only in a way that is suitable for
 398         <option>Accept=false</option>. A daemon listening on an
 399         <constant>AF_UNIX</constant> socket may, but does not need to,
 400         call
 401         <citerefentry><refentrytitle>close</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 402         on the received socket before exiting. However, it must not
 403         unlink the socket from a file system. It should not invoke
 404         <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 405         on sockets it got with <varname>Accept=false</varname>, but it
 406         may do so for sockets it got with
 407         <varname>Accept=true</varname> set. Setting
 408         <varname>Accept=true</varname> is mostly useful to allow
 409         daemons designed for usage with
 410         <citerefentry project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 411         to work unmodified with systemd socket
 412         activation.</para>
 413
 414         <para>For IPv4 and IPv6 connections, the <varname>REMOTE_ADDR</varname>
 415         environment variable will contain the remote IP address, and <varname>REMOTE_PORT</varname>
 416         will contain the remote port. This is the same as the format used by CGI.
 417         For SOCK_RAW, the port is the IP protocol.</para></listitem>
 418       </varlistentry>
 419
 420       <varlistentry>
 421         <term><varname>Writable=</varname></term>
 422         <listitem><para>Takes a boolean argument. May only be used in
 423         conjunction with <varname>ListenSpecial=</varname>. If true,
 424         the specified special file is opened in read-write mode, if
 425         false, in read-only mode. Defaults to false.</para></listitem>
 426       </varlistentry>
 427
 428       <varlistentry>
 429         <term><varname>MaxConnections=</varname></term>
 430         <listitem><para>The maximum number of connections to
 431         simultaneously run services instances for, when
 432         <option>Accept=true</option> is set. If more concurrent
 433         connections are coming in, they will be refused until at least
 434         one existing connection is terminated. This setting has no
 435         effect on sockets configured with
 436         <option>Accept=false</option> or datagram sockets. Defaults to
 437         64.</para></listitem>
 438       </varlistentry>
 439
 440       <varlistentry>
 441         <term><varname>MaxConnectionsPerSource=</varname></term>
 442         <listitem><para>The maximum number of connections for a service per source IP address.
 443         This is very similar to the <varname>MaxConnections=</varname> directive
 444         above. Disabled by default.</para>
 445         </listitem>
 446       </varlistentry>
 447
 448        <varlistentry>
 449         <term><varname>KeepAlive=</varname></term>
 450         <listitem><para>Takes a boolean argument. If true, the TCP/IP
 451         stack will send a keep alive message after 2h (depending on
 452         the configuration of
 453         <filename>/proc/sys/net/ipv4/tcp_keepalive_time</filename>)
 454         for all TCP streams accepted on this socket. This controls the
 455         SO_KEEPALIVE socket option (see
 456         <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 457         and the <ulink
 458         url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
 459         Keepalive HOWTO</ulink> for details.) Defaults to
 460         <option>false</option>.</para></listitem>
 461       </varlistentry>
 462
 463       <varlistentry>
 464         <term><varname>KeepAliveTimeSec=</varname></term>
 465         <listitem><para>Takes time (in seconds) as argument. The connection needs to remain
 466         idle before TCP starts sending keepalive probes. This controls the TCP_KEEPIDLE
 467         socket option (see
 468         <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 469         and the <ulink
 470         url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
 471         Keepalive HOWTO</ulink> for details.)
 472         Defaults value is 7200 seconds (2 hours).</para></listitem>
 473       </varlistentry>
 474
 475       <varlistentry>
 476         <term><varname>KeepAliveIntervalSec=</varname></term>
 477         <listitem><para>Takes time (in seconds) as argument between
 478         individual keepalive probes, if the socket option SO_KEEPALIVE
 479         has been set on this socket. This controls
 480         the TCP_KEEPINTVL socket option (see
 481         <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 482         and the <ulink
 483         url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
 484         Keepalive HOWTO</ulink> for details.) Defaults value is 75
 485         seconds.</para></listitem>
 486       </varlistentry>
 487
 488       <varlistentry>
 489         <term><varname>KeepAliveProbes=</varname></term>
 490         <listitem><para>Takes an integer as argument. It is the number of
 491         unacknowledged probes to send before considering the
 492         connection dead and notifying the application layer. This
 493         controls the TCP_KEEPCNT socket option (see
 494         <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 495         and the <ulink
 496         url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
 497         Keepalive HOWTO</ulink> for details.) Defaults value is
 498         9.</para></listitem>
 499       </varlistentry>
 500
 501       <varlistentry>
 502         <term><varname>NoDelay=</varname></term>
 503         <listitem><para>Takes a boolean argument. TCP Nagle's
 504         algorithm works by combining a number of small outgoing
 505         messages, and sending them all at once. This controls the
 506         TCP_NODELAY socket option (see
 507         <citerefentry project='die-net'><refentrytitle>tcp</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 508         Defaults to <option>false</option>.</para></listitem>
 509       </varlistentry>
 510
 511       <varlistentry>
 512         <term><varname>Priority=</varname></term>
 513         <listitem><para>Takes an integer argument controlling the
 514         priority for all traffic sent from this socket. This controls
 515         the SO_PRIORITY socket option (see
 516         <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 517         for details.).</para></listitem>
 518       </varlistentry>
 519
 520       <varlistentry>
 521         <term><varname>DeferAcceptSec=</varname></term>
 522
 523         <listitem><para>Takes time (in seconds) as argument. If set,
 524         the listening process will be awakened only when data arrives
 525         on the socket, and not immediately when connection is
 526         established. When this option is set, the
 527         <constant>TCP_DEFER_ACCEPT</constant> socket option will be
 528         used (see
 529         <citerefentry project='die-net'><refentrytitle>tcp</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
 530         and the kernel will ignore initial ACK packets without any
 531         data. The argument specifies the approximate amount of time
 532         the kernel should wait for incoming data before falling back
 533         to the normal behavior of honoring empty ACK packets. This
 534         option is beneficial for protocols where the client sends the
 535         data first (e.g. HTTP, in contrast to SMTP), because the
 536         server process will not be woken up unnecessarily before it
 537         can take any action.
 538         </para>
 539
 540         <para>If the client also uses the
 541         <constant>TCP_DEFER_ACCEPT</constant> option, the latency of
 542         the initial connection may be reduced, because the kernel will
 543         send data in the final packet establishing the connection (the
 544         third packet in the "three-way handshake").</para>
 545
 546         <para>Disabled by default.</para>
 547         </listitem>
 548       </varlistentry>
 549
 550       <varlistentry>
 551         <term><varname>ReceiveBuffer=</varname></term>
 552         <term><varname>SendBuffer=</varname></term>
 553         <listitem><para>Takes an integer argument controlling the
 554         receive or send buffer sizes of this socket, respectively.
 555         This controls the SO_RCVBUF and SO_SNDBUF socket options (see
 556         <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 557         for details.). The usual suffixes K, M, G are supported and
 558         are understood to the base of 1024.</para></listitem>
 559       </varlistentry>
 560
 561       <varlistentry>
 562         <term><varname>IPTOS=</varname></term>
 563         <listitem><para>Takes an integer argument controlling the IP
 564         Type-Of-Service field for packets generated from this socket.
 565         This controls the IP_TOS socket option (see
 566         <citerefentry project='die-net'><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 567         for details.). Either a numeric string or one of
 568         <option>low-delay</option>, <option>throughput</option>,
 569         <option>reliability</option> or <option>low-cost</option> may
 570         be specified.</para></listitem>
 571       </varlistentry>
 572
 573       <varlistentry>
 574         <term><varname>IPTTL=</varname></term>
 575         <listitem><para>Takes an integer argument controlling the IPv4
 576         Time-To-Live/IPv6 Hop-Count field for packets generated from
 577         this socket. This sets the IP_TTL/IPV6_UNICAST_HOPS socket
 578         options (see
 579         <citerefentry project='die-net'><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 580         and
 581         <citerefentry project='die-net'><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 582         for details.)</para></listitem>
 583       </varlistentry>
 584
 585       <varlistentry>
 586         <term><varname>Mark=</varname></term>
 587         <listitem><para>Takes an integer value. Controls the firewall
 588         mark of packets generated by this socket. This can be used in
 589         the firewall logic to filter packets from this socket. This
 590         sets the SO_MARK socket option. See
 591         <citerefentry project='die-net'><refentrytitle>iptables</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 592         for details.</para></listitem>
 593       </varlistentry>
 594
 595       <varlistentry>
 596         <term><varname>ReusePort=</varname></term>
 597         <listitem><para>Takes a boolean value. If true, allows
 598         multiple
 599         <citerefentry><refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum></citerefentry>s
 600         to this TCP or UDP port. This controls the SO_REUSEPORT socket
 601         option. See
 602         <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 603         for details.</para></listitem>
 604       </varlistentry>
 605
 606       <varlistentry>
 607         <term><varname>SmackLabel=</varname></term>
 608         <term><varname>SmackLabelIPIn=</varname></term>
 609         <term><varname>SmackLabelIPOut=</varname></term>
 610         <listitem><para>Takes a string value. Controls the extended
 611         attributes <literal>security.SMACK64</literal>,
 612         <literal>security.SMACK64IPIN</literal> and
 613         <literal>security.SMACK64IPOUT</literal>, respectively, i.e.
 614         the security label of the FIFO, or the security label for the
 615         incoming or outgoing connections of the socket, respectively.
 616         See <ulink
 617         url="https://www.kernel.org/doc/Documentation/security/Smack.txt">Smack.txt</ulink>
 618         for details.</para></listitem>
 619       </varlistentry>
 620
 621       <varlistentry>
 622         <term><varname>SELinuxContextFromNet=</varname></term>
 623          <listitem><para>Takes a boolean argument. When true, systemd
 624          will attempt to figure out the SELinux label used for the
 625          instantiated service from the information handed by the peer
 626          over the network. Note that only the security level is used
 627          from the information provided by the peer. Other parts of the
 628          resulting SELinux context originate from either the target
 629          binary that is effectively triggered by socket unit or from
 630          the value of the <varname>SELinuxContext=</varname> option.
 631          This configuration option only affects sockets with
 632          <varname>Accept=</varname> mode set to
 633          <literal>true</literal>. Also note that this option is useful
 634          only when MLS/MCS SELinux policy is deployed. Defaults to
 635          <literal>false</literal>. </para></listitem>
 636       </varlistentry>
 637
 638       <varlistentry>
 639         <term><varname>PipeSize=</varname></term>
 640         <listitem><para>Takes a size in bytes. Controls the pipe
 641         buffer size of FIFOs configured in this socket unit. See
 642         <citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 643         for details. The usual suffixes K, M, G are supported and are
 644         understood to the base of 1024.</para></listitem>
 645       </varlistentry>
 646
 647       <varlistentry>
 648         <term><varname>MessageQueueMaxMessages=</varname>,
 649         <varname>MessageQueueMessageSize=</varname></term>
 650         <listitem><para>These two settings take integer values and
 651         control the mq_maxmsg field or the mq_msgsize field,
 652         respectively, when creating the message queue. Note that
 653         either none or both of these variables need to be set. See
 654         <citerefentry project='die-net'><refentrytitle>mq_setattr</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 655         for details.</para></listitem>
 656       </varlistentry>
 657
 658       <varlistentry>
 659         <term><varname>FreeBind=</varname></term>
 660         <listitem><para>Takes a boolean value. Controls whether the
 661         socket can be bound to non-local IP addresses. This is useful
 662         to configure sockets listening on specific IP addresses before
 663         those IP addresses are successfully configured on a network
 664         interface. This sets the IP_FREEBIND socket option. For
 665         robustness reasons it is recommended to use this option
 666         whenever you bind a socket to a specific IP address. Defaults
 667         to <option>false</option>.</para></listitem>
 668       </varlistentry>
 669
 670       <varlistentry>
 671         <term><varname>Transparent=</varname></term>
 672         <listitem><para>Takes a boolean value. Controls the
 673         IP_TRANSPARENT socket option. Defaults to
 674         <option>false</option>.</para></listitem>
 675       </varlistentry>
 676
 677       <varlistentry>
 678         <term><varname>Broadcast=</varname></term>
 679         <listitem><para>Takes a boolean value. This controls the
 680         SO_BROADCAST socket option, which allows broadcast datagrams
 681         to be sent from this socket. Defaults to
 682         <option>false</option>.</para></listitem>
 683       </varlistentry>
 684
 685       <varlistentry>
 686         <term><varname>PassCredentials=</varname></term>
 687         <listitem><para>Takes a boolean value. This controls the
 688         SO_PASSCRED socket option, which allows
 689         <constant>AF_UNIX</constant> sockets to receive the
 690         credentials of the sending process in an ancillary message.
 691         Defaults to <option>false</option>.</para></listitem>
 692       </varlistentry>
 693
 694       <varlistentry>
 695         <term><varname>PassSecurity=</varname></term>
 696         <listitem><para>Takes a boolean value. This controls the
 697         SO_PASSSEC socket option, which allows
 698         <constant>AF_UNIX</constant> sockets to receive the security
 699         context of the sending process in an ancillary message.
 700         Defaults to <option>false</option>.</para></listitem>
 701       </varlistentry>
 702
 703       <varlistentry>
 704         <term><varname>TCPCongestion=</varname></term>
 705         <listitem><para>Takes a string value. Controls the TCP
 706         congestion algorithm used by this socket. Should be one of
 707         "westwood", "veno", "cubic", "lp" or any other available
 708         algorithm supported by the IP stack. This setting applies only
 709         to stream sockets.</para></listitem>
 710       </varlistentry>
 711
 712       <varlistentry>
 713         <term><varname>ExecStartPre=</varname></term>
 714         <term><varname>ExecStartPost=</varname></term>
 715         <listitem><para>Takes one or more command lines, which are
 716         executed before or after the listening sockets/FIFOs are
 717         created and bound, respectively. The first token of the
 718         command line must be an absolute filename, then followed by
 719         arguments for the process. Multiple command lines may be
 720         specified following the same scheme as used for
 721         <varname>ExecStartPre=</varname> of service unit
 722         files.</para></listitem>
 723       </varlistentry>
 724
 725       <varlistentry>
 726         <term><varname>ExecStopPre=</varname></term>
 727         <term><varname>ExecStopPost=</varname></term>
 728         <listitem><para>Additional commands that are executed before
 729         or after the listening sockets/FIFOs are closed and removed,
 730         respectively. Multiple command lines may be specified
 731         following the same scheme as used for
 732         <varname>ExecStartPre=</varname> of service unit
 733         files.</para></listitem>
 734       </varlistentry>
 735
 736       <varlistentry>
 737         <term><varname>TimeoutSec=</varname></term>
 738         <listitem><para>Configures the time to wait for the commands
 739         specified in <varname>ExecStartPre=</varname>,
 740         <varname>ExecStartPost=</varname>,
 741         <varname>ExecStopPre=</varname> and
 742         <varname>ExecStopPost=</varname> to finish. If a command does
 743         not exit within the configured time, the socket will be
 744         considered failed and be shut down again. All commands still
 745         running will be terminated forcibly via
 746         <constant>SIGTERM</constant>, and after another delay of this
 747         time with <constant>SIGKILL</constant>. (See
 748         <option>KillMode=</option> in
 749         <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
 750         Takes a unit-less value in seconds, or a time span value such
 751         as "5min 20s". Pass <literal>0</literal> to disable the
 752         timeout logic. Defaults to
 753         <varname>DefaultTimeoutStartSec=</varname> from the manager
 754         configuration file (see
 755         <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 756         </para></listitem>
 757       </varlistentry>
 758
 759       <varlistentry>
 760         <term><varname>Service=</varname></term>
 761         <listitem><para>Specifies the service unit name to activate on
 762         incoming traffic. This setting is only allowed for sockets
 763         with <varname>Accept=no</varname>. It defaults to the service
 764         that bears the same name as the socket (with the suffix
 765         replaced). In most cases, it should not be necessary to use
 766         this option. Note that setting this parameter might result in
 767         additional dependencies to be added to the unit (see
 768         above).</para></listitem>
 769       </varlistentry>
 770
 771       <varlistentry>
 772         <term><varname>RemoveOnStop=</varname></term>
 773         <listitem><para>Takes a boolean argument. If enabled, any file
 774         nodes created by this socket unit are removed when it is
 775         stopped. This applies to AF_UNIX sockets in the file system,
 776         POSIX message queues, FIFOs, as well as any symlinks to them
 777         configured with <varname>Symlinks=</varname>. Normally, it
 778         should not be necessary to use this option, and is not
 779         recommended as services might continue to run after the socket
 780         unit has been terminated and it should still be possible to
 781         communicate with them via their file system node. Defaults to
 782         off.</para></listitem>
 783       </varlistentry>
 784
 785       <varlistentry>
 786         <term><varname>Symlinks=</varname></term>
 787         <listitem><para>Takes a list of file system paths. The specified paths will be created as symlinks to the
 788         <constant>AF_UNIX</constant> socket path or FIFO path of this socket unit. If this setting is used, only one
 789         <constant>AF_UNIX</constant> socket in the file system or one FIFO may be configured for the socket unit. Use
 790         this option to manage one or more symlinked alias names for a socket, binding their lifecycle together. Note
 791         that if creation of a symlink fails this is not considered fatal for the socket unit, and the socket unit may
 792         still start. If an empty string is assigned, the list of paths is reset. Defaults to an empty
 793         list.</para></listitem>
 794       </varlistentry>
 795
 796       <varlistentry>
 797         <term><varname>FileDescriptorName=</varname></term>
 798         <listitem><para>Assigns a name to all file descriptors this
 799         socket unit encapsulates. This is useful to help activated
 800         services identify specific file descriptors, if multiple fds
 801         are passed. Services may use the
 802         <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 803         call to acquire the names configured for the received file
 804         descriptors. Names may contain any ASCII character, but must
 805         exclude control characters and <literal>:</literal>, and must
 806         be at most 255 characters in length. If this setting is not
 807         used, the file descriptor name defaults to the name of the
 808         socket unit, including its <filename>.socket</filename>
 809         suffix.</para></listitem>
 810       </varlistentry>
 811
 812       <varlistentry>
 813         <term><varname>TriggerLimitIntervalSec=</varname></term>
 814         <term><varname>TriggerLimitBurst=</varname></term>
 815
 816         <listitem><para>Configures a limit on how often this socket unit my be activated within a specific time
 817         interval. The <varname>TriggerLimitIntervalSec=</varname> may be used to configure the length of the time
 818         interval in the usual time units <literal>us</literal>, <literal>ms</literal>, <literal>s</literal>,
 819         <literal>min</literal>, <literal>h</literal>, … and defaults to 2s (See
 820         <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details on
 821         the various time units understood). The <varname>TriggerLimitBurst=</varname> setting takes a positive integer
 822         value and specifies the number of permitted activations per time interval, and defaults to 200 for
 823         <varname>Accept=yes</varname> sockets (thus by default permitting 200 activations per 2s), and 20 otherwise (20
 824         activations per 2s). Set either to 0 to disable any form of trigger rate limiting. If the limit is hit, the
 825         socket unit is placed into a failure mode, and will not be connectible anymore until restarted. Note that this
 826         limit is enforced before the service activation is enqueued.</para></listitem>
 827       </varlistentry>
 828
 829     </variablelist>
 830
 831     <para>Check
 832     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 833     and
 834     <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 835     for more settings.</para>
 836
 837   </refsect1>
 838
 839   <refsect1>
 840       <title>See Also</title>
 841       <para>
 842         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 843         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 844         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 845         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 846         <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 847         <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 848         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 849         <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 850         <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 851         <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 852       </para>
 853       <para>
 854         For more extensive descriptions see the "systemd for Developers" series:
 855         <ulink url="http://0pointer.de/blog/projects/socket-activation.html">Socket Activation</ulink>,
 856         <ulink url="http://0pointer.de/blog/projects/socket-activation2.html">Socket Activation, part II</ulink>,
 857         <ulink url="http://0pointer.de/blog/projects/inetd.html">Converting inetd Services</ulink>,
 858         <ulink url="http://0pointer.de/blog/projects/socket-activated-containers.html">Socket Activated Internet Services and OS Containers</ulink>.
 859       </para>
 860   </refsect1>
 861
 862 </refentry>