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 unit, a matching service unit must exist, describing
30 the service to start on incoming traffic on the socket (see
31 systemd.service(5) for more information about .service units). 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=no is set. If Accept=yes
39 is set, a service template foo@.service must exist from which services
40 are instantiated for each incoming connection.
41 No implicit WantedBy= or RequiredBy= dependency from the socket to the
43 service is added. This means that the service may be started without
44 the socket, in which case it must be able to open sockets by itself. To
45 prevent this, an explicit Requires= dependency may be added.
46 Socket units may be used to implement on-demand starting of services,
48 as well as parallelized starting of services. See the blog stories
49 linked at the end for an introduction.
50 Note that the daemon software configured for socket activation with
52 socket units needs to be able to accept sockets from systemd, either
53 via systemd's native socket passing interface (see sd_listen_fds(3) for
54 details) or via the traditional inetd(8)-style socket passing (i.e.
55 sockets passed in via standard input and output, using
56 StandardInput=socket in the service file).
57 All network sockets allocated through .socket units are allocated in
59 the host's network namespace (see network_namespaces(7)). This does not
60 mean however that the service activated by a configured socket unit has
61 to be part of the host's network namespace as well. It is supported and
62 even good practice to run services in their own network namespace (for
63 example through PrivateNetwork=, see systemd.exec(5)), receiving only
64 the sockets configured through socket-activation from the host's
65 namespace. In such a set-up communication within the host's network
66 namespace is only permitted through the activation sockets passed in
67 while all sockets allocated from the service code itself will be
68 associated with the service's own namespace, and thus possibly subject
69 to a a much more restrictive configuration.
70
72 Implicit Dependencies
73 The following dependencies are implicitly added:
74 · Socket units automatically gain a Before= dependency on the service
76 units they activate.
77 · Socket units referring to file system paths (such as AF_UNIX
79 sockets or FIFOs) implicitly gain Requires= and After= dependencies
80 on all mount units necessary to access those paths.
81 · Socket units using the BindToDevice= setting automatically gain a
83 BindsTo= and After= dependency on the device unit encapsulating the
84 specified network interface.
85 Additional implicit dependencies may be added as result of execution
87 and resource control parameters as documented in systemd.exec(5) and
88 systemd.resource-control(5).
89 Default Dependencies
91 The following dependencies are added unless DefaultDependencies=no is
92 set:
93 · Socket units automatically gain a Before= dependency on
95 sockets.target.
96 · Socket units automatically gain a pair of After= and Requires=
98 dependency on sysinit.target, and a pair of Before= and Conflicts=
99 dependencies on shutdown.target. These dependencies ensure that the
100 socket unit is started before normal services at boot, and is
101 stopped on shutdown. Only sockets involved with early boot or late
102 system shutdown should disable DefaultDependencies= option.
103
105 Socket files must include a [Socket] section, which carries information
106 about the socket or FIFO it supervises. A number of options that may be
107 used in this section are shared with other unit types. These options
108 are documented in systemd.exec(5) and systemd.kill(5). The options
109 specific to the [Socket] section of socket units are the following:
110 ListenStream=, ListenDatagram=, ListenSequentialPacket=
112 Specifies an address to listen on for a stream (SOCK_STREAM),
113 datagram (SOCK_DGRAM), or sequential packet (SOCK_SEQPACKET)
114 socket, respectively. The address can be written in various
115 formats:
116 If the address starts with a slash ("/"), it is read as file system
118 socket in the AF_UNIX socket family.
119 If the address starts with an at symbol ("@"), it is read as
121 abstract namespace socket in the AF_UNIX family. The "@" is
122 replaced with a NUL character before binding. For details, see
123 unix(7).
124 If the address string is a single number, it is read as port number
126 to listen on via IPv6. Depending on the value of BindIPv6Only= (see
127 below) this might result in the service being available via both
128 IPv6 and IPv4 (default) or just via IPv6.
129 If the address string is a string in the format v.w.x.y:z, it is
131 read as IPv4 specifier for listening on an address v.w.x.y on a
132 port z.
133 If the address string is a string in the format [x]:y, it is read
135 as IPv6 address x on a port y. Note that this might make the
136 service available via IPv4, too, depending on the BindIPv6Only=
137 setting (see below).
138 If the address string is a string in the format "vsock:x:y", it is
140 read as CID "x" on a port "y" address in the AF_VSOCK family. The
141 CID is a unique 32-bit integer identifier in AF_VSOCK analogous to
142 an IP address. Specifying the CID is optional, and may be set to
143 the empty string.
144 Note that SOCK_SEQPACKET (i.e. ListenSequentialPacket=) is only
146 available for AF_UNIX sockets. SOCK_STREAM (i.e. ListenStream=)
147 when used for IP sockets refers to TCP sockets, SOCK_DGRAM (i.e.
148 ListenDatagram=) to UDP.
149 These options may be specified more than once, in which case
151 incoming traffic on any of the sockets will trigger service
152 activation, and all listed sockets will be passed to the service,
153 regardless of whether there is incoming traffic on them or not. If
154 the empty string is assigned to any of these options, the list of
155 addresses to listen on is reset, all prior uses of any of these
156 options will have no effect.
157 It is also possible to have more than one socket unit for the same
159 service when using Service=, and the service will receive all the
160 sockets configured in all the socket units. Sockets configured in
161 one unit are passed in the order of configuration, but no ordering
162 between socket units is specified.
163 If an IP address is used here, it is often desirable to listen on
165 it before the interface it is configured on is up and running, and
166 even regardless of whether it will be up and running at any point.
167 To deal with this, it is recommended to set the FreeBind= option
168 described below.
169 ListenFIFO=
171 Specifies a file system FIFO to listen on. This expects an absolute
172 file system path as argument. Behavior otherwise is very similar to
173 the ListenDatagram= directive above.
174 ListenSpecial=
176 Specifies a special file in the file system to listen on. This
177 expects an absolute file system path as argument. Behavior
178 otherwise is very similar to the ListenFIFO= directive above. Use
179 this to open character device nodes as well as special files in
180 /proc and /sys.
181 ListenNetlink=
183 Specifies a Netlink family to create a socket for to listen on.
184 This expects a short string referring to the AF_NETLINK family name
185 (such as audit or kobject-uevent) as argument, optionally suffixed
186 by a whitespace followed by a multicast group integer. Behavior
187 otherwise is very similar to the ListenDatagram= directive above.
188 ListenMessageQueue=
190 Specifies a POSIX message queue name to listen on. This expects a
191 valid message queue name (i.e. beginning with /). Behavior
192 otherwise is very similar to the ListenFIFO= directive above. On
193 Linux message queue descriptors are actually file descriptors and
194 can be inherited between processes.
195 ListenUSBFunction=
197 Specifies a USB FunctionFS[1] endpoints location to listen on, for
198 implementation of USB gadget functions. This expects an absolute
199 file system path of functionfs mount point as the argument.
200 Behavior otherwise is very similar to the ListenFIFO= directive
201 above. Use this to open the FunctionFS endpoint ep0. When using
202 this option, the activated service has to have the
203 USBFunctionDescriptors= and USBFunctionStrings= options set.
204 SocketProtocol=
206 Takes one of udplite or sctp. Specifies a socket protocol
207 (IPPROTO_UDPLITE) UDP-Lite (IPPROTO_SCTP) SCTP socket respectively.
208 BindIPv6Only=
210 Takes one of default, both or ipv6-only. Controls the IPV6_V6ONLY
211 socket option (see ipv6(7) for details). If both, IPv6 sockets
212 bound will be accessible via both IPv4 and IPv6. If ipv6-only, they
213 will be accessible via IPv6 only. If default (which is the default,
214 surprise!), the system wide default setting is used, as controlled
215 by /proc/sys/net/ipv6/bindv6only, which in turn defaults to the
216 equivalent of both.
217 Backlog=
219 Takes an unsigned integer argument. Specifies the number of
220 connections to queue that have not been accepted yet. This setting
221 matters only for stream and sequential packet sockets. See
222 listen(2) for details. Defaults to SOMAXCONN (128).
223 BindToDevice=
225 Specifies a network interface name to bind this socket to. If set,
226 traffic will only be accepted from the specified network
227 interfaces. This controls the SO_BINDTODEVICE socket option (see
228 socket(7) for details). If this option is used, an implicit
229 dependency from this socket unit on the network interface device
230 unit (systemd.device(5) is created. Note that setting this
231 parameter might result in additional dependencies to be added to
232 the unit (see above).
233 SocketUser=, SocketGroup=
235 Takes a UNIX user/group name. When specified, all AF_UNIX sockets
236 and FIFO nodes in the file system are owned by the specified user
237 and group. If unset (the default), the nodes are owned by the root
238 user/group (if run in system context) or the invoking user/group
239 (if run in user context). If only a user is specified but no group,
240 then the group is derived from the user's default group.
241 SocketMode=
243 If listening on a file system socket or FIFO, this option specifies
244 the file system access mode used when creating the file node. Takes
245 an access mode in octal notation. Defaults to 0666.
246 DirectoryMode=
248 If listening on a file system socket or FIFO, the parent
249 directories are automatically created if needed. This option
250 specifies the file system access mode used when creating these
251 directories. Takes an access mode in octal notation. Defaults to
252 0755.
253 Accept=
255 Takes a boolean argument. If true, a service instance is spawned
256 for each incoming connection and only the connection socket is
257 passed to it. If false, all listening sockets themselves are passed
258 to the started service unit, and only one service unit is spawned
259 for all connections (also see above). This value is ignored for
260 datagram sockets and FIFOs where a single service unit
261 unconditionally handles all incoming traffic. Defaults to false.
262 For performance reasons, it is recommended to write new daemons
263 only in a way that is suitable for Accept=no. A daemon listening on
264 an AF_UNIX socket may, but does not need to, call close(2) on the
265 received socket before exiting. However, it must not unlink the
266 socket from a file system. It should not invoke shutdown(2) on
267 sockets it got with Accept=no, but it may do so for sockets it got
268 with Accept=yes set. Setting Accept=yes is mostly useful to allow
269 daemons designed for usage with inetd(8) to work unmodified with
270 systemd socket activation.
271 For IPv4 and IPv6 connections, the REMOTE_ADDR environment variable
273 will contain the remote IP address, and REMOTE_PORT will contain
274 the remote port. This is the same as the format used by CGI. For
275 SOCK_RAW, the port is the IP protocol.
276 Writable=
278 Takes a boolean argument. May only be used in conjunction with
279 ListenSpecial=. If true, the specified special file is opened in
280 read-write mode, if false, in read-only mode. Defaults to false.
281 MaxConnections=
283 The maximum number of connections to simultaneously run services
284 instances for, when Accept=yes is set. If more concurrent
285 connections are coming in, they will be refused until at least one
286 existing connection is terminated. This setting has no effect on
287 sockets configured with Accept=no or datagram sockets. Defaults to
288 64.
289 MaxConnectionsPerSource=
291 The maximum number of connections for a service per source IP
292 address. This is very similar to the MaxConnections= directive
293 above. Disabled by default.
294 KeepAlive=
296 Takes a boolean argument. If true, the TCP/IP stack will send a
297 keep alive message after 2h (depending on the configuration of
298 /proc/sys/net/ipv4/tcp_keepalive_time) for all TCP streams accepted
299 on this socket. This controls the SO_KEEPALIVE socket option (see
300 socket(7) and the TCP Keepalive HOWTO[2] for details.) Defaults to
301 false.
302 KeepAliveTimeSec=
304 Takes time (in seconds) as argument. The connection needs to remain
305 idle before TCP starts sending keepalive probes. This controls the
306 TCP_KEEPIDLE socket option (see socket(7) and the TCP Keepalive
307 HOWTO[2] for details.) Defaults value is 7200 seconds (2 hours).
308 KeepAliveIntervalSec=
310 Takes time (in seconds) as argument between individual keepalive
311 probes, if the socket option SO_KEEPALIVE has been set on this
312 socket. This controls the TCP_KEEPINTVL socket option (see
313 socket(7) and the TCP Keepalive HOWTO[2] for details.) Defaults
314 value is 75 seconds.
315 KeepAliveProbes=
317 Takes an integer as argument. It is the number of unacknowledged
318 probes to send before considering the connection dead and notifying
319 the application layer. This controls the TCP_KEEPCNT socket option
320 (see socket(7) and the TCP Keepalive HOWTO[2] for details.)
321 Defaults value is 9.
322 NoDelay=
324 Takes a boolean argument. TCP Nagle's algorithm works by combining
325 a number of small outgoing messages, and sending them all at once.
326 This controls the TCP_NODELAY socket option (see tcp(7) Defaults to
327 false.
328 Priority=
330 Takes an integer argument controlling the priority for all traffic
331 sent from this socket. This controls the SO_PRIORITY socket option
332 (see socket(7) for details.).
333 DeferAcceptSec=
335 Takes time (in seconds) as argument. If set, the listening process
336 will be awakened only when data arrives on the socket, and not
337 immediately when connection is established. When this option is
338 set, the TCP_DEFER_ACCEPT socket option will be used (see tcp(7)),
339 and the kernel will ignore initial ACK packets without any data.
340 The argument specifies the approximate amount of time the kernel
341 should wait for incoming data before falling back to the normal
342 behavior of honoring empty ACK packets. This option is beneficial
343 for protocols where the client sends the data first (e.g. HTTP, in
344 contrast to SMTP), because the server process will not be woken up
345 unnecessarily before it can take any action.
346 If the client also uses the TCP_DEFER_ACCEPT option, the latency of
348 the initial connection may be reduced, because the kernel will send
349 data in the final packet establishing the connection (the third
350 packet in the "three-way handshake").
351 Disabled by default.
353 ReceiveBuffer=, SendBuffer=
355 Takes an integer argument controlling the receive or send buffer
356 sizes of this socket, respectively. This controls the SO_RCVBUF and
357 SO_SNDBUF socket options (see socket(7) for details.). The usual
358 suffixes K, M, G are supported and are understood to the base of
359 1024.
360 IPTOS=
362 Takes an integer argument controlling the IP Type-Of-Service field
363 for packets generated from this socket. This controls the IP_TOS
364 socket option (see ip(7) for details.). Either a numeric string or
365 one of low-delay, throughput, reliability or low-cost may be
366 specified.
367 IPTTL=
369 Takes an integer argument controlling the IPv4 Time-To-Live/IPv6
370 Hop-Count field for packets generated from this socket. This sets
371 the IP_TTL/IPV6_UNICAST_HOPS socket options (see ip(7) and ipv6(7)
372 for details.)
373 Mark=
375 Takes an integer value. Controls the firewall mark of packets
376 generated by this socket. This can be used in the firewall logic to
377 filter packets from this socket. This sets the SO_MARK socket
378 option. See iptables(8) for details.
379 ReusePort=
381 Takes a boolean value. If true, allows multiple bind(2)s to this
382 TCP or UDP port. This controls the SO_REUSEPORT socket option. See
383 socket(7) for details.
384 SmackLabel=, SmackLabelIPIn=, SmackLabelIPOut=
386 Takes a string value. Controls the extended attributes
387 "security.SMACK64", "security.SMACK64IPIN" and
388 "security.SMACK64IPOUT", respectively, i.e. the security label of
389 the FIFO, or the security label for the incoming or outgoing
390 connections of the socket, respectively. See Smack.txt[3] for
391 details.
392 SELinuxContextFromNet=
394 Takes a boolean argument. When true, systemd will attempt to figure
395 out the SELinux label used for the instantiated service from the
396 information handed by the peer over the network. Note that only the
397 security level is used from the information provided by the peer.
398 Other parts of the resulting SELinux context originate from either
399 the target binary that is effectively triggered by socket unit or
400 from the value of the SELinuxContext= option. This configuration
401 option only affects sockets with Accept= mode set to "true". Also
402 note that this option is useful only when MLS/MCS SELinux policy is
403 deployed. Defaults to "false".
404 PipeSize=
406 Takes a size in bytes. Controls the pipe buffer size of FIFOs
407 configured in this socket unit. See fcntl(2) for details. The usual
408 suffixes K, M, G are supported and are understood to the base of
409 1024.
410 MessageQueueMaxMessages=, MessageQueueMessageSize=
412 These two settings take integer values and control the mq_maxmsg
413 field or the mq_msgsize field, respectively, when creating the
414 message queue. Note that either none or both of these variables
415 need to be set. See mq_setattr(3) for details.
416 FreeBind=
418 Takes a boolean value. Controls whether the socket can be bound to
419 non-local IP addresses. This is useful to configure sockets
420 listening on specific IP addresses before those IP addresses are
421 successfully configured on a network interface. This sets the
422 IP_FREEBIND socket option. For robustness reasons it is recommended
423 to use this option whenever you bind a socket to a specific IP
424 address. Defaults to false.
425 Transparent=
427 Takes a boolean value. Controls the IP_TRANSPARENT socket option.
428 Defaults to false.
429 Broadcast=
431 Takes a boolean value. This controls the SO_BROADCAST socket
432 option, which allows broadcast datagrams to be sent from this
433 socket. Defaults to false.
434 PassCredentials=
436 Takes a boolean value. This controls the SO_PASSCRED socket option,
437 which allows AF_UNIX sockets to receive the credentials of the
438 sending process in an ancillary message. Defaults to false.
439 PassSecurity=
441 Takes a boolean value. This controls the SO_PASSSEC socket option,
442 which allows AF_UNIX sockets to receive the security context of the
443 sending process in an ancillary message. Defaults to false.
444 TCPCongestion=
446 Takes a string value. Controls the TCP congestion algorithm used by
447 this socket. Should be one of "westwood", "veno", "cubic", "lp" or
448 any other available algorithm supported by the IP stack. This
449 setting applies only to stream sockets.
450 ExecStartPre=, ExecStartPost=
452 Takes one or more command lines, which are executed before or after
453 the listening sockets/FIFOs are created and bound, respectively.
454 The first token of the command line must be an absolute filename,
455 then followed by arguments for the process. Multiple command lines
456 may be specified following the same scheme as used for
457 ExecStartPre= of service unit files.
458 ExecStopPre=, ExecStopPost=
460 Additional commands that are executed before or after the listening
461 sockets/FIFOs are closed and removed, respectively. Multiple
462 command lines may be specified following the same scheme as used
463 for ExecStartPre= of service unit files.
464 TimeoutSec=
466 Configures the time to wait for the commands specified in
467 ExecStartPre=, ExecStartPost=, ExecStopPre= and ExecStopPost= to
468 finish. If a command does not exit within the configured time, the
469 socket will be considered failed and be shut down again. All
470 commands still running will be terminated forcibly via SIGTERM, and
471 after another delay of this time with SIGKILL. (See KillMode= in
472 systemd.kill(5).) Takes a unit-less value in seconds, or a time
473 span value such as "5min 20s". Pass "0" to disable the timeout
474 logic. Defaults to DefaultTimeoutStartSec= from the manager
475 configuration file (see systemd-system.conf(5)).
476 Service=
478 Specifies the service unit name to activate on incoming traffic.
479 This setting is only allowed for sockets with Accept=no. It
480 defaults to the service that bears the same name as the socket
481 (with the suffix replaced). In most cases, it should not be
482 necessary to use this option. Note that setting this parameter
483 might result in additional dependencies to be added to the unit
484 (see above).
485 RemoveOnStop=
487 Takes a boolean argument. If enabled, any file nodes created by
488 this socket unit are removed when it is stopped. This applies to
489 AF_UNIX sockets in the file system, POSIX message queues, FIFOs, as
490 well as any symlinks to them configured with Symlinks=. Normally,
491 it should not be necessary to use this option, and is not
492 recommended as services might continue to run after the socket unit
493 has been terminated and it should still be possible to communicate
494 with them via their file system node. Defaults to off.
495 Symlinks=
497 Takes a list of file system paths. The specified paths will be
498 created as symlinks to the AF_UNIX socket path or FIFO path of this
499 socket unit. If this setting is used, only one AF_UNIX socket in
500 the file system or one FIFO may be configured for the socket unit.
501 Use this option to manage one or more symlinked alias names for a
502 socket, binding their lifecycle together. Note that if creation of
503 a symlink fails this is not considered fatal for the socket unit,
504 and the socket unit may still start. If an empty string is
505 assigned, the list of paths is reset. Defaults to an empty list.
506 FileDescriptorName=
508 Assigns a name to all file descriptors this socket unit
509 encapsulates. This is useful to help activated services identify
510 specific file descriptors, if multiple fds are passed. Services may
511 use the sd_listen_fds_with_names(3) call to acquire the names
512 configured for the received file descriptors. Names may contain any
513 ASCII character, but must exclude control characters and ":", and
514 must be at most 255 characters in length. If this setting is not
515 used, the file descriptor name defaults to the name of the socket
516 unit, including its .socket suffix.
517 TriggerLimitIntervalSec=, TriggerLimitBurst=
519 Configures a limit on how often this socket unit my be activated
520 within a specific time interval. The TriggerLimitIntervalSec= may
521 be used to configure the length of the time interval in the usual
522 time units "us", "ms", "s", "min", "h", ... and defaults to 2s (See
523 systemd.time(7) for details on the various time units understood).
524 The TriggerLimitBurst= setting takes a positive integer value and
525 specifies the number of permitted activations per time interval,
526 and defaults to 200 for Accept=yes sockets (thus by default
527 permitting 200 activations per 2s), and 20 otherwise (20
528 activations per 2s). Set either to 0 to disable any form of trigger
529 rate limiting. If the limit is hit, the socket unit is placed into
530 a failure mode, and will not be connectible anymore until
531 restarted. Note that this limit is enforced before the service
532 activation is enqueued.
533 Check systemd.exec(5) and systemd.kill(5) for more settings.
535
537 systemd(1), systemctl(1), systemd-system.conf(5), systemd.unit(5),
538 systemd.exec(5), systemd.kill(5), systemd.resource-control(5),
539 systemd.service(5), systemd.directives(7), sd_listen_fds(3),
540 sd_listen_fds_with_names(3)
541 For more extensive descriptions see the "systemd for Developers"
543 series: Socket Activation[4], Socket Activation, part II[5], Converting
544 inetd Services[6], Socket Activated Internet Services and OS
545 Containers[7].
546
548 1. USB FunctionFS
549 https://www.kernel.org/doc/Documentation/usb/functionfs.txt
550 2. TCP Keepalive HOWTO
552 http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/
553 3. Smack.txt
555 https://www.kernel.org/doc/Documentation/security/Smack.txt
556 4. Socket Activation
558 http://0pointer.de/blog/projects/socket-activation.html
559 5. Socket Activation, part II
561 http://0pointer.de/blog/projects/socket-activation2.html
562 6. Converting inetd Services
564 http://0pointer.de/blog/projects/inetd.html
565 7. Socket Activated Internet Services and OS Containers
567 http://0pointer.de/blog/projects/socket-activated-containers.html
568systemd 245 SYSTEMD.SOCKET(5)