systemd.socket.xml 47.5 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57
<?xml version='1.0'?> <!--*-nxml-*-->
<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  This file is part of systemd.

  Copyright 2010 Lennart Poettering

  systemd is free software; you can redistribute it and/or modify it
  under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or
  (at your option) any later version.

  systemd is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

<refentry id="systemd.socket">
        <refentryinfo>
                <title>systemd.socket</title>
                <productname>systemd</productname>

                <authorgroup>
                        <author>
                                <contrib>Developer</contrib>
                                <firstname>Lennart</firstname>
                                <surname>Poettering</surname>
                                <email>lennart@poettering.net</email>
                        </author>
                </authorgroup>
        </refentryinfo>

        <refmeta>
                <refentrytitle>systemd.socket</refentrytitle>
                <manvolnum>5</manvolnum>
        </refmeta>

        <refnamediv>
                <refname>systemd.socket</refname>
                <refpurpose>Socket unit configuration</refpurpose>
        </refnamediv>

        <refsynopsisdiv>
                <para><filename><replaceable>socket</replaceable>.socket</filename></para>
        </refsynopsisdiv>

        <refsect1>
                <title>Description</title>

                <para>A unit configuration file whose name ends in
Michael Biebl's avatar
Michael Biebl committed
58
                <literal>.socket</literal> encodes information about
59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79
                an IPC or network socket or a file system FIFO
                controlled and supervised by systemd, for socket-based
                activation.</para>

                <para>This man page lists the configuration options
                specific to this unit type. See
                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                for the common options of all unit configuration
                files. The common configuration items are configured
                in the generic [Unit] and [Install] sections. The
                socket specific configuration options are configured
                in the [Socket] section.</para>

                <para>Additional options are listed in
                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                which define the execution environment the
                <option>ExecStartPre=</option>,
                <option>ExecStartPost=</option>,
                <option>ExecStopPre=</option> and
                <option>ExecStopPost=</option> commands are executed
                in, and in
Michael Biebl's avatar
Michael Biebl committed
80 81 82 83 84 85
                <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                which define the way the processes are terminated, and
                in
                <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                which configure resource control settings for the
                processes of the socket.</para>
86

87 88 89
                <para>For each socket file, a matching service file
                must exist, describing the service to start on
                incoming traffic on the socket (see
90
                <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
91 92 93 94 95 96 97 98 99 100
                for more information about .service files). The name
                of the .service unit is by default the same as the
                name of the .socket unit, but can be altered with the
                <option>Service=</option> option described below.
                Depending on the setting of the <option>Accept=</option>
                option described below, this .service unit must either
                be named like the .socket unit, but with the suffix
                replaced, unless overridden with
                <option>Service=</option>; or it must be a template
                unit named the same way. Example: a socket file
101 102 103
                <filename>foo.socket</filename> needs a matching
                service <filename>foo.service</filename> if
                <option>Accept=false</option> is set. If
104 105 106 107
                <option>Accept=true</option> is set, a service
                template file <filename>foo@.service</filename> must
                exist from which services are instantiated for each
                incoming connection.</para>
108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123

                <para>Unless <varname>DefaultDependencies=</varname>
                is set to <option>false</option>, socket units will
                implicitly have dependencies of type
                <varname>Requires=</varname> and
                <varname>After=</varname> on
                <filename>sysinit.target</filename> as well as
                dependencies of type <varname>Conflicts=</varname> and
                <varname>Before=</varname> on
                <filename>shutdown.target</filename>. These ensure
                that socket units pull in basic system
                initialization, and are terminated cleanly prior to
                system shutdown. Only sockets involved with early
                boot or late system shutdown should disable this
                option.</para>

124 125 126 127 128 129 130 131 132 133 134
                <para>Socket units will have a
                <varname>Before=</varname> dependency on the service
                which they trigger added implicitly. No implicit
                <varname>WantedBy=</varname> or
                <varname>RequiredBy=</varname> dependency from the
                socket to the service is added. This means that the
                service may be started without the socket, in which
                case it must be able to open sockets by itself. To
                prevent this, an explicit <varname>Requires=</varname>
                dependency may be added.</para>

