man/systemd.socket.xml

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