1SYSTEMD.SOCKET(5) systemd.socket SYSTEMD.SOCKET(5)
2
6 systemd.socket - Socket unit configuration
7
9 socket.socket
10
12 A unit configuration file whose name ends in ".socket" encodes
13 information about an IPC or network socket or a file system FIFO
14 controlled and supervised by systemd, for socket-based activation.
15 This man page lists the configuration options specific to this unit
17 type. See systemd.unit(5) for the common options of all unit
18 configuration files. The common configuration items are configured in
19 the generic [Unit] and [Install] sections. The socket specific
20 configuration options are configured in the [Socket] section.
21 Additional options are listed in systemd.exec(5), which define the
23 execution environment the ExecStartPre=, ExecStartPost=, ExecStopPre=
24 and ExecStopPost= commands are executed in, and in systemd.kill(5),
25 which define the way the processes are terminated, and in
26 systemd.resource-control(5), which configure resource control settings
27 for the processes of the socket.
28 For each socket file, a matching service file must exist, describing
30 the service to start on incoming traffic on the socket (see
31 systemd.service(5) for more information about .service files). The name
32 of the .service unit is by default the same as the name of the .socket
33 unit, but can be altered with the Service= option described below.
34 Depending on the setting of the Accept= option described below, this
35 .service unit must either be named like the .socket unit, but with the
36 suffix replaced, unless overridden with Service=; or it must be a
37 template unit named the same way. Example: a socket file foo.socket
38 needs a matching service foo.service if Accept=false is set. If
39 Accept=true is set, a service template file foo@.service must exist
40 from which services are instantiated for each incoming connection.
41 Unless DefaultDependencies= is set to false, socket units will
43 implicitly have dependencies of type Requires= and After= on
44 sysinit.target as well as dependencies of type Conflicts= and Before=
45 on shutdown.target. These ensure that socket units pull in basic system
46 initialization, and are terminated cleanly prior to system shutdown.
47 Only sockets involved with early boot or late system shutdown should
48 disable this option.
49 Socket units will have a Before= dependency on the service which they
51 trigger added implicitly. No implicit WantedBy= or RequiredBy=
52 dependency from the socket to the service is added. This means that the
53 service may be started without the socket, in which case it must be
54 able to open sockets by itself. To prevent this, an explicit Requires=
55 dependency may be added.
56 Socket units may be used to implement on-demand starting of services,
58 as well as parallelized starting of services. See the blog stories
59 linked at the end for an introduction.
60 Note that the daemon software configured for socket activation with
62 socket units needs to be able to accept sockets from systemd, either
63 via systemd's native socket passing interface (see sd_listen_fds(3) for
64 details) or via the traditional inetd(8)-style socket passing (i.e.
65 sockets passed in via standard input and output, using
66 StandardInput=socket in the service file).
67
69 Socket files must include a [Socket] section, which carries information
70 about the socket or FIFO it supervises. A number of options that may be
71 used in this section are shared with other unit types. These options
72 are documented in systemd.exec(5) and systemd.kill(5). The options
73 specific to the [Socket] section of socket units are the following:
74 ListenStream=, ListenDatagram=, ListenSequentialPacket=
76 Specifies an address to listen on for a stream (SOCK_STREAM),
77 datagram (SOCK_DGRAM), or sequential packet (SOCK_SEQPACKET)
78 socket, respectively. The address can be written in various
79 formats:
80 If the address starts with a slash ("/"), it is read as file system
82 socket in the AF_UNIX socket family.
83 If the address starts with an at symbol ("@"), it is read as
85 abstract namespace socket in the AF_UNIX family. The "@" is
86 replaced with a NUL character before binding. For details, see
87 unix(7).
88 If the address string is a single number, it is read as port number
90 to listen on via IPv6. Depending on the value of BindIPv6Only= (see
91 below) this might result in the service being available via both
92 IPv6 and IPv4 (default) or just via IPv6.
93 If the address string is a string in the format v.w.x.y:z, it is
95 read as IPv4 specifier for listening on an address v.w.x.y on a
96 port z.
97 If the address string is a string in the format [x]:y, it is read
99 as IPv6 address x on a port y. Note that this might make the
100 service available via IPv4, too, depending on the BindIPv6Only=
101 setting (see below).
102 Note that SOCK_SEQPACKET (i.e. ListenSequentialPacket=) is only
104 available for AF_UNIX sockets. SOCK_STREAM (i.e. ListenStream=)
105 when used for IP sockets refers to TCP sockets, SOCK_DGRAM (i.e.
106 ListenDatagram=) to UDP.
107 These options may be specified more than once in which case
109 incoming traffic on any of the sockets will trigger service
110 activation, and all listed sockets will be passed to the service,
111 regardless of whether there is incoming traffic on them or not. If
112 the empty string is assigned to any of these options, the list of
113 addresses to listen on is reset, all prior uses of any of these
114 options will have no effect.
115 It is also possible to have more than one socket unit for the same
117 service when using Service=, and the service will receive all the
118 sockets configured in all the socket units. Sockets configured in
119 one unit are passed in the order of configuration, but no ordering
120 between socket units is specified.
121 If an IP address is used here, it is often desirable to listen on
123 it before the interface it is configured on is up and running, and
124 even regardless of whether it will be up and running at any point.
125 To deal with this, it is recommended to set the FreeBind= option
126 described below.
127 ListenFIFO=
129 Specifies a file system FIFO to listen on. This expects an absolute
130 file system path as argument. Behavior otherwise is very similar to
131 the ListenDatagram= directive above.
132 ListenSpecial=
134 Specifies a special file in the file system to listen on. This
135 expects an absolute file system path as argument. Behavior
136 otherwise is very similar to the ListenFIFO= directive above. Use
137 this to open character device nodes as well as special files in
138 /proc and /sys.
139 ListenNetlink=
141 Specifies a Netlink family to create a socket for to listen on.
142 This expects a short string referring to the AF_NETLINK family name
143 (such as audit or kobject-uevent) as argument, optionally suffixed
144 by a whitespace followed by a multicast group integer. Behavior
145 otherwise is very similar to the ListenDatagram= directive above.
146 ListenMessageQueue=
148 Specifies a POSIX message queue name to listen on. This expects a
149 valid message queue name (i.e. beginning with /). Behavior
150 otherwise is very similar to the ListenFIFO= directive above. On
151 Linux message queue descriptors are actually file descriptors and
152 can be inherited between processes.
153 BindIPv6Only=
155 Takes a one of default, both or ipv6-only. Controls the IPV6_V6ONLY
156 socket option (see ipv6(7) for details). If both, IPv6 sockets
157 bound will be accessible via both IPv4 and IPv6. If ipv6-only, they
158 will be accessible via IPv6 only. If default (which is the default,
159 surprise!), the system wide default setting is used, as controlled
160 by /proc/sys/net/ipv6/bindv6only, which in turn defaults to the
161 equivalent of both.
162 Backlog=
164 Takes an unsigned integer argument. Specifies the number of
165 connections to queue that have not been accepted yet. This setting
166 matters only for stream and sequential packet sockets. See
167 listen(2) for details. Defaults to SOMAXCONN (128).
168 BindToDevice=
170 Specifies a network interface name to bind this socket to. If set,
171 traffic will only be accepted from the specified network
172 interfaces. This controls the SO_BINDTODEVICE socket option (see
173 socket(7) for details). If this option is used, an automatic
174 dependency from this socket unit on the network interface device
175 unit (systemd.device(5) is created.
176 SocketUser=, SocketGroup=
178 Takes a UNIX user/group name. When specified, all AF_UNIX sockets
179 and FIFO nodes in the file system are owned by the specified user
180 and group. If unset (the default), the nodes are owned by the root
181 user/group (if run in system context) or the invoking user/group
182 (if run in user context). If only a user is specified but no group,
183 then the group is derived from the user's default group.
184 SocketMode=
186 If listening on a file system socket or FIFO, this option specifies
187 the file system access mode used when creating the file node. Takes
188 an access mode in octal notation. Defaults to 0666.
189 DirectoryMode=
191 If listening on a file system socket or FIFO, the parent
192 directories are automatically created if needed. This option
193 specifies the file system access mode used when creating these
194 directories. Takes an access mode in octal notation. Defaults to
195 0755.
196 Accept=
198 Takes a boolean argument. If true, a service instance is spawned
199 for each incoming connection and only the connection socket is
200 passed to it. If false, all listening sockets themselves are passed
201 to the started service unit, and only one service unit is spawned
202 for all connections (also see above). This value is ignored for
203 datagram sockets and FIFOs where a single service unit
204 unconditionally handles all incoming traffic. Defaults to false.
205 For performance reasons, it is recommended to write new daemons
206 only in a way that is suitable for Accept=false. A daemon listening
207 on an AF_UNIX socket may, but does not need to, call close(2) on
208 the received socket before exiting. However, it must not unlink the
209 socket from a file system. It should not invoke shutdown(2) on
210 sockets it got with Accept=false, but it may do so for sockets it
211 got with Accept=true set. Setting Accept=true is mostly useful to
212 allow daemons designed for usage with inetd(8) to work unmodified
213 with systemd socket activation.
214 For IPv4 and IPv6 connections the REMOTE_ADDR environment variable
216 will contain the remote IP, and REMOTE_PORT will contain the remote
217 port. This is the same as the format used by CGI. For SOCK_RAW the
218 port is the IP protocol.
219 MaxConnections=
221 The maximum number of connections to simultaneously run services
222 instances for, when Accept=true is set. If more concurrent
223 connections are coming in, they will be refused until at least one
224 existing connection is terminated. This setting has no effect on
225 sockets configured with Accept=false or datagram sockets. Defaults
226 to 64.
227 KeepAlive=
229 Takes a boolean argument. If true, the TCP/IP stack will send a
230 keep alive message after 2h (depending on the configuration of
231 /proc/sys/net/ipv4/tcp_keepalive_time) for all TCP streams accepted
232 on this socket. This controls the SO_KEEPALIVE socket option (see
233 socket(7) and the TCP Keepalive HOWTO[1] for details.) Defaults to
234 false.
235 KeepAliveTimeSec=
237 Takes time (in seconds) as argument . The connection needs to
238 remain idle before TCP starts sending keepalive probes. This
239 controls the TCP_KEEPIDLE socket option (see socket(7) and the TCP
240 Keepalive HOWTO[1] for details.) Defaults value is 7200 seconds (2
241 hours).
242 KeepAliveIntervalSec=
244 Takes time (in seconds) as argument between individual keepalive
245 probes, if the socket option SO_KEEPALIVE has been set on this
246 socket seconds as argument. This controls the TCP_KEEPINTVL socket
247 option (see socket(7) and the TCP Keepalive HOWTO[1] for details.)
248 Defaults value is 75 seconds.
249 KeepAliveProbes=
251 Takes integer as argument. It's the number of unacknowledged probes
252 to send before considering the connection dead and notifying the
253 application layer. This controls the TCP_KEEPCNT socket option (see
254 socket(7) and the TCP Keepalive HOWTO[1] for details.) Defaults
255 value is 9.
256 NoDelay=
258 Takes a boolean argument. TCP Nagle's algorithm works by combining
259 a number of small outgoing messages, and sending them all at once.
260 This controls the TCP_NODELAY socket option (see tcp(7) Defaults to
261 false.
262 Priority=
264 Takes an integer argument controlling the priority for all traffic
265 sent from this socket. This controls the SO_PRIORITY socket option
266 (see socket(7) for details.).
267 DeferAcceptSec=
269 Takes time (in seconds) as argument. If set, the listening process
270 will be awakened only when data arrives on the socket, and not
271 immediately when connection is established. When this option is
272 set, the TCP_DEFER_ACCEPT socket option will be used (see tcp(7)),
273 and the kernel will ignore initial ACK packets without any data.
274 The argument specifies the approximate amount of time the kernel
275 should wait for incoming data before falling back to the normal
276 behaviour of honouring empty ACK packets. This option is beneficial
277 for protocols where the client sends the data first (e.g. HTTP, in
278 contrast to SMTP), because the server process will not be woken up
279 unnecessarily before it can take any action.
280 If the client also uses the TCP_DEFER_ACCEPT option, the latency of
282 the initial connection may be reduced, because the kernel will send
283 data in the final packet establishing the connection (the third
284 packet in the "three-way handshake").
285 Disabled by default.
287 ReceiveBuffer=, SendBuffer=
289 Takes an integer argument controlling the receive or send buffer
290 sizes of this socket, respectively. This controls the SO_RCVBUF and
291 SO_SNDBUF socket options (see socket(7) for details.). The usual
292 suffixes K, M, G are supported and are understood to the base of
293 1024.
294 IPTOS=
296 Takes an integer argument controlling the IP Type-Of-Service field
297 for packets generated from this socket. This controls the IP_TOS
298 socket option (see ip(7) for details.). Either a numeric string or
299 one of low-delay, throughput, reliability or low-cost may be
300 specified.
301 IPTTL=
303 Takes an integer argument controlling the IPv4 Time-To-Live/IPv6
304 Hop-Count field for packets generated from this socket. This sets
305 the IP_TTL/IPV6_UNICAST_HOPS socket options (see ip(7) and ipv6(7)
306 for details.)
307 Mark=
309 Takes an integer value. Controls the firewall mark of packets
310 generated by this socket. This can be used in the firewall logic to
311 filter packets from this socket. This sets the SO_MARK socket
312 option. See iptables(8) for details.
313 ReusePort=
315 Takes a boolean value. If true, allows multiple bind(2)s to this
316 TCP or UDP port. This controls the SO_REUSEPORT socket option. See
317 socket(7) for details.
318 SmackLabel=, SmackLabelIPIn=, SmackLabelIPOut=
320 Takes a string value. Controls the extended attributes
321 "security.SMACK64", "security.SMACK64IPIN" and
322 "security.SMACK64IPOUT", respectively, i.e. the security label of
323 the FIFO, or the security label for the incoming or outgoing
324 connections of the socket, respectively. See Smack.txt[2] for
325 details.
326 SELinuxContextFromNet=
328 Takes a boolean argument. When true, systemd will attempt to figure
329 out the SELinux label used for the instantiated service from the
330 information handed by the peer over the network. Note that only the
331 security level is used from the information provided by the peer.
332 Other parts of the resulting SELinux context originate from either
333 the target binary that is effectively triggered by socket unit or
334 from the value of the SELinuxContext= option. This configuration
335 option only affects sockets with Accept= mode set to "true". Also
336 note that this option is useful only when MLS/MCS SELinux policy is
337 deployed. Defaults to "false".
338 PipeSize=
340 Takes a size in bytes. Controls the pipe buffer size of FIFOs
341 configured in this socket unit. See fcntl(2) for details. The usual
342 suffixes K, M, G are supported and are understood to the base of
343 1024.
344 MessageQueueMaxMessages=, MessageQueueMessageSize=
346 These two settings take integer values and control the mq_maxmsg
347 field or the mq_msgsize field, respectively, when creating the
348 message queue. Note that either none or both of these variables
349 need to be set. See mq_setattr(3) for details.
350 FreeBind=
352 Takes a boolean value. Controls whether the socket can be bound to
353 non-local IP addresses. This is useful to configure sockets
354 listening on specific IP addresses before those IP addresses are
355 successfully configured on a network interface. This sets the
356 IP_FREEBIND socket option. For robustness reasons it is recommended
357 to use this option whenever you bind a socket to a specific IP
358 address. Defaults to false.
359 Transparent=
361 Takes a boolean value. Controls the IP_TRANSPARENT socket option.
362 Defaults to false.
363 Broadcast=
365 Takes a boolean value. This controls the SO_BROADCAST socket
366 option, which allows broadcast datagrams to be sent from this
367 socket. Defaults to false.
368 PassCredentials=
370 Takes a boolean value. This controls the SO_PASSCRED socket option,
371 which allows AF_UNIX sockets to receive the credentials of the
372 sending process in an ancillary message. Defaults to false.
373 PassSecurity=
375 Takes a boolean value. This controls the SO_PASSSEC socket option,
376 which allows AF_UNIX sockets to receive the security context of the
377 sending process in an ancillary message. Defaults to false.
378 TCPCongestion=
380 Takes a string value. Controls the TCP congestion algorithm used by
381 this socket. Should be one of "westwood", "veno", "cubic", "lp" or
382 any other available algorithm supported by the IP stack. This
383 setting applies only to stream sockets.
384 ExecStartPre=, ExecStartPost=
386 Takes one or more command lines, which are executed before or after
387 the listening sockets/FIFOs are created and bound, respectively.
388 The first token of the command line must be an absolute filename,
389 then followed by arguments for the process. Multiple command lines
390 may be specified following the same scheme as used for
391 ExecStartPre= of service unit files.
392 ExecStopPre=, ExecStopPost=
394 Additional commands that are executed before or after the listening
395 sockets/FIFOs are closed and removed, respectively. Multiple
396 command lines may be specified following the same scheme as used
397 for ExecStartPre= of service unit files.
398 TimeoutSec=
400 Configures the time to wait for the commands specified in
401 ExecStartPre=, ExecStartPost=, ExecStopPre= and ExecStopPost= to
402 finish. If a command does not exit within the configured time, the
403 socket will be considered failed and be shut down again. All
404 commands still running will be terminated forcibly via SIGTERM, and
405 after another delay of this time with SIGKILL. (See KillMode= in
406 systemd.kill(5).) Takes a unit-less value in seconds, or a time
407 span value such as "5min 20s". Pass "0" to disable the timeout
408 logic. Defaults to DefaultTimeoutStartSec= from the manager
409 configuration file (see systemd-system.conf(5)).
410 Service=
412 Specifies the service unit name to activate on incoming traffic.
413 This setting is only allowed for sockets with Accept=no. It
414 defaults to the service that bears the same name as the socket
415 (with the suffix replaced). In most cases, it should not be
416 necessary to use this option.
417 RemoveOnStop=
419 Takes a boolean argument. If enabled, any file nodes created by
420 this socket unit are removed when it is stopped. This applies to
421 AF_UNIX sockets in the file system, POSIX message queues, FIFOs, as
422 well as any symlinks to them configured with Symlinks=. Normally,
423 it should not be necessary to use this option, and is not
424 recommended as services might continue to run after the socket unit
425 has been terminated and it should still be possible to communicate
426 with them via their file system node. Defaults to off.
427 Symlinks=
429 Takes a list of file system paths. The specified paths will be
430 created as symlinks to the AF_UNIX socket path or FIFO path of this
431 socket unit. If this setting is used, only one AF_UNIX socket in
432 the file system or one FIFO may be configured for the socket unit.
433 Use this option to manage one or more symlinked alias names for a
434 socket, binding their lifecycle together. Defaults to the empty
435 list.
436 Check systemd.exec(5) and systemd.kill(5) for more settings.
438
440 systemd(1), systemctl(1), systemd.unit(5), systemd.exec(5),
441 systemd.kill(5), systemd.resource-control(5), systemd.service(5),
442 systemd.directives(7)
443 For more extensive descriptions see the "systemd for Developers"
445 series: Socket Activation[3], Socket Activation, part II[4], Converting
446 inetd Services[5], Socket Activated Internet Services and OS
447 Containers[6].
448
450 1. TCP Keepalive HOWTO
451 http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/
452 2. Smack.txt
454 https://www.kernel.org/doc/Documentation/security/Smack.txt
455 3. Socket Activation
457 http://0pointer.de/blog/projects/socket-activation.html
458 4. Socket Activation, part II
460 http://0pointer.de/blog/projects/socket-activation2.html
461 5. Converting inetd Services
463 http://0pointer.de/blog/projects/inetd.html
464 6. Socket Activated Internet Services and OS Containers
466 http://0pointer.de/blog/projects/socket-activated-containers.html
467systemd 219 SYSTEMD.SOCKET(5)