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