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 <literal>.socket</literal> 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 (<literal>/</literal>), it is read as file system
160 socket in the <constant>AF_UNIX</constant> socket
163 <para>If the address starts with an at
164 symbol (<literal>@</literal>) it is read as abstract
165 namespace socket in the
166 <constant>AF_UNIX</constant>
167 family. The <literal>@</literal> is
169 <constant>NUL</constant> character
170 before binding. For details see
171 <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
173 <para>If the address string is a
174 single number it is read as port
175 number to listen on via
176 IPv6. Depending on the value of
177 <varname>BindIPv6Only=</varname> (see below) this
178 might result in the service being
179 available via both IPv6 and IPv4 (default) or
183 <para>If the address string is a
184 string in the format v.w.x.y:z it is
185 read as IPv4 specifier for listening
186 on an address v.w.x.y on a port
189 <para>If the address string is a
190 string in the format [x]:y it is read
191 as IPv6 address x on a port y. Note
192 that this might make the service
193 available via IPv4, too, depending on
194 the <varname>BindIPv6Only=</varname>
198 <para>Note that <constant>SOCK_SEQPACKET</constant>
199 (i.e. <varname>ListenSequentialPacket=</varname>)
200 is only available for <constant>AF_UNIX</constant>
201 sockets. <constant>SOCK_STREAM</constant>
202 (i.e. <varname>ListenStream=</varname>)
203 when used for IP sockets refers to TCP
204 sockets, <constant>SOCK_DGRAM</constant>
205 (i.e. <varname>ListenDatagram=</varname>)
208 <para>These options may be specified
209 more than once in which case incoming
210 traffic on any of the sockets will
211 trigger service activation, and all
212 listed sockets will be passed to the
213 service, regardless whether there is
214 incoming traffic on them or not. If
215 the empty string is assigned to any of
216 these options, the list of addresses
217 to listen on is reset, all prior uses
218 of any of these options will have no
221 <para>If an IP address is used here,
222 it is often desirable to listen on it
223 before the interface it is configured
224 on is up and running, and even
225 regardless whether it will be up and
226 running ever at all. To deal with this
227 it is recommended to set the
228 <varname>FreeBind=</varname> option
229 described below.</para></listitem>
233 <term><varname>ListenFIFO=</varname></term>
234 <listitem><para>Specifies a file
235 system FIFO to listen on. This expects
236 an absolute file system path as
237 argument. Behavior otherwise is very
239 <varname>ListenDatagram=</varname>
240 directive above.</para></listitem>
244 <term><varname>ListenSpecial=</varname></term>
245 <listitem><para>Specifies a special
246 file in the file system to listen
247 on. This expects an absolute file
248 system path as argument. Behavior
249 otherwise is very similar to the
250 <varname>ListenFIFO=</varname>
251 directive above. Use this to open
252 character device nodes as well as
254 <filename>/proc</filename> and
255 <filename>/sys</filename>.</para></listitem>
259 <term><varname>ListenNetlink=</varname></term>
260 <listitem><para>Specifies a Netlink
261 family to create a socket for to
262 listen on. This expects a short string
263 referring to the <constant>AF_NETLINK</constant> family
264 name (such as <varname>audit</varname>
265 or <varname>kobject-uevent</varname>)
266 as argument, optionally suffixed by a
267 whitespace followed by a multicast
268 group integer. Behavior otherwise is
270 <varname>ListenDatagram=</varname>
271 directive above.</para></listitem>
275 <term><varname>ListenMessageQueue=</varname></term>
276 <listitem><para>Specifies a POSIX
277 message queue name to listen on. This
278 expects a valid message queue name
279 (i.e. beginning with /). Behavior
280 otherwise is very similar to the
281 <varname>ListenFIFO=</varname>
282 directive above. On Linux message
283 queue descriptors are actually file
284 descriptors and can be inherited
285 between processes.</para></listitem>
289 <term><varname>BindIPv6Only=</varname></term>
290 <listitem><para>Takes a one of
291 <option>default</option>,
292 <option>both</option> or
293 <option>ipv6-only</option>. Controls
294 the IPV6_V6ONLY socket option (see
295 <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
297 <option>both</option>, IPv6 sockets
298 bound will be accessible via both IPv4
300 <option>ipv6-only</option>, they will
301 be accessible via IPv6 only. If
302 <option>default</option> (which is the
303 default, surprise!) the system wide
304 default setting is used, as controlled
306 <filename>/proc/sys/net/ipv6/bindv6only</filename>,
307 which in turn defaults to the
309 <option>both</option>.</para>
314 <term><varname>Backlog=</varname></term>
315 <listitem><para>Takes an unsigned
316 integer argument. Specifies the number
317 of connections to queue that have not
318 been accepted yet. This setting
319 matters only for stream and sequential
321 <citerefentry><refentrytitle>listen</refentrytitle><manvolnum>2</manvolnum></citerefentry>
322 for details. Defaults to SOMAXCONN
323 (128).</para></listitem>
327 <term><varname>BindToDevice=</varname></term>
328 <listitem><para>Specifies a network
329 interface name to bind this socket
330 to. If set traffic will only be
331 accepted from the specified network
332 interfaces. This controls the
333 SO_BINDTODEVICE socket option (see
334 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
335 for details). If this option is used,
336 an automatic dependency from this
337 socket unit on the network interface
339 (<citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
340 is created.</para></listitem>
344 <term><varname>DirectoryMode=</varname></term>
345 <listitem><para>If listening on a file
346 system socket or FIFO, the parent
347 directories are automatically created
348 if needed. This option specifies the
349 file system access mode used when
350 creating these directories. Takes an
352 notation. Defaults to
353 0755.</para></listitem>
357 <term><varname>SocketMode=</varname></term>
358 <listitem><para>If listening on a file
359 system socket or FIFO, this option
360 specifies the file system access mode
361 used when creating the file
362 node. Takes an access mode in octal
363 notation. Defaults to
364 0666.</para></listitem>
368 <term><varname>Accept=</varname></term>
369 <listitem><para>Takes a boolean
370 argument. If true, a service instance
371 is spawned for each incoming
372 connection and only the connection
373 socket is passed to it. If false, all
374 listening sockets themselves are
375 passed to the started service unit,
376 and only one service unit is spawned
377 for all connections (also see
378 above). This value is ignored for
379 datagram sockets and FIFOs where a
380 single service unit unconditionally
381 handles all incoming traffic. Defaults
382 to <option>false</option>. For
383 performance reasons, it is recommended
384 to write new daemons only in a way
386 <option>Accept=false</option>. A
387 daemon listening on an <constant>AF_UNIX</constant> socket
388 may, but does not need to, call
389 <citerefentry><refentrytitle>close</refentrytitle><manvolnum>2</manvolnum></citerefentry>
390 on the received socket before
391 exiting. However, it must not unlink
392 the socket from a file system. It
394 <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>2</manvolnum></citerefentry>
395 on sockets it got with
396 <varname>Accept=false</varname>, but
397 it may do so for sockets it got with
398 <varname>Accept=true</varname> set.
399 Setting <varname>Accept=true</varname>
400 is mostly useful to allow daemons
401 designed for usage with
402 <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
403 to work unmodified with systemd socket
404 activation.</para></listitem>
408 <term><varname>MaxConnections=</varname></term>
409 <listitem><para>The maximum number of
410 connections to simultaneously run
411 services instances for, when
412 <option>Accept=true</option> is
413 set. If more concurrent connections
414 are coming in, they will be refused
415 until at least one existing connection
416 is terminated. This setting has no
417 effect on sockets configured with
418 <option>Accept=false</option> or datagram
420 64.</para></listitem>
424 <term><varname>KeepAlive=</varname></term>
425 <listitem><para>Takes a boolean
426 argument. If true, the TCP/IP stack
427 will send a keep alive message after
428 2h (depending on the configuration of
429 <filename>/proc/sys/net/ipv4/tcp_keepalive_time</filename>)
430 for all TCP streams accepted on this
431 socket. This controls the SO_KEEPALIVE
433 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
435 url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
436 Keepalive HOWTO</ulink> for details.)
438 <option>false</option>.</para></listitem>
442 <term><varname>Priority=</varname></term>
443 <listitem><para>Takes an integer
444 argument controlling the priority for
445 all traffic sent from this
446 socket. This controls the SO_PRIORITY
448 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
449 for details.).</para></listitem>
453 <term><varname>ReceiveBuffer=</varname></term>
454 <term><varname>SendBuffer=</varname></term>
455 <listitem><para>Takes an integer
456 argument controlling the receive
457 or send buffer sizes of this
458 socket, respectively. This controls the SO_RCVBUF
459 and SO_SNDBUF socket options (see
460 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
461 for details.).</para></listitem>
465 <term><varname>IPTOS=</varname></term>
466 <listitem><para>Takes an integer
467 argument controlling the IP
468 Type-Of-Service field for packets
469 generated from this socket. This
470 controls the IP_TOS socket option (see
471 <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
472 for details.). Either a numeric string
473 or one of <option>low-delay</option>,
474 <option>throughput</option>,
475 <option>reliability</option> or
476 <option>low-cost</option> may be
477 specified.</para></listitem>
481 <term><varname>IPTTL=</varname></term>
482 <listitem><para>Takes an integer
483 argument controlling the IPv4
484 Time-To-Live/IPv6 Hop-Count field for
485 packets generated from this
486 socket. This sets the
487 IP_TTL/IPV6_UNICAST_HOPS socket
489 <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
491 <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
492 for details.)</para></listitem>
496 <term><varname>Mark=</varname></term>
497 <listitem><para>Takes an integer
498 value. Controls the firewall mark of
499 packets generated by this socket. This
500 can be used in the firewall logic to
501 filter packets from this socket. This
502 sets the SO_MARK socket option. See
503 <citerefentry><refentrytitle>iptables</refentrytitle><manvolnum>8</manvolnum></citerefentry>
504 for details.</para></listitem>
508 <term><varname>ReusePort=</varname></term>
509 <listitem><para>Takes a boolean
510 value. If true allows multiple bind()s
511 to this TCP or UDP port. This
512 controls the SO_REUSEPORT socket
514 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
515 for details.</para></listitem>
519 <term><varname>SmackLabel=</varname></term>
520 <term><varname>SmackLabelIPIn=</varname></term>
521 <term><varname>SmackLabelIPOut=</varname></term>
522 <listitem><para>Takes a string
523 value. Controls the extended
525 <literal>security.SMACK64</literal>,
526 <literal>security.SMACK64IPIN</literal>
528 <literal>security.SMACK64IPOUT</literal>,
529 respectively, i.e. the security label
530 of the FIFO, or the security label for
531 the incoming or outgoing connections
532 of the socket, respectively. See
534 url="https://www.kernel.org/doc/Documentation/security/Smack.txt">Smack.txt</ulink>
535 for details.</para></listitem>
539 <term><varname>PipeSize=</varname></term>
540 <listitem><para>Takes an integer
541 value. Controls the pipe buffer size
542 of FIFOs configured in this socket
544 <citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
545 for details.</para></listitem>
549 <term><varname>MessageQueueMaxMessages=</varname>,
550 <varname>MessageQueueMessageSize=</varname></term>
551 <listitem><para>These two settings
552 take integer values and control the
553 mq_maxmsg field or the mq_msgsize field, respectively, when
554 creating the message queue. Note that
555 either none or both of these variables
557 <citerefentry><refentrytitle>mq_setattr</refentrytitle><manvolnum>3</manvolnum></citerefentry>
558 for details.</para></listitem>
562 <term><varname>FreeBind=</varname></term>
563 <listitem><para>Takes a boolean
564 value. Controls whether the socket can
565 be bound to non-local IP
566 addresses. This is useful to configure
567 sockets listening on specific IP
568 addresses before those IP addresses
569 are successfully configured on a
570 network interface. This sets the
571 IP_FREEBIND socket option. For
572 robustness reasons it is recommended
573 to use this option whenever you bind a
574 socket to a specific IP
575 address. Defaults to <option>false</option>.</para></listitem>
579 <term><varname>Transparent=</varname></term>
580 <listitem><para>Takes a boolean
581 value. Controls the IP_TRANSPARENT
582 socket option. Defaults to
583 <option>false</option>.</para></listitem>
587 <term><varname>Broadcast=</varname></term>
588 <listitem><para>Takes a boolean
589 value. This controls the SO_BROADCAST
590 socket option, which allows broadcast
591 datagrams to be sent from this
593 <option>false</option>.</para></listitem>
597 <term><varname>PassCredentials=</varname></term>
598 <listitem><para>Takes a boolean
599 value. This controls the SO_PASSCRED
600 socket option, which allows <constant>AF_UNIX</constant> sockets to
601 receive the credentials of the sending
602 process in an ancillary message.
604 <option>false</option>.</para></listitem>
608 <term><varname>PassSecurity=</varname></term>
609 <listitem><para>Takes a boolean
610 value. This controls the SO_PASSSEC
611 socket option, which allows <constant>AF_UNIX</constant>
612 sockets to receive the security
613 context of the sending process in an
614 ancillary message. Defaults to
615 <option>false</option>.</para></listitem>
619 <term><varname>TCPCongestion=</varname></term>
620 <listitem><para>Takes a string
621 value. Controls the TCP congestion
622 algorithm used by this socket. Should
623 be one of "westwood", "veno", "cubic",
624 "lp" or any other available algorithm
625 supported by the IP stack. This
626 setting applies only to stream
627 sockets.</para></listitem>
631 <term><varname>ExecStartPre=</varname></term>
632 <term><varname>ExecStartPost=</varname></term>
633 <listitem><para>Takes one or more
634 command lines, which are executed
635 before or after the listening
636 sockets/FIFOs are created and
637 bound, respectively. The first token of the command
638 line must be an absolute filename,
639 then followed by arguments for the
640 process. Multiple command lines may be
641 specified following the same scheme as
643 <varname>ExecStartPre=</varname> of
644 service unit files.</para></listitem>
648 <term><varname>ExecStopPre=</varname></term>
649 <term><varname>ExecStopPost=</varname></term>
650 <listitem><para>Additional commands
651 that are executed before or after
652 the listening sockets/FIFOs are closed
653 and removed, respectively. Multiple command lines
654 may be specified following the same
656 <varname>ExecStartPre=</varname> of
657 service unit files.</para></listitem>
661 <term><varname>TimeoutSec=</varname></term>
662 <listitem><para>Configures the time to
663 wait for the commands specified in
664 <varname>ExecStartPre=</varname>,
665 <varname>ExecStartPost=</varname>,
666 <varname>ExecStopPre=</varname> and
667 <varname>ExecStopPost=</varname> to
668 finish. If a command does not exit
669 within the configured time, the socket
670 will be considered failed and be shut
671 down again. All commands still running,
672 will be terminated forcibly via
673 <constant>SIGTERM</constant>, and after another delay of
674 this time with <constant>SIGKILL</constant>. (See
675 <option>KillMode=</option> in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
676 Takes a unit-less value in seconds, or
677 a time span value such as "5min
678 20s". Pass 0 to disable the timeout
680 90s.</para></listitem>
684 <term><varname>Service=</varname></term>
685 <listitem><para>Specifies the service
686 unit name to activate on incoming
687 traffic. This defaults to the service
688 that bears the same name as the socket
689 (ignoring the different suffixes). In
690 most cases it should not be necessary
691 to use this option.</para></listitem>
697 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
699 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
700 for more settings.</para>
705 <title>See Also</title>
707 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
708 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
709 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
710 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
711 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
712 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
713 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
717 For more extensive descriptions see the "systemd for Developers" series:
718 <ulink url="http://0pointer.de/blog/projects/socket-activation.html">Socket Activation</ulink>,
719 <ulink url="http://0pointer.de/blog/projects/socket-activation2.html">Socket Activation, part II</ulink>,
720 <ulink url="http://0pointer.de/blog/projects/inetd.html">Converting inetd Services</ulink>,
721 <ulink url="http://0pointer.de/blog/projects/socket-activated-containers.html">Socket Activated Internet Services and OS Containers</ulink>.