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