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