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://docs.kernel.org/usb/functionfs.html">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 32-bit integer argument. Specifies the number of connections to
 345         queue that have not been accepted yet. This setting matters only for stream and sequential packet
 346         sockets. See
 347         <citerefentry><refentrytitle>listen</refentrytitle><manvolnum>2</manvolnum></citerefentry> for
 348         details. Note that this value is silently capped by the <literal>net.core.somaxconn</literal> sysctl,
 349         which typically defaults to 4096. By default this is set to 4294967295, so that the sysctl takes full
 350         effect.</para></listitem>
 351       </varlistentry>
 352
 353       <varlistentry>
 354         <term><varname>BindToDevice=</varname></term>
 355         <listitem><para>Specifies a network interface name to bind this socket to. If set, traffic will only
 356         be accepted from the specified network interfaces. This controls the
 357         <constant>SO_BINDTODEVICE</constant> socket option (see <citerefentry
 358         project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
 359         details). If this option is used, an implicit dependency from this socket unit on the network
 360         interface device unit is created
 361         (see <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 362         Note that setting this parameter might result in additional dependencies to be added to the unit (see
 363         above).</para></listitem>
 364       </varlistentry>
 365
 366       <varlistentry>
 367         <term><varname>SocketUser=</varname></term>
 368         <term><varname>SocketGroup=</varname></term>
 369
 370         <listitem><para>Takes a UNIX user/group name. When specified, all <constant>AF_UNIX</constant>
 371         sockets and FIFO nodes in the file system are owned by the specified user and group. If unset (the
 372         default), the nodes are owned by the root user/group (if run in system context) or the invoking
 373         user/group (if run in user context).  If only a user is specified but no group, then the group is
 374         derived from the user's default group.</para></listitem>
 375       </varlistentry>
 376
 377       <varlistentry>
 378         <term><varname>SocketMode=</varname></term>
 379         <listitem><para>If listening on a file system socket or FIFO,
 380         this option specifies the file system access mode used when
 381         creating the file node. Takes an access mode in octal
 382         notation. Defaults to 0666.</para></listitem>
 383       </varlistentry>
 384
 385       <varlistentry>
 386         <term><varname>DirectoryMode=</varname></term>
 387         <listitem><para>If listening on a file system socket or FIFO,
 388         the parent directories are automatically created if needed.
 389         This option specifies the file system access mode used when
 390         creating these directories. Takes an access mode in octal
 391         notation. Defaults to 0755.</para></listitem>
 392       </varlistentry>
 393
 394       <varlistentry>
 395         <term><varname>Accept=</varname></term>
 396         <listitem><para>Takes a boolean argument. If yes, a service instance is spawned for each incoming
 397         connection and only the connection socket is passed to it. If no, all listening sockets themselves
 398         are passed to the started service unit, and only one service unit is spawned for all connections
 399         (also see above). This value is ignored for datagram sockets and FIFOs where a single service unit
 400         unconditionally handles all incoming traffic. Defaults to <option>no</option>. For performance
 401         reasons, it is recommended to write new daemons only in a way that is suitable for
 402         <option>Accept=no</option>. A daemon listening on an <constant>AF_UNIX</constant> socket may, but
 403         does not need to, call
 404         <citerefentry><refentrytitle>close</refentrytitle><manvolnum>2</manvolnum></citerefentry> on the
 405         received socket before exiting. However, it must not unlink the socket from a file system. It should
 406         not invoke
 407         <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>2</manvolnum></citerefentry> on
 408         sockets it got with <varname>Accept=no</varname>, but it may do so for sockets it got with
 409         <varname>Accept=yes</varname> set. Setting <varname>Accept=yes</varname> is mostly useful to allow
 410         daemons designed for usage with <citerefentry
 411         project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry> to work
 412         unmodified with systemd socket activation.</para>
 413
 414         <para>Note that depending on this setting the services activated by units of this type are either
 415         regular services (in case of <varname>Accept=</varname><option>no</option>) or instances of templated
 416         services (in case of <varname>Accept=</varname><option>yes</option>). See the Description section
 417         above for a more detailed discussion of the naming rules of triggered services.</para>
 418
 419         <para>For IPv4 and IPv6 connections, the <varname>REMOTE_ADDR</varname> environment variable will
 420         contain the remote IP address, and <varname>REMOTE_PORT</varname> will contain the remote port. This
 421         is the same as the format used by CGI. For <constant>SOCK_RAW</constant>, the port is the IP
 422         protocol.</para>
 423
 424         <para>It is recommended to set <varname>CollectMode=inactive-or-failed</varname> for service
 425         instances activated via <varname>Accept=yes</varname>, to ensure that failed connection services are
 426         cleaned up and released from memory, and do not accumulate.</para></listitem>
 427       </varlistentry>
 428
 429       <varlistentry>
 430         <term><varname>Writable=</varname></term>
 431         <listitem><para>Takes a boolean argument. May only be used in
 432         conjunction with <varname>ListenSpecial=</varname>. If true,
 433         the specified special file is opened in read-write mode, if
 434         false, in read-only mode. Defaults to false.</para></listitem>
 435       </varlistentry>
 436
 437       <varlistentry>
 438         <term><varname>FlushPending=</varname></term>
 439         <listitem><para>Takes a boolean argument. May only be used when
 440         <option>Accept=no</option>. If yes, the socket's buffers are cleared after the
 441         triggered service exited. This causes any pending data to be
 442         flushed and any pending incoming connections to be rejected. If no, the
 443         socket's buffers won't be cleared, permitting the service to handle any
 444         pending connections after restart, which is the usually expected behaviour.
 445         Defaults to <option>no</option>.
 446         </para></listitem>
 447       </varlistentry>
 448
 449       <varlistentry>
 450         <term><varname>MaxConnections=</varname></term>
 451         <listitem><para>The maximum number of connections to
 452         simultaneously run services instances for, when
 453         <option>Accept=yes</option> is set. If more concurrent
 454         connections are coming in, they will be refused until at least
 455         one existing connection is terminated. This setting has no
 456         effect on sockets configured with
 457         <option>Accept=no</option> or datagram sockets. Defaults to
 458         64.</para></listitem>
 459       </varlistentry>
 460
 461       <varlistentry>
 462         <term><varname>MaxConnectionsPerSource=</varname></term>
 463         <listitem><para>The maximum number of connections for a service per source IP address.
 464         This is very similar to the <varname>MaxConnections=</varname> directive
 465         above. Disabled by default.</para>
 466         </listitem>
 467       </varlistentry>
 468
 469        <varlistentry>
 470         <term><varname>KeepAlive=</varname></term>
 471         <listitem><para>Takes a boolean argument. If true, the TCP/IP stack will send a keep alive message
 472         after 2h (depending on the configuration of
 473         <filename>/proc/sys/net/ipv4/tcp_keepalive_time</filename>) for all TCP streams accepted on this
 474         socket. This controls the <constant>SO_KEEPALIVE</constant> socket option (see <citerefentry
 475         project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> and
 476         the <ulink url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP Keepalive
 477         HOWTO</ulink> for details.) Defaults to <option>false</option>.</para></listitem>
 478       </varlistentry>
 479
 480       <varlistentry>
 481         <term><varname>KeepAliveTimeSec=</varname></term>
 482         <listitem><para>Takes time (in seconds) as argument. The connection needs to remain
 483         idle before TCP starts sending keepalive probes. This controls the TCP_KEEPIDLE
 484         socket option (see
 485         <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 486         and the <ulink
 487         url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
 488         Keepalive HOWTO</ulink> for details.)
 489         Defaults value is 7200 seconds (2 hours).</para></listitem>
 490       </varlistentry>
 491
 492       <varlistentry>
 493         <term><varname>KeepAliveIntervalSec=</varname></term>
 494         <listitem><para>Takes time (in seconds) as argument between individual keepalive probes, if the
 495         socket option <constant>SO_KEEPALIVE</constant> has been set on this socket. This controls the
 496         <constant>TCP_KEEPINTVL</constant> socket option (see <citerefentry
 497         project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> and
 498         the <ulink url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP Keepalive
 499         HOWTO</ulink> for details.) Defaults value is 75 seconds.</para></listitem>
 500       </varlistentry>
 501
 502       <varlistentry>
 503         <term><varname>KeepAliveProbes=</varname></term>
 504         <listitem><para>Takes an integer as argument. It is the number of
 505         unacknowledged probes to send before considering the
 506         connection dead and notifying the application layer. This
 507         controls the TCP_KEEPCNT socket option (see
 508         <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 509         and the <ulink
 510         url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
 511         Keepalive HOWTO</ulink> for details.) Defaults value is
 512         9.</para></listitem>
 513       </varlistentry>
 514
 515       <varlistentry>
 516         <term><varname>NoDelay=</varname></term>
 517         <listitem><para>Takes a boolean argument. TCP Nagle's
 518         algorithm works by combining a number of small outgoing
 519         messages, and sending them all at once. This controls the
 520         TCP_NODELAY socket option (see
 521         <citerefentry project='die-net'><refentrytitle>tcp</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
 522         Defaults to <option>false</option>.</para></listitem>
 523       </varlistentry>
 524
 525       <varlistentry>
 526         <term><varname>Priority=</varname></term>
 527         <listitem><para>Takes an integer argument controlling the priority for all traffic sent from this
 528         socket. This controls the <constant>SO_PRIORITY</constant> socket option (see <citerefentry
 529         project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
 530         details.).</para></listitem>
 531       </varlistentry>
 532
 533       <varlistentry>
 534         <term><varname>DeferAcceptSec=</varname></term>
 535
 536         <listitem><para>Takes time (in seconds) as argument. If set,
 537         the listening process will be awakened only when data arrives
 538         on the socket, and not immediately when connection is
 539         established. When this option is set, the
 540         <constant>TCP_DEFER_ACCEPT</constant> socket option will be
 541         used (see
 542         <citerefentry project='die-net'><refentrytitle>tcp</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
 543         and the kernel will ignore initial ACK packets without any
 544         data. The argument specifies the approximate amount of time
 545         the kernel should wait for incoming data before falling back
 546         to the normal behavior of honoring empty ACK packets. This
 547         option is beneficial for protocols where the client sends the
 548         data first (e.g. HTTP, in contrast to SMTP), because the
 549         server process will not be woken up unnecessarily before it
 550         can take any action.
 551         </para>
 552
 553         <para>If the client also uses the
 554         <constant>TCP_DEFER_ACCEPT</constant> option, the latency of
 555         the initial connection may be reduced, because the kernel will
 556         send data in the final packet establishing the connection (the
 557         third packet in the "three-way handshake").</para>
 558
 559         <para>Disabled by default.</para>
 560         </listitem>
 561       </varlistentry>
 562
 563       <varlistentry>
 564         <term><varname>ReceiveBuffer=</varname></term>
 565         <term><varname>SendBuffer=</varname></term>
 566         <listitem><para>Takes an integer argument controlling the receive or send buffer sizes of this
 567         socket, respectively.  This controls the <constant>SO_RCVBUF</constant> and
 568         <constant>SO_SNDBUF</constant> socket options (see <citerefentry
 569         project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
 570         details.). The usual suffixes K, M, G are supported and are understood to the base of
 571         1024.</para></listitem>
 572       </varlistentry>
 573
 574       <varlistentry>
 575         <term><varname>IPTOS=</varname></term>
 576         <listitem><para>Takes an integer argument controlling the IP Type-Of-Service field for packets
 577         generated from this socket.  This controls the <constant>IP_TOS</constant> socket option (see
 578         <citerefentry
 579         project='die-net'><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
 580         details.). Either a numeric string or one of <option>low-delay</option>, <option>throughput</option>,
 581         <option>reliability</option> or <option>low-cost</option> may be specified.</para></listitem>
 582       </varlistentry>
 583
 584       <varlistentry>
 585         <term><varname>IPTTL=</varname></term>
 586         <listitem><para>Takes an integer argument controlling the IPv4 Time-To-Live/IPv6 Hop-Count field for
 587         packets generated from this socket. This sets the
 588         <constant>IP_TTL</constant>/<constant>IPV6_UNICAST_HOPS</constant> socket options (see <citerefentry
 589         project='die-net'><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry> and
 590         <citerefentry
 591         project='die-net'><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
 592         details.)</para></listitem>
 593       </varlistentry>
 594
 595       <varlistentry>
 596         <term><varname>Mark=</varname></term>
 597         <listitem><para>Takes an integer value. Controls the firewall mark of packets generated by this
 598         socket. This can be used in the firewall logic to filter packets from this socket. This sets the
 599         <constant>SO_MARK</constant> socket option. See <citerefentry
 600         project='die-net'><refentrytitle>iptables</refentrytitle><manvolnum>8</manvolnum></citerefentry> for
 601         details.</para></listitem>
 602       </varlistentry>
 603
 604       <varlistentry>
 605         <term><varname>ReusePort=</varname></term>
 606         <listitem><para>Takes a boolean value. If true, allows multiple
 607         <citerefentry><refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum></citerefentry>s to this TCP
 608         or UDP port. This controls the <constant>SO_REUSEPORT</constant> socket option. See <citerefentry
 609         project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
 610         details.</para></listitem>
 611       </varlistentry>
 612
 613       <varlistentry>
 614         <term><varname>SmackLabel=</varname></term>
 615         <term><varname>SmackLabelIPIn=</varname></term>
 616         <term><varname>SmackLabelIPOut=</varname></term>
 617         <listitem><para>Takes a string value. Controls the extended
 618         attributes <literal>security.SMACK64</literal>,
 619         <literal>security.SMACK64IPIN</literal> and
 620         <literal>security.SMACK64IPOUT</literal>, respectively, i.e.
 621         the security label of the FIFO, or the security label for the
 622         incoming or outgoing connections of the socket, respectively.
 623         See <ulink
 624         url="https://docs.kernel.org/admin-guide/LSM/Smack.html">Smack</ulink>
 625         for details.</para></listitem>
 626       </varlistentry>
 627
 628       <varlistentry>
 629         <term><varname>SELinuxContextFromNet=</varname></term>
 630          <listitem><para>Takes a boolean argument. When true, systemd
 631          will attempt to figure out the SELinux label used for the
 632          instantiated service from the information handed by the peer
 633          over the network. Note that only the security level is used
 634          from the information provided by the peer. Other parts of the
 635          resulting SELinux context originate from either the target
 636          binary that is effectively triggered by socket unit or from
 637          the value of the <varname>SELinuxContext=</varname> option.
 638          This configuration option applies only when activated service
 639          is passed in single socket file descriptor, i.e. service
 640          instances that have standard input connected to a socket or
 641          services triggered by exactly one socket unit. Also note
 642          that this option is useful only when MLS/MCS SELinux policy
 643          is deployed. Defaults to
 644          <literal>false</literal>. </para></listitem>
 645       </varlistentry>
 646
 647       <varlistentry>
 648         <term><varname>PipeSize=</varname></term>
 649         <listitem><para>Takes a size in bytes. Controls the pipe
 650         buffer size of FIFOs configured in this socket unit. See
 651         <citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 652         for details. The usual suffixes K, M, G are supported and are
 653         understood to the base of 1024.</para></listitem>
 654       </varlistentry>
 655
 656       <varlistentry>
 657         <term><varname>MessageQueueMaxMessages=</varname>,
 658         <varname>MessageQueueMessageSize=</varname></term>
 659         <listitem><para>These two settings take integer values and
 660         control the mq_maxmsg field or the mq_msgsize field,
 661         respectively, when creating the message queue. Note that
 662         either none or both of these variables need to be set. See
 663         <citerefentry project='die-net'><refentrytitle>mq_setattr</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 664         for details.</para></listitem>
 665       </varlistentry>
 666
 667       <varlistentry>
 668         <term><varname>FreeBind=</varname></term>
 669         <listitem><para>Takes a boolean value. Controls whether the socket can be bound to non-local IP
 670         addresses. This is useful to configure sockets listening on specific IP addresses before those IP
 671         addresses are successfully configured on a network interface. This sets the
 672         <constant>IP_FREEBIND</constant>/<constant>IPV6_FREEBIND</constant> socket option. For robustness
 673         reasons it is recommended to use this option whenever you bind a socket to a specific IP
 674         address. Defaults to <option>false</option>.</para></listitem>
 675       </varlistentry>
 676
 677       <varlistentry>
 678         <term><varname>Transparent=</varname></term>
 679         <listitem><para>Takes a boolean value. Controls the
 680         <constant>IP_TRANSPARENT</constant>/<constant>IPV6_TRANSPARENT</constant> socket option. Defaults to
 681         <option>false</option>.</para></listitem>
 682       </varlistentry>
 683
 684       <varlistentry>
 685         <term><varname>Broadcast=</varname></term>
 686         <listitem><para>Takes a boolean value. This controls the <constant>SO_BROADCAST</constant> socket
 687         option, which allows broadcast datagrams to be sent from this socket. Defaults to
 688         <option>false</option>.</para></listitem>
 689       </varlistentry>
 690
 691       <varlistentry>
 692         <term><varname>PassCredentials=</varname></term>
 693         <listitem><para>Takes a boolean value. This controls the <constant>SO_PASSCRED</constant> socket
 694         option, which allows <constant>AF_UNIX</constant> sockets to receive the credentials of the sending
 695         process in an ancillary message. Defaults to <option>false</option>.</para></listitem>
 696       </varlistentry>
 697
 698       <varlistentry>
 699         <term><varname>PassSecurity=</varname></term>
 700         <listitem><para>Takes a boolean value. This controls the <constant>SO_PASSSEC</constant> socket
 701         option, which allows <constant>AF_UNIX</constant> sockets to receive the security context of the
 702         sending process in an ancillary message.  Defaults to <option>false</option>.</para></listitem>
 703       </varlistentry>
 704
 705       <varlistentry>
 706         <term><varname>PassPacketInfo=</varname></term>
 707         <listitem><para>Takes a boolean value. This controls the <constant>IP_PKTINFO</constant>,
 708         <constant>IPV6_RECVPKTINFO</constant>, <constant>NETLINK_PKTINFO</constant> or
 709         <constant>PACKET_AUXDATA</constant> socket options, which enable reception of additional per-packet
 710         metadata as ancillary message, on <constant>AF_INET</constant>, <constant>AF_INET6</constant>,
 711         <constant>AF_UNIX</constant> and <constant>AF_PACKET</constant> sockets.  Defaults to
 712         <option>false</option>.</para></listitem>
 713       </varlistentry>
 714
 715       <varlistentry>
 716         <term><varname>Timestamping=</varname></term>
 717         <listitem><para>Takes one of <literal>off</literal>, <literal>us</literal> (alias:
 718         <literal>usec</literal>, <literal>μs</literal>) or <literal>ns</literal> (alias:
 719         <literal>nsec</literal>). This controls the <constant>SO_TIMESTAMP</constant> or
 720         <constant>SO_TIMESTAMPNS</constant> socket options, and enables whether ingress network traffic shall
 721         carry timestamping metadata. Defaults to <option>off</option>.</para></listitem>
 722       </varlistentry>
 723
 724       <varlistentry>
 725         <term><varname>TCPCongestion=</varname></term>
 726         <listitem><para>Takes a string value. Controls the TCP congestion algorithm used by this
 727         socket. Should be one of <literal>westwood</literal>, <literal>veno</literal>,
 728         <literal>cubic</literal>, <literal>lp</literal> or any other available algorithm supported by the IP
 729         stack. This setting applies only to stream sockets.</para></listitem>
 730       </varlistentry>
 731
 732       <varlistentry>
 733         <term><varname>ExecStartPre=</varname></term>
 734         <term><varname>ExecStartPost=</varname></term>
 735         <listitem><para>Takes one or more command lines, which are
 736         executed before or after the listening sockets/FIFOs are
 737         created and bound, respectively. The first token of the
 738         command line must be an absolute filename, then followed by
 739         arguments for the process. Multiple command lines may be
 740         specified following the same scheme as used for
 741         <varname>ExecStartPre=</varname> of service unit
 742         files.</para></listitem>
 743       </varlistentry>
 744
 745       <varlistentry>
 746         <term><varname>ExecStopPre=</varname></term>
 747         <term><varname>ExecStopPost=</varname></term>
 748         <listitem><para>Additional commands that are executed before
 749         or after the listening sockets/FIFOs are closed and removed,
 750         respectively. Multiple command lines may be specified
 751         following the same scheme as used for
 752         <varname>ExecStartPre=</varname> of service unit
 753         files.</para></listitem>
 754       </varlistentry>
 755
 756       <varlistentry>
 757         <term><varname>TimeoutSec=</varname></term>
 758         <listitem><para>Configures the time to wait for the commands
 759         specified in <varname>ExecStartPre=</varname>,
 760         <varname>ExecStartPost=</varname>,
 761         <varname>ExecStopPre=</varname> and
 762         <varname>ExecStopPost=</varname> to finish. If a command does
 763         not exit within the configured time, the socket will be
 764         considered failed and be shut down again. All commands still
 765         running will be terminated forcibly via
 766         <constant>SIGTERM</constant>, and after another delay of this
 767         time with <constant>SIGKILL</constant>. (See
 768         <option>KillMode=</option> in
 769         <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
 770         Takes a unit-less value in seconds, or a time span value such
 771         as "5min 20s". Pass <literal>0</literal> to disable the
 772         timeout logic. Defaults to
 773         <varname>DefaultTimeoutStartSec=</varname> from the manager
 774         configuration file (see
 775         <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 776         </para></listitem>
 777       </varlistentry>
 778
 779       <varlistentry>
 780         <term><varname>Service=</varname></term>
 781         <listitem><para>Specifies the service unit name to activate on
 782         incoming traffic. This setting is only allowed for sockets
 783         with <varname>Accept=no</varname>. It defaults to the service
 784         that bears the same name as the socket (with the suffix
 785         replaced). In most cases, it should not be necessary to use
 786         this option. Note that setting this parameter might result in
 787         additional dependencies to be added to the unit (see
 788         above).</para></listitem>
 789       </varlistentry>
 790
 791       <varlistentry>
 792         <term><varname>RemoveOnStop=</varname></term>
 793         <listitem><para>Takes a boolean argument. If enabled, any file nodes created by this socket unit are
 794         removed when it is stopped. This applies to <constant>AF_UNIX</constant> sockets in the file system,
 795         POSIX message queues, FIFOs, as well as any symlinks to them configured with
 796         <varname>Symlinks=</varname>. Normally, it should not be necessary to use this option, and is not
 797         recommended as services might continue to run after the socket unit has been terminated and it should
 798         still be possible to communicate with them via their file system node. Defaults to
 799         off.</para></listitem>
 800       </varlistentry>
 801
 802       <varlistentry>
 803         <term><varname>Symlinks=</varname></term>
 804         <listitem><para>Takes a list of file system paths. The specified paths will be created as symlinks to the
 805         <constant>AF_UNIX</constant> socket path or FIFO path of this socket unit. If this setting is used, only one
 806         <constant>AF_UNIX</constant> socket in the file system or one FIFO may be configured for the socket unit. Use
 807         this option to manage one or more symlinked alias names for a socket, binding their lifecycle together. Note
 808         that if creation of a symlink fails this is not considered fatal for the socket unit, and the socket unit may
 809         still start. If an empty string is assigned, the list of paths is reset. Defaults to an empty
 810         list.</para></listitem>
 811       </varlistentry>
 812
 813       <varlistentry>
 814         <term><varname>FileDescriptorName=</varname></term>
 815         <listitem><para>Assigns a name to all file descriptors this
 816         socket unit encapsulates. This is useful to help activated
 817         services identify specific file descriptors, if multiple fds
 818         are passed. Services may use the
 819         <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 820         call to acquire the names configured for the received file
 821         descriptors. Names may contain any ASCII character, but must
 822         exclude control characters and <literal>:</literal>, and must
 823         be at most 255 characters in length. If this setting is not
 824         used, the file descriptor name defaults to the name of the
 825         socket unit, including its <filename>.socket</filename>
 826         suffix.</para></listitem>
 827       </varlistentry>
 828
 829       <varlistentry>
 830         <term><varname>TriggerLimitIntervalSec=</varname></term>
 831         <term><varname>TriggerLimitBurst=</varname></term>
 832
 833         <listitem><para>Configures a limit on how often this socket unit may be activated within a specific time
 834         interval. The <varname>TriggerLimitIntervalSec=</varname> may be used to configure the length of the time
 835         interval in the usual time units <literal>us</literal>, <literal>ms</literal>, <literal>s</literal>,
 836         <literal>min</literal>, <literal>h</literal>, … and defaults to 2s (See
 837         <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details on
 838         the various time units understood). The <varname>TriggerLimitBurst=</varname> setting takes a positive integer
 839         value and specifies the number of permitted activations per time interval, and defaults to 200 for
 840         <varname>Accept=yes</varname> sockets (thus by default permitting 200 activations per 2s), and 20 otherwise (20
 841         activations per 2s). Set either to 0 to disable any form of trigger rate limiting. If the limit is hit, the
 842         socket unit is placed into a failure mode, and will not be connectible anymore until restarted. Note that this
 843         limit is enforced before the service activation is enqueued.</para></listitem>
 844       </varlistentry>
 845
 846     </variablelist>
 847
 848     <xi:include href="systemd.service.xml" xpointer="shared-unit-options" />
 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="https://0pointer.de/blog/projects/socket-activation.html">Socket Activation</ulink>,
 869         <ulink url="https://0pointer.de/blog/projects/socket-activation2.html">Socket Activation, part II</ulink>,
 870         <ulink url="https://0pointer.de/blog/projects/inetd.html">Converting inetd Services</ulink>,
 871         <ulink url="https://0pointer.de/blog/projects/socket-activated-containers.html">Socket Activated Internet Services and OS Containers</ulink>.
 872       </para>
 873   </refsect1>
 874
 875 </refentry>