models/Systemd/Section/Socket.pl

filter: Statementstmt 100% 23 / 23 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 8 / 8 Podpod n/a totaltotal 100% 31 / 31 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« models/Systemd/Section/ServiceUnit.pl ↑ Summary models/Systemd/Section/SocketUnit.pl »
1 #
2 # This file is part of Config-Model-Systemd
3 #
4 # This software is Copyright (c) 2008-2026 by Dominique Dumont.
5 #
6 # This is free software, licensed under:
7 #
8 # The GNU Lesser General Public License, Version 2.1, February 1999
9 #
10 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
Subroutine BEGIN: called CC=1 SCAR=0.0
11 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
Subroutine BEGIN: called CC=1 SCAR=0.0
12 1 ▶use v5.20;
Subroutine BEGIN: called CC=1 SCAR=0.0
Subroutine BEGIN: called CC=1 SCAR=0.0
13 1 ▶use utf8;
Subroutine BEGIN: called CC=1 SCAR=0.0
Subroutine BEGIN: called CC=1 SCAR=0.0
14  
15 return [
16 {
17 1 'accept' => [
18 '.*',
19 {
20 'type' => 'leaf',
21 'value_type' => 'uniline',
22 'warn' => 'Unexpected systemd parameter. Please contact cme author to update systemd model.'
23 }
24 ],
25 'class_description' => 'A unit configuration file whose name ends in
26 C<.socket> encodes information about an IPC or
27 network socket or a file system FIFO controlled and supervised by
28 systemd, for socket-based activation.
29  
30 This man page lists the configuration options specific to
31 this unit type. See
32 L<systemd.unit(5)>
33 for the common options of all unit configuration files. The common
34 configuration items are configured in the generic [Unit] and
35 [Install] sections. The socket specific configuration options are
36 configured in the [Socket] section.
37  
38 Additional options are listed in
39 L<systemd.exec(5)>,
40 which define the execution environment the
41 C<ExecStartPre>, C<ExecStartPost>,
42 C<ExecStopPre> and C<ExecStopPost>
43 commands are executed in, and in
44 L<systemd.kill(5)>,
45 which define the way the processes are terminated, and in
46 L<systemd.resource-control(5)>,
47 which configure resource control settings for the processes of the
48 socket.
49  
50 For each socket unit, a matching service unit must exist,
51 describing the service to start on incoming traffic on the socket
52 (see
53 L<systemd.service(5)>
54 for more information about .service units). The name of the
55 .service unit is by default the same as the name of the .socket
56 unit, but can be altered with the C<Service> option
57 described below. Depending on the setting of the
58 C<Accept> option described below, this .service
59 unit must either be named like the .socket unit, but with the
60 suffix replaced, unless overridden with C<Service>;
61 or it must be a template unit named the same way. Example: a
62 socket file C<foo.socket> needs a matching
63 service C<foo.service> if
64 C<Accept=no> is set. If
65 C<Accept=yes> is set, a service template
66 C<foo@.service> must exist from which services
67 are instantiated for each incoming connection.
68  
69 No implicit C<WantedBy> or
70 C<RequiredBy> dependency from the socket to the
71 service is added. This means that the service may be started
72 without the socket, in which case it must be able to open sockets
73 by itself. To prevent this, an explicit
74 C<Requires> dependency may be added.
75  
76 Socket units may be used to implement on-demand starting of
77 services, as well as parallelized starting of services. See the
78 blog stories linked at the end for an introduction.
79  
80 Note that the daemon software configured for socket activation with socket units needs to be able
81 to accept sockets from systemd, either via systemd\'s native socket passing interface (see
82 L<sd_listen_fds(3)> for
83 details about the precise protocol used and the order in which the file descriptors are passed) or via
84 traditional L<inetd(8)>-style
85 socket passing (i.e. sockets passed in via standard input and output, using
86 C<StandardInput=socket> in the service file).
87  
88 By default, network sockets allocated through C<.socket> units are allocated in the host\'s network
89 namespace (see L<network_namespaces(7)>). This
90 does not mean however that the service activated by a configured socket unit has to be part of the host\'s network
91 namespace as well. It is supported and even good practice to run services in their own network namespace (for
92 example through C<PrivateNetwork>, see
93 L<systemd.exec(5)>), receiving only
94 the sockets configured through socket-activation from the host\'s namespace. In such a set-up communication within
95 the host\'s network namespace is only permitted through the activation sockets passed in while all sockets allocated
96 from the service code itself will be associated with the service\'s own namespace, and thus possibly subject to a
97 restrictive configuration.
98  
99 Alternatively, it is possible to run a C<.socket> unit in another network namespace
100 by setting C<PrivateNetwork=yes> in combination with C<JoinsNamespaceOf>, see
101 L<systemd.exec(5)> and
102 L<systemd.unit(5)> for details.
103 This configuration class was generated from systemd documentation.
104 by L<parse-man.pl|https://github.com/dod38fr/config-model-systemd/contrib/parse-man.pl>
105 ',
106 'copyright' => [
107 '2010-2016 Lennart Poettering and others',
108 '2016 Dominique Dumont'
109 ],
110 'description' => {
111 'Accept' => 'Takes a boolean argument. If yes, a service instance is spawned for each incoming
112 connection and only the connection socket is passed to it. If no, all listening sockets themselves
113 are passed to the started service unit, and only one service unit is spawned for all connections
114 (also see above). This value is ignored for datagram sockets and FIFOs where a single service unit
115 unconditionally handles all incoming traffic. Defaults to C<no>.
116  
117 Typically, for performance sensitive services, a choice of C<Accept=no> is
118 preferable, since that way only the first connection will have to pay the activation resource
119 cost. On the other hand, for sporadically used services C<Accept=yes> can be preferable
120 as it simplifies the implementation (as the service program code only has to process a single
121 connection instead of handling multiple) and enables stronger security (since the various sandboxing
122 options can be used to isolate parallel connections from each other, as each is serviced by a
123 separate service instance and process).
124  
125 A service listening on an C<AF_UNIX> socket may, but does not need to, call
126 L<close(2)> on the
127 received socket before exiting. However, it must not unlink the socket from a file system. It should
128 not invoke
129 L<shutdown(2)> on
130 sockets it got with C<Accept=no>, but it may do so for sockets it got with
131 C<Accept=yes> set.
132  
133 Setting C<Accept=yes> is in particular useful for allowing daemons designed for
134 usage with L<inetd(8)> to work
135 unmodified with systemd socket activation.
136  
137 Note that depending on this setting the services activated by units of this type are either
138 regular services (in case of C<Accept>=C<no>) or instances of templated
139 services (in case of C<Accept>=C<yes>). See the Description section
140 above for a more detailed discussion of the naming rules of triggered services.
141  
142 For IPv4 and IPv6 connections, the C<$REMOTE_ADDR> environment variable will
143 contain the remote IP address, and C<$REMOTE_PORT> will contain the remote port
144 number. These two variables correspond to those defined by the CGI interface for web services (see
145 L<RFC 3875|https://datatracker.ietf.org/doc/html/rfc3875>).
146  
147 For C<AF_UNIX> socket connections, the C<$REMOTE_ADDR>
148 environment variable will contain either the remote socket\'s file system path starting with a slash
149 (C</>) or its address in the abstract namespace starting with an at symbol
150 (C<@>). If the socket is unnamed, C<$REMOTE_ADDR> will not be
151 set.
152  
153 If C<Accept=yes> is used, the activated service process will have set the
154 C<$SO_COOKIE> environment variable to the Linux socket cookie, formatted as decimal
155 integer. The socket cookie can otherwise be acquired via L<getsockopt(7)>.
156  
157 It is recommended to set C<CollectMode=inactive-or-failed> for service
158 instances activated via C<Accept=yes>, to ensure that failed connection services are
159 cleaned up and released from memory, and do not accumulate.',
160 'AcceptFileDescriptors' => 'Takes a boolean value. This controls the C<SO_PASSRIGHTS> socket
161 option, which when disabled prohibits the peer from sending C<SCM_RIGHTS>
162 ancillary messages (aka file descriptors) via C<AF_UNIX> sockets. Defaults to
163 C<true>.',
164 'Backlog' => 'Takes an unsigned 32-bit integer argument. Specifies the number of connections to
165 queue that have not been accepted yet. This setting matters only for stream and sequential packet
166 sockets. See
167 L<listen(2)> for
168 details. Defaults to 4294967295. Note that this value is silently capped by the
169 C<net.core.somaxconn> sysctl, which typically defaults to 4096, so typically
170 the sysctl is the setting that actually matters.',
171 'BindIPv6Only' => 'Takes one of C<default>,
172 C<both> or C<ipv6-only>. Controls
173 the IPV6_V6ONLY socket option (see
174 L<ipv6(7)>
175 for details). If C<both>, IPv6 sockets bound
176 will be accessible via both IPv4 and IPv6. If
177 C<ipv6-only>, they will be accessible via IPv6
178 only. If C<default> (which is the default,
179 surprise!), the system wide default setting is used, as
180 controlled by
181 C</proc/sys/net/ipv6/bindv6only>, which in
182 turn defaults to the equivalent of
183 C<both>.',
184 'BindToDevice' => 'Specifies a network interface name to bind this socket to. If set, traffic will only
185 be accepted from the specified network interfaces. This controls the
186 C<SO_BINDTODEVICE> socket option (see L<socket(7)> for
187 details). If this option is used, an implicit dependency from this socket unit on the network
188 interface device unit is created
189 (see L<systemd.device(5)>).
190 Note that setting this parameter might result in additional dependencies to be added to the unit (see
191 above).',
192 'Broadcast' => 'Takes a boolean value. This controls the C<SO_BROADCAST> socket
193 option, which allows broadcast datagrams to be sent from this socket. Defaults to
194 C<false>.',
195 'DeferAcceptSec' => 'Takes time (in seconds) as argument. If set,
196 the listening process will be awakened only when data arrives
197 on the socket, and not immediately when connection is
198 established. When this option is set, the
199 C<TCP_DEFER_ACCEPT> socket option will be
200 used (see
201 L<tcp(7)>),
202 and the kernel will ignore initial ACK packets without any
203 data. The argument specifies the approximate amount of time
204 the kernel should wait for incoming data before falling back
205 to the normal behavior of honoring empty ACK packets. This
206 option is beneficial for protocols where the client sends the
207 data first (e.g. HTTP, in contrast to SMTP), because the
208 server process will not be woken up unnecessarily before it
209 can take any action.
210  
211 If the client also uses the
212 C<TCP_DEFER_ACCEPT> option, the latency of
213 the initial connection may be reduced, because the kernel will
214 send data in the final packet establishing the connection (the
215 third packet in the "three-way handshake").
216  
217 Disabled by default.',
218 'DeferTrigger' => 'Takes a boolean argument, or C<patient>. May only be used when C<Accept=no>.
219 If enabled, job mode C<lenient> instead of C<replace> is used when
220 triggering the service, which means currently activating/running units that conflict with the service
221 won\'t be disturbed/brought down. Furthermore, if a conflict exists, the socket unit will wait for
222 current job queue to complete and potentially defer the activation by then. An upper limit of total time
223 to wait can be configured via C<DeferTriggerMaxSec>. If set to C<yes>,
224 the socket unit will fail if all jobs have finished or the timeout has been reached but the conflict remains.
225 If C<patient>, always wait until C<DeferTriggerMaxSec> elapses.
226 Defaults to no.
227  
228 This setting is particularly useful if the socket unit should stay active across switch-root/soft-reboot
229 operations while the triggered service is stopped.',
230 'DeferTriggerMaxSec' => 'Configures the maximum time to defer the triggering when C<DeferTrigger>
231 is enabled. If the service cannot be activated within the specified time, the socket will be considered
232 failed and get terminated. Takes a unit-less value in seconds, or a time span value such as "5min 20s".
233 Pass C<0> or C<infinity> to disable the timeout logic (the default).
234 ',
235 'DirectoryMode' => 'If listening on a file system socket or FIFO,
236 the parent directories are automatically created if needed.
237 This option specifies the file system access mode used when
238 creating these directories. Takes an access mode in octal
239 notation. Defaults to 0755.',
240 'ExecStartPost' => 'Takes one or more command lines, which are
241 executed before or after the listening sockets/FIFOs are
242 created and bound, respectively. The first token of the
243 command line must be an absolute filename, then followed by
244 arguments for the process. Multiple command lines may be
245 specified following the same scheme as used for
246 C<ExecStartPre> of service unit
247 files.',
248 'ExecStartPre' => '*ExecStartPost',
249 'ExecStopPost' => 'Additional commands that are executed before
250 or after the listening sockets/FIFOs are closed and removed,
251 respectively. Multiple command lines may be specified
252 following the same scheme as used for
253 C<ExecStartPre> of service unit
254 files.',
255 'ExecStopPre' => '*ExecStopPost',
256 'FileDescriptorName' => 'Assigns a name to all file descriptors this socket unit encapsulates.
257 This is useful to help activated services identify specific file descriptors, if multiple fds are passed.
258 Services may use the
259 L<sd_listen_fds_with_names(3)>
260 call to acquire the names configured for the received file descriptors. Names may contain any ASCII character,
261 but must exclude control characters and C<:>, and must be at most 255 characters in length.
262 If this setting is not used, the file descriptor name defaults to the name of the socket unit
263 (including its C<.socket> suffix) when C<Accept=no>,
264 C<connection> otherwise.',
265 'FlushPending' => 'Takes a boolean argument. May only be used when
266 C<Accept=no>. If yes, the socket\'s buffers are cleared after the
267 triggered service exited. This causes any pending data to be
268 flushed and any pending incoming connections to be rejected. If no, the
269 socket\'s buffers will not be cleared, permitting the service to handle any
270 pending connections after restart, which is the usually expected behaviour.
271 Defaults to C<no>.
272 ',
273 'FreeBind' => 'Takes a boolean value. Controls whether the socket can be bound to non-local IP
274 addresses. This is useful to configure sockets listening on specific IP addresses before those IP
275 addresses are successfully configured on a network interface. This sets the
276 C<IP_FREEBIND>/C<IPV6_FREEBIND> socket option. For robustness
277 reasons it is recommended to use this option whenever you bind a socket to a specific IP
278 address. Defaults to C<false>.',
279 'IPTOS' => 'Takes an integer argument controlling the IP Type-Of-Service field for packets
280 generated from this socket. This controls the C<IP_TOS> socket option (see
281 L<ip(7)> for
282 details.). Either a numeric string or one of C<low-delay>, C<throughput>,
283 C<reliability> or C<low-cost> may be specified.',
284 'IPTTL' => 'Takes an integer argument controlling the IPv4 Time-To-Live/IPv6 Hop-Count field for
285 packets generated from this socket. This sets the
286 C<IP_TTL>/C<IPV6_UNICAST_HOPS> socket options (see L<ip(7)> and
287 L<ipv6(7)> for
288 details.)',
289 'KeepAlive' => 'Takes a boolean argument. If true, the TCP/IP stack will send a keep alive message
290 after 2h (depending on the configuration of
291 C</proc/sys/net/ipv4/tcp_keepalive_time>) for all TCP streams accepted on this
292 socket. This controls the C<SO_KEEPALIVE> socket option (see L<socket(7)> and
293 the L<TCP Keepalive
294 HOWTO|http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/> for details.) Defaults to C<false>.',
295 'KeepAliveIntervalSec' => 'Takes time (in seconds) as argument between individual keepalive probes, if the
296 socket option C<SO_KEEPALIVE> has been set on this socket. This controls the
297 C<TCP_KEEPINTVL> socket option (see L<socket(7)> and
298 the L<TCP Keepalive
299 HOWTO|http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/> for details.) Default value is 75 seconds.',
300 'KeepAliveProbes' => 'Takes an integer as argument. It is the number of
301 unacknowledged probes to send before considering the
302 connection dead and notifying the application layer. This
303 controls the TCP_KEEPCNT socket option (see
304 L<socket(7)>
305 and the L<TCP
306 Keepalive HOWTO|http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/> for details.) Default value is
307 9.',
308 'KeepAliveTimeSec' => 'Takes time (in seconds) as argument. The connection needs to remain
309 idle before TCP starts sending keepalive probes. This controls the TCP_KEEPIDLE
310 socket option (see
311 L<socket(7)>
312 and the L<TCP
313 Keepalive HOWTO|http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/> for details.)
314 Default value is 7200 seconds (2 hours).',
315 'ListenDatagram' => 'Specifies an address to listen on for a stream
316 (C<SOCK_STREAM>), datagram
317 (C<SOCK_DGRAM>), or sequential packet
318 (C<SOCK_SEQPACKET>) socket, respectively.
319 The address can be written in various formats:
320  
321 If the address starts with a slash
322 (C</>), it is read as file system socket in
323 the C<AF_UNIX> socket family.
324  
325 If the address starts with an at symbol
326 (C<@>), it is read as abstract namespace
327 socket in the C<AF_UNIX> family. The
328 C<@> is replaced with a
329 C<NUL> character before binding. For
330 details, see
331 L<unix(7)>.
332  
333 If the address string is a single number, it is read as
334 port number to listen on via IPv6. Depending on the value of
335 C<BindIPv6Only> (see below) this might result
336 in the service being available via both IPv6 and IPv4
337 (default) or just via IPv6.
338  
339 If the address string is a string in the format
340 C<v.w.x.y:z>, it is interpreted
341 as IPv4 address v.w.x.y and port z.
342  
343 If the address string is a string in the format
344 C<[x]:y>, it is interpreted as
345 IPv6 address x and port y. An optional
346 interface scope (interface name or number) may be specified after a C<%> symbol:
347 C<[x]:y%dev>.
348 Interface scopes are only useful with link-local addresses, because the kernel ignores them in other
349 cases. Note that if an address is specified as IPv6, it might still make the service available via
350 IPv4 too, depending on the C<BindIPv6Only> setting (see below).
351  
352 If the address string is a string in the format
353 C<vsock:x:y>, it is read as CID
354 x on a port y address in the
355 C<AF_VSOCK> family. The CID is a unique 32-bit integer identifier in
356 C<AF_VSOCK> analogous to an IP address. Specifying the CID is optional, and may be
357 set to the empty string. C<vsock> may be replaced with
358 C<vsock-stream>, C<vsock-dgram> or C<vsock-seqpacket>
359 to force usage of the corresponding socket type.
360  
361 Note that C<SOCK_SEQPACKET> (i.e.
362 C<ListenSequentialPacket>) is only available
363 for C<AF_UNIX> sockets.
364 C<SOCK_STREAM> (i.e.
365 C<ListenStream>) when used for IP sockets
366 refers to TCP sockets, C<SOCK_DGRAM> (i.e.
367 C<ListenDatagram>) to UDP.
368  
369 These options may be specified more than once, in which
370 case incoming traffic on any of the sockets will trigger
371 service activation, and all listed sockets will be passed to
372 the service, regardless of whether there is incoming traffic
373 on them or not. If the empty string is assigned to any of
374 these options, the list of addresses to listen on is reset,
375 all prior uses of any of these options will have no
376 effect.
377  
378 It is also possible to have more than one socket unit
379 for the same service when using C<Service>,
380 and the service will receive all the sockets configured in all
381 the socket units. Sockets configured in one unit are passed in
382 the order of configuration, but no ordering between socket
383 units is specified.
384  
385 If an IP address is used here, it is often desirable to
386 listen on it before the interface it is configured on is up
387 and running, and even regardless of whether it will be up and
388 running at any point. To deal with this, it is recommended to
389 set the C<FreeBind> option described
390 below.',
391 'ListenFIFO' => 'Specifies a file system FIFO (see L<fifo(7)> for
392 details) to listen on. This expects an absolute file system path as argument. Behavior otherwise is
393 very similar to the C<ListenDatagram> directive above.',
394 'ListenMessageQueue' => 'Specifies a POSIX message queue name to listen on (see L<mq_overview(7)>
395 for details). This expects a valid message queue name (i.e. beginning with
396 C</>). Behavior otherwise is very similar to the C<ListenFIFO>
397 directive above. On Linux message queue descriptors are actually file descriptors and can be
398 inherited between processes.',
399 'ListenNetlink' => 'Specifies a Netlink family to create a socket
400 for to listen on. This expects a short string referring to the
401 C<AF_NETLINK> family name (such as
402 C<audit> or C<kobject-uevent>)
403 as argument, optionally suffixed by a whitespace followed by a
404 multicast group integer. Behavior otherwise is very similar to
405 the C<ListenDatagram> directive
406 above.',
407 'ListenSequentialPacket' => '*ListenDatagram',
408 'ListenSpecial' => 'Specifies a special file in the file system to
409 listen on. This expects an absolute file system path as
410 argument. Behavior otherwise is very similar to the
411 C<ListenFIFO> directive above. Use this to
412 open character device nodes as well as special files in
413 C</proc/> and
414 C</sys/>.',
415 'ListenStream' => '*ListenDatagram',
416 'ListenUSBFunction' => 'Specifies a L<USB
417 FunctionFS|https://docs.kernel.org/usb/functionfs.html> endpoints location to listen on, for
418 implementation of USB gadget functions. This expects an
419 absolute file system path of a FunctionFS mount point as the argument.
420 Behavior otherwise is very similar to the C<ListenFIFO>
421 directive above. Use this to open the FunctionFS endpoint
422 C<ep0>. When using this option, the
423 activated service has to have the
424 C<USBFunctionDescriptors> and
425 C<USBFunctionStrings> options set.
426 ',
427 'Mark' => 'Takes an integer value. Controls the firewall mark of packets generated by this
428 socket. This can be used in the firewall logic to filter packets from this socket. This sets the
429 C<SO_MARK> socket option. See L<iptables(8)> for
430 details.',
431 'MaxConnections' => 'The maximum number of connections to simultaneously run services instances for, when
432 C<Accept=yes> is set. If more concurrent connections are coming in, they will be refused
433 until at least one existing connection is terminated. This setting has no effect on sockets configured
434 with C<Accept=no> or datagram sockets. Defaults to 64.',
435 'MaxConnectionsPerSource' => 'The maximum number of connections for a service per source IP address (in case of
436 IPv4/IPv6), per source CID (in case of C<AF_VSOCK>), or source UID (in case of
437 C<AF_UNIX>). This is very similar to the C<MaxConnections>
438 directive above. Defaults to 0, i.e. disabled.',
439 'MessageQueueMaxMessages' => 'These two settings take integer values and
440 control the mq_maxmsg field or the mq_msgsize field,
441 respectively, when creating the message queue. Note that
442 either none or both of these variables need to be set. See
443 L<mq_setattr(3)>
444 for details.',
445 'NoDelay' => 'Takes a boolean argument. TCP Nagle\'s
446 algorithm works by combining a number of small outgoing
447 messages, and sending them all at once. This controls the
448 TCP_NODELAY socket option (see
449 L<tcp(7)>).
450 Defaults to C<false>.',
451 'PassCredentials' => 'Takes a boolean value. This controls the C<SO_PASSCRED> socket
452 option, which allows C<AF_UNIX> sockets to receive the credentials of the sending
453 process in an ancillary message. Defaults to C<false>.',
454 'PassFileDescriptorsToExec' => 'Takes a boolean argument. Defaults to off. If enabled, file descriptors created by
455 the socket unit are passed to C<ExecStartPost>, C<ExecStopPre>, and
456 C<ExecStopPost> commands from the socket unit. The passed file descriptors can be
457 accessed with
458 L<sd_listen_fds(3)> as
459 if the commands were invoked from the associated service units. Note that
460 C<ExecStartPre> command cannot access socket file descriptors.',
461 'PassPIDFD' => 'Takes a boolean value. This controls the C<SO_PASSPIDFD> socket
462 option, which allows C<AF_UNIX> sockets to receive the pidfd of the sending
463 process in an ancillary message. Defaults to C<false>.',
464 'PassPacketInfo' => 'Takes a boolean value. This controls the C<IP_PKTINFO>,
465 C<IPV6_RECVPKTINFO>, C<NETLINK_PKTINFO> or
466 C<PACKET_AUXDATA> socket options, which enable reception of additional per-packet
467 metadata as ancillary message, on C<AF_INET>, C<AF_INET6>,
468 C<AF_UNIX> and C<AF_PACKET> sockets. Defaults to
469 C<false>.',
470 'PassSecurity' => 'Takes a boolean value. This controls the C<SO_PASSSEC> socket
471 option, which allows C<AF_UNIX> sockets to receive the security context of the
472 sending process in an ancillary message. Defaults to C<false>.',
473 'PipeSize' => 'Takes a size in bytes. Controls the pipe
474 buffer size of FIFOs configured in this socket unit. See
475 L<fcntl(2)>
476 for details. The usual suffixes K, M, G are supported and are
477 understood to the base of 1024.',
478 'PollLimitBurst' => 'Configures a limit on how often polling events on the file descriptors backing this
479 socket unit will be considered. This pair of settings is similar to
480 C<TriggerLimitIntervalSec>/C<TriggerLimitBurst> but instead of
481 putting a (fatal) limit on the activation frequency puts a (transient) limit on the polling
482 frequency. The expected parameter syntax and range are identical to that of the aforementioned
483 options, and can be disabled the same way.
484  
485 If the polling limit is hit polling is temporarily disabled on it until the specified time
486 window passes. The polling limit hence slows down connection attempts if hit, but unlike the trigger
487 limit will not cause permanent failures. It\'s the recommended mechanism to deal with DoS attempts
488 through packet flooding.
489  
490 The polling limit is enforced per file descriptor to listen on, as opposed to the trigger limit
491 which is enforced for the entire socket unit. This distinction matters for socket units that listen
492 on multiple file descriptors (i.e. have multiple C<ListenXYZ> stanzas).
493  
494 These setting defaults to 150 (in case of C<Accept=yes>) and 15 (otherwise)
495 polling events per 2s. This is considerably lower than the default values for the trigger limit (see
496 above) and means that the polling limit should typically ensure the trigger limit is never hit,
497 unless one of them is reconfigured or disabled.',
498 'PollLimitIntervalSec' => '*PollLimitBurst',
499 'Priority' => 'Takes an integer argument controlling the priority for all traffic sent from this
500 socket. This controls the C<SO_PRIORITY> socket option (see L<socket(7)> for
501 details.).',
502 'ReceiveBuffer' => 'Takes an integer argument controlling the receive or send buffer sizes of this
503 socket, respectively. This controls the C<SO_RCVBUF> and
504 C<SO_SNDBUF> socket options (see L<socket(7)> for
505 details.). The usual suffixes K, M, G are supported and are understood to the base of
506 1024.',
507 'RemoveOnStop' => 'Takes a boolean argument. If enabled, any file nodes created by this socket unit are
508 removed when it is stopped. This applies to C<AF_UNIX> sockets in the file system,
509 POSIX message queues, FIFOs, as well as any symlinks to them configured with
510 C<Symlinks>. Normally, it should not be necessary to use this option, and is not
511 recommended as services might continue to run after the socket unit has been terminated and it should
512 still be possible to communicate with them via their file system node. Defaults to
513 off.',
514 'ReusePort' => 'Takes a boolean value. If true, allows multiple
515 L<bind(2)>s to this TCP
516 or UDP port. This controls the C<SO_REUSEPORT> socket option. See L<socket(7)> for
517 details.',
518 'SELinuxContextFromNet' => 'Takes a boolean argument. When true, systemd
519 will attempt to figure out the SELinux label used for the
520 instantiated service from the information handed by the peer
521 over the network. Note that only the security level is used
522 from the information provided by the peer. Other parts of the
523 resulting SELinux context originate from either the target
524 binary that is effectively triggered by socket unit or from
525 the value of the C<SELinuxContext> option.
526 This configuration option applies only when activated service
527 is passed in single socket file descriptor, i.e. service
528 instances that have standard input connected to a socket or
529 services triggered by exactly one socket unit. Also note
530 that this option is useful only when MLS/MCS SELinux policy
531 is deployed. Defaults to
532 C<false>.',
533 'SendBuffer' => '*ReceiveBuffer',
534 'Service' => 'Specifies the service unit name to activate on
535 incoming traffic. This setting is only allowed for sockets
536 with C<Accept=no>. It defaults to the service
537 that bears the same name as the socket (with the suffix
538 replaced). In most cases, it should not be necessary to use
539 this option. Note that setting this parameter might result in
540 additional dependencies to be added to the unit (see
541 above).',
542 'SmackLabel' => 'Takes a string value. Controls the extended
543 attributes C<security.SMACK64>,
544 C<security.SMACK64IPIN> and
545 C<security.SMACK64IPOUT>, respectively, i.e.
546 the security label of the FIFO, or the security label for the
547 incoming or outgoing connections of the socket, respectively.
548 See L<Smack|https://docs.kernel.org/admin-guide/LSM/Smack.html>
549 for details.',
550 'SmackLabelIPIn' => '*SmackLabel',
551 'SmackLabelIPOut' => '*SmackLabel',
552 'SocketGroup' => 'Takes a UNIX user/group name. When specified, all C<AF_UNIX>
553 sockets, FIFO nodes, and message queues are owned by the specified user and group. If unset (the
554 default), the nodes are owned by the root user/group (if run in system context) or the invoking
555 user/group (if run in user context). If only a user is specified but no group, then the group is
556 derived from the user\'s default group.',
557 'SocketMode' => 'If listening on a file system socket, FIFO, or message queue, this option specifies
558 the file system access mode used when creating the file node. Takes an access mode in octal notation.
559 Defaults to 0666.',
560 'SocketProtocol' => 'Takes one of C<udplite>,
561 C<sctp> or C<mptcp>. The socket will use
562 the UDP-Lite (C<IPPROTO_UDPLITE>), SCTP
563 (C<IPPROTO_SCTP>) or MPTCP
564 (C<IPPROTO_MPTCP>) protocol, respectively.',
565 'SocketUser' => '*SocketGroup',
566 'Symlinks' => 'Takes a list of file system paths. The specified paths will be created as symlinks to the
567 C<AF_UNIX> socket path or FIFO path of this socket unit. If this setting is used, only one
568 C<AF_UNIX> socket in the file system or one FIFO may be configured for the socket unit. Use
569 this option to manage one or more symlinked alias names for a socket, binding their lifecycle together. Note
570 that if creation of a symlink fails this is not considered fatal for the socket unit, and the socket unit may
571 still start. If an empty string is assigned, the list of paths is reset. Defaults to an empty
572 list.',
573 'TCPCongestion' => 'Takes a string value. Controls the TCP congestion algorithm used by this
574 socket. Should be one of C<westwood>, C<reno>,
575 C<cubic>, C<lp> or any other available algorithm supported by the IP
576 stack. This setting applies only to stream sockets.',
577 'TimeoutSec' => 'Configures the time to wait for the commands
578 specified in C<ExecStartPre>,
579 C<ExecStartPost>,
580 C<ExecStopPre> and
581 C<ExecStopPost> to finish. If a command does
582 not exit within the configured time, the socket will be
583 considered failed and be shut down again. All commands still
584 running will be terminated forcibly via
585 C<SIGTERM>, and after another delay of this
586 time with C<SIGKILL>. (See
587 C<KillMode> in
588 L<systemd.kill(5)>.)
589 Takes a unit-less value in seconds, or a time span value such
590 as "5min 20s". Pass C<0> to disable the
591 timeout logic. Defaults to
592 C<DefaultTimeoutStartSec> from the manager
593 configuration file (see
594 L<systemd-system.conf(5)>).
595 ',
596 'Timestamping' => "Takes one of C<off>, C<us> (alias:
597 C<usec>, C<\x{3bc}s>) or C<ns> (alias:
598 C<nsec>). This controls the C<SO_TIMESTAMP> or
599 C<SO_TIMESTAMPNS> socket options, and enables whether ingress network traffic shall
600 carry timestamping metadata. Defaults to C<off>.",
601 'Transparent' => 'Takes a boolean value. Controls the
602 C<IP_TRANSPARENT>/C<IPV6_TRANSPARENT> socket option. Defaults to
603 C<false>.',
604 'TriggerLimitBurst' => "Configures a limit on how often this socket unit may be activated within a specific
605 time interval. The C<TriggerLimitIntervalSec> setting may be used to configure the
606 length of the time interval in the usual time units C<us>, C<ms>,
607 C<s>, C<min>, C<h>, \x{2026} and defaults to 2s (See
608 L<systemd.time(7)> for
609 details on the various time units understood). The C<TriggerLimitBurst> setting
610 takes a positive integer value and specifies the number of permitted activations per time interval,
611 and defaults to 200 for C<Accept=yes> sockets (thus by default permitting 200
612 activations per 2s), and 20 otherwise (20 activations per 2s). Set either to 0 to disable any form of
613 trigger rate limiting.
614  
615 If the limit is hit, the socket unit is placed into a failure mode, and will not be connectible
616 anymore until restarted. Note that this limit is enforced before the service activation is
617 enqueued.
618  
619 Compare with C<PollLimitIntervalSec>/C<PollLimitBurst>
620 described below, which implements a temporary slowdown if a socket unit is flooded with incoming
621 traffic, as opposed to the permanent failure state
622 C<TriggerLimitIntervalSec>/C<TriggerLimitBurst> results in.",
623 'TriggerLimitIntervalSec' => '*TriggerLimitBurst',
624 'Writable' => 'Takes a boolean argument. May only be used in
625 conjunction with C<ListenSpecial>. If true,
626 the specified special file is opened in read-write mode, if
627 false, in read-only mode. Defaults to false.'
628 },
629 'element' => [
630 'ListenStream',
631 {
632 'cargo' => {
633 'type' => 'leaf',
634 'value_type' => 'uniline'
635 },
636 'type' => 'list'
637 },
638 'ListenDatagram',
639 '*ListenStream',
640 'ListenSequentialPacket',
641 '*ListenStream',
642 'ListenFIFO',
643 '*ListenStream',
644 'ListenSpecial',
645 '*ListenStream',
646 'ListenNetlink',
647 '*ListenStream',
648 'ListenMessageQueue',
649 '*ListenStream',
650 'ListenUSBFunction',
651 '*ListenStream',
652 'SocketProtocol',
653 {
654 'choice' => [
655 'mptcp',
656 'sctp',
657 'udplite'
658 ],
659 'type' => 'leaf',
660 'value_type' => 'enum'
661 },
662 'BindIPv6Only',
663 {
664 'choice' => [
665 'both',
666 'default',
667 'ipv6-only'
668 ],
669 'type' => 'leaf',
670 'value_type' => 'enum'
671 },
672 'Backlog',
673 {
674 'type' => 'leaf',
675 'value_type' => 'uniline'
676 },
677 'BindToDevice',
678 '*Backlog',
679 'SocketUser',
680 '*Backlog',
681 'SocketGroup',
682 '*Backlog',
683 'SocketMode',
684 '*Backlog',
685 'DirectoryMode',
686 '*Backlog',
687 'Accept',
688 {
689 'type' => 'leaf',
690 'upstream_default' => 'no',
691 'value_type' => 'boolean',
692 'write_as' => [
693 'no',
694 'yes'
695 ]
696 },
697 'Writable',
698 '*Accept',
699 'FlushPending',
700 '*Accept',
701 'MaxConnections',
702 {
703 'type' => 'leaf',
704 'value_type' => 'uniline'
705 },
706 'MaxConnectionsPerSource',
707 '*MaxConnections',
708 'KeepAlive',
709 {
710 'type' => 'leaf',
711 'upstream_default' => 'no',
712 'value_type' => 'boolean',
713 'write_as' => [
714 'no',
715 'yes'
716 ]
717 },
718 'KeepAliveTimeSec',
719 {
720 'type' => 'leaf',
721 'upstream_default' => '7200',
722 'value_type' => 'integer'
723 },
724 'KeepAliveIntervalSec',
725 {
726 'type' => 'leaf',
727 'upstream_default' => '75',
728 'value_type' => 'integer'
729 },
730 'KeepAliveProbes',
731 {
732 'type' => 'leaf',
733 'upstream_default' => '9',
734 'value_type' => 'integer'
735 },
736 'NoDelay',
737 {
738 'type' => 'leaf',
739 'upstream_default' => 'no',
740 'value_type' => 'boolean',
741 'write_as' => [
742 'no',
743 'yes'
744 ]
745 },
746 'Priority',
747 {
748 'type' => 'leaf',
749 'value_type' => 'integer'
750 },
751 'DeferAcceptSec',
752 '*Priority',
753 'ReceiveBuffer',
754 {
755 'match' => '^\\d+(?i)[KMG]$',
756 'type' => 'leaf',
757 'value_type' => 'uniline'
758 },
759 'SendBuffer',
760 '*ReceiveBuffer',
761 'IPTOS',
762 {
763 'type' => 'leaf',
764 'value_type' => 'integer'
765 },
766 'IPTTL',
767 '*IPTOS',
768 'Mark',
769 '*IPTOS',
770 'ReusePort',
771 {
772 'type' => 'leaf',
773 'value_type' => 'boolean',
774 'write_as' => [
775 'no',
776 'yes'
777 ]
778 },
779 'SmackLabel',
780 {
781 'type' => 'leaf',
782 'value_type' => 'uniline'
783 },
784 'SmackLabelIPIn',
785 '*SmackLabel',
786 'SmackLabelIPOut',
787 '*SmackLabel',
788 'SELinuxContextFromNet',
789 {
790 'type' => 'leaf',
791 'upstream_default' => 'no',
792 'value_type' => 'boolean',
793 'write_as' => [
794 'no',
795 'yes'
796 ]
797 },
798 'PipeSize',
799 {
800 'type' => 'leaf',
801 'value_type' => 'uniline'
802 },
803 'MessageQueueMaxMessages',
804 '*PipeSize',
805 'FreeBind',
806 {
807 'type' => 'leaf',
808 'upstream_default' => 'no',
809 'value_type' => 'boolean',
810 'write_as' => [
811 'no',
812 'yes'
813 ]
814 },
815 'Transparent',
816 '*FreeBind',
817 'Broadcast',
818 '*FreeBind',
819 'PassCredentials',
820 '*FreeBind',
821 'PassPIDFD',
822 '*FreeBind',
823 'PassSecurity',
824 '*FreeBind',
825 'PassPacketInfo',
826 '*FreeBind',
827 'AcceptFileDescriptors',
828 {
829 'type' => 'leaf',
830 'upstream_default' => 'yes',
831 'value_type' => 'boolean',
832 'write_as' => [
833 'no',
834 'yes'
835 ]
836 },
837 'Timestamping',
838 {
839 'choice' => [
840 'ns',
841 'nsec',
842 'off',
843 'us',
844 'usec',
845 "\x{3bc}s"
846 ],
847 'type' => 'leaf',
848 'value_type' => 'enum'
849 },
850 'TCPCongestion',
851 {
852 'type' => 'leaf',
853 'value_type' => 'uniline'
854 },
855 'ExecStartPre',
856 {
857 'cargo' => {
858 'type' => 'leaf',
859 'value_type' => 'uniline'
860 },
861 'type' => 'list'
862 },
863 'ExecStartPost',
864 '*ExecStartPre',
865 'ExecStopPre',
866 '*ExecStartPre',
867 'ExecStopPost',
868 '*ExecStartPre',
869 'TimeoutSec',
870 {
871 'type' => 'leaf',
872 'value_type' => 'uniline'
873 },
874 'Service',
875 '*TimeoutSec',
876 'RemoveOnStop',
877 {
878 'type' => 'leaf',
879 'upstream_default' => 'no',
880 'value_type' => 'boolean',
881 'write_as' => [
882 'no',
883 'yes'
884 ]
885 },
886 'Symlinks',
887 {
888 'type' => 'leaf',
889 'value_type' => 'uniline'
890 },
891 'FileDescriptorName',
892 '*Symlinks',
893 'TriggerLimitIntervalSec',
894 '*Symlinks',
895 'TriggerLimitBurst',
896 '*Symlinks',
897 'PollLimitIntervalSec',
898 '*Symlinks',
899 'PollLimitBurst',
900 '*Symlinks',
901 'DeferTrigger',
902 {
903 'choice' => [
904 'no',
905 'patient',
906 'yes'
907 ],
908 'replace' => {
909 '0' => 'no',
910 '1' => 'yes',
911 'false' => 'no',
912 'true' => 'yes'
913 },
914 'type' => 'leaf',
915 'upstream_default' => 'no',
916 'value_type' => 'enum'
917 },
918 'DeferTriggerMaxSec',
919 {
920 'type' => 'leaf',
921 'value_type' => 'uniline'
922 },
923 'PassFileDescriptorsToExec',
924 {
925 'type' => 'leaf',
926 'upstream_default' => 'no',
927 'value_type' => 'boolean',
928 'write_as' => [
929 'no',
930 'yes'
931 ]
932 }
933 ],
934 'generated_by' => 'parse-man.pl from systemd 261 doc',
935 'license' => 'LGPLv2.1+',
936 'name' => 'Systemd::Section::Socket'
937 }
938 ]
939 ;
« models/Systemd/Section/ServiceUnit.pl ↑ Summary models/Systemd/Section/SocketUnit.pl »