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 .socket
58 encodes information about an IPC or network socket or
59 a file system FIFO controlled and supervised by systemd,
60 for socket-based activation.</para>
62 <para>This man page lists the configuration options
63 specific to this unit type. See
64 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
65 for the common options of all unit configuration
66 files. The common configuration items are configured
67 in the generic [Unit] and [Install] sections. The
68 service specific configuration options are configured
69 in the [Socket] section.</para>
71 <para>Additional options are listed in
72 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
74 <para>For each socket file a matching service file (see <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details)
75 must exist, describing the service to start on
76 incoming traffic on the socket. Depending on the
77 setting of <option>Accept=</option> (see below) this
78 must either be named like the socket unit, but with
79 the suffix replaced; or it must be a template file
80 named the same way. Example: a socket file
81 <filename>foo.socket</filename> needs a matching
82 service <filename>foo.service</filename> if
83 <option>Accept=false</option> is set. If
84 <option>Accept=true</option> is set a service template
85 file <filename>foo@.service</filename> must exist from
86 which services are instantiated for each incoming
91 <title>Options</title>
93 <para>Socket files must include a [Socket] section,
94 which carries information about the socket or FIFO it
95 supervises. A number of options that may be used in
96 this section are shared with other unit types. These
97 options are documented in
98 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
99 options specific to the [Socket] section of service
100 units are the following:</para>
104 <term><varname>ListenStream=</varname></term>
105 <term><varname>ListenDatagram=</varname></term>
106 <term><varname>ListenSequentialPacket=</varname></term>
107 <listitem><para>Specifies an address
108 to listen on for a stream
109 (SOCK_STREAM), datagram (SOCK_DGRAM)
110 resp. sequential packet
111 (SOCK_SEQPACKET) socket. The address
112 can be written in various formats:</para>
114 <para>If the address starts with a
115 slash (/), it is read as file system
116 socket in the AF_UNIX socket
119 <para>If the address starts with an
120 ampersand (@) it is read as abstract
121 namespace socket in the AF_UNIX
122 family. The @ is replaced with a NUL
123 character before binding. For details
125 <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
127 <para>If the address string is a
128 single number it is read as port
129 number to listen on for both IPv4 and
132 <para>If the address string is a
133 string in the format v.w.x.y:z it is
134 read as IPv4 specifier for listening
135 on an address v.w.x.y on a port
138 <para>If the address string is a
139 string in the format [x]:y it is read
140 as IPv6 address x on a port y.</para>
142 <para>Note that SOCK_SEQPACKET
143 (i.e. <varname>ListenSequentialPacket=</varname>)
144 is only available for AF_UNIX
146 (i.e. <varname>ListenStream=</varname>)
147 when used for IP sockets refers to TCP
149 (i.e. <varname>ListenDatagram=</varname>)
152 <para>These options may be specified
153 more than once in which case incoming
154 traffic on any of the sockets will trigger
155 service activation, and all listed
156 sockets will be passed to the service,
157 regardless whether there is incoming
158 traffic on them or not.</para>
160 <para>If an IP address is used here it
161 is often desirable to listen on it
162 before the interface it is configured
163 on is up and running, and even
164 regardless whether it will be up and
165 running ever at all. To deal with this it is
166 recommended to set the
167 <varname>FreeBind=</varname> option
168 described below.</para></listitem>
172 <term><varname>ListenFIFO=</varname></term>
173 <listitem><para>Specifies a file
174 system FIFO to listen on. This expects
175 an absolute file system path as
176 argument. Behaviour otherwise is very
178 <varname>ListenDatagram=</varname>
179 directive above.</para></listitem>
183 <term><varname>BindIPv6Only=</varname></term>
184 <listitem><para>Takes a one of
185 <option>default</option>,
186 <option>both</option> or
187 <option>ipv6-only</option>. Controls
188 the IPV6_V6ONLY socket option (see
189 <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
191 <option>both</option>, IPv6 sockets
192 bound will be accessible via both IPv4
194 <option>ipv6-only</option>, they will
195 be accessible via IPv6 only. If
196 <option>default</option> (which is the
197 default, surprise!) the system wide
198 default setting is used, as controlled
200 <filename>/proc/sys/net/ipv6/bindv6only</filename>.</para>
205 <term><varname>Backlog=</varname></term>
206 <listitem><para>Takes an unsigned
207 integer argument. Specifies the number
208 of connections to queue that have not
209 been accepted yet. This setting
210 matters only for stream and sequential
212 <citerefentry><refentrytitle>listen</refentrytitle><manvolnum>2</manvolnum></citerefentry>
213 for details. Defaults to SOMAXCONN
214 (128).</para></listitem>
218 <term><varname>BindToDevice=</varname></term>
219 <listitem><para>Specifies a network
220 interface name to bind this socket
221 to. If set traffic will only be
222 accepted from the specified network
223 interfaces. This controls the
224 SO_BINDTODEVICE socket option (see
225 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
226 for details). If this option is used
227 an automatic dependency from this
228 socket unit on the network interface
230 (<citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
231 is created.</para></listitem>
235 <term><varname>DirectoryMode=</varname></term>
236 <listitem><para>If listening on a file
237 system socket of FIFO the parent
238 directories are automatically created
239 if needed. This option specifies the
240 file system access mode used when
241 creating these directories. Defaults
242 to 0755.</para></listitem>
246 <term><varname>SocketMode=</varname></term>
247 <listitem><para>If listening on a file
248 system socket of FIFO this option
249 specifies the file system access mode
250 used when creating the file
252 0666.</para></listitem>
256 <term><varname>Accept=</varname></term>
257 <listitem><para>Takes a boolean
258 argument. If true a service instance
259 is spawned for each incoming
260 connection and only the connection
261 socket is passed to it. If false all
262 listening sockets themselves are
263 passed to the started service unit,
264 and only one service unit is spawned
265 for all connections (also see
266 above). This value is ignored for
267 datagram sockets and FIFOs where
268 unconditionally a single service unit
269 handles all incoming traffic. Defaults
270 to <option>false</option>. For
271 performance reasons it is recommended
272 to write new daemons only in a way
274 <option>Accept=false</option>. This
275 option is mostly useful to allow
276 daemons designed for usage with
277 <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
278 to work unmodified with system socket
279 activation.</para></listitem>
283 <term><varname>MaxConnections=</varname></term>
284 <listitem><para>The maximum number of
285 connections to simultaneously run
286 services instances for, when
287 <option>Accept=true</option> is
288 set. If more concurrent connections
289 are coming in they will be refused,
290 until at least one existing connection
291 is terminated. This setting has no
292 effect for sockets configured with
293 <option>Accept=no</option> or datagram
295 64.</para></listitem>
299 <term><varname>KeepAlive=</varname></term>
300 <listitem><para>Takes a boolean
301 argument. If true, the TCP/IP stack
302 will send a keep alive message after
303 2h (depending on the configuration of
304 <filename>/proc/sys/net/ipv4/tcp_keepalive_time</filename>)
305 for all TCP streams accepted on this
306 socket. This controls the SO_KEEPALIVE
308 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
310 url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
311 Keepalive HOWTO</ulink> for details.)
313 <option>false</option>.</para></listitem>
317 <term><varname>Priority=</varname></term>
318 <listitem><para>Takes an integer
319 argument controlling the priority for
320 all traffic sent from this
321 socket. This controls the SO_PRIORITY
323 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
324 for details.).</para></listitem>
328 <term><varname>ReceiveBuffer=</varname></term>
329 <term><varname>SendBuffer=</varname></term>
330 <listitem><para>Takes an integer
331 argument controlling the receive
332 resp. send buffer sizes of this
333 socket. This controls the SO_RCVBUF
334 resp. SO_SNDBUF socket options (see
335 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
336 for details.).</para></listitem>
340 <term><varname>IPTOS=</varname></term>
341 <listitem><para>Takes an integer
342 argument controlling the IP
343 Type-Of-Service field for packets
344 generated from this socket. This
345 controls the IP_TOS socket option (see
346 <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
347 for details.). Either a numeric string
348 or one of <option>low-delay</option>,
349 <option>throughput</option>,
350 <option>reliability</option> or
351 <option>low-cost</option> may be
352 specified.</para></listitem>
356 <term><varname>IPTTL=</varname></term>
357 <listitem><para>Takes an integer
358 argument controlling the IPv4
359 Time-To-Live/IPv6 Hop-Count field for
360 packets generated from this
361 socket. This sets the
362 IP_TTL/IPV6_UNICAST_HOPS socket
364 <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
366 <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
367 for details.)</para></listitem>
371 <term><varname>Mark=</varname></term>
372 <listitem><para>Takes an integer
373 value. Controls the firewall mark of
374 packets generated by this socket. This
375 can be used in the firewall logic to
376 filter packets from this socket. This
377 sets the SO_MARK socket option. See
378 <citerefentry><refentrytitle>iptables</refentrytitle><manvolnum>8</manvolnum></citerefentry>
379 for details.</para></listitem>
383 <term><varname>PipeSize=</varname></term>
384 <listitem><para>Takes an integer
385 value. Controls the pipe buffer size
386 of FIFOs configured in this socket
388 <citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
389 for details.</para></listitem>
393 <term><varname>FreeBind=</varname></term>
394 <listitem><para>Takes a boolean
395 value. Controls whether the socket can
396 be bound to non-local IP
397 addresses. This is useful to configure
398 sockets listening on specific IP
399 addresses before those IP addresses
400 are successfully configured on a
401 network interface. This sets the
402 IP_FREEBIND socket option. For
403 robustness reasons it is recommended
404 to use this option whenever you bind a
405 socket to a specific IP
406 address. Defaults to <option>false</option>.</para></listitem>
410 { "TimeoutSec", config_parse_usec, &u->socket.timeout_usec, "Socket" },
411 { "KillMode", config_parse_kill_mode, &u->socket.kill_mode, "Socket" },
414 <term><varname>ExecStartPre=</varname></term>
415 <term><varname>ExecStartPost=</varname></term>
416 <listitem><para>Takes a command line
417 that is executed before (resp. after)
418 the listening sockets/FIFOs are created and
419 bound. The first token of the command
420 line must be an absolute file name,
421 then followed by arguments for the
422 process. If specified more than once,
423 all commands are executed one after
424 the other, serially. Use of these
425 settings is optional.</para></listitem>
429 <term><varname>ExecStopPre=</varname></term>
430 <term><varname>ExecStopPost=</varname></term>
431 <listitem><para>Additional commands
432 that are executed before (resp. after)
433 the listening sockets/FIFOs are closed
434 and removed. If specified more than
435 once, all commands are executed one
436 after the other, serially. Use of
438 optional.</para></listitem>
443 <term><varname>TimeoutSec=</varname></term>
444 <listitem><para>Configures the time to
445 wait for the commands specified in
446 <varname>ExecStartPre=</varname>,
447 <varname>ExecStartPost=</varname>,
448 <varname>ExecStopPre=</varname> and
449 <varname>ExecStopPost=</varname> to
450 finish. If a comand does not exit
451 within the configured time the socket
452 will be considered failed and be shut
453 down again. All commands still running
454 will be terminated forcibly via
455 SIGTERM, and after another delay of
456 this time with SIGKILL. (See
457 <option>KilleMode=</option> below.)
458 Takes a unit-less value in seconds, or
459 a time span value such as "5min
460 20s". Pass 0 to disable the timeout
462 60s.</para></listitem>
467 <term><varname>KillMode=</varname></term>
468 <listitem><para>Specifies how
469 processes of this service shall be
471 <option>control-group</option>,
472 <option>process-group</option>,
473 <option>process</option>,
474 <option>none</option>.</para>
476 <para>This option is mostly equivalent
477 to the <option>KillMode=</option>
478 option of service files. See
479 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
480 for details.</para></listitem>
488 <title>See Also</title>
490 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
491 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
492 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
493 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
494 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>