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