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">
7 This file is part of systemd.
9 Copyright 2010 Lennart Poettering
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.
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.
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/>.
25 <refentry id="systemd.socket">
27 <title>systemd.socket</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>systemd.socket</refentrytitle>
42 <manvolnum>5</manvolnum>
46 <refname>systemd.socket</refname>
47 <refpurpose>systemd socket configuration files</refpurpose>
51 <para><filename>systemd.socket</filename></para>
55 <title>Description</title>
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
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>
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
81 <para>For each socket file a matching service file
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
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
113 <para>Socket units may be used to implement on-demand
114 starting of services, as well as parallelized starting
117 <para>Note that the daemon software configured for
118 socket activation with socket units needs to be able
119 to accept sockets from systemd, either via systemd's
120 native socket passing interface (see
121 <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
122 for details) or via the traditional
123 <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>-style
124 socket passing (i.e. sockets passed in via STDIN and
125 STDOUT, using <varname>StandardInput=socket</varname>
126 in the service file).</para>
130 <title>Options</title>
132 <para>Socket files must include a [Socket] section,
133 which carries information about the socket or FIFO it
134 supervises. A number of options that may be used in
135 this section are shared with other unit types. These
136 options are documented in
137 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
138 options specific to the [Socket] section of socket
139 units are the following:</para>
143 <term><varname>ListenStream=</varname></term>
144 <term><varname>ListenDatagram=</varname></term>
145 <term><varname>ListenSequentialPacket=</varname></term>
146 <listitem><para>Specifies an address
147 to listen on for a stream
148 (SOCK_STREAM), datagram (SOCK_DGRAM)
149 resp. sequential packet
150 (SOCK_SEQPACKET) socket. The address
151 can be written in various formats:</para>
153 <para>If the address starts with a
154 slash (/), it is read as file system
155 socket in the AF_UNIX socket
158 <para>If the address starts with an
159 ampersand (@) it is read as abstract
160 namespace socket in the AF_UNIX
161 family. The @ is replaced with a NUL
162 character before binding. For details
164 <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
166 <para>If the address string is a
167 single number it is read as port
168 number to listen on for both IPv4 and
171 <para>If the address string is a
172 string in the format v.w.x.y:z it is
173 read as IPv4 specifier for listening
174 on an address v.w.x.y on a port
177 <para>If the address string is a
178 string in the format [x]:y it is read
179 as IPv6 address x on a port y.</para>
181 <para>Note that SOCK_SEQPACKET
182 (i.e. <varname>ListenSequentialPacket=</varname>)
183 is only available for AF_UNIX
185 (i.e. <varname>ListenStream=</varname>)
186 when used for IP sockets refers to TCP
188 (i.e. <varname>ListenDatagram=</varname>)
191 <para>These options may be specified
192 more than once in which case incoming
193 traffic on any of the sockets will trigger
194 service activation, and all listed
195 sockets will be passed to the service,
196 regardless whether there is incoming
197 traffic on them or not.</para>
199 <para>If an IP address is used here, it
200 is often desirable to listen on it
201 before the interface it is configured
202 on is up and running, and even
203 regardless whether it will be up and
204 running ever at all. To deal with this it is
205 recommended to set the
206 <varname>FreeBind=</varname> option
207 described below.</para></listitem>
211 <term><varname>ListenFIFO=</varname></term>
212 <listitem><para>Specifies a file
213 system FIFO to listen on. This expects
214 an absolute file system path as
215 argument. Behaviour otherwise is very
217 <varname>ListenDatagram=</varname>
218 directive above.</para></listitem>
222 <term><varname>ListenNetlink=</varname></term>
223 <listitem><para>Specifies a Netlink
224 family to create a socket for to
225 listen on. This expects a short string
226 referring to the AF_NETLINK family
227 name (such as <varname>audit</varname>
228 or <varname>kobject-uevent</varname>)
229 as argument, optionally suffixed by a
230 whitespace followed by a multicast
231 group integer. Behaviour otherwise is
233 <varname>ListenDatagram=</varname>
234 directive above.</para></listitem>
238 <term><varname>BindIPv6Only=</varname></term>
239 <listitem><para>Takes a one of
240 <option>default</option>,
241 <option>both</option> or
242 <option>ipv6-only</option>. Controls
243 the IPV6_V6ONLY socket option (see
244 <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
246 <option>both</option>, IPv6 sockets
247 bound will be accessible via both IPv4
249 <option>ipv6-only</option>, they will
250 be accessible via IPv6 only. If
251 <option>default</option> (which is the
252 default, surprise!) the system wide
253 default setting is used, as controlled
255 <filename>/proc/sys/net/ipv6/bindv6only</filename>.</para>
260 <term><varname>Backlog=</varname></term>
261 <listitem><para>Takes an unsigned
262 integer argument. Specifies the number
263 of connections to queue that have not
264 been accepted yet. This setting
265 matters only for stream and sequential
267 <citerefentry><refentrytitle>listen</refentrytitle><manvolnum>2</manvolnum></citerefentry>
268 for details. Defaults to SOMAXCONN
269 (128).</para></listitem>
273 <term><varname>BindToDevice=</varname></term>
274 <listitem><para>Specifies a network
275 interface name to bind this socket
276 to. If set traffic will only be
277 accepted from the specified network
278 interfaces. This controls the
279 SO_BINDTODEVICE socket option (see
280 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
281 for details). If this option is used,
282 an automatic dependency from this
283 socket unit on the network interface
285 (<citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
286 is created.</para></listitem>
290 <term><varname>DirectoryMode=</varname></term>
291 <listitem><para>If listening on a file
292 system socket of FIFO, the parent
293 directories are automatically created
294 if needed. This option specifies the
295 file system access mode used when
296 creating these directories. Takes an
298 notation. Defaults to
299 0755.</para></listitem>
303 <term><varname>SocketMode=</varname></term>
304 <listitem><para>If listening on a file
305 system socket of FIFO, this option
306 specifies the file system access mode
307 used when creating the file
308 node. Takes an access mode in octal
309 notation. Defaults to
310 0666.</para></listitem>
314 <term><varname>Accept=</varname></term>
315 <listitem><para>Takes a boolean
316 argument. If true, a service instance
317 is spawned for each incoming
318 connection and only the connection
319 socket is passed to it. If false, all
320 listening sockets themselves are
321 passed to the started service unit,
322 and only one service unit is spawned
323 for all connections (also see
324 above). This value is ignored for
325 datagram sockets and FIFOs where
326 a single service unit unconditionally
327 handles all incoming traffic. Defaults
328 to <option>false</option>. For
329 performance reasons, it is recommended
330 to write new daemons only in a way
332 <option>Accept=false</option>. This
333 option is mostly useful to allow
334 daemons designed for usage with
335 <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
336 to work unmodified with systemd socket
337 activation.</para></listitem>
341 <term><varname>MaxConnections=</varname></term>
342 <listitem><para>The maximum number of
343 connections to simultaneously run
344 services instances for, when
345 <option>Accept=true</option> is
346 set. If more concurrent connections
347 are coming in, they will be refused
348 until at least one existing connection
349 is terminated. This setting has no
350 effect for sockets configured with
351 <option>Accept=no</option> or datagram
353 64.</para></listitem>
357 <term><varname>KeepAlive=</varname></term>
358 <listitem><para>Takes a boolean
359 argument. If true, the TCP/IP stack
360 will send a keep alive message after
361 2h (depending on the configuration of
362 <filename>/proc/sys/net/ipv4/tcp_keepalive_time</filename>)
363 for all TCP streams accepted on this
364 socket. This controls the SO_KEEPALIVE
366 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
368 url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
369 Keepalive HOWTO</ulink> for details.)
371 <option>false</option>.</para></listitem>
375 <term><varname>Priority=</varname></term>
376 <listitem><para>Takes an integer
377 argument controlling the priority for
378 all traffic sent from this
379 socket. This controls the SO_PRIORITY
381 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
382 for details.).</para></listitem>
386 <term><varname>ReceiveBuffer=</varname></term>
387 <term><varname>SendBuffer=</varname></term>
388 <listitem><para>Takes an integer
389 argument controlling the receive
390 resp. send buffer sizes of this
391 socket. This controls the SO_RCVBUF
392 resp. SO_SNDBUF socket options (see
393 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
394 for details.).</para></listitem>
398 <term><varname>IPTOS=</varname></term>
399 <listitem><para>Takes an integer
400 argument controlling the IP
401 Type-Of-Service field for packets
402 generated from this socket. This
403 controls the IP_TOS socket option (see
404 <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
405 for details.). Either a numeric string
406 or one of <option>low-delay</option>,
407 <option>throughput</option>,
408 <option>reliability</option> or
409 <option>low-cost</option> may be
410 specified.</para></listitem>
414 <term><varname>IPTTL=</varname></term>
415 <listitem><para>Takes an integer
416 argument controlling the IPv4
417 Time-To-Live/IPv6 Hop-Count field for
418 packets generated from this
419 socket. This sets the
420 IP_TTL/IPV6_UNICAST_HOPS socket
422 <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
424 <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
425 for details.)</para></listitem>
429 <term><varname>Mark=</varname></term>
430 <listitem><para>Takes an integer
431 value. Controls the firewall mark of
432 packets generated by this socket. This
433 can be used in the firewall logic to
434 filter packets from this socket. This
435 sets the SO_MARK socket option. See
436 <citerefentry><refentrytitle>iptables</refentrytitle><manvolnum>8</manvolnum></citerefentry>
437 for details.</para></listitem>
441 <term><varname>PipeSize=</varname></term>
442 <listitem><para>Takes an integer
443 value. Controls the pipe buffer size
444 of FIFOs configured in this socket
446 <citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
447 for details.</para></listitem>
451 <term><varname>FreeBind=</varname></term>
452 <listitem><para>Takes a boolean
453 value. Controls whether the socket can
454 be bound to non-local IP
455 addresses. This is useful to configure
456 sockets listening on specific IP
457 addresses before those IP addresses
458 are successfully configured on a
459 network interface. This sets the
460 IP_FREEBIND socket option. For
461 robustness reasons it is recommended
462 to use this option whenever you bind a
463 socket to a specific IP
464 address. Defaults to <option>false</option>.</para></listitem>
468 <term><varname>TCPCongestion=</varname></term>
469 <listitem><para>Takes a string
470 value. Controls the TCP congestion
471 algorithm used by this socket. Should
472 be one of "westwood", "veno", "cubic",
473 "lp" or any other available algorithm
474 supported by the IP stack. This
475 setting applies only to stream
476 sockets.</para></listitem>
480 <term><varname>ExecStartPre=</varname></term>
481 <term><varname>ExecStartPost=</varname></term>
482 <listitem><para>Takes one or more
483 command lines, which are executed
484 before (resp. after) the listening
485 sockets/FIFOs are created and
486 bound. The first token of the command
487 line must be an absolute file name,
488 then followed by arguments for the
489 process. Multiple command lines may be
490 specified following the same scheme as
492 <varname>ExecStartPre=</varname> of
493 service unit files.</para></listitem>
497 <term><varname>ExecStopPre=</varname></term>
498 <term><varname>ExecStopPost=</varname></term>
499 <listitem><para>Additional commands
500 that are executed before (resp. after)
501 the listening sockets/FIFOs are closed
502 and removed. Multiple command lines
503 may be specified following the same
505 <varname>ExecStartPre=</varname> of
506 service unit files.</para></listitem>
510 <term><varname>TimeoutSec=</varname></term>
511 <listitem><para>Configures the time to
512 wait for the commands specified in
513 <varname>ExecStartPre=</varname>,
514 <varname>ExecStartPost=</varname>,
515 <varname>ExecStopPre=</varname> and
516 <varname>ExecStopPost=</varname> to
517 finish. If a command does not exit
518 within the configured time, the socket
519 will be considered failed and be shut
520 down again. All commands still running,
521 will be terminated forcibly via
522 SIGTERM, and after another delay of
523 this time with SIGKILL. (See
524 <option>KillMode=</option> below.)
525 Takes a unit-less value in seconds, or
526 a time span value such as "5min
527 20s". Pass 0 to disable the timeout
529 60s.</para></listitem>
533 <term><varname>KillMode=</varname></term>
534 <listitem><para>Specifies how
535 processes of this socket unit shall be
537 <option>control-group</option>,
538 <option>process</option>,
539 <option>none</option>.</para>
541 <para>This option is mostly equivalent
542 to the <option>KillMode=</option>
543 option of service files. See
544 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
545 for details.</para></listitem>
549 <term><varname>KillSignal=</varname></term>
550 <listitem><para>Specifies which signal
551 to use when killing a process of this
552 socket. Defaults to SIGTERM.
557 <term><varname>SendSIGKILL=</varname></term>
558 <listitem><para>Specifies whether to
559 send SIGKILL to remaining processes
560 after a timeout, if the normal
561 shutdown procedure left processes of
562 the socket around. Takes a boolean
563 value. Defaults to "yes".
568 <term><varname>Service=</varname></term>
569 <listitem><para>Specifies the service
570 unit name to activate on incoming
571 traffic. This defaults to the service
572 that bears the same name as the socket
573 (ignoring the different suffixes). In
574 most cases it should not be necessary
575 to use this option.</para></listitem>
582 <title>See Also</title>
584 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
585 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
586 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
587 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
588 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>