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>ListenSpecial=</varname></term>
223 <listitem><para>Specifies a special
224 file in the file system to listen
225 on. This expects an absolute file
226 system path as argument. Behaviour
227 otherwise is very similar to the
228 <varname>ListenFIFO=</varname>
229 directive above. Use this to open
230 character device nodes as well as
232 <filename>/proc</filename> and
233 <filename>/sys</filename>.</para></listitem>
237 <term><varname>ListenNetlink=</varname></term>
238 <listitem><para>Specifies a Netlink
239 family to create a socket for to
240 listen on. This expects a short string
241 referring to the AF_NETLINK family
242 name (such as <varname>audit</varname>
243 or <varname>kobject-uevent</varname>)
244 as argument, optionally suffixed by a
245 whitespace followed by a multicast
246 group integer. Behaviour otherwise is
248 <varname>ListenDatagram=</varname>
249 directive above.</para></listitem>
253 <term><varname>BindIPv6Only=</varname></term>
254 <listitem><para>Takes a one of
255 <option>default</option>,
256 <option>both</option> or
257 <option>ipv6-only</option>. Controls
258 the IPV6_V6ONLY socket option (see
259 <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
261 <option>both</option>, IPv6 sockets
262 bound will be accessible via both IPv4
264 <option>ipv6-only</option>, they will
265 be accessible via IPv6 only. If
266 <option>default</option> (which is the
267 default, surprise!) the system wide
268 default setting is used, as controlled
270 <filename>/proc/sys/net/ipv6/bindv6only</filename>.</para>
275 <term><varname>Backlog=</varname></term>
276 <listitem><para>Takes an unsigned
277 integer argument. Specifies the number
278 of connections to queue that have not
279 been accepted yet. This setting
280 matters only for stream and sequential
282 <citerefentry><refentrytitle>listen</refentrytitle><manvolnum>2</manvolnum></citerefentry>
283 for details. Defaults to SOMAXCONN
284 (128).</para></listitem>
288 <term><varname>BindToDevice=</varname></term>
289 <listitem><para>Specifies a network
290 interface name to bind this socket
291 to. If set traffic will only be
292 accepted from the specified network
293 interfaces. This controls the
294 SO_BINDTODEVICE socket option (see
295 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
296 for details). If this option is used,
297 an automatic dependency from this
298 socket unit on the network interface
300 (<citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
301 is created.</para></listitem>
305 <term><varname>DirectoryMode=</varname></term>
306 <listitem><para>If listening on a file
307 system socket of FIFO, the parent
308 directories are automatically created
309 if needed. This option specifies the
310 file system access mode used when
311 creating these directories. Takes an
313 notation. Defaults to
314 0755.</para></listitem>
318 <term><varname>SocketMode=</varname></term>
319 <listitem><para>If listening on a file
320 system socket of FIFO, this option
321 specifies the file system access mode
322 used when creating the file
323 node. Takes an access mode in octal
324 notation. Defaults to
325 0666.</para></listitem>
329 <term><varname>Accept=</varname></term>
330 <listitem><para>Takes a boolean
331 argument. If true, a service instance
332 is spawned for each incoming
333 connection and only the connection
334 socket is passed to it. If false, all
335 listening sockets themselves are
336 passed to the started service unit,
337 and only one service unit is spawned
338 for all connections (also see
339 above). This value is ignored for
340 datagram sockets and FIFOs where
341 a single service unit unconditionally
342 handles all incoming traffic. Defaults
343 to <option>false</option>. For
344 performance reasons, it is recommended
345 to write new daemons only in a way
347 <option>Accept=false</option>. This
348 option is mostly useful to allow
349 daemons designed for usage with
350 <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
351 to work unmodified with systemd socket
352 activation.</para></listitem>
356 <term><varname>MaxConnections=</varname></term>
357 <listitem><para>The maximum number of
358 connections to simultaneously run
359 services instances for, when
360 <option>Accept=true</option> is
361 set. If more concurrent connections
362 are coming in, they will be refused
363 until at least one existing connection
364 is terminated. This setting has no
365 effect for sockets configured with
366 <option>Accept=no</option> or datagram
368 64.</para></listitem>
372 <term><varname>KeepAlive=</varname></term>
373 <listitem><para>Takes a boolean
374 argument. If true, the TCP/IP stack
375 will send a keep alive message after
376 2h (depending on the configuration of
377 <filename>/proc/sys/net/ipv4/tcp_keepalive_time</filename>)
378 for all TCP streams accepted on this
379 socket. This controls the SO_KEEPALIVE
381 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
383 url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
384 Keepalive HOWTO</ulink> for details.)
386 <option>false</option>.</para></listitem>
390 <term><varname>Priority=</varname></term>
391 <listitem><para>Takes an integer
392 argument controlling the priority for
393 all traffic sent from this
394 socket. This controls the SO_PRIORITY
396 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
397 for details.).</para></listitem>
401 <term><varname>ReceiveBuffer=</varname></term>
402 <term><varname>SendBuffer=</varname></term>
403 <listitem><para>Takes an integer
404 argument controlling the receive
405 resp. send buffer sizes of this
406 socket. This controls the SO_RCVBUF
407 resp. SO_SNDBUF socket options (see
408 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
409 for details.).</para></listitem>
413 <term><varname>IPTOS=</varname></term>
414 <listitem><para>Takes an integer
415 argument controlling the IP
416 Type-Of-Service field for packets
417 generated from this socket. This
418 controls the IP_TOS socket option (see
419 <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
420 for details.). Either a numeric string
421 or one of <option>low-delay</option>,
422 <option>throughput</option>,
423 <option>reliability</option> or
424 <option>low-cost</option> may be
425 specified.</para></listitem>
429 <term><varname>IPTTL=</varname></term>
430 <listitem><para>Takes an integer
431 argument controlling the IPv4
432 Time-To-Live/IPv6 Hop-Count field for
433 packets generated from this
434 socket. This sets the
435 IP_TTL/IPV6_UNICAST_HOPS socket
437 <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
439 <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
440 for details.)</para></listitem>
444 <term><varname>Mark=</varname></term>
445 <listitem><para>Takes an integer
446 value. Controls the firewall mark of
447 packets generated by this socket. This
448 can be used in the firewall logic to
449 filter packets from this socket. This
450 sets the SO_MARK socket option. See
451 <citerefentry><refentrytitle>iptables</refentrytitle><manvolnum>8</manvolnum></citerefentry>
452 for details.</para></listitem>
456 <term><varname>PipeSize=</varname></term>
457 <listitem><para>Takes an integer
458 value. Controls the pipe buffer size
459 of FIFOs configured in this socket
461 <citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
462 for details.</para></listitem>
466 <term><varname>FreeBind=</varname></term>
467 <listitem><para>Takes a boolean
468 value. Controls whether the socket can
469 be bound to non-local IP
470 addresses. This is useful to configure
471 sockets listening on specific IP
472 addresses before those IP addresses
473 are successfully configured on a
474 network interface. This sets the
475 IP_FREEBIND socket option. For
476 robustness reasons it is recommended
477 to use this option whenever you bind a
478 socket to a specific IP
479 address. Defaults to <option>false</option>.</para></listitem>
483 <term><varname>TCPCongestion=</varname></term>
484 <listitem><para>Takes a string
485 value. Controls the TCP congestion
486 algorithm used by this socket. Should
487 be one of "westwood", "veno", "cubic",
488 "lp" or any other available algorithm
489 supported by the IP stack. This
490 setting applies only to stream
491 sockets.</para></listitem>
495 <term><varname>ExecStartPre=</varname></term>
496 <term><varname>ExecStartPost=</varname></term>
497 <listitem><para>Takes one or more
498 command lines, which are executed
499 before (resp. after) the listening
500 sockets/FIFOs are created and
501 bound. The first token of the command
502 line must be an absolute file name,
503 then followed by arguments for the
504 process. Multiple command lines may be
505 specified following the same scheme as
507 <varname>ExecStartPre=</varname> of
508 service unit files.</para></listitem>
512 <term><varname>ExecStopPre=</varname></term>
513 <term><varname>ExecStopPost=</varname></term>
514 <listitem><para>Additional commands
515 that are executed before (resp. after)
516 the listening sockets/FIFOs are closed
517 and removed. Multiple command lines
518 may be specified following the same
520 <varname>ExecStartPre=</varname> of
521 service unit files.</para></listitem>
525 <term><varname>TimeoutSec=</varname></term>
526 <listitem><para>Configures the time to
527 wait for the commands specified in
528 <varname>ExecStartPre=</varname>,
529 <varname>ExecStartPost=</varname>,
530 <varname>ExecStopPre=</varname> and
531 <varname>ExecStopPost=</varname> to
532 finish. If a command does not exit
533 within the configured time, the socket
534 will be considered failed and be shut
535 down again. All commands still running,
536 will be terminated forcibly via
537 SIGTERM, and after another delay of
538 this time with SIGKILL. (See
539 <option>KillMode=</option> below.)
540 Takes a unit-less value in seconds, or
541 a time span value such as "5min
542 20s". Pass 0 to disable the timeout
544 90s.</para></listitem>
548 <term><varname>KillMode=</varname></term>
549 <listitem><para>Specifies how
550 processes of this socket unit shall be
552 <option>control-group</option>,
553 <option>process</option>,
554 <option>none</option>.</para>
556 <para>This option is mostly equivalent
557 to the <option>KillMode=</option>
558 option of service files. See
559 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
560 for details.</para></listitem>
564 <term><varname>KillSignal=</varname></term>
565 <listitem><para>Specifies which signal
566 to use when killing a process of this
567 socket. Defaults to SIGTERM.
572 <term><varname>SendSIGKILL=</varname></term>
573 <listitem><para>Specifies whether to
574 send SIGKILL to remaining processes
575 after a timeout, if the normal
576 shutdown procedure left processes of
577 the socket around. Takes a boolean
578 value. Defaults to "yes".
583 <term><varname>Service=</varname></term>
584 <listitem><para>Specifies the service
585 unit name to activate on incoming
586 traffic. This defaults to the service
587 that bears the same name as the socket
588 (ignoring the different suffixes). In
589 most cases it should not be necessary
590 to use this option.</para></listitem>
597 <title>See Also</title>
599 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
600 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
601 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
602 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
603 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>