DescriptionA unit configuration file whose name ends in
- .socket encodes information about
+ .socket encodes information about
an IPC or network socket or a file system FIFO
controlled and supervised by systemd, for socket-based
activation.
@@ -77,26 +77,34 @@
and
commands are executed
in, and in
- systemd.kill5
- which define the way the processes are
- terminated.
-
- For each socket file a matching service file
- (see
+ systemd.kill5,
+ which define the way the processes are terminated, and
+ in
+ systemd.resource-control5,
+ which configure resource control settings for the
+ processes of the socket.
+
+ For each socket file, a matching service file
+ must exist, describing the service to start on
+ incoming traffic on the socket (see
systemd.service5
- for details) must exist, describing the service to
- start on incoming traffic on the socket. Depending on
- the setting of (see below),
- this must either be named like the socket unit, but
- with the suffix replaced; or it must be a template
- file named the same way. Example: a socket file
+ for more information about .service files). The name
+ of the .service unit is by default the same as the
+ name of the .socket unit, but can be altered with the
+ option described below.
+ Depending on the setting of the
+ option described below, this .service unit must either
+ be named like the .socket unit, but with the suffix
+ replaced, unless overridden with
+ ; or it must be a template
+ unit named the same way. Example: a socket file
foo.socket needs a matching
service foo.service if
is set. If
- is set a service template
- file foo@.service must exist from
- which services are instantiated for each incoming
- connection.
+ is set, a service
+ template file foo@.service must
+ exist from which services are instantiated for each
+ incoming connection.
Unless DefaultDependencies=
is set to , socket units will
@@ -113,9 +121,21 @@
boot or late system shutdown should disable this
option.
+ Socket units will have a
+ Before= dependency on the service
+ which they trigger added implicitly. No implicit
+ WantedBy= or
+ RequiredBy= dependency from the
+ socket to the service is added. This means that the
+ service may be started without the socket, in which
+ case it must be able to open sockets by itself. To
+ prevent this, an explicit Requires=
+ dependency may be added.
+
Socket units may be used to implement on-demand
starting of services, as well as parallelized starting
- of services.
+ of services. See the blog stories linked at the end
+ for an introduction.
Note that the daemon software configured for
socket activation with socket units needs to be able
@@ -124,8 +144,8 @@
sd_listen_fds3
for details) or via the traditional
inetd8-style
- socket passing (i.e. sockets passed in via STDIN and
- STDOUT, using StandardInput=socket
+ socket passing (i.e. sockets passed in via standard input and
+ output, using StandardInput=socket
in the service file).
@@ -156,20 +176,22 @@
can be written in various formats:
If the address starts with a
- slash (/), it is read as file system
+ slash (/), it is read as file system
socket in the AF_UNIX socket
family.
- If the address starts with an
- at symbol (@) it is read as abstract
- namespace socket in the AF_UNIX
- family. The @ is replaced with a NUL
- character before binding. For details
- see
- unix7.
+ If the address starts with an at
+ symbol (@), it is read as abstract
+ namespace socket in the
+ AF_UNIX
+ family. The @ is
+ replaced with a
+ NUL character
+ before binding. For details, see
+ unix7.If the address string is a
- single number it is read as port
+ single number, it is read as port
number to listen on via
IPv6. Depending on the value of
BindIPv6Only= (see below) this
@@ -179,13 +201,13 @@
If the address string is a
- string in the format v.w.x.y:z it is
+ string in the format v.w.x.y:z, it is
read as IPv4 specifier for listening
on an address v.w.x.y on a port
z.If the address string is a
- string in the format [x]:y it is read
+ string in the format [x]:y, it is read
as IPv6 address x on a port y. Note
that this might make the service
available via IPv4, too, depending on
@@ -208,7 +230,7 @@
traffic on any of the sockets will
trigger service activation, and all
listed sockets will be passed to the
- service, regardless whether there is
+ service, regardless of whether there is
incoming traffic on them or not. If
the empty string is assigned to any of
these options, the list of addresses
@@ -216,12 +238,23 @@
of any of these options will have no
effect.
+ It is also possible to have more
+ than one socket unit for the same
+ service when using
+ Service=, and the
+ service will receive all the sockets
+ configured in all the socket units.
+ Sockets configured in one unit are
+ passed in the order of configuration,
+ but no ordering between socket units
+ is specified.
+
If an IP address is used here,
it is often desirable to listen on it
before the interface it is configured
on is up and running, and even
- regardless whether it will be up and
- running ever at all. To deal with this
+ regardless of whether it will be up and
+ running at any point. To deal with this,
it is recommended to set the
FreeBind= option
described below.
@@ -298,7 +331,7 @@
, they will
be accessible via IPv6 only. If
(which is the
- default, surprise!) the system wide
+ default, surprise!), the system wide
default setting is used, as controlled
by
/proc/sys/net/ipv6/bindv6only,
@@ -325,7 +358,7 @@
BindToDevice=Specifies a network
interface name to bind this socket
- to. If set traffic will only be
+ to. If set, traffic will only be
accepted from the specified network
interfaces. This controls the
SO_BINDTODEVICE socket option (see
@@ -339,16 +372,21 @@
- DirectoryMode=
- If listening on a file
- system socket or FIFO, the parent
- directories are automatically created
- if needed. This option specifies the
- file system access mode used when
- creating these directories. Takes an
- access mode in octal
- notation. Defaults to
- 0755.
+ SocketUser=
+ SocketGroup=
+
+ Takes a UNIX
+ user/group name. When specified,
+ all AF_UNIX sockets and FIFO nodes in
+ the file system are owned by the
+ specified user and group. If unset
+ (the default), the nodes are owned by
+ the root user/group (if run in system
+ context) or the invoking user/group
+ (if run in user context). If only a
+ user is specified but no group, then
+ the group is derived from the user's
+ default group.
@@ -362,6 +400,19 @@
0666.
+
+ DirectoryMode=
+ If listening on a file
+ system socket or FIFO, the parent
+ directories are automatically created
+ if needed. This option specifies the
+ file system access mode used when
+ creating these directories. Takes an
+ access mode in octal
+ notation. Defaults to
+ 0755.
+
+
Accept=Takes a boolean
@@ -387,8 +438,8 @@
close2
on the received socket before
exiting. However, it must not unlink
- the socket from a filesystem. It
- should note invoke
+ the socket from a file system. It
+ should not invoke
shutdown2
on sockets it got with
Accept=false, but
@@ -412,7 +463,7 @@
are coming in, they will be refused
until at least one existing connection
is terminated. This setting has no
- effect for sockets configured with
+ effect on sockets configured with
or datagram
sockets. Defaults to
64.
@@ -451,12 +502,15 @@
ReceiveBuffer=SendBuffer=Takes an integer
- argument controlling the receive
- or send buffer sizes of this
- socket, respectively. This controls the SO_RCVBUF
- and SO_SNDBUF socket options (see
+ argument controlling the receive or
+ send buffer sizes of this socket,
+ respectively. This controls the
+ SO_RCVBUF and SO_SNDBUF socket options
+ (see
socket7
- for details.).
+ for details.). The usual suffixes K,
+ M, G are supported and are understood
+ to the base of 1024.
@@ -502,6 +556,17 @@
for details.
+
+ ReusePort=
+ Takes a boolean
+ value. If true, allows multiple bind2s
+ to this TCP or UDP port. This
+ controls the SO_REUSEPORT socket
+ option. See
+ socket7
+ for details.
+
+
SmackLabel=SmackLabelIPIn=
@@ -516,7 +581,7 @@
respectively, i.e. the security label
of the FIFO, or the security label for
the incoming or outgoing connections
- of the socket, respectively. See
+ of the socket, respectively. See
Smack.txt
for details.
@@ -524,12 +589,14 @@
PipeSize=
- Takes an integer
- value. Controls the pipe buffer size
+ Takes a size in
+ bytes. Controls the pipe buffer size
of FIFOs configured in this socket
- unit. See
+ unit. See
fcntl2
- for details.
+ for details. The usual suffixes K, M,
+ G are supported and are understood to
+ the base of 1024.
@@ -598,7 +665,7 @@
socket option, which allows AF_UNIX
sockets to receive the security
context of the sending process in an
- ancillary message. Defaults to
+ ancillary message. Defaults to
.
@@ -622,7 +689,7 @@
before or after the listening
sockets/FIFOs are created and
bound, respectively. The first token of the command
- line must be an absolute file name,
+ line must be an absolute filename,
then followed by arguments for the
process. Multiple command lines may be
specified following the same scheme as
@@ -657,25 +724,65 @@
will be considered failed and be shut
down again. All commands still running,
will be terminated forcibly via
- SIGTERM, and after another delay of
- this time with SIGKILL. (See
+ SIGTERM, and after another delay of
+ this time with SIGKILL. (See
in systemd.kill5.)
Takes a unit-less value in seconds, or
a time span value such as "5min
20s". Pass 0 to disable the timeout
- logic. Defaults to
- 90s.
+ logic. Defaults to TimeoutStartSec= from the
+ manager configuration file.
Service=Specifies the service
unit name to activate on incoming
- traffic. This defaults to the service
- that bears the same name as the socket
- (ignoring the different suffixes). In
- most cases it should not be necessary
- to use this option.
+ traffic. This setting is only allowed
+ for sockets with
+ Accept=no. It
+ defaults to the service that bears the
+ same name as the socket (with the
+ suffix replaced). In most cases, it
+ should not be necessary to use this
+ option.
+
+
+
+ RemoveOnStop=
+ Takes a boolean
+ argument. If enabled, any file nodes
+ created by this socket unit are
+ removed when it is stopped. This
+ applies to AF_UNIX sockets in the file
+ system, POSIX message queues, FIFOs,
+ as well as any symlinks to
+ them configured with
+ Symlinks=. Normally,
+ it should not be necessary to use this
+ option, and is not recommended as
+ services might continue to run after
+ the socket unit has been terminated
+ and it should still be possible to
+ communicate with them via their file
+ system node. Defaults to
+ off.
+
+
+
+ Symlinks=
+ Takes a list of file
+ system paths. The specified paths will
+ be created as symlinks to the AF_UNIX
+ socket path or FIFO path of this
+ socket unit. If this setting is used,
+ only one AF_UNIX socket in the file
+ system or one FIFO may be configured
+ for the socket unit. Use this option
+ to manage one or more symlinked alias
+ names for a socket, binding their
+ lifecycle together. Defaults to the
+ empty list.
@@ -696,12 +803,13 @@
systemd.unit5,
systemd.exec5,
systemd.kill5,
+ systemd.resource-control5,
systemd.service5,
systemd.directives7
- For more extensive descriptions see the "Systemd for Developers" series:
+ For more extensive descriptions see the "systemd for Developers" series:
Socket Activation,
Socket Activation, part II,
Converting inetd Services,