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>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
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>
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 (SOCK_STREAM), datagram (SOCK_DGRAM)
154 resp. sequential packet
155 (SOCK_SEQPACKET) socket. 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 AF_UNIX socket
163 <para>If the address starts with an
164 at symbol (@) it is read as abstract
165 namespace socket in the AF_UNIX
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 for both IPv4 and
176 <para>If the address string is a
177 string in the format v.w.x.y:z it is
178 read as IPv4 specifier for listening
179 on an address v.w.x.y on a port
182 <para>If the address string is a
183 string in the format [x]:y it is read
184 as IPv6 address x on a port y.</para>
186 <para>Note that SOCK_SEQPACKET
187 (i.e. <varname>ListenSequentialPacket=</varname>)
188 is only available for AF_UNIX
190 (i.e. <varname>ListenStream=</varname>)
191 when used for IP sockets refers to TCP
193 (i.e. <varname>ListenDatagram=</varname>)
196 <para>These options may be specified
197 more than once in which case incoming
198 traffic on any of the sockets will trigger
199 service activation, and all listed
200 sockets will be passed to the service,
201 regardless whether there is incoming
202 traffic on them or not.</para>
204 <para>If an IP address is used here, it
205 is often desirable to listen on it
206 before the interface it is configured
207 on is up and running, and even
208 regardless whether it will be up and
209 running ever at all. To deal with this it is
210 recommended to set the
211 <varname>FreeBind=</varname> option
212 described below.</para></listitem>
216 <term><varname>ListenFIFO=</varname></term>
217 <listitem><para>Specifies a file
218 system FIFO to listen on. This expects
219 an absolute file system path as
220 argument. Behaviour otherwise is very
222 <varname>ListenDatagram=</varname>
223 directive above.</para></listitem>
227 <term><varname>ListenSpecial=</varname></term>
228 <listitem><para>Specifies a special
229 file in the file system to listen
230 on. This expects an absolute file
231 system path as argument. Behaviour
232 otherwise is very similar to the
233 <varname>ListenFIFO=</varname>
234 directive above. Use this to open
235 character device nodes as well as
237 <filename>/proc</filename> and
238 <filename>/sys</filename>.</para></listitem>
242 <term><varname>ListenNetlink=</varname></term>
243 <listitem><para>Specifies a Netlink
244 family to create a socket for to
245 listen on. This expects a short string
246 referring to the AF_NETLINK family
247 name (such as <varname>audit</varname>
248 or <varname>kobject-uevent</varname>)
249 as argument, optionally suffixed by a
250 whitespace followed by a multicast
251 group integer. Behaviour otherwise is
253 <varname>ListenDatagram=</varname>
254 directive above.</para></listitem>
258 <term><varname>ListenMessageQueue=</varname></term>
259 <listitem><para>Specifies a POSIX
260 message queue name to listen on. This
261 expects a valid message queue name
262 (i.e. beginning with /). Behaviour
263 otherwise is very similar to the
264 <varname>ListenFIFO=</varname>
265 directive above. On Linux message
266 queue descriptors are actually file
267 descriptors and can be inherited
268 between processes.</para></listitem>
272 <term><varname>BindIPv6Only=</varname></term>
273 <listitem><para>Takes a one of
274 <option>default</option>,
275 <option>both</option> or
276 <option>ipv6-only</option>. Controls
277 the IPV6_V6ONLY socket option (see
278 <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
280 <option>both</option>, IPv6 sockets
281 bound will be accessible via both IPv4
283 <option>ipv6-only</option>, they will
284 be accessible via IPv6 only. If
285 <option>default</option> (which is the
286 default, surprise!) the system wide
287 default setting is used, as controlled
289 <filename>/proc/sys/net/ipv6/bindv6only</filename>.</para>
294 <term><varname>Backlog=</varname></term>
295 <listitem><para>Takes an unsigned
296 integer argument. Specifies the number
297 of connections to queue that have not
298 been accepted yet. This setting
299 matters only for stream and sequential
301 <citerefentry><refentrytitle>listen</refentrytitle><manvolnum>2</manvolnum></citerefentry>
302 for details. Defaults to SOMAXCONN
303 (128).</para></listitem>
307 <term><varname>BindToDevice=</varname></term>
308 <listitem><para>Specifies a network
309 interface name to bind this socket
310 to. If set traffic will only be
311 accepted from the specified network
312 interfaces. This controls the
313 SO_BINDTODEVICE socket option (see
314 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
315 for details). If this option is used,
316 an automatic dependency from this
317 socket unit on the network interface
319 (<citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
320 is created.</para></listitem>
324 <term><varname>DirectoryMode=</varname></term>
325 <listitem><para>If listening on a file
326 system socket of FIFO, the parent
327 directories are automatically created
328 if needed. This option specifies the
329 file system access mode used when
330 creating these directories. Takes an
332 notation. Defaults to
333 0755.</para></listitem>
337 <term><varname>SocketMode=</varname></term>
338 <listitem><para>If listening on a file
339 system socket of FIFO, this option
340 specifies the file system access mode
341 used when creating the file
342 node. Takes an access mode in octal
343 notation. Defaults to
344 0666.</para></listitem>
348 <term><varname>Accept=</varname></term>
349 <listitem><para>Takes a boolean
350 argument. If true, a service instance
351 is spawned for each incoming
352 connection and only the connection
353 socket is passed to it. If false, all
354 listening sockets themselves are
355 passed to the started service unit,
356 and only one service unit is spawned
357 for all connections (also see
358 above). This value is ignored for
359 datagram sockets and FIFOs where
360 a single service unit unconditionally
361 handles all incoming traffic. Defaults
362 to <option>false</option>. For
363 performance reasons, it is recommended
364 to write new daemons only in a way
366 <option>Accept=false</option>. This
367 option is mostly useful to allow
368 daemons designed for usage with
369 <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
370 to work unmodified with systemd socket
371 activation.</para></listitem>
375 <term><varname>MaxConnections=</varname></term>
376 <listitem><para>The maximum number of
377 connections to simultaneously run
378 services instances for, when
379 <option>Accept=true</option> is
380 set. If more concurrent connections
381 are coming in, they will be refused
382 until at least one existing connection
383 is terminated. This setting has no
384 effect for sockets configured with
385 <option>Accept=no</option> or datagram
387 64.</para></listitem>
391 <term><varname>KeepAlive=</varname></term>
392 <listitem><para>Takes a boolean
393 argument. If true, the TCP/IP stack
394 will send a keep alive message after
395 2h (depending on the configuration of
396 <filename>/proc/sys/net/ipv4/tcp_keepalive_time</filename>)
397 for all TCP streams accepted on this
398 socket. This controls the SO_KEEPALIVE
400 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
402 url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
403 Keepalive HOWTO</ulink> for details.)
405 <option>false</option>.</para></listitem>
409 <term><varname>Priority=</varname></term>
410 <listitem><para>Takes an integer
411 argument controlling the priority for
412 all traffic sent from this
413 socket. This controls the SO_PRIORITY
415 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
416 for details.).</para></listitem>
420 <term><varname>ReceiveBuffer=</varname></term>
421 <term><varname>SendBuffer=</varname></term>
422 <listitem><para>Takes an integer
423 argument controlling the receive
424 resp. send buffer sizes of this
425 socket. This controls the SO_RCVBUF
426 resp. SO_SNDBUF socket options (see
427 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
428 for details.).</para></listitem>
432 <term><varname>IPTOS=</varname></term>
433 <listitem><para>Takes an integer
434 argument controlling the IP
435 Type-Of-Service field for packets
436 generated from this socket. This
437 controls the IP_TOS socket option (see
438 <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
439 for details.). Either a numeric string
440 or one of <option>low-delay</option>,
441 <option>throughput</option>,
442 <option>reliability</option> or
443 <option>low-cost</option> may be
444 specified.</para></listitem>
448 <term><varname>IPTTL=</varname></term>
449 <listitem><para>Takes an integer
450 argument controlling the IPv4
451 Time-To-Live/IPv6 Hop-Count field for
452 packets generated from this
453 socket. This sets the
454 IP_TTL/IPV6_UNICAST_HOPS socket
456 <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
458 <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
459 for details.)</para></listitem>
463 <term><varname>Mark=</varname></term>
464 <listitem><para>Takes an integer
465 value. Controls the firewall mark of
466 packets generated by this socket. This
467 can be used in the firewall logic to
468 filter packets from this socket. This
469 sets the SO_MARK socket option. See
470 <citerefentry><refentrytitle>iptables</refentrytitle><manvolnum>8</manvolnum></citerefentry>
471 for details.</para></listitem>
475 <term><varname>PipeSize=</varname></term>
476 <listitem><para>Takes an integer
477 value. Controls the pipe buffer size
478 of FIFOs configured in this socket
480 <citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
481 for details.</para></listitem>
485 <term><varname>MessageQueueMaxMessages=</varname>,
486 <varname>MessageQueueMessageSize=</varname></term>
487 <listitem><para>These two settings
488 take integer values and control the
489 mq_maxmsg resp. mq_msgsize field when
490 creating the message queue. Note that
491 either none or both of these variables
493 <citerefentry><refentrytitle>mq_setattr</refentrytitle><manvolnum>3</manvolnum></citerefentry>
494 for details.</para></listitem>
498 <term><varname>FreeBind=</varname></term>
499 <listitem><para>Takes a boolean
500 value. Controls whether the socket can
501 be bound to non-local IP
502 addresses. This is useful to configure
503 sockets listening on specific IP
504 addresses before those IP addresses
505 are successfully configured on a
506 network interface. This sets the
507 IP_FREEBIND socket option. For
508 robustness reasons it is recommended
509 to use this option whenever you bind a
510 socket to a specific IP
511 address. Defaults to <option>false</option>.</para></listitem>
515 <term><varname>Transparent=</varname></term>
516 <listitem><para>Takes a boolean
517 value. Controls the IP_TRANSPARENT
518 socket option. Defaults to
519 <option>false</option>.</para></listitem>
523 <term><varname>Broadcast=</varname></term>
524 <listitem><para>Takes a boolean
525 value. This controls the SO_BROADCAST
526 socket option, which allows broadcast
527 datagrams to be sent from this
529 <option>false</option>.</para></listitem>
533 <term><varname>PassCredentials=</varname></term>
534 <listitem><para>Takes a boolean
535 value. This controls the SO_PASSCRED
536 socket option, which allows AF_UNIX sockets to
537 receive the credentials of the sending
538 process in an ancillary message.
540 <option>false</option>.</para></listitem>
544 <term><varname>PassSecurity=</varname></term>
545 <listitem><para>Takes a boolean
546 value. This controls the SO_PASSSEC
547 socket option, which allows AF_UNIX
548 sockets to receive the security
549 context of the sending process in an
550 ancillary message. Defaults to
551 <option>false</option>.</para></listitem>
555 <term><varname>TCPCongestion=</varname></term>
556 <listitem><para>Takes a string
557 value. Controls the TCP congestion
558 algorithm used by this socket. Should
559 be one of "westwood", "veno", "cubic",
560 "lp" or any other available algorithm
561 supported by the IP stack. This
562 setting applies only to stream
563 sockets.</para></listitem>
567 <term><varname>ExecStartPre=</varname></term>
568 <term><varname>ExecStartPost=</varname></term>
569 <listitem><para>Takes one or more
570 command lines, which are executed
571 before (resp. after) the listening
572 sockets/FIFOs are created and
573 bound. The first token of the command
574 line must be an absolute file name,
575 then followed by arguments for the
576 process. Multiple command lines may be
577 specified following the same scheme as
579 <varname>ExecStartPre=</varname> of
580 service unit files.</para></listitem>
584 <term><varname>ExecStopPre=</varname></term>
585 <term><varname>ExecStopPost=</varname></term>
586 <listitem><para>Additional commands
587 that are executed before (resp. after)
588 the listening sockets/FIFOs are closed
589 and removed. Multiple command lines
590 may be specified following the same
592 <varname>ExecStartPre=</varname> of
593 service unit files.</para></listitem>
597 <term><varname>TimeoutSec=</varname></term>
598 <listitem><para>Configures the time to
599 wait for the commands specified in
600 <varname>ExecStartPre=</varname>,
601 <varname>ExecStartPost=</varname>,
602 <varname>ExecStopPre=</varname> and
603 <varname>ExecStopPost=</varname> to
604 finish. If a command does not exit
605 within the configured time, the socket
606 will be considered failed and be shut
607 down again. All commands still running,
608 will be terminated forcibly via
609 SIGTERM, and after another delay of
610 this time with SIGKILL. (See
611 <option>KillMode=</option> in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
612 Takes a unit-less value in seconds, or
613 a time span value such as "5min
614 20s". Pass 0 to disable the timeout
616 90s.</para></listitem>
620 <term><varname>Service=</varname></term>
621 <listitem><para>Specifies the service
622 unit name to activate on incoming
623 traffic. This defaults to the service
624 that bears the same name as the socket
625 (ignoring the different suffixes). In
626 most cases it should not be necessary
627 to use this option.</para></listitem>
633 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
635 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
636 for more settings.</para>
641 <title>See Also</title>
643 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
644 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
645 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
646 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
647 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
648 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>