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 Lesser General Public License as published by
13 the Free Software Foundation; either version 2.1 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 Lesser General Public License for more details.
21 You should have received a copy of the GNU Lesser 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>Socket unit configuration</refpurpose>
51 <para><filename><replaceable>socket</replaceable>.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>ExecStopPost=</option> commands are executed
80 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
81 which define the way the processes are
84 <para>For each socket file a matching service file
86 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
87 for details) must exist, describing the service to
88 start on incoming traffic on the socket. Depending on
89 the setting of <option>Accept=</option> (see below),
90 this must either be named like the socket unit, but
91 with the suffix replaced; or it must be a template
92 file named the same way. Example: a socket file
93 <filename>foo.socket</filename> needs a matching
94 service <filename>foo.service</filename> if
95 <option>Accept=false</option> is set. If
96 <option>Accept=true</option> is set a service template
97 file <filename>foo@.service</filename> must exist from
98 which services are instantiated for each incoming
101 <para>Unless <varname>DefaultDependencies=</varname>
102 is set to <option>false</option>, socket units will
103 implicitly have dependencies of type
104 <varname>Requires=</varname> and
105 <varname>After=</varname> on
106 <filename>sysinit.target</filename> as well as
107 dependencies of type <varname>Conflicts=</varname> and
108 <varname>Before=</varname> on
109 <filename>shutdown.target</filename>. These ensure
110 that socket units pull in basic system
111 initialization, and are terminated cleanly prior to
112 system shutdown. Only sockets involved with early
113 boot or late system shutdown should disable this
116 <para>Socket units may be used to implement on-demand
117 starting of services, as well as parallelized starting
120 <para>Note that the daemon software configured for
121 socket activation with socket units needs to be able
122 to accept sockets from systemd, either via systemd's
123 native socket passing interface (see
124 <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
125 for details) or via the traditional
126 <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>-style
127 socket passing (i.e. sockets passed in via STDIN and
128 STDOUT, using <varname>StandardInput=socket</varname>
129 in the service file).</para>
133 <title>Options</title>
135 <para>Socket files must include a [Socket] section,
136 which carries information about the socket or FIFO it
137 supervises. A number of options that may be used in
138 this section are shared with other unit types. These
139 options are documented in
140 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
142 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
143 options specific to the [Socket] section of socket
144 units are the following:</para>
146 <variablelist class='unit-directives'>
148 <term><varname>ListenStream=</varname></term>
149 <term><varname>ListenDatagram=</varname></term>
150 <term><varname>ListenSequentialPacket=</varname></term>
151 <listitem><para>Specifies an address
152 to listen on for a stream
153 (<constant>SOCK_STREAM</constant>), datagram (<constant>SOCK_DGRAM</constant>),
155 (<constant>SOCK_SEQPACKET</constant>) socket, respectively. The address
156 can be written in various formats:</para>
158 <para>If the address starts with a
159 slash (/), it is read as file system
160 socket in the <constant>AF_UNIX</constant> socket
163 <para>If the address starts with an
164 at symbol (@) it is read as abstract
165 namespace socket in the <constant>AF_UNIX</constant>
166 family. The @ is replaced with a NUL
167 character before binding. For details
169 <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
171 <para>If the address string is a
172 single number it is read as port
173 number to listen on via
174 IPv6. Depending on the value of
175 <varname>BindIPv6Only=</varname> (see below) this
176 might result in the service being
177 available via both IPv6 and IPv4 (default) or
181 <para>If the address string is a
182 string in the format v.w.x.y:z it is
183 read as IPv4 specifier for listening
184 on an address v.w.x.y on a port
187 <para>If the address string is a
188 string in the format [x]:y it is read
189 as IPv6 address x on a port y. Note
190 that this might make the service
191 available via IPv4, too, depending on
192 the <varname>BindIPv6Only=</varname>
196 <para>Note that <constant>SOCK_SEQPACKET</constant>
197 (i.e. <varname>ListenSequentialPacket=</varname>)
198 is only available for <constant>AF_UNIX</constant>
199 sockets. <constant>SOCK_STREAM</constant>
200 (i.e. <varname>ListenStream=</varname>)
201 when used for IP sockets refers to TCP
202 sockets, <constant>SOCK_DGRAM</constant>
203 (i.e. <varname>ListenDatagram=</varname>)
206 <para>These options may be specified
207 more than once in which case incoming
208 traffic on any of the sockets will
209 trigger service activation, and all
210 listed sockets will be passed to the
211 service, regardless whether there is
212 incoming traffic on them or not. If
213 the empty string is assigned to any of
214 these options, the list of addresses
215 to listen on is reset, all prior uses
216 of any of these options will have no
219 <para>If an IP address is used here,
220 it is often desirable to listen on it
221 before the interface it is configured
222 on is up and running, and even
223 regardless whether it will be up and
224 running ever at all. To deal with this
225 it is recommended to set the
226 <varname>FreeBind=</varname> option
227 described below.</para></listitem>
231 <term><varname>ListenFIFO=</varname></term>
232 <listitem><para>Specifies a file
233 system FIFO to listen on. This expects
234 an absolute file system path as
235 argument. Behavior otherwise is very
237 <varname>ListenDatagram=</varname>
238 directive above.</para></listitem>
242 <term><varname>ListenSpecial=</varname></term>
243 <listitem><para>Specifies a special
244 file in the file system to listen
245 on. This expects an absolute file
246 system path as argument. Behavior
247 otherwise is very similar to the
248 <varname>ListenFIFO=</varname>
249 directive above. Use this to open
250 character device nodes as well as
252 <filename>/proc</filename> and
253 <filename>/sys</filename>.</para></listitem>
257 <term><varname>ListenNetlink=</varname></term>
258 <listitem><para>Specifies a Netlink
259 family to create a socket for to
260 listen on. This expects a short string
261 referring to the <constant>AF_NETLINK</constant> family
262 name (such as <varname>audit</varname>
263 or <varname>kobject-uevent</varname>)
264 as argument, optionally suffixed by a
265 whitespace followed by a multicast
266 group integer. Behavior otherwise is
268 <varname>ListenDatagram=</varname>
269 directive above.</para></listitem>
273 <term><varname>ListenMessageQueue=</varname></term>
274 <listitem><para>Specifies a POSIX
275 message queue name to listen on. This
276 expects a valid message queue name
277 (i.e. beginning with /). Behavior
278 otherwise is very similar to the
279 <varname>ListenFIFO=</varname>
280 directive above. On Linux message
281 queue descriptors are actually file
282 descriptors and can be inherited
283 between processes.</para></listitem>
287 <term><varname>BindIPv6Only=</varname></term>
288 <listitem><para>Takes a one of
289 <option>default</option>,
290 <option>both</option> or
291 <option>ipv6-only</option>. Controls
292 the IPV6_V6ONLY socket option (see
293 <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
295 <option>both</option>, IPv6 sockets
296 bound will be accessible via both IPv4
298 <option>ipv6-only</option>, they will
299 be accessible via IPv6 only. If
300 <option>default</option> (which is the
301 default, surprise!) the system wide
302 default setting is used, as controlled
304 <filename>/proc/sys/net/ipv6/bindv6only</filename>,
305 which in turn defaults to the
307 <option>both</option>.</para>
312 <term><varname>Backlog=</varname></term>
313 <listitem><para>Takes an unsigned
314 integer argument. Specifies the number
315 of connections to queue that have not
316 been accepted yet. This setting
317 matters only for stream and sequential
319 <citerefentry><refentrytitle>listen</refentrytitle><manvolnum>2</manvolnum></citerefentry>
320 for details. Defaults to SOMAXCONN
321 (128).</para></listitem>
325 <term><varname>BindToDevice=</varname></term>
326 <listitem><para>Specifies a network
327 interface name to bind this socket
328 to. If set traffic will only be
329 accepted from the specified network
330 interfaces. This controls the
331 SO_BINDTODEVICE socket option (see
332 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
333 for details). If this option is used,
334 an automatic dependency from this
335 socket unit on the network interface
337 (<citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
338 is created.</para></listitem>
342 <term><varname>DirectoryMode=</varname></term>
343 <listitem><para>If listening on a file
344 system socket or FIFO, the parent
345 directories are automatically created
346 if needed. This option specifies the
347 file system access mode used when
348 creating these directories. Takes an
350 notation. Defaults to
351 0755.</para></listitem>
355 <term><varname>SocketMode=</varname></term>
356 <listitem><para>If listening on a file
357 system socket or FIFO, this option
358 specifies the file system access mode
359 used when creating the file
360 node. Takes an access mode in octal
361 notation. Defaults to
362 0666.</para></listitem>
366 <term><varname>Accept=</varname></term>
367 <listitem><para>Takes a boolean
368 argument. If true, a service instance
369 is spawned for each incoming
370 connection and only the connection
371 socket is passed to it. If false, all
372 listening sockets themselves are
373 passed to the started service unit,
374 and only one service unit is spawned
375 for all connections (also see
376 above). This value is ignored for
377 datagram sockets and FIFOs where a
378 single service unit unconditionally
379 handles all incoming traffic. Defaults
380 to <option>false</option>. For
381 performance reasons, it is recommended
382 to write new daemons only in a way
384 <option>Accept=false</option>. A
385 daemon listening on an <constant>AF_UNIX</constant> socket
386 may, but does not need to, call
387 <citerefentry><refentrytitle>close</refentrytitle><manvolnum>2</manvolnum></citerefentry>
388 on the received socket before
389 exiting. However, it must not unlink
390 the socket from a filesystem. It
392 <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>2</manvolnum></citerefentry>
393 on sockets it got with
394 <varname>Accept=false</varname>, but
395 it may do so for sockets it got with
396 <varname>Accept=true</varname> set.
397 Setting <varname>Accept=true</varname>
398 is mostly useful to allow daemons
399 designed for usage with
400 <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
401 to work unmodified with systemd socket
402 activation.</para></listitem>
406 <term><varname>MaxConnections=</varname></term>
407 <listitem><para>The maximum number of
408 connections to simultaneously run
409 services instances for, when
410 <option>Accept=true</option> is
411 set. If more concurrent connections
412 are coming in, they will be refused
413 until at least one existing connection
414 is terminated. This setting has no
415 effect for sockets configured with
416 <option>Accept=false</option> or datagram
418 64.</para></listitem>
422 <term><varname>KeepAlive=</varname></term>
423 <listitem><para>Takes a boolean
424 argument. If true, the TCP/IP stack
425 will send a keep alive message after
426 2h (depending on the configuration of
427 <filename>/proc/sys/net/ipv4/tcp_keepalive_time</filename>)
428 for all TCP streams accepted on this
429 socket. This controls the SO_KEEPALIVE
431 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
433 url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
434 Keepalive HOWTO</ulink> for details.)
436 <option>false</option>.</para></listitem>
440 <term><varname>Priority=</varname></term>
441 <listitem><para>Takes an integer
442 argument controlling the priority for
443 all traffic sent from this
444 socket. This controls the SO_PRIORITY
446 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
447 for details.).</para></listitem>
451 <term><varname>ReceiveBuffer=</varname></term>
452 <term><varname>SendBuffer=</varname></term>
453 <listitem><para>Takes an integer
454 argument controlling the receive
455 or send buffer sizes of this
456 socket, respectively. This controls the SO_RCVBUF
457 and SO_SNDBUF socket options (see
458 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
459 for details.).</para></listitem>
463 <term><varname>IPTOS=</varname></term>
464 <listitem><para>Takes an integer
465 argument controlling the IP
466 Type-Of-Service field for packets
467 generated from this socket. This
468 controls the IP_TOS socket option (see
469 <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
470 for details.). Either a numeric string
471 or one of <option>low-delay</option>,
472 <option>throughput</option>,
473 <option>reliability</option> or
474 <option>low-cost</option> may be
475 specified.</para></listitem>
479 <term><varname>IPTTL=</varname></term>
480 <listitem><para>Takes an integer
481 argument controlling the IPv4
482 Time-To-Live/IPv6 Hop-Count field for
483 packets generated from this
484 socket. This sets the
485 IP_TTL/IPV6_UNICAST_HOPS socket
487 <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
489 <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
490 for details.)</para></listitem>
494 <term><varname>Mark=</varname></term>
495 <listitem><para>Takes an integer
496 value. Controls the firewall mark of
497 packets generated by this socket. This
498 can be used in the firewall logic to
499 filter packets from this socket. This
500 sets the SO_MARK socket option. See
501 <citerefentry><refentrytitle>iptables</refentrytitle><manvolnum>8</manvolnum></citerefentry>
502 for details.</para></listitem>
506 <term><varname>SmackLabel=</varname></term>
507 <term><varname>SmackLabelIPIn=</varname></term>
508 <term><varname>SmackLabelIPOut=</varname></term>
509 <listitem><para>Takes a string
510 value. Controls the extended
512 <literal>security.SMACK64</literal>,
513 <literal>security.SMACK64IPIN</literal>
515 <literal>security.SMACK64IPOUT</literal>,
516 respectively, i.e. the security label
517 of the FIFO, or the security label for
518 the incoming or outgoing connections
519 of the socket, respectively. See
521 url="https://www.kernel.org/doc/Documentation/security/Smack.txt">Smack.txt</ulink>
522 for details.</para></listitem>
526 <term><varname>PipeSize=</varname></term>
527 <listitem><para>Takes an integer
528 value. Controls the pipe buffer size
529 of FIFOs configured in this socket
531 <citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
532 for details.</para></listitem>
536 <term><varname>MessageQueueMaxMessages=</varname>,
537 <varname>MessageQueueMessageSize=</varname></term>
538 <listitem><para>These two settings
539 take integer values and control the
540 mq_maxmsg field or the mq_msgsize field, respectively, when
541 creating the message queue. Note that
542 either none or both of these variables
544 <citerefentry><refentrytitle>mq_setattr</refentrytitle><manvolnum>3</manvolnum></citerefentry>
545 for details.</para></listitem>
549 <term><varname>FreeBind=</varname></term>
550 <listitem><para>Takes a boolean
551 value. Controls whether the socket can
552 be bound to non-local IP
553 addresses. This is useful to configure
554 sockets listening on specific IP
555 addresses before those IP addresses
556 are successfully configured on a
557 network interface. This sets the
558 IP_FREEBIND socket option. For
559 robustness reasons it is recommended
560 to use this option whenever you bind a
561 socket to a specific IP
562 address. Defaults to <option>false</option>.</para></listitem>
566 <term><varname>Transparent=</varname></term>
567 <listitem><para>Takes a boolean
568 value. Controls the IP_TRANSPARENT
569 socket option. Defaults to
570 <option>false</option>.</para></listitem>
574 <term><varname>Broadcast=</varname></term>
575 <listitem><para>Takes a boolean
576 value. This controls the SO_BROADCAST
577 socket option, which allows broadcast
578 datagrams to be sent from this
580 <option>false</option>.</para></listitem>
584 <term><varname>PassCredentials=</varname></term>
585 <listitem><para>Takes a boolean
586 value. This controls the SO_PASSCRED
587 socket option, which allows <constant>AF_UNIX</constant> sockets to
588 receive the credentials of the sending
589 process in an ancillary message.
591 <option>false</option>.</para></listitem>
595 <term><varname>PassSecurity=</varname></term>
596 <listitem><para>Takes a boolean
597 value. This controls the SO_PASSSEC
598 socket option, which allows <constant>AF_UNIX</constant>
599 sockets to receive the security
600 context of the sending process in an
601 ancillary message. Defaults to
602 <option>false</option>.</para></listitem>
606 <term><varname>TCPCongestion=</varname></term>
607 <listitem><para>Takes a string
608 value. Controls the TCP congestion
609 algorithm used by this socket. Should
610 be one of "westwood", "veno", "cubic",
611 "lp" or any other available algorithm
612 supported by the IP stack. This
613 setting applies only to stream
614 sockets.</para></listitem>
618 <term><varname>ExecStartPre=</varname></term>
619 <term><varname>ExecStartPost=</varname></term>
620 <listitem><para>Takes one or more
621 command lines, which are executed
622 before or after the listening
623 sockets/FIFOs are created and
624 bound, respectively. The first token of the command
625 line must be an absolute file name,
626 then followed by arguments for the
627 process. Multiple command lines may be
628 specified following the same scheme as
630 <varname>ExecStartPre=</varname> of
631 service unit files.</para></listitem>
635 <term><varname>ExecStopPre=</varname></term>
636 <term><varname>ExecStopPost=</varname></term>
637 <listitem><para>Additional commands
638 that are executed before or after
639 the listening sockets/FIFOs are closed
640 and removed, respectively. Multiple command lines
641 may be specified following the same
643 <varname>ExecStartPre=</varname> of
644 service unit files.</para></listitem>
648 <term><varname>TimeoutSec=</varname></term>
649 <listitem><para>Configures the time to
650 wait for the commands specified in
651 <varname>ExecStartPre=</varname>,
652 <varname>ExecStartPost=</varname>,
653 <varname>ExecStopPre=</varname> and
654 <varname>ExecStopPost=</varname> to
655 finish. If a command does not exit
656 within the configured time, the socket
657 will be considered failed and be shut
658 down again. All commands still running,
659 will be terminated forcibly via
660 SIGTERM, and after another delay of
661 this time with SIGKILL. (See
662 <option>KillMode=</option> in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
663 Takes a unit-less value in seconds, or
664 a time span value such as "5min
665 20s". Pass 0 to disable the timeout
667 90s.</para></listitem>
671 <term><varname>Service=</varname></term>
672 <listitem><para>Specifies the service
673 unit name to activate on incoming
674 traffic. This defaults to the service
675 that bears the same name as the socket
676 (ignoring the different suffixes). In
677 most cases it should not be necessary
678 to use this option.</para></listitem>
684 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
686 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
687 for more settings.</para>
692 <title>See Also</title>
694 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
695 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
696 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
697 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
698 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
699 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
700 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
704 For more extensive descriptions see the "Systemd for Developers" series:
705 <ulink url="http://0pointer.de/blog/projects/socket-activation.html">Socket Activation</ulink>,
706 <ulink url="http://0pointer.de/blog/projects/socket-activation2.html">Socket Activation, part II</ulink>,
707 <ulink url="http://0pointer.de/blog/projects/inetd.html">Converting inetd Services</ulink>,
708 <ulink url="http://0pointer.de/blog/projects/socket-activated-containers.html">Socket Activated Internet Services and OS Containers</ulink>.