]> git.ipfire.org Git - thirdparty/systemd.git/blob - man/systemd.socket.xml
projects / thirdparty / systemd.git / blob
? search:


d3762cd63d9312d9d76c9c5aabc5607a3f3e5703
[thirdparty/systemd.git] / man / systemd.socket.xml
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">
5
6 <!--
7 This file is part of systemd.
8
9 Copyright 2010 Lennart Poettering
10
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.
15
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.
20
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/>.
23 -->
24
25 <refentry id="systemd.socket">
26 <refentryinfo>
27 <title>systemd.socket</title>
28 <productname>systemd</productname>
29
30 <authorgroup>
31 <author>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
36 </author>
37 </authorgroup>
38 </refentryinfo>
39
40 <refmeta>
41 <refentrytitle>systemd.socket</refentrytitle>
42 <manvolnum>5</manvolnum>
43 </refmeta>
44
45 <refnamediv>
46 <refname>systemd.socket</refname>
47 <refpurpose>systemd socket configuration files</refpurpose>
48 </refnamediv>
49
50 <refsynopsisdiv>
51 <para><filename>systemd.socket</filename></para>
52 </refsynopsisdiv>
53
54 <refsect1>
55 <title>Description</title>
56
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
61 activation.</para>
62
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>
71
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
79 in.</para>
80
81 <para>For each socket file a matching service file
82 (see
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
96 connection.</para>
97
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
111 option.</para>
112
113 <para>Socket units may be used to implement on-demand
114 starting of services, as well as parallelized starting
115 of services.</para>
116
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>
127 </refsect1>
128
129 <refsect1>
130 <title>Options</title>
131
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>
140
141 <variablelist>
142 <varlistentry>
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>
152
153 <para>If the address starts with a
154 slash (/), it is read as file system
155 socket in the AF_UNIX socket
156 family.</para>
157
158 <para>If the address starts with an
159 at symbol (@) 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
163 see
164 <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
165
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
169 IPv6.</para>
170
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
175 z.</para>
176
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>
180
181 <para>Note that SOCK_SEQPACKET
182 (i.e. <varname>ListenSequentialPacket=</varname>)
183 is only available for AF_UNIX
184 sockets. SOCK_STREAM
185 (i.e. <varname>ListenStream=</varname>)
186 when used for IP sockets refers to TCP
187 sockets, SOCK_DGRAM
188 (i.e. <varname>ListenDatagram=</varname>)
189 to UDP.</para>
190
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>
198
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>
208 </varlistentry>
209
210 <varlistentry>
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
216 similar to the
217 <varname>ListenDatagram=</varname>
218 directive above.</para></listitem>
219 </varlistentry>
220
221 <varlistentry>
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
231 special files in
232 <filename>/proc</filename> and
233 <filename>/sys</filename>.</para></listitem>
234 </varlistentry>
235
236 <varlistentry>
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
247 very similar to the
248 <varname>ListenDatagram=</varname>
249 directive above.</para></listitem>
250 </varlistentry>
251
252 <varlistentry>
253 <term><varname>ListenMessageQueue=</varname></term>
254 <listitem><para>Specifies a POSIX
255 message queue name to listen on. This
256 expects a valid message queue name
257 (i.e. beginning with /). Behaviour
258 otherwise is very similar to the
259 <varname>ListenFIFO=</varname>
260 directive above. On Linux message
261 queue descriptors are actually file
262 descriptors and can be inherited
263 between processes.</para></listitem>
264 </varlistentry>
265
266 <varlistentry>
267 <term><varname>BindIPv6Only=</varname></term>
268 <listitem><para>Takes a one of
269 <option>default</option>,
270 <option>both</option> or
271 <option>ipv6-only</option>. Controls
272 the IPV6_V6ONLY socket option (see
273 <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
274 for details). If
275 <option>both</option>, IPv6 sockets
276 bound will be accessible via both IPv4
277 and IPv6. If
278 <option>ipv6-only</option>, they will
279 be accessible via IPv6 only. If
280 <option>default</option> (which is the
281 default, surprise!) the system wide
282 default setting is used, as controlled
283 by
284 <filename>/proc/sys/net/ipv6/bindv6only</filename>.</para>
285 </listitem>
286 </varlistentry>
287
288 <varlistentry>
289 <term><varname>Backlog=</varname></term>
290 <listitem><para>Takes an unsigned
291 integer argument. Specifies the number
292 of connections to queue that have not
293 been accepted yet. This setting
294 matters only for stream and sequential
295 packet sockets. See
296 <citerefentry><refentrytitle>listen</refentrytitle><manvolnum>2</manvolnum></citerefentry>
297 for details. Defaults to SOMAXCONN
298 (128).</para></listitem>
299 </varlistentry>
300
301 <varlistentry>
302 <term><varname>BindToDevice=</varname></term>
303 <listitem><para>Specifies a network
304 interface name to bind this socket
305 to. If set traffic will only be
306 accepted from the specified network
307 interfaces. This controls the
308 SO_BINDTODEVICE socket option (see
309 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
310 for details). If this option is used,
311 an automatic dependency from this
312 socket unit on the network interface
313 device unit
314 (<citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
315 is created.</para></listitem>
316 </varlistentry>
317
318 <varlistentry>
319 <term><varname>DirectoryMode=</varname></term>
320 <listitem><para>If listening on a file
321 system socket of FIFO, the parent
322 directories are automatically created
323 if needed. This option specifies the
324 file system access mode used when
325 creating these directories. Takes an
326 access mode in octal
327 notation. Defaults to
328 0755.</para></listitem>
329 </varlistentry>
330
331 <varlistentry>
332 <term><varname>SocketMode=</varname></term>
333 <listitem><para>If listening on a file
334 system socket of FIFO, this option
335 specifies the file system access mode
336 used when creating the file
337 node. Takes an access mode in octal
338 notation. Defaults to
339 0666.</para></listitem>
340 </varlistentry>
341
342 <varlistentry>
343 <term><varname>Accept=</varname></term>
344 <listitem><para>Takes a boolean
345 argument. If true, a service instance
346 is spawned for each incoming
347 connection and only the connection
348 socket is passed to it. If false, all
349 listening sockets themselves are
350 passed to the started service unit,
351 and only one service unit is spawned
352 for all connections (also see
353 above). This value is ignored for
354 datagram sockets and FIFOs where
355 a single service unit unconditionally
356 handles all incoming traffic. Defaults
357 to <option>false</option>. For
358 performance reasons, it is recommended
359 to write new daemons only in a way
360 that is suitable for
361 <option>Accept=false</option>. This
362 option is mostly useful to allow
363 daemons designed for usage with
364 <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
365 to work unmodified with systemd socket
366 activation.</para></listitem>
367 </varlistentry>
368
369 <varlistentry>
370 <term><varname>MaxConnections=</varname></term>
371 <listitem><para>The maximum number of
372 connections to simultaneously run
373 services instances for, when
374 <option>Accept=true</option> is
375 set. If more concurrent connections
376 are coming in, they will be refused
377 until at least one existing connection
378 is terminated. This setting has no
379 effect for sockets configured with
380 <option>Accept=no</option> or datagram
381 sockets. Defaults to
382 64.</para></listitem>
383 </varlistentry>
384
385 <varlistentry>
386 <term><varname>KeepAlive=</varname></term>
387 <listitem><para>Takes a boolean
388 argument. If true, the TCP/IP stack
389 will send a keep alive message after
390 2h (depending on the configuration of
391 <filename>/proc/sys/net/ipv4/tcp_keepalive_time</filename>)
392 for all TCP streams accepted on this
393 socket. This controls the SO_KEEPALIVE
394 socket option (see
395 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
396 and the <ulink
397 url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
398 Keepalive HOWTO</ulink> for details.)
399 Defaults to
400 <option>false</option>.</para></listitem>
401 </varlistentry>
402
403 <varlistentry>
404 <term><varname>Priority=</varname></term>
405 <listitem><para>Takes an integer
406 argument controlling the priority for
407 all traffic sent from this
408 socket. This controls the SO_PRIORITY
409 socket option (see
410 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
411 for details.).</para></listitem>
412 </varlistentry>
413
414 <varlistentry>
415 <term><varname>ReceiveBuffer=</varname></term>
416 <term><varname>SendBuffer=</varname></term>
417 <listitem><para>Takes an integer
418 argument controlling the receive
419 resp. send buffer sizes of this
420 socket. This controls the SO_RCVBUF
421 resp. SO_SNDBUF socket options (see
422 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
423 for details.).</para></listitem>
424 </varlistentry>
425
426 <varlistentry>
427 <term><varname>IPTOS=</varname></term>
428 <listitem><para>Takes an integer
429 argument controlling the IP
430 Type-Of-Service field for packets
431 generated from this socket. This
432 controls the IP_TOS socket option (see
433 <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
434 for details.). Either a numeric string
435 or one of <option>low-delay</option>,
436 <option>throughput</option>,
437 <option>reliability</option> or
438 <option>low-cost</option> may be
439 specified.</para></listitem>
440 </varlistentry>
441
442 <varlistentry>
443 <term><varname>IPTTL=</varname></term>
444 <listitem><para>Takes an integer
445 argument controlling the IPv4
446 Time-To-Live/IPv6 Hop-Count field for
447 packets generated from this
448 socket. This sets the
449 IP_TTL/IPV6_UNICAST_HOPS socket
450 options (see
451 <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
452 and
453 <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
454 for details.)</para></listitem>
455 </varlistentry>
456
457 <varlistentry>
458 <term><varname>Mark=</varname></term>
459 <listitem><para>Takes an integer
460 value. Controls the firewall mark of
461 packets generated by this socket. This
462 can be used in the firewall logic to
463 filter packets from this socket. This
464 sets the SO_MARK socket option. See
465 <citerefentry><refentrytitle>iptables</refentrytitle><manvolnum>8</manvolnum></citerefentry>
466 for details.</para></listitem>
467 </varlistentry>
468
469 <varlistentry>
470 <term><varname>PipeSize=</varname></term>
471 <listitem><para>Takes an integer
472 value. Controls the pipe buffer size
473 of FIFOs configured in this socket
474 unit. See
475 <citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
476 for details.</para></listitem>
477 </varlistentry>
478
479 <varlistentry>
480 <term><varname>MessageQueueMaxMessages=</varname>,
481 <varname>MessageQueueMessageSize=</varname></term>
482 <listitem><para>These two settings
483 take integer values and control the
484 mq_maxmsg resp. mq_msgsize field when
485 creating the message queue. Note that
486 either none or both of these variables
487 need to be set. See
488 <citerefentry><refentrytitle>mq_setattr</refentrytitle><manvolnum>3</manvolnum></citerefentry>
489 for details.</para></listitem>
490 </varlistentry>
491
492 <varlistentry>
493 <term><varname>FreeBind=</varname></term>
494 <listitem><para>Takes a boolean
495 value. Controls whether the socket can
496 be bound to non-local IP
497 addresses. This is useful to configure
498 sockets listening on specific IP
499 addresses before those IP addresses
500 are successfully configured on a
501 network interface. This sets the
502 IP_FREEBIND socket option. For
503 robustness reasons it is recommended
504 to use this option whenever you bind a
505 socket to a specific IP
506 address. Defaults to <option>false</option>.</para></listitem>
507 </varlistentry>
508
509 <varlistentry>
510 <term><varname>Transparent=</varname></term>
511 <listitem><para>Takes a boolean
512 value. Controls the IP_TRANSPARENT
513 socket option. Defaults to
514 <option>false</option>.</para></listitem>
515 </varlistentry>
516
517 <varlistentry>
518 <term><varname>Broadcast=</varname></term>
519 <listitem><para>Takes a boolean
520 value. This controls the SO_BROADCAST
521 socket option, which allows broadcast
522 datagrams to be sent from this
523 socket. Defaults to
524 <option>false</option>.</para></listitem>
525 </varlistentry>
526
527 <varlistentry>
528 <term><varname>PassCredentials=</varname></term>
529 <listitem><para>Takes a boolean
530 value. This controls the SO_PASSCRED
531 socket option, which allows AF_UNIX sockets to
532 receive the credentials of the sending
533 process in an ancillary message.
534 Defaults to
535 <option>false</option>.</para></listitem>
536 </varlistentry>
537
538 <varlistentry>
539 <term><varname>PassSecurity=</varname></term>
540 <listitem><para>Takes a boolean
541 value. This controls the SO_PASSSEC
542 socket option, which allows AF_UNIX
543 sockets to receive the security
544 context of the sending process in an
545 ancillary message. Defaults to
546 <option>false</option>.</para></listitem>
547 </varlistentry>
548
549 <varlistentry>
550 <term><varname>TCPCongestion=</varname></term>
551 <listitem><para>Takes a string
552 value. Controls the TCP congestion
553 algorithm used by this socket. Should
554 be one of "westwood", "veno", "cubic",
555 "lp" or any other available algorithm
556 supported by the IP stack. This
557 setting applies only to stream
558 sockets.</para></listitem>
559 </varlistentry>
560
561 <varlistentry>
562 <term><varname>ExecStartPre=</varname></term>
563 <term><varname>ExecStartPost=</varname></term>
564 <listitem><para>Takes one or more
565 command lines, which are executed
566 before (resp. after) the listening
567 sockets/FIFOs are created and
568 bound. The first token of the command
569 line must be an absolute file name,
570 then followed by arguments for the
571 process. Multiple command lines may be
572 specified following the same scheme as
573 used for
574 <varname>ExecStartPre=</varname> of
575 service unit files.</para></listitem>
576 </varlistentry>
577
578 <varlistentry>
579 <term><varname>ExecStopPre=</varname></term>
580 <term><varname>ExecStopPost=</varname></term>
581 <listitem><para>Additional commands
582 that are executed before (resp. after)
583 the listening sockets/FIFOs are closed
584 and removed. Multiple command lines
585 may be specified following the same
586 scheme as used for
587 <varname>ExecStartPre=</varname> of
588 service unit files.</para></listitem>
589 </varlistentry>
590
591 <varlistentry>
592 <term><varname>TimeoutSec=</varname></term>
593 <listitem><para>Configures the time to
594 wait for the commands specified in
595 <varname>ExecStartPre=</varname>,
596 <varname>ExecStartPost=</varname>,
597 <varname>ExecStopPre=</varname> and
598 <varname>ExecStopPost=</varname> to
599 finish. If a command does not exit
600 within the configured time, the socket
601 will be considered failed and be shut
602 down again. All commands still running,
603 will be terminated forcibly via
604 SIGTERM, and after another delay of
605 this time with SIGKILL. (See
606 <option>KillMode=</option> below.)
607 Takes a unit-less value in seconds, or
608 a time span value such as "5min
609 20s". Pass 0 to disable the timeout
610 logic. Defaults to
611 90s.</para></listitem>
612 </varlistentry>
613
614 <varlistentry>
615 <term><varname>KillMode=</varname></term>
616 <listitem><para>Specifies how
617 processes of this socket unit shall be
618 killed. One of
619 <option>control-group</option>,
620 <option>process</option>,
621 <option>none</option>.</para>
622
623 <para>This option is mostly equivalent
624 to the <option>KillMode=</option>
625 option of service files. See
626 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
627 for details.</para></listitem>
628 </varlistentry>
629
630 <varlistentry>
631 <term><varname>KillSignal=</varname></term>
632 <listitem><para>Specifies which signal
633 to use when killing a process of this
634 socket. Defaults to SIGTERM.
635 </para></listitem>
636 </varlistentry>
637
638 <varlistentry>
639 <term><varname>SendSIGKILL=</varname></term>
640 <listitem><para>Specifies whether to
641 send SIGKILL to remaining processes
642 after a timeout, if the normal
643 shutdown procedure left processes of
644 the socket around. Takes a boolean
645 value. Defaults to "yes".
646 </para></listitem>
647 </varlistentry>
648
649 <varlistentry>
650 <term><varname>Service=</varname></term>
651 <listitem><para>Specifies the service
652 unit name to activate on incoming
653 traffic. This defaults to the service
654 that bears the same name as the socket
655 (ignoring the different suffixes). In
656 most cases it should not be necessary
657 to use this option.</para></listitem>
658 </varlistentry>
659
660 </variablelist>
661 </refsect1>
662
663 <refsect1>
664 <title>See Also</title>
665 <para>
666 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
667 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
668 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
669 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
670 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
671 </para>
672 </refsect1>
673
674 </refentry>
Unnamed repository; edit this file 'description' to name the repository.