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