135 136
                <para>Socket units may be used to implement on-demand
                starting of services, as well as parallelized starting
137 138
                of services. See the blog stories linked at the end
                for an introduction.</para>
139 140 141 142 143 144 145 146

                <para>Note that the daemon software configured for
                socket activation with socket units needs to be able
                to accept sockets from systemd, either via systemd's
                native socket passing interface (see
                <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                for details) or via the traditional
                <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>-style
147 148
                socket passing (i.e. sockets passed in via standard input and
                output, using <varname>StandardInput=socket</varname>
149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172
                in the service file).</para>
        </refsect1>

        <refsect1>
                <title>Options</title>

                <para>Socket files must include a [Socket] section,
                which carries information about the socket or FIFO it
                supervises. A number of options that may be used in
                this section are shared with other unit types. These
                options are documented in
                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                and
                <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
                options specific to the [Socket] section of socket
                units are the following:</para>

                <variablelist class='unit-directives'>
                        <varlistentry>
                                <term><varname>ListenStream=</varname></term>
                                <term><varname>ListenDatagram=</varname></term>
                                <term><varname>ListenSequentialPacket=</varname></term>
                                <listitem><para>Specifies an address
                                to listen on for a stream
Michael Biebl's avatar
Michael Biebl committed
173
                                (<constant>SOCK_STREAM</constant>), datagram (<constant>SOCK_DGRAM</constant>),
174
                                or sequential packet
Michael Biebl's avatar
Michael Biebl committed
175
                                (<constant>SOCK_SEQPACKET</constant>) socket, respectively. The address
176 177 178
                                can be written in various formats:</para>

                                <para>If the address starts with a
Michael Biebl's avatar
Michael Biebl committed
179 180
                                slash (<literal>/</literal>), it is read as file system
                                socket in the <constant>AF_UNIX</constant> socket
181 182
                                family.</para>

Michael Biebl's avatar
Michael Biebl committed
183 184 185 186 187 188 189 190
                                <para>If the address starts with an at
                                symbol (<literal>@</literal>), it is read as abstract
                                namespace socket in the
                                <constant>AF_UNIX</constant>
                                family. The <literal>@</literal> is
                                replaced with a
                                <constant>NUL</constant> character
                                before binding. For details, see
191 192 193
                                <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>

                                <para>If the address string is a
Michael Biebl's avatar
Michael Biebl committed
194
                                single number, it is read as port
195 196 197 198 199 200 201 202 203
                                number to listen on via
                                IPv6. Depending on the value of
                                <varname>BindIPv6Only=</varname> (see below) this
                                might result in the service being
                                available via both IPv6 and IPv4 (default) or
                                just via IPv6.
                                </para>

                                <para>If the address string is a
Michael Biebl's avatar
Michael Biebl committed
204
                                string in the format v.w.x.y:z, it is
205 206 207 208 209
                                read as IPv4 specifier for listening
                                on an address v.w.x.y on a port
                                z.</para>

                                <para>If the address string is a
Michael Biebl's avatar
Michael Biebl committed
210
                                string in the format [x]:y, it is read
211 212 213 214 215 216 217
                                as IPv6 address x on a port y. Note
                                that this might make the service
                                available via IPv4, too, depending on
                                the <varname>BindIPv6Only=</varname>
                                setting (see below).
                                </para>

Michael Biebl's avatar
Michael Biebl committed
218
                                <para>Note that <constant>SOCK_SEQPACKET</constant>
219
                                (i.e. <varname>ListenSequentialPacket=</varname>)
Michael Biebl's avatar
Michael Biebl committed
220 221
                                is only available for <constant>AF_UNIX</constant>
                                sockets. <constant>SOCK_STREAM</constant>
222 223
                                (i.e. <varname>ListenStream=</varname>)
                                when used for IP sockets refers to TCP
Michael Biebl's avatar
Michael Biebl committed
224
                                sockets, <constant>SOCK_DGRAM</constant>
