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