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