1
<?xml version='1.0'?> <!--*-nxml-*-->
2
<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
3
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
4
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
7
This file is part of systemd.
9
Copyright 2010 Lennart Poettering
11
systemd is free software; you can redistribute it and/or modify it
12
under the terms of the GNU General Public License as published by
13
the Free Software Foundation; either version 2 of the License, or
14
(at your option) any later version.
16
systemd is distributed in the hope that it will be useful, but
17
WITHOUT ANY WARRANTY; without even the implied warranty of
18
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19
General Public License for more details.
21
You should have received a copy of the GNU General Public License
22
along with systemd; If not, see <http://www.gnu.org/licenses/>.
25
<refentry id="systemd.socket">
27
<title>systemd.socket</title>
28
<productname>systemd</productname>
32
<contrib>Developer</contrib>
33
<firstname>Lennart</firstname>
34
<surname>Poettering</surname>
35
<email>lennart@poettering.net</email>
41
<refentrytitle>systemd.socket</refentrytitle>
42
<manvolnum>5</manvolnum>
46
<refname>systemd.socket</refname>
47
<refpurpose>systemd socket configuration files</refpurpose>
51
<para><filename>systemd.socket</filename></para>
55
<title>Description</title>
57
<para>A unit configuration file whose name ends in
58
<filename>.socket</filename> encodes information about
59
an IPC or network socket or a file system FIFO
60
controlled and supervised by systemd, for socket-based
63
<para>This man page lists the configuration options
64
specific to this unit type. See
65
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
66
for the common options of all unit configuration
67
files. The common configuration items are configured
68
in the generic [Unit] and [Install] sections. The
69
socket specific configuration options are configured
70
in the [Socket] section.</para>
72
<para>Additional options are listed in
73
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
74
which define the execution environment the
75
<option>ExecStartPre=</option>,
76
<option>ExecStartPost=</option>,
77
<option>ExecStopPre=</option> and
78
<option>ExecStoptPost=</option> commands are executed
81
<para>For each socket file a matching service file
83
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
84
for details) must exist, describing the service to
85
start on incoming traffic on the socket. Depending on
86
the setting of <option>Accept=</option> (see below),
87
this must either be named like the socket unit, but
88
with the suffix replaced; or it must be a template
89
file named the same way. Example: a socket file
90
<filename>foo.socket</filename> needs a matching
91
service <filename>foo.service</filename> if
92
<option>Accept=false</option> is set. If
93
<option>Accept=true</option> is set a service template
94
file <filename>foo@.service</filename> must exist from
95
which services are instantiated for each incoming
98
<para>Unless <varname>DefaultDependencies=</varname>
99
is set to <option>false</option>, socket units will
100
implicitly have dependencies of type
101
<varname>Requires=</varname> and
102
<varname>After=</varname> on
103
<filename>sysinit.target</filename> as well as
104
dependencies of type <varname>Conflicts=</varname> and
105
<varname>Before=</varname> on
106
<filename>shutdown.target</filename>. These ensure
107
that socket units pull in basic system
108
initialization, and are terminated cleanly prior to
109
system shutdown. Only sockets involved with early
110
boot or late system shutdown should disable this
113
<para>Socket units may be used to implement on-demand
114
starting of services, as well as parallelized starting
117
<para>Note that the daemon software configured for
118
socket activation with socket units needs to be able
119
to accept sockets from systemd, either via systemd's
120
native socket passing interface (see
121
<citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
122
for details) or via the traditional
123
<citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>-style
124
socket passing (i.e. sockets passed in via STDIN and
125
STDOUT, using <varname>StandardInput=socket</varname>
126
in the service file).</para>
130
<title>Options</title>
132
<para>Socket files must include a [Socket] section,
133
which carries information about the socket or FIFO it
134
supervises. A number of options that may be used in
135
this section are shared with other unit types. These
136
options are documented in
137
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
138
options specific to the [Socket] section of socket
139
units are the following:</para>
143
<term><varname>ListenStream=</varname></term>
144
<term><varname>ListenDatagram=</varname></term>
145
<term><varname>ListenSequentialPacket=</varname></term>
146
<listitem><para>Specifies an address
147
to listen on for a stream
148
(SOCK_STREAM), datagram (SOCK_DGRAM)
149
resp. sequential packet
150
(SOCK_SEQPACKET) socket. The address
151
can be written in various formats:</para>
153
<para>If the address starts with a
154
slash (/), it is read as file system
155
socket in the AF_UNIX socket
158
<para>If the address starts with an
159
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
164
<citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
166
<para>If the address string is a
167
single number it is read as port
168
number to listen on for both IPv4 and
171
<para>If the address string is a
172
string in the format v.w.x.y:z it is
173
read as IPv4 specifier for listening
174
on an address v.w.x.y on a port
177
<para>If the address string is a
178
string in the format [x]:y it is read
179
as IPv6 address x on a port y.</para>
181
<para>Note that SOCK_SEQPACKET
182
(i.e. <varname>ListenSequentialPacket=</varname>)
183
is only available for AF_UNIX
185
(i.e. <varname>ListenStream=</varname>)
186
when used for IP sockets refers to TCP
188
(i.e. <varname>ListenDatagram=</varname>)
191
<para>These options may be specified
192
more than once in which case incoming
193
traffic on any of the sockets will trigger
194
service activation, and all listed
195
sockets will be passed to the service,
196
regardless whether there is incoming
197
traffic on them or not.</para>
199
<para>If an IP address is used here, it
200
is often desirable to listen on it
201
before the interface it is configured
202
on is up and running, and even
203
regardless whether it will be up and
204
running ever at all. To deal with this it is
205
recommended to set the
206
<varname>FreeBind=</varname> option
207
described below.</para></listitem>
211
<term><varname>ListenFIFO=</varname></term>
212
<listitem><para>Specifies a file
213
system FIFO to listen on. This expects
214
an absolute file system path as
215
argument. Behaviour otherwise is very
217
<varname>ListenDatagram=</varname>
218
directive above.</para></listitem>
222
<term><varname>ListenSpecial=</varname></term>
223
<listitem><para>Specifies a special
224
file in the file system to listen
225
on. This expects an absolute file
226
system path as argument. Behaviour
227
otherwise is very similar to the
228
<varname>ListenFIFO=</varname>
229
directive above. Use this to open
230
character device nodes as well as
232
<filename>/proc</filename> and
233
<filename>/sys</filename>.</para></listitem>
237
<term><varname>ListenNetlink=</varname></term>
238
<listitem><para>Specifies a Netlink
239
family to create a socket for to
240
listen on. This expects a short string
241
referring to the AF_NETLINK family
242
name (such as <varname>audit</varname>
243
or <varname>kobject-uevent</varname>)
244
as argument, optionally suffixed by a
245
whitespace followed by a multicast
246
group integer. Behaviour otherwise is
248
<varname>ListenDatagram=</varname>
249
directive above.</para></listitem>
253
<term><varname>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>
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>
275
<option>both</option>, IPv6 sockets
276
bound will be accessible via both IPv4
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
284
<filename>/proc/sys/net/ipv6/bindv6only</filename>.</para>
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
296
<citerefentry><refentrytitle>listen</refentrytitle><manvolnum>2</manvolnum></citerefentry>
297
for details. Defaults to SOMAXCONN
298
(128).</para></listitem>
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
314
(<citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
315
is created.</para></listitem>
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
327
notation. Defaults to
328
0755.</para></listitem>
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>
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
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>
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
382
64.</para></listitem>
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
395
<citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
397
url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
398
Keepalive HOWTO</ulink> for details.)
400
<option>false</option>.</para></listitem>
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
410
<citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
411
for details.).</para></listitem>
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>
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>
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
451
<citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
453
<citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
454
for details.)</para></listitem>
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>
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
475
<citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
476
for details.</para></listitem>
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
488
<citerefentry><refentrytitle>mq_setattr</refentrytitle><manvolnum>3</manvolnum></citerefentry>
489
for details.</para></listitem>
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>
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>
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
524
<option>false</option>.</para></listitem>
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.
535
<option>false</option>.</para></listitem>
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>
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>
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
574
<varname>ExecStartPre=</varname> of
575
service unit files.</para></listitem>
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
587
<varname>ExecStartPre=</varname> of
588
service unit files.</para></listitem>
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
611
90s.</para></listitem>
615
<term><varname>KillMode=</varname></term>
616
<listitem><para>Specifies how
617
processes of this socket unit shall be
619
<option>control-group</option>,
620
<option>process</option>,
621
<option>none</option>.</para>
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>
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.
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".
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>
664
<title>See Also</title>
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>