man/systemd.socket.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
   3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   4         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   5
   6 <!--
   7   This file is part of systemd.
   8
   9   Copyright 2010 Lennart Poettering
  10
  11   systemd is free software; you can redistribute it and/or modify it
  12   under the terms of the GNU General Public License as published by
  13   the Free Software Foundation; either version 2 of the License, or
  14   (at your option) any later version.
  15
  16   systemd is distributed in the hope that it will be useful, but
  17   WITHOUT ANY WARRANTY; without even the implied warranty of
  18   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  19   General Public License for more details.
  20
  21   You should have received a copy of the GNU General Public License
  22   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  23 -->
  24
  25 <refentry id="systemd.socket">
  26         <refentryinfo>
  27                 <title>systemd.socket</title>
  28                 <productname>systemd</productname>
  29
  30                 <authorgroup>
  31                         <author>
  32                                 <contrib>Developer</contrib>
  33                                 <firstname>Lennart</firstname>
  34                                 <surname>Poettering</surname>
  35                                 <email>lennart@poettering.net</email>
  36                         </author>
  37                 </authorgroup>
  38         </refentryinfo>
  39
  40         <refmeta>
  41                 <refentrytitle>systemd.socket</refentrytitle>
  42                 <manvolnum>5</manvolnum>
  43         </refmeta>
  44
  45         <refnamediv>
  46                 <refname>systemd.socket</refname>
  47                 <refpurpose>systemd socket configuration files</refpurpose>
  48         </refnamediv>
  49
  50         <refsynopsisdiv>
  51                 <para><filename>systemd.socket</filename></para>
  52         </refsynopsisdiv>
  53
  54         <refsect1>
  55                 <title>Description</title>
  56
  57                 <para>A unit configuration file whose name ends in
  58                 <filename>.socket</filename> encodes information about
  59                 an IPC or network socket or a file system FIFO
  60                 controlled and supervised by systemd, for socket-based
  61                 activation.</para>
  62
  63                 <para>This man page lists the configuration options
  64                 specific to this unit type. See
  65                 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  66                 for the common options of all unit configuration
  67                 files. The common configuration items are configured
  68                 in the generic [Unit] and [Install] sections. The
  69                 socket specific configuration options are configured
  70                 in the [Socket] section.</para>
  71
  72                 <para>Additional options are listed in
  73                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  74                 which define the execution environment the
  75                 <option>ExecStartPre=</option>,
  76                 <option>ExecStartPost=</option>,
  77                 <option>ExecStopPre=</option> and
  78                 <option>ExecStoptPost=</option> commands are executed
  79                 in.</para>
  80
  81                 <para>For each socket file a matching service file
  82                 (see
  83                 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  84                 for details) must exist, describing the service to
  85                 start on incoming traffic on the socket. Depending on
  86                 the setting of <option>Accept=</option> (see below),
  87                 this must either be named like the socket unit, but
  88                 with the suffix replaced; or it must be a template
  89                 file named the same way. Example: a socket file
  90                 <filename>foo.socket</filename> needs a matching
  91                 service <filename>foo.service</filename> if
  92                 <option>Accept=false</option> is set. If
  93                 <option>Accept=true</option> is set a service template
  94                 file <filename>foo@.service</filename> must exist from
  95                 which services are instantiated for each incoming
  96                 connection.</para>
  97
  98                 <para>Socket units may be used to implement on-demand
  99                 starting of services, as well as parallelized starting
 100                 of services.</para>
 101         </refsect1>
 102
 103         <refsect1>
 104                 <title>Options</title>
 105
 106                 <para>Socket files must include a [Socket] section,
 107                 which carries information about the socket or FIFO it
 108                 supervises. A number of options that may be used in
 109                 this section are shared with other unit types. These
 110                 options are documented in
 111                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
 112                 options specific to the [Socket] section of socket
 113                 units are the following:</para>
 114
 115                 <variablelist>
 116                         <varlistentry>
 117                                 <term><varname>ListenStream=</varname></term>
 118                                 <term><varname>ListenDatagram=</varname></term>
 119                                 <term><varname>ListenSequentialPacket=</varname></term>
 120                                 <listitem><para>Specifies an address
 121                                 to listen on for a stream
 122                                 (SOCK_STREAM), datagram (SOCK_DGRAM)
 123                                 resp. sequential packet
 124                                 (SOCK_SEQPACKET) socket. The address
 125                                 can be written in various formats:</para>
 126
 127                                 <para>If the address starts with a
 128                                 slash (/), it is read as file system
 129                                 socket in the AF_UNIX socket
 130                                 family.</para>
 131
 132                                 <para>If the address starts with an
 133                                 ampersand (@) it is read as abstract
 134                                 namespace socket in the AF_UNIX
 135                                 family. The @ is replaced with a NUL
 136                                 character before binding. For details
 137                                 see
 138                                 <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
 139
 140                                 <para>If the address string is a
 141                                 single number it is read as port
 142                                 number to listen on for both IPv4 and
 143                                 IPv6.</para>
 144
 145                                 <para>If the address string is a
 146                                 string in the format v.w.x.y:z it is
 147                                 read as IPv4 specifier for listening
 148                                 on an address v.w.x.y on a port
 149                                 z.</para>
 150
 151                                 <para>If the address string is a
 152                                 string in the format [x]:y it is read
 153                                 as IPv6 address x on a port y.</para>
 154
 155                                 <para>Note that SOCK_SEQPACKET
 156                                 (i.e. <varname>ListenSequentialPacket=</varname>)
 157                                 is only available for AF_UNIX
 158                                 sockets. SOCK_STREAM
 159                                 (i.e. <varname>ListenStream=</varname>)
 160                                 when used for IP sockets refers to TCP
 161                                 sockets, SOCK_DGRAM
 162                                 (i.e. <varname>ListenDatagram=</varname>)
 163                                 to UDP.</para>
 164
 165                                 <para>These options may be specified
 166                                 more than once in which case incoming
 167                                 traffic on any of the sockets will trigger
 168                                 service activation, and all listed
 169                                 sockets will be passed to the service,
 170                                 regardless whether there is incoming
 171                                 traffic on them or not.</para>
 172
 173                                 <para>If an IP address is used here, it
 174                                 is often desirable to listen on it
 175                                 before the interface it is configured
 176                                 on is up and running, and even
 177                                 regardless whether it will be up and
 178                                 running ever at all. To deal with this it is
 179                                 recommended to set the
 180                                 <varname>FreeBind=</varname> option
 181                                 described below.</para></listitem>
 182                         </varlistentry>
 183
 184                         <varlistentry>
 185                                 <term><varname>ListenFIFO=</varname></term>
 186                                 <listitem><para>Specifies a file
 187                                 system FIFO to listen on. This expects
 188                                 an absolute file system path as
 189                                 argument. Behaviour otherwise is very
 190                                 similar to the
 191                                 <varname>ListenDatagram=</varname>
 192                                 directive above.</para></listitem>
 193                         </varlistentry>
 194
 195                         <varlistentry>
 196                                 <term><varname>BindIPv6Only=</varname></term>
 197                                 <listitem><para>Takes a one of
 198                                 <option>default</option>,
 199                                 <option>both</option> or
 200                                 <option>ipv6-only</option>. Controls
 201                                 the IPV6_V6ONLY socket option (see
 202                                 <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 203                                 for details). If
 204                                 <option>both</option>, IPv6 sockets
 205                                 bound will be accessible via both IPv4
 206                                 and IPv6. If
 207                                 <option>ipv6-only</option>, they will
 208                                 be accessible via IPv6 only. If
 209                                 <option>default</option> (which is the
 210                                 default, surprise!) the system wide
 211                                 default setting is used, as controlled
 212                                 by
 213                                 <filename>/proc/sys/net/ipv6/bindv6only</filename>.</para>
 214                                 </listitem>
 215                         </varlistentry>
 216
 217                         <varlistentry>
 218                                 <term><varname>Backlog=</varname></term>
 219                                 <listitem><para>Takes an unsigned
 220                                 integer argument. Specifies the number
 221                                 of connections to queue that have not
 222                                 been accepted yet. This setting
 223                                 matters only for stream and sequential
 224                                 packet sockets. See
 225                                 <citerefentry><refentrytitle>listen</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 226                                 for details. Defaults to SOMAXCONN
 227                                 (128).</para></listitem>
 228                         </varlistentry>
 229
 230                         <varlistentry>
 231                                 <term><varname>BindToDevice=</varname></term>
 232                                 <listitem><para>Specifies a network
 233                                 interface name to bind this socket
 234                                 to. If set traffic will only be
 235                                 accepted from the specified network
 236                                 interfaces. This controls the
 237                                 SO_BINDTODEVICE socket option (see
 238                                 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 239                                 for details). If this option is used,
 240                                 an automatic dependency from this
 241                                 socket unit on the network interface
 242                                 device unit
 243                                 (<citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 244                                 is created.</para></listitem>
 245                         </varlistentry>
 246
 247                         <varlistentry>
 248                                 <term><varname>DirectoryMode=</varname></term>
 249                                 <listitem><para>If listening on a file
 250                                 system socket of FIFO, the parent
 251                                 directories are automatically created
 252                                 if needed. This option specifies the
 253                                 file system access mode used when
 254                                 creating these directories. Takes an
 255                                 access mode in octal
 256                                 notation. Defaults to
 257                                 0755.</para></listitem>
 258                         </varlistentry>
 259
 260                         <varlistentry>
 261                                 <term><varname>SocketMode=</varname></term>
 262                                 <listitem><para>If listening on a file
 263                                 system socket of FIFO, this option
 264                                 specifies the file system access mode
 265                                 used when creating the file
 266                                 node. Takes an access mode in octal
 267                                 notation. Defaults to
 268                                 0666.</para></listitem>
 269                         </varlistentry>
 270
 271                         <varlistentry>
 272                                 <term><varname>Accept=</varname></term>
 273                                 <listitem><para>Takes a boolean
 274                                 argument. If true, a service instance
 275                                 is spawned for each incoming
 276                                 connection and only the connection
 277                                 socket is passed to it. If false, all
 278                                 listening sockets themselves are
 279                                 passed to the started service unit,
 280                                 and only one service unit is spawned
 281                                 for all connections (also see
 282                                 above). This value is ignored for
 283                                 datagram sockets and FIFOs where
 284                                 a single service unit unconditionally
 285                                 handles all incoming traffic. Defaults
 286                                 to <option>false</option>. For
 287                                 performance reasons, it is recommended
 288                                 to write new daemons only in a way
 289                                 that is suitable for
 290                                 <option>Accept=false</option>. This
 291                                 option is mostly useful to allow
 292                                 daemons designed for usage with
 293                                 <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 294                                 to work unmodified with systemd socket
 295                                 activation.</para></listitem>
 296                         </varlistentry>
 297
 298                         <varlistentry>
 299                                 <term><varname>MaxConnections=</varname></term>
 300                                 <listitem><para>The maximum number of
 301                                 connections to simultaneously run
 302                                 services instances for, when
 303                                 <option>Accept=true</option> is
 304                                 set. If more concurrent connections
 305                                 are coming in, they will be refused
 306                                 until at least one existing connection
 307                                 is terminated. This setting has no
 308                                 effect for sockets configured with
 309                                 <option>Accept=no</option> or datagram
 310                                 sockets. Defaults to
 311                                 64.</para></listitem>
 312                         </varlistentry>
 313
 314                         <varlistentry>
 315                                 <term><varname>KeepAlive=</varname></term>
 316                                 <listitem><para>Takes a boolean
 317                                 argument. If true, the TCP/IP stack
 318                                 will send a keep alive message after
 319                                 2h (depending on the configuration of
 320                                 <filename>/proc/sys/net/ipv4/tcp_keepalive_time</filename>)
 321                                 for all TCP streams accepted on this
 322                                 socket. This controls the SO_KEEPALIVE
 323                                 socket option (see
 324                                 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 325                                 and the <ulink
 326                                 url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
 327                                 Keepalive HOWTO</ulink> for details.)
 328                                 Defaults to
 329                                 <option>false</option>.</para></listitem>
 330                         </varlistentry>
 331
 332                         <varlistentry>
 333                                 <term><varname>Priority=</varname></term>
 334                                 <listitem><para>Takes an integer
 335                                 argument controlling the priority for
 336                                 all traffic sent from this
 337                                 socket. This controls the SO_PRIORITY
 338                                 socket option (see
 339                                 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 340                                 for details.).</para></listitem>
 341                         </varlistentry>
 342
 343                         <varlistentry>
 344                                 <term><varname>ReceiveBuffer=</varname></term>
 345                                 <term><varname>SendBuffer=</varname></term>
 346                                 <listitem><para>Takes an integer
 347                                 argument controlling the receive
 348                                 resp. send buffer sizes of this
 349                                 socket. This controls the SO_RCVBUF
 350                                 resp. SO_SNDBUF socket options (see
 351                                 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 352                                 for details.).</para></listitem>
 353                         </varlistentry>
 354
 355                         <varlistentry>
 356                                 <term><varname>IPTOS=</varname></term>
 357                                 <listitem><para>Takes an integer
 358                                 argument controlling the IP
 359                                 Type-Of-Service field for packets
 360                                 generated from this socket. This
 361                                 controls the IP_TOS socket option (see
 362                                 <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 363                                 for details.). Either a numeric string
 364                                 or one of <option>low-delay</option>,
 365                                 <option>throughput</option>,
 366                                 <option>reliability</option> or
 367                                 <option>low-cost</option> may be
 368                                 specified.</para></listitem>
 369                         </varlistentry>
 370
 371                         <varlistentry>
 372                                 <term><varname>IPTTL=</varname></term>
 373                                 <listitem><para>Takes an integer
 374                                 argument controlling the IPv4
 375                                 Time-To-Live/IPv6 Hop-Count field for
 376                                 packets generated from this
 377                                 socket. This sets the
 378                                 IP_TTL/IPV6_UNICAST_HOPS socket
 379                                 options (see
 380                                 <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 381                                 and
 382                                 <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 383                                 for details.)</para></listitem>
 384                         </varlistentry>
 385
 386                         <varlistentry>
 387                                 <term><varname>Mark=</varname></term>
 388                                 <listitem><para>Takes an integer
 389                                 value. Controls the firewall mark of
 390                                 packets generated by this socket. This
 391                                 can be used in the firewall logic to
 392                                 filter packets from this socket. This
 393                                 sets the SO_MARK socket option. See
 394                                 <citerefentry><refentrytitle>iptables</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 395                                 for details.</para></listitem>
 396                         </varlistentry>
 397
 398                         <varlistentry>
 399                                 <term><varname>PipeSize=</varname></term>
 400                                 <listitem><para>Takes an integer
 401                                 value. Controls the pipe buffer size
 402                                 of FIFOs configured in this socket
 403                                 unit.  See
 404                                 <citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 405                                 for details.</para></listitem>
 406                         </varlistentry>
 407
 408                         <varlistentry>
 409                                 <term><varname>FreeBind=</varname></term>
 410                                 <listitem><para>Takes a boolean
 411                                 value. Controls whether the socket can
 412                                 be bound to non-local IP
 413                                 addresses. This is useful to configure
 414                                 sockets listening on specific IP
 415                                 addresses before those IP addresses
 416                                 are successfully configured on a
 417                                 network interface. This sets the
 418                                 IP_FREEBIND socket option. For
 419                                 robustness reasons it is recommended
 420                                 to use this option whenever you bind a
 421                                 socket to a specific IP
 422                                 address. Defaults to <option>false</option>.</para></listitem>
 423                         </varlistentry>
 424
 425                         <varlistentry>
 426                                 <term><varname>ExecStartPre=</varname></term>
 427                                 <term><varname>ExecStartPost=</varname></term>
 428                                 <listitem><para>Takes a command line,
 429                                 which is executed before (resp. after)
 430                                 the listening sockets/FIFOs are created and
 431                                 bound. The first token of the command
 432                                 line must be an absolute file name,
 433                                 then followed by arguments for the
 434                                 process. If specified more than once,
 435                                 all commands are executed one after
 436                                 the other, fully serialized. The use of
 437                                 these settings is optional.</para></listitem>
 438                         </varlistentry>
 439
 440                         <varlistentry>
 441                                 <term><varname>ExecStopPre=</varname></term>
 442                                 <term><varname>ExecStopPost=</varname></term>
 443                                 <listitem><para>Additional commands
 444                                 that are executed before (resp. after)
 445                                 the listening sockets/FIFOs are closed
 446                                 and removed. If specified more than
 447                                 once, all commands are executed one
 448                                 after the other, fully serialized. The use of
 449                                 these settings is optional.</para></listitem>
 450                         </varlistentry>
 451
 452                         <varlistentry>
 453                                 <term><varname>TimeoutSec=</varname></term>
 454                                 <listitem><para>Configures the time to
 455                                 wait for the commands specified in
 456                                 <varname>ExecStartPre=</varname>,
 457                                 <varname>ExecStartPost=</varname>,
 458                                 <varname>ExecStopPre=</varname> and
 459                                 <varname>ExecStopPost=</varname> to
 460                                 finish. If a command does not exit
 461                                 within the configured time, the socket
 462                                 will be considered failed and be shut
 463                                 down again. All commands still running,
 464                                 will be terminated forcibly via
 465                                 SIGTERM, and after another delay of
 466                                 this time with SIGKILL. (See
 467                                 <option>KillMode=</option> below.)
 468                                 Takes a unit-less value in seconds, or
 469                                 a time span value such as "5min
 470                                 20s". Pass 0 to disable the timeout
 471                                 logic. Defaults to
 472                                 60s.</para></listitem>
 473                         </varlistentry>
 474
 475                         <varlistentry>
 476                                 <term><varname>KillMode=</varname></term>
 477                                 <listitem><para>Specifies how
 478                                 processes of this socket unit shall be
 479                                 killed. One of
 480                                 <option>control-group</option>,
 481                                 <option>process-group</option>,
 482                                 <option>process</option>,
 483                                 <option>none</option>.</para>
 484
 485                                 <para>This option is mostly equivalent
 486                                 to the <option>KillMode=</option>
 487                                 option of service files. See
 488                                 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 489                                 for details.</para></listitem>
 490                         </varlistentry>
 491                 </variablelist>
 492         </refsect1>
 493
 494         <refsect1>
 495                   <title>See Also</title>
 496                   <para>
 497                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 498                           <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 499                           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 500                           <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 501                           <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 502                   </para>
 503         </refsect1>
 504
 505 </refentry>