1SYSTEMD.SOCKET(5) systemd.socket SYSTEMD.SOCKET(5)
2
6 systemd.socket - systemd socket configuration files
7
9 systemd.socket
10
12 A unit configuration file whose name ends in .socket encodes
13 information about an IPC or network socket or a file system FIFO
14 controlled and supervised by systemd, for socket-based activation.
15 This man page lists the configuration options specific to this unit
17 type. See systemd.unit(5) for the common options of all unit
18 configuration files. The common configuration items are configured in
19 the generic [Unit] and [Install] sections. The socket specific
20 configuration options are configured in the [Socket] section.
21 Additional options are listed in systemd.exec(5), which define the
23 execution environment the ExecStartPre=, ExecStartPost=, ExecStopPre=
24 and ExecStoptPost= commands are executed in.
25 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 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 Socket units may be used to implement on-demand starting of services,
45 as well as parallelized starting of services.
46
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 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 If the address starts with a slash (/), it is read as file system
60 socket in the AF_UNIX socket family.
61 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 If the address string is a single number it is read as port number
67 to listen on for both IPv4 and IPv6.
68 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 KillMode=
234 Specifies how processes of this socket unit shall be killed. One of
235 control-group, process-group, process, none.
236 This option is mostly equivalent to the KillMode= option of service
238 files. See systemd.service(5) for details.
239
241 systemd(1), systemctl(8), systemd.unit(5), systemd.exec(5),
242 systemd.service(5)
243
245 Lennart Poettering <lennart@poettering.net>
246 Developer
247
249 1. TCP Keepalive HOWTO
250 http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/
251systemd 09/14/2010 SYSTEMD.SOCKET(5)