1SYSTEMD.SOCKET(5)               systemd.socket               SYSTEMD.SOCKET(5)
2
3
4

NAME

6       systemd.socket - systemd socket configuration files
7

SYNOPSIS

9       systemd.socket
10

DESCRIPTION

12       A unit configuration file whose name ends in .socket encodes
13       information about an IPC or network socket or a file system FIFO
14       controlled and supervised by systemd, for socket-based activation.
15
16       This man page lists the configuration options specific to this unit
17       type. See systemd.unit(5) for the common options of all unit
18       configuration files. The common configuration items are configured in
19       the generic [Unit] and [Install] sections. The socket specific
20       configuration options are configured in the [Socket] section.
21
22       Additional options are listed in systemd.exec(5), which define the
23       execution environment the ExecStartPre=, ExecStartPost=, ExecStopPre=
24       and ExecStoptPost= commands are executed in.
25
26       For each socket file a matching service file (see systemd.service(5)
27       for details) must exist, describing the service to start on incoming
28       traffic on the socket. Depending on the setting of Accept= (see below),
29       this must either be named like the socket unit, but with the suffix
30       replaced; or it must be a template file named the same way. Example: a
31       socket file foo.socket needs a matching service foo.service if
32       Accept=false is set. If Accept=true is set a service template file
33       foo@.service must exist from which services are instantiated for each
34       incoming connection.
35
36       Unless DefaultDependencies= is set to false, socket units will
37       implicitly have dependencies of type Requires= and After= on
38       sysinit.target as well as dependencies of type Conflicts= and Before=
39       on shutdown.target. These ensure that socket units pull in basic system
40       initialization, and are terminated cleanly prior to system shutdown.
41       Only sockets involved with early boot or late system shutdown should
42       disable this option.
43
44       Socket units may be used to implement on-demand starting of services,
45       as well as parallelized starting of services.
46

OPTIONS

