File Coverage

blib/lib/Config/Model/models/Systemd/Section/Socket.pl
Criterion Covered Total %
statement 12 12 100.0
branch n/a
condition n/a
subroutine 4 4 100.0
pod n/a
total 16 16 100.0


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