man/systemd.socket.xml

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