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>Socket units may be used to implement on-demand
99 starting of services, as well as parallelized starting
104 <title>Options</title>
106 <para>Socket files must include a [Socket] section,
107 which carries information about the socket or FIFO it
108 supervises. A number of options that may be used in
109 this section are shared with other unit types. These
110 options are documented in
111 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
112 options specific to the [Socket] section of socket
113 units are the following:</para>
117 <term><varname>ListenStream=</varname></term>
118 <term><varname>ListenDatagram=</varname></term>
119 <term><varname>ListenSequentialPacket=</varname></term>
120 <listitem><para>Specifies an address
121 to listen on for a stream
122 (SOCK_STREAM), datagram (SOCK_DGRAM)
123 resp. sequential packet
124 (SOCK_SEQPACKET) socket. The address
125 can be written in various formats:</para>
127 <para>If the address starts with a
128 slash (/), it is read as file system
129 socket in the AF_UNIX socket
132 <para>If the address starts with an
133 ampersand (@) it is read as abstract
134 namespace socket in the AF_UNIX
135 family. The @ is replaced with a NUL
136 character before binding. For details
138 <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
140 <para>If the address string is a
141 single number it is read as port
142 number to listen on for both IPv4 and
145 <para>If the address string is a
146 string in the format v.w.x.y:z it is
147 read as IPv4 specifier for listening
148 on an address v.w.x.y on a port
151 <para>If the address string is a
152 string in the format [x]:y it is read
153 as IPv6 address x on a port y.</para>
155 <para>Note that SOCK_SEQPACKET
156 (i.e. <varname>ListenSequentialPacket=</varname>)
157 is only available for AF_UNIX
159 (i.e. <varname>ListenStream=</varname>)
160 when used for IP sockets refers to TCP
162 (i.e. <varname>ListenDatagram=</varname>)
165 <para>These options may be specified
166 more than once in which case incoming
167 traffic on any of the sockets will trigger
168 service activation, and all listed
169 sockets will be passed to the service,
170 regardless whether there is incoming
171 traffic on them or not.</para>
173 <para>If an IP address is used here, it
174 is often desirable to listen on it
175 before the interface it is configured
176 on is up and running, and even
177 regardless whether it will be up and
178 running ever at all. To deal with this it is
179 recommended to set the
180 <varname>FreeBind=</varname> option
181 described below.</para></listitem>
185 <term><varname>ListenFIFO=</varname></term>
186 <listitem><para>Specifies a file
187 system FIFO to listen on. This expects
188 an absolute file system path as
189 argument. Behaviour otherwise is very
191 <varname>ListenDatagram=</varname>
192 directive above.</para></listitem>
196 <term><varname>BindIPv6Only=</varname></term>
197 <listitem><para>Takes a one of
198 <option>default</option>,
199 <option>both</option> or
200 <option>ipv6-only</option>. Controls
201 the IPV6_V6ONLY socket option (see
202 <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
204 <option>both</option>, IPv6 sockets
205 bound will be accessible via both IPv4
207 <option>ipv6-only</option>, they will
208 be accessible via IPv6 only. If
209 <option>default</option> (which is the
210 default, surprise!) the system wide
211 default setting is used, as controlled
213 <filename>/proc/sys/net/ipv6/bindv6only</filename>.</para>
218 <term><varname>Backlog=</varname></term>
219 <listitem><para>Takes an unsigned
220 integer argument. Specifies the number
221 of connections to queue that have not
222 been accepted yet. This setting
223 matters only for stream and sequential
225 <citerefentry><refentrytitle>listen</refentrytitle><manvolnum>2</manvolnum></citerefentry>
226 for details. Defaults to SOMAXCONN
227 (128).</para></listitem>
231 <term><varname>BindToDevice=</varname></term>
232 <listitem><para>Specifies a network
233 interface name to bind this socket
234 to. If set traffic will only be
235 accepted from the specified network
236 interfaces. This controls the
237 SO_BINDTODEVICE socket option (see
238 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
239 for details). If this option is used,
240 an automatic dependency from this
241 socket unit on the network interface
243 (<citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
244 is created.</para></listitem>
248 <term><varname>DirectoryMode=</varname></term>
249 <listitem><para>If listening on a file
250 system socket of FIFO, the parent
251 directories are automatically created
252 if needed. This option specifies the
253 file system access mode used when
254 creating these directories. Defaults
255 to 0755.</para></listitem>
259 <term><varname>SocketMode=</varname></term>
260 <listitem><para>If listening on a file
261 system socket of FIFO, this option
262 specifies the file system access mode
263 used when creating the file
265 0666.</para></listitem>
269 <term><varname>Accept=</varname></term>
270 <listitem><para>Takes a boolean
271 argument. If true, a service instance
272 is spawned for each incoming
273 connection and only the connection
274 socket is passed to it. If false, all
275 listening sockets themselves are
276 passed to the started service unit,
277 and only one service unit is spawned
278 for all connections (also see
279 above). This value is ignored for
280 datagram sockets and FIFOs where
281 a single service unit unconditionally
282 handles all incoming traffic. Defaults
283 to <option>false</option>. For
284 performance reasons, it is recommended
285 to write new daemons only in a way
287 <option>Accept=false</option>. This
288 option is mostly useful to allow
289 daemons designed for usage with
290 <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
291 to work unmodified with systemd socket
292 activation.</para></listitem>
296 <term><varname>MaxConnections=</varname></term>
297 <listitem><para>The maximum number of
298 connections to simultaneously run
299 services instances for, when
300 <option>Accept=true</option> is
301 set. If more concurrent connections
302 are coming in, they will be refused
303 until at least one existing connection
304 is terminated. This setting has no
305 effect for sockets configured with
306 <option>Accept=no</option> or datagram
308 64.</para></listitem>
312 <term><varname>KeepAlive=</varname></term>
313 <listitem><para>Takes a boolean
314 argument. If true, the TCP/IP stack
315 will send a keep alive message after
316 2h (depending on the configuration of
317 <filename>/proc/sys/net/ipv4/tcp_keepalive_time</filename>)
318 for all TCP streams accepted on this
319 socket. This controls the SO_KEEPALIVE
321 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
323 url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
324 Keepalive HOWTO</ulink> for details.)
326 <option>false</option>.</para></listitem>
330 <term><varname>Priority=</varname></term>
331 <listitem><para>Takes an integer
332 argument controlling the priority for
333 all traffic sent from this
334 socket. This controls the SO_PRIORITY
336 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
337 for details.).</para></listitem>
341 <term><varname>ReceiveBuffer=</varname></term>
342 <term><varname>SendBuffer=</varname></term>
343 <listitem><para>Takes an integer
344 argument controlling the receive
345 resp. send buffer sizes of this
346 socket. This controls the SO_RCVBUF
347 resp. SO_SNDBUF socket options (see
348 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
349 for details.).</para></listitem>
353 <term><varname>IPTOS=</varname></term>
354 <listitem><para>Takes an integer
355 argument controlling the IP
356 Type-Of-Service field for packets
357 generated from this socket. This
358 controls the IP_TOS socket option (see
359 <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
360 for details.). Either a numeric string
361 or one of <option>low-delay</option>,
362 <option>throughput</option>,
363 <option>reliability</option> or
364 <option>low-cost</option> may be
365 specified.</para></listitem>
369 <term><varname>IPTTL=</varname></term>
370 <listitem><para>Takes an integer
371 argument controlling the IPv4
372 Time-To-Live/IPv6 Hop-Count field for
373 packets generated from this
374 socket. This sets the
375 IP_TTL/IPV6_UNICAST_HOPS socket
377 <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
379 <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
380 for details.)</para></listitem>
384 <term><varname>Mark=</varname></term>
385 <listitem><para>Takes an integer
386 value. Controls the firewall mark of
387 packets generated by this socket. This
388 can be used in the firewall logic to
389 filter packets from this socket. This
390 sets the SO_MARK socket option. See
391 <citerefentry><refentrytitle>iptables</refentrytitle><manvolnum>8</manvolnum></citerefentry>
392 for details.</para></listitem>
396 <term><varname>PipeSize=</varname></term>
397 <listitem><para>Takes an integer
398 value. Controls the pipe buffer size
399 of FIFOs configured in this socket
401 <citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
402 for details.</para></listitem>
406 <term><varname>FreeBind=</varname></term>
407 <listitem><para>Takes a boolean
408 value. Controls whether the socket can
409 be bound to non-local IP
410 addresses. This is useful to configure
411 sockets listening on specific IP
412 addresses before those IP addresses
413 are successfully configured on a
414 network interface. This sets the
415 IP_FREEBIND socket option. For
416 robustness reasons it is recommended
417 to use this option whenever you bind a
418 socket to a specific IP
419 address. Defaults to <option>false</option>.</para></listitem>
423 <term><varname>ExecStartPre=</varname></term>
424 <term><varname>ExecStartPost=</varname></term>
425 <listitem><para>Takes a command line,
426 which is executed before (resp. after)
427 the listening sockets/FIFOs are created and
428 bound. The first token of the command
429 line must be an absolute file name,
430 then followed by arguments for the
431 process. If specified more than once,
432 all commands are executed one after
433 the other, fully serialized. The use of
434 these settings is optional.</para></listitem>
438 <term><varname>ExecStopPre=</varname></term>
439 <term><varname>ExecStopPost=</varname></term>
440 <listitem><para>Additional commands
441 that are executed before (resp. after)
442 the listening sockets/FIFOs are closed
443 and removed. If specified more than
444 once, all commands are executed one
445 after the other, fully serialized. The use of
446 these settings is optional.</para></listitem>
450 <term><varname>TimeoutSec=</varname></term>
451 <listitem><para>Configures the time to
452 wait for the commands specified in
453 <varname>ExecStartPre=</varname>,
454 <varname>ExecStartPost=</varname>,
455 <varname>ExecStopPre=</varname> and
456 <varname>ExecStopPost=</varname> to
457 finish. If a command does not exit
458 within the configured time, the socket
459 will be considered failed and be shut
460 down again. All commands still running,
461 will be terminated forcibly via
462 SIGTERM, and after another delay of
463 this time with SIGKILL. (See
464 <option>KillMode=</option> below.)
465 Takes a unit-less value in seconds, or
466 a time span value such as "5min
467 20s". Pass 0 to disable the timeout
469 60s.</para></listitem>
473 <term><varname>KillMode=</varname></term>
474 <listitem><para>Specifies how
475 processes of this socket unit shall be
477 <option>control-group</option>,
478 <option>process-group</option>,
479 <option>process</option>,
480 <option>none</option>.</para>
482 <para>This option is mostly equivalent
483 to the <option>KillMode=</option>
484 option of service files. See
485 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
486 for details.</para></listitem>
492 <title>See Also</title>
494 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
495 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
496 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
497 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
498 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>