48       Socket files must include a [Socket] section, which carries information
49       about the socket or FIFO it supervises. A number of options that may be
50       used in this section are shared with other unit types. These options
51       are documented in systemd.exec(5). The options specific to the [Socket]
52       section of socket units are the following:
53
54       ListenStream=, ListenDatagram=, ListenSequentialPacket=
55           Specifies an address to listen on for a stream (SOCK_STREAM),
56           datagram (SOCK_DGRAM) resp. sequential packet (SOCK_SEQPACKET)
57           socket. The address can be written in various formats:
58
59           If the address starts with a slash (/), it is read as file system
60           socket in the AF_UNIX socket family.
61
62           If the address starts with an ampersand (@) it is read as abstract
63           namespace socket in the AF_UNIX family. The @ is replaced with a
64           NUL character before binding. For details see unix(7).
65
66           If the address string is a single number it is read as port number
67           to listen on for both IPv4 and IPv6.
68
69           If the address string is a string in the format v.w.x.y:z it is
70           read as IPv4 specifier for listening on an address v.w.x.y on a
71           port z.
72
73           If the address string is a string in the format [x]:y it is read as
74           IPv6 address x on a port y.
75
76           Note that SOCK_SEQPACKET (i.e.  ListenSequentialPacket=) is only
77           available for AF_UNIX sockets. SOCK_STREAM (i.e.  ListenStream=)
78           when used for IP sockets refers to TCP sockets, SOCK_DGRAM (i.e.
79           ListenDatagram=) to UDP.
80
81           These options may be specified more than once in which case
82           incoming traffic on any of the sockets will trigger service
83           activation, and all listed sockets will be passed to the service,
84           regardless whether there is incoming traffic on them or not.
85
86           If an IP address is used here, it is often desirable to listen on
87           it before the interface it is configured on is up and running, and
88           even regardless whether it will be up and running ever at all. To
89           deal with this it is recommended to set the FreeBind= option
90           described below.
91
92       ListenFIFO=
93           Specifies a file system FIFO to listen on. This expects an absolute
94           file system path as argument. Behaviour otherwise is very similar
95           to the ListenDatagram= directive above.
96
97       BindIPv6Only=
98           Takes a one of default, both or ipv6-only. Controls the IPV6_V6ONLY
99           socket option (see ipv6(7) for details). If both, IPv6 sockets
100           bound will be accessible via both IPv4 and IPv6. If ipv6-only, they
101           will be accessible via IPv6 only. If default (which is the default,
102           surprise!) the system wide default setting is used, as controlled
103           by /proc/sys/net/ipv6/bindv6only.
104
105       Backlog=
106           Takes an unsigned integer argument. Specifies the number of
107           connections to queue that have not been accepted yet. This setting
108           matters only for stream and sequential packet sockets. See
109           listen(2) for details. Defaults to SOMAXCONN (128).
110
111       BindToDevice=
112           Specifies a network interface name to bind this socket to. If set
113           traffic will only be accepted from the specified network
114           interfaces. This controls the SO_BINDTODEVICE socket option (see
115           socket(7) for details). If this option is used, an automatic
116           dependency from this socket unit on the network interface device
117           unit (systemd.device(5) is created.
118
119       DirectoryMode=
120           If listening on a file system socket of FIFO, the parent
121           directories are automatically created if needed. This option
122           specifies the file system access mode used when creating these
123           directories. Takes an access mode in octal notation. Defaults to
124           0755.
125
126       SocketMode=
127           If listening on a file system socket of FIFO, this option specifies
128           the file system access mode used when creating the file node. Takes
129           an access mode in octal notation. Defaults to 0666.
130
131       Accept=
132           Takes a boolean argument. If true, a service instance is spawned
133           for each incoming connection and only the connection socket is
134           passed to it. If false, all listening sockets themselves are passed
135           to the started service unit, and only one service unit is spawned
136           for all connections (also see above). This value is ignored for
137           datagram sockets and FIFOs where a single service unit
138           unconditionally handles all incoming traffic. Defaults to false.
139           For performance reasons, it is recommended to write new daemons
140           only in a way that is suitable for Accept=false. This option is
141           mostly useful to allow daemons designed for usage with inetd(8), to
142           work unmodified with systemd socket activation.
143
144       MaxConnections=
145           The maximum number of connections to simultaneously run services
146           instances for, when Accept=true is set. If more concurrent
147           connections are coming in, they will be refused until at least one
148           existing connection is terminated. This setting has no effect for
149           sockets configured with Accept=no or datagram sockets. Defaults to
150           64.
151
152       KeepAlive=
153           Takes a boolean argument. If true, the TCP/IP stack will send a
154           keep alive message after 2h (depending on the configuration of
155           /proc/sys/net/ipv4/tcp_keepalive_time) for all TCP streams accepted
156           on this socket. This controls the SO_KEEPALIVE socket option (see
157           socket(7) and the TCP Keepalive HOWTO[1] for details.) Defaults to
158           false.
159
160       Priority=
161           Takes an integer argument controlling the priority for all traffic
162           sent from this socket. This controls the SO_PRIORITY socket option
163           (see socket(7) for details.).
164
165       ReceiveBuffer=, SendBuffer=
166           Takes an integer argument controlling the receive resp. send buffer
167           sizes of this socket. This controls the SO_RCVBUF resp. SO_SNDBUF
168           socket options (see socket(7) for details.).
169
170       IPTOS=
171           Takes an integer argument controlling the IP Type-Of-Service field
172           for packets generated from this socket. This controls the IP_TOS
173           socket option (see ip(7) for details.). Either a numeric string or
174           one of low-delay, throughput, reliability or low-cost may be
175           specified.
176
177       IPTTL=
178           Takes an integer argument controlling the IPv4 Time-To-Live/IPv6
179           Hop-Count field for packets generated from this socket. This sets
180           the IP_TTL/IPV6_UNICAST_HOPS socket options (see ip(7) and ipv6(7)
181           for details.)
182
183       Mark=
184           Takes an integer value. Controls the firewall mark of packets
185           generated by this socket. This can be used in the firewall logic to
186           filter packets from this socket. This sets the SO_MARK socket
187           option. See iptables(8) for details.
188
189       PipeSize=
190           Takes an integer value. Controls the pipe buffer size of FIFOs
191           configured in this socket unit. See fcntl(2) for details.
192
193       FreeBind=
194           Takes a boolean value. Controls whether the socket can be bound to
195           non-local IP addresses. This is useful to configure sockets
196           listening on specific IP addresses before those IP addresses are
197           successfully configured on a network interface. This sets the
198           IP_FREEBIND socket option. For robustness reasons it is recommended
199           to use this option whenever you bind a socket to a specific IP
200           address. Defaults to false.
201
202       TCPCongestion=
203           Takes a string value. Controls the TCP congestion algorithm used by
204           this socket. Should be one of "westwood", "veno", "cubic", "lp" or
205           any other available algorithm supported by the IP stack. This
206           setting applies only to stream sockets.
207
208       ExecStartPre=, ExecStartPost=
209           Takes one or more command lines, which are executed before (resp.
210           after) the listening sockets/FIFOs are created and bound. The first
211           token of the command line must be an absolute file name, then
212           followed by arguments for the process. Multiple command lines may
213           be specified following the same scheme as used for ExecStartPre= of
214           service unit files.
215
216       ExecStopPre=, ExecStopPost=
217           Additional commands that are executed before (resp. after) the
218           listening sockets/FIFOs are closed and removed. Multiple command
219           lines may be specified following the same scheme as used for
220           ExecStartPre= of service unit files.
221
222       TimeoutSec=
223           Configures the time to wait for the commands specified in
224           ExecStartPre=, ExecStartPost=, ExecStopPre= and ExecStopPost= to
225           finish. If a command does not exit within the configured time, the
226           socket will be considered failed and be shut down again. All
227           commands still running, will be terminated forcibly via SIGTERM,
228           and after another delay of this time with SIGKILL. (See KillMode=
229           below.) Takes a unit-less value in seconds, or a time span value
230           such as "5min 20s". Pass 0 to disable the timeout logic. Defaults
231           to 60s.
232
233       KillMode=
234           Specifies how processes of this socket unit shall be killed. One of
235           control-group, process-group, process, none.
236
237           This option is mostly equivalent to the KillMode= option of service
238           files. See systemd.service(5) for details.
239

SEE ALSO

241       systemd(1), systemctl(8), systemd.unit(5), systemd.exec(5),
242       systemd.service(5)
243

AUTHOR

245       Lennart Poettering <lennart@poettering.net>
246           Developer
247

NOTES

249        1. TCP Keepalive HOWTO
250           http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/
251
252
253
254systemd                           09/14/2010                 SYSTEMD.SOCKET(5)
Impressum