225 226 227 228 229 230 231 232
                                (i.e. <varname>ListenDatagram=</varname>)
                                to UDP.</para>

                                <para>These options may be specified
                                more than once in which case incoming
                                traffic on any of the sockets will
                                trigger service activation, and all
                                listed sockets will be passed to the
233
                                service, regardless of whether there is
234 235 236 237 238 239 240
                                incoming traffic on them or not. If
                                the empty string is assigned to any of
                                these options, the list of addresses
                                to listen on is reset, all prior uses
                                of any of these options will have no
                                effect.</para>

241 242 243 244 245 246 247 248 249 250 251
                                <para>It is also possible to have more
                                than one socket unit for the same
                                service when using
                                <varname>Service=</varname>, and the
                                service will receive all the sockets
                                configured in all the socket units.
                                Sockets configured in one unit are
                                passed in the order of configuration,
                                but no ordering between socket units
                                is specified.</para>

252 253 254 255
                                <para>If an IP address is used here,
                                it is often desirable to listen on it
                                before the interface it is configured
                                on is up and running, and even
256 257
                                regardless of whether it will be up and
                                running at any point. To deal with this,
258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293
                                it is recommended to set the
                                <varname>FreeBind=</varname> option
                                described below.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ListenFIFO=</varname></term>
                                <listitem><para>Specifies a file
                                system FIFO to listen on. This expects
                                an absolute file system path as
                                argument. Behavior otherwise is very
                                similar to the
                                <varname>ListenDatagram=</varname>
                                directive above.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ListenSpecial=</varname></term>
                                <listitem><para>Specifies a special
                                file in the file system to listen
                                on. This expects an absolute file
                                system path as argument. Behavior
                                otherwise is very similar to the
                                <varname>ListenFIFO=</varname>
                                directive above. Use this to open
                                character device nodes as well as
                                special files in
                                <filename>/proc</filename> and
                                <filename>/sys</filename>.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ListenNetlink=</varname></term>
                                <listitem><para>Specifies a Netlink
                                family to create a socket for to
                                listen on. This expects a short string
Michael Biebl's avatar
Michael Biebl committed
294
                                referring to the <constant>AF_NETLINK</constant> family
295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333
                                name (such as <varname>audit</varname>
                                or <varname>kobject-uevent</varname>)
                                as argument, optionally suffixed by a
                                whitespace followed by a multicast
                                group integer. Behavior otherwise is
                                very similar to the
                                <varname>ListenDatagram=</varname>
                                directive above.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ListenMessageQueue=</varname></term>
                                <listitem><para>Specifies a POSIX
                                message queue name to listen on. This
                                expects a valid message queue name
                                (i.e. beginning with /). Behavior
                                otherwise is very similar to the
                                <varname>ListenFIFO=</varname>
                                directive above. On Linux message
                                queue descriptors are actually file
                                descriptors and can be inherited
                                between processes.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>BindIPv6Only=</varname></term>
                                <listitem><para>Takes a one of
                                <option>default</option>,
                                <option>both</option> or
                                <option>ipv6-only</option>. Controls
                                the IPV6_V6ONLY socket option (see
                                <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                                for details). If
                                <option>both</option>, IPv6 sockets
                                bound will be accessible via both IPv4
                                and IPv6. If
                                <option>ipv6-only</option>, they will
                                be accessible via IPv6 only. If
                                <option>default</option> (which is the
Michael Biebl's avatar
Michael Biebl committed
334
                                default, surprise!), the system wide
335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360
                                default setting is used, as controlled
                                by
                                <filename>/proc/sys/net/ipv6/bindv6only</filename>,
                                which in turn defaults to the
                                equivalent of
                                <option>both</option>.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>Backlog=</varname></term>
                                <listitem><para>Takes an unsigned
                                integer argument. Specifies the number
                                of connections to queue that have not
                                been accepted yet. This setting
                                matters only for stream and sequential
                                packet sockets. See
                                <citerefentry><refentrytitle>listen</refentrytitle><manvolnum>2</manvolnum></citerefentry>
                                for details. Defaults to SOMAXCONN
                                (128).</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>BindToDevice=</varname></term>
                                <listitem><para>Specifies a network
                                interface name to bind this socket
