man/systemd.socket.xml

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