Michael Biebl's avatar
Michael Biebl committed
361
                                to. If set, traffic will only be
362 363 364 365 366 367 368 369 370 371 372 373 374
                                accepted from the specified network
                                interfaces. This controls the
                                SO_BINDTODEVICE socket option (see
                                <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                                for details). If this option is used,
                                an automatic dependency from this
                                socket unit on the network interface
                                device unit
                                (<citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                                is created.</para></listitem>
                        </varlistentry>

                        <varlistentry>
375 376 377 378
                                <term><varname>SocketUser=</varname></term>
                                <term><varname>SocketGroup=</varname></term>

                                <listitem><para>Takes a UNIX
Michael Biebl's avatar
Michael Biebl committed
379
                                user/group name. When specified,
380 381 382 383 384 385 386 387 388 389
                                all AF_UNIX sockets and FIFO nodes in
                                the file system are owned by the
                                specified user and group. If unset
                                (the default), the nodes are owned by
                                the root user/group (if run in system
                                context) or the invoking user/group
                                (if run in user context). If only a
                                user is specified but no group, then
                                the group is derived from the user's
                                default group.</para></listitem>
390 391 392 393 394 395 396 397 398 399 400 401 402
                        </varlistentry>

                        <varlistentry>
                                <term><varname>SocketMode=</varname></term>
                                <listitem><para>If listening on a file
                                system socket or FIFO, this option
                                specifies the file system access mode
                                used when creating the file
                                node. Takes an access mode in octal
                                notation. Defaults to
                                0666.</para></listitem>
                        </varlistentry>

403 404 405 406 407 408 409 410 411 412 413 414 415
                        <varlistentry>
                                <term><varname>DirectoryMode=</varname></term>
                                <listitem><para>If listening on a file
                                system socket or FIFO, the parent
                                directories are automatically created
                                if needed. This option specifies the
                                file system access mode used when
                                creating these directories. Takes an
                                access mode in octal
                                notation. Defaults to
                                0755.</para></listitem>
                        </varlistentry>

416 417 418 419 420 421 422 423 424 425 426 427
                        <varlistentry>
                                <term><varname>Accept=</varname></term>
                                <listitem><para>Takes a boolean
                                argument. If true, a service instance
                                is spawned for each incoming
                                connection and only the connection
                                socket is passed to it. If false, all
                                listening sockets themselves are
                                passed to the started service unit,
                                and only one service unit is spawned
                                for all connections (also see
                                above). This value is ignored for
Michael Biebl's avatar
Michael Biebl committed
428 429
                                datagram sockets and FIFOs where a
                                single service unit unconditionally
430 431 432 433 434
                                handles all incoming traffic. Defaults
                                to <option>false</option>. For
                                performance reasons, it is recommended
                                to write new daemons only in a way
                                that is suitable for
Michael Biebl's avatar
Michael Biebl committed
435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451
                                <option>Accept=false</option>. A
                                daemon listening on an <constant>AF_UNIX</constant> socket
                                may, but does not need to, call
                                <citerefentry><refentrytitle>close</refentrytitle><manvolnum>2</manvolnum></citerefentry>
                                on the received socket before
                                exiting. However, it must not unlink
                                the socket from a file system. It
                                should not invoke
                                <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>2</manvolnum></citerefentry>
                                on sockets it got with
                                <varname>Accept=false</varname>, but
                                it may do so for sockets it got with
                                <varname>Accept=true</varname> set.
                                Setting <varname>Accept=true</varname>
                                is mostly useful to allow daemons
                                designed for usage with
                                <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
452 453 454 455 456 457 458 459 460 461 462 463 464 465
                                to work unmodified with systemd socket
                                activation.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>MaxConnections=</varname></term>
                                <listitem><para>The maximum number of
                                connections to simultaneously run
                                services instances for, when
                                <option>Accept=true</option> is
                                set. If more concurrent connections
                                are coming in, they will be refused
                                until at least one existing connection
                                is terminated. This setting has no
Michael Biebl's avatar
Michael Biebl committed
466
                                effect on sockets configured with
467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504
                                <option>Accept=false</option> or datagram
                                sockets. Defaults to
                                64.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>KeepAlive=</varname></term>
                                <listitem><para>Takes a boolean
                                argument. If true, the TCP/IP stack
                                will send a keep alive message after
                                2h (depending on the configuration of
                                <filename>/proc/sys/net/ipv4/tcp_keepalive_time</filename>)
                                for all TCP streams accepted on this
                                socket. This controls the SO_KEEPALIVE
                                socket option (see
                                <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                                and the <ulink
                                url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
                                Keepalive HOWTO</ulink> for details.)
                                Defaults to
                                <option>false</option>.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>Priority=</varname></term>
                                <listitem><para>Takes an integer
                                argument controlling the priority for
                                all traffic sent from this
                                socket. This controls the SO_PRIORITY
                                socket option (see
                                <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                                for details.).</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ReceiveBuffer=</varname></term>
                                <term><varname>SendBuffer=</varname></term>
                                <listitem><para>Takes an integer
505 506 507 508 509
                                argument controlling the receive or
                                send buffer sizes of this socket,
                                respectively. This controls the
                                SO_RCVBUF and SO_SNDBUF socket options
                                (see
510
                                <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
511 512 513
                                for details.). The usual suffixes K,
                                M, G are supported and are understood
                                to the base of 1024.</para></listitem>
514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558
                        </varlistentry>

                        <varlistentry>
                                <term><varname>IPTOS=</varname></term>
                                <listitem><para>Takes an integer
                                argument controlling the IP
                                Type-Of-Service field for packets
                                generated from this socket. This
                                controls the IP_TOS socket option (see
                                <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                                for details.). Either a numeric string
                                or one of <option>low-delay</option>,
                                <option>throughput</option>,
                                <option>reliability</option> or
                                <option>low-cost</option> may be
                                specified.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>IPTTL=</varname></term>
                                <listitem><para>Takes an integer
                                argument controlling the IPv4
                                Time-To-Live/IPv6 Hop-Count field for
                                packets generated from this
                                socket. This sets the
                                IP_TTL/IPV6_UNICAST_HOPS socket
                                options (see
                                <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                                and
                                <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                                for details.)</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>Mark=</varname></term>
                                <listitem><para>Takes an integer
                                value. Controls the firewall mark of
                                packets generated by this socket. This
                                can be used in the firewall logic to
                                filter packets from this socket. This
                                sets the SO_MARK socket option. See
                                <citerefentry><refentrytitle>iptables</refentrytitle><manvolnum>8</manvolnum></citerefentry>
                                for details.</para></listitem>
                        </varlistentry>

Michael Biebl's avatar
Michael Biebl committed
559 560 561 562 563 564 565 566 567 568 569
                        <varlistentry>
                                <term><varname>ReusePort=</varname></term>
                                <listitem><para>Takes a boolean
                                value. If true, allows multiple <citerefentry><refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum></citerefentry>s
                                to this TCP or UDP port.  This
                                controls the SO_REUSEPORT socket
                                option.  See
                                <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                                for details.</para></listitem>
                        </varlistentry>

570 571 572 573 574 575 576 577 578 579 580 581 582 583
                        <varlistentry>
                                <term><varname>SmackLabel=</varname></term>
                                <term><varname>SmackLabelIPIn=</varname></term>
                                <term><varname>SmackLabelIPOut=</varname></term>
                                <listitem><para>Takes a string
                                value. Controls the extended
                                attributes
                                <literal>security.SMACK64</literal>,
                                <literal>security.SMACK64IPIN</literal>
                                and
                                <literal>security.SMACK64IPOUT</literal>,
                                respectively, i.e. the security label
                                of the FIFO, or the security label for
                                the incoming or outgoing connections
Michael Biebl's avatar
Michael Biebl committed
584
                                of the socket, respectively. See
585 586 587 588 589 590 591
                                <ulink
                                url="https://www.kernel.org/doc/Documentation/security/Smack.txt">Smack.txt</ulink>
                                for details.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>PipeSize=</varname></term>
592 593
                                <listitem><para>Takes a size in
                                bytes. Controls the pipe buffer size
594
                                of FIFOs configured in this socket
Michael Biebl's avatar
Michael Biebl committed
595
                                unit. See
596
                                <citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
597 598 599
                                for details. The usual suffixes K, M,
                                G are supported and are understood to
                                the base of 1024.</para></listitem>
600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653
                        </varlistentry>

                        <varlistentry>
                                <term><varname>MessageQueueMaxMessages=</varname>,
                                <varname>MessageQueueMessageSize=</varname></term>
                                <listitem><para>These two settings
                                take integer values and control the
                                mq_maxmsg field or the mq_msgsize field, respectively, when
                                creating the message queue. Note that
                                either none or both of these variables
                                need to be set. See
                                <citerefentry><refentrytitle>mq_setattr</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                                for details.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>FreeBind=</varname></term>
                                <listitem><para>Takes a boolean
                                value. Controls whether the socket can
                                be bound to non-local IP
                                addresses. This is useful to configure
                                sockets listening on specific IP
                                addresses before those IP addresses
                                are successfully configured on a
                                network interface. This sets the
                                IP_FREEBIND socket option. For
                                robustness reasons it is recommended
                                to use this option whenever you bind a
                                socket to a specific IP
                                address. Defaults to <option>false</option>.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>Transparent=</varname></term>
                                <listitem><para>Takes a boolean
                                value. Controls the IP_TRANSPARENT
                                socket option. Defaults to
                                <option>false</option>.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>Broadcast=</varname></term>
                                <listitem><para>Takes a boolean
                                value. This controls the SO_BROADCAST
                                socket option, which allows broadcast
                                datagrams to be sent from this
                                socket. Defaults to
                                <option>false</option>.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>PassCredentials=</varname></term>
                                <listitem><para>Takes a boolean
                                value. This controls the SO_PASSCRED
Michael Biebl's avatar
Michael Biebl committed
654
                                socket option, which allows <constant>AF_UNIX</constant> sockets to
655 656 657 658 659 660 661 662 663 664
                                receive the credentials of the sending
                                process in an ancillary message.
                                Defaults to
                                <option>false</option>.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>PassSecurity=</varname></term>
                                <listitem><para>Takes a boolean
                                value. This controls the SO_PASSSEC
Michael Biebl's avatar
Michael Biebl committed
665
                                socket option, which allows <constant>AF_UNIX</constant>
666 667
                                sockets to receive the security
                                context of the sending process in an
Michael Biebl's avatar
Michael Biebl committed
668
                                ancillary message. Defaults to
669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691
                                <option>false</option>.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>TCPCongestion=</varname></term>
                                <listitem><para>Takes a string
                                value. Controls the TCP congestion
                                algorithm used by this socket. Should
                                be one of "westwood", "veno", "cubic",
                                "lp" or any other available algorithm
                                supported by the IP stack. This
                                setting applies only to stream
                                sockets.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ExecStartPre=</varname></term>
                                <term><varname>ExecStartPost=</varname></term>
                                <listitem><para>Takes one or more
                                command lines, which are executed
                                before or after the listening
                                sockets/FIFOs are created and
                                bound, respectively. The first token of the command
Michael Biebl's avatar
Michael Biebl committed
692
                                line must be an absolute filename,
693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726
                                then followed by arguments for the
                                process. Multiple command lines may be
                                specified following the same scheme as
                                used for
                                <varname>ExecStartPre=</varname> of
                                service unit files.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ExecStopPre=</varname></term>
                                <term><varname>ExecStopPost=</varname></term>
                                <listitem><para>Additional commands
                                that are executed before or after
                                the listening sockets/FIFOs are closed
                                and removed, respectively. Multiple command lines
                                may be specified following the same
                                scheme as used for
                                <varname>ExecStartPre=</varname> of
                                service unit files.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>TimeoutSec=</varname></term>
                                <listitem><para>Configures the time to
                                wait for the commands specified in
                                <varname>ExecStartPre=</varname>,
                                <varname>ExecStartPost=</varname>,
                                <varname>ExecStopPre=</varname> and
                                <varname>ExecStopPost=</varname> to
                                finish. If a command does not exit
                                within the configured time, the socket
                                will be considered failed and be shut
                                down again. All commands still running,
                                will be terminated forcibly via
Michael Biebl's avatar
Michael Biebl committed
727 728
                                <constant>SIGTERM</constant>, and after another delay of
                                this time with <constant>SIGKILL</constant>. (See
729 730 731 732
                                <option>KillMode=</option> in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
                                Takes a unit-less value in seconds, or
                                a time span value such as "5min
                                20s". Pass 0 to disable the timeout
733 734
                                logic. Defaults to <varname>TimeoutStartSec=</varname> from the
                                manager configuration file.</para></listitem>
735 736 737 738 739 740
                        </varlistentry>

                        <varlistentry>
                                <term><varname>Service=</varname></term>
                                <listitem><para>Specifies the service
                                unit name to activate on incoming
741 742 743 744 745 746 747 748 749 750 751 752 753
                                traffic. This setting is only allowed
                                for sockets with
                                <varname>Accept=no</varname>. It
                                defaults to the service that bears the
                                same name as the socket (with the
                                suffix replaced). In most cases, it
                                should not be necessary to use this
                                option.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>RemoveOnStop=</varname></term>
                                <listitem><para>Takes a boolean
Michael Biebl's avatar
Michael Biebl committed
754
                                argument. If enabled, any file nodes
755 756 757
                                created by this socket unit are
                                removed when it is stopped. This
                                applies to AF_UNIX sockets in the file
Michael Biebl's avatar
Michael Biebl committed
758 759
                                system, POSIX message queues, FIFOs,
                                as well as any symlinks to
760
                                them configured with
Michael Biebl's avatar
Michael Biebl committed
761
                                <varname>Symlinks=</varname>. Normally,
762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777
                                it should not be necessary to use this
                                option, and is not recommended as
                                services might continue to run after
                                the socket unit has been terminated
                                and it should still be possible to
                                communicate with them via their file
                                system node. Defaults to
                                off.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>Symlinks=</varname></term>
                                <listitem><para>Takes a list of file
                                system paths. The specified paths will
                                be created as symlinks to the AF_UNIX
                                socket path or FIFO path of this
Michael Biebl's avatar
Michael Biebl committed
778
                                socket unit.  If this setting is used,
779 780 781 782 783 784 785
                                only one AF_UNIX socket in the file
                                system or one FIFO may be configured
                                for the socket unit. Use this option
                                to manage one or more symlinked alias
                                names for a socket, binding their
                                lifecycle together. Defaults to the
                                empty list.</para></listitem>
786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805
                        </varlistentry>

                </variablelist>

                <para>Check
                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                and
                <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                for more settings.</para>

        </refsect1>

        <refsect1>
                  <title>See Also</title>
                  <para>
                          <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                          <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                          <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                          <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                          <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
Michael Biebl's avatar
Michael Biebl committed
806
                          <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
807 808 809 810 811
                          <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                          <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                  </para>

                  <para>
Michael Biebl's avatar
Michael Biebl committed
812
                          For more extensive descriptions see the "systemd for Developers" series:
813 814 815 816 817 818 819 820
                          <ulink url="http://0pointer.de/blog/projects/socket-activation.html">Socket Activation</ulink>,
                          <ulink url="http://0pointer.de/blog/projects/socket-activation2.html">Socket Activation, part II</ulink>,
                          <ulink url="http://0pointer.de/blog/projects/inetd.html">Converting inetd Services</ulink>,
                          <ulink url="http://0pointer.de/blog/projects/socket-activated-containers.html">Socket Activated Internet Services and OS Containers</ulink>.
                  </para>
        </refsect1>

</refentry>