NAME
systemd.socket - Socket unit configuration
SYNOPSIS
socket.socket
DESCRIPTION
A unit configuration file whose name ends in ".socket" encodes information about an IPC or network socket or a file system FIFO controlled and supervised by systemd, for socket-based activation.
This man page lists the configuration options specific to this unit type. See systemd.unit(5) for the common options of all unit configuration files. The common configuration items are configured in the generic [Unit] and [Install] sections. The socket specific configuration options are configured in the [Socket] section.
Additional options are listed in systemd.exec(5), which define the execution environment the ExecStartPre=, ExecStartPost=, ExecStopPre= and ExecStopPost= commands are executed in, and in systemd.kill(5), which define the way the processes are terminated, and in systemd.resource-control(5), which configure resource control settings for the processes of the socket.
For each socket unit, a matching service unit must exist, describing the service to start on incoming traffic on the socket (see systemd.service(5) for more information about .service units). The name of the .service unit is by default the same as the name of the .socket unit, but can be altered with the Service= option described below. Depending on the setting of the Accept= option described below, this .service unit must either be named like the .socket unit, but with the suffix replaced, unless overridden with Service=; or it must be a template unit named the same way. Example: a socket file foo.socket needs a matching service foo.service if Accept=no is set. If Accept=yes is set, a service template [email protected] must exist from which services are instantiated for each incoming connection.
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. 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 to accept sockets from systemd, either via systemd's native socket passing interface (see sd_listen_fds(3) for details about the precise protocol used and the order in which the file descriptors are passed) or via traditional inetd(8)-style socket passing (i.e. sockets passed in via standard input and output, using StandardInput=socket in the service file).
All network sockets allocated through .socket units are allocated in the host's network namespace (see network_namespaces(7)). This does not mean however that the service activated by a configured socket unit has to be part of the host's network namespace as well. It is supported and even good practice to run services in their own network namespace (for example through PrivateNetwork=, see systemd.exec(5)), receiving only the sockets configured through socket-activation from the host's namespace. In such a set-up communication within the host's network namespace is only permitted through the activation sockets passed in while all sockets allocated from the service code itself will be associated with the service's own namespace, and thus possibly subject to a restrictive configuration.
AUTOMATIC DEPENDENCIES
Implicit Dependencies
The following dependencies are implicitly added:
Additional implicit dependencies may be added as result of execution and resource control parameters as documented in systemd.exec(5) and systemd.resource-control(5).
Default Dependencies
The following dependencies are added unless DefaultDependencies=no is set:
OPTIONS
Socket unit files may include [Unit] and [Install] sections, which are described in systemd.unit(5).
Socket unit files must include a [Socket] section, which carries information about the socket or FIFO it supervises. A number of options that may be used in this section are shared with other unit types. These options are documented in systemd.exec(5), systemd.kill(5) and systemd.resource-control(5). The options specific to the [Socket] section of socket units are the following:
ListenStream=, ListenDatagram=, ListenSequentialPacket=
If the address starts with a 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 unix(7).
If the address string is a single number, it is read as port number to listen on via IPv6. Depending on the value of BindIPv6Only= (see below) this might result in the service being available via both IPv6 and IPv4 (default) or just via IPv6.
If the address string is a string in the format "v.w.x.y:z", it is interpreted as IPv4 address v.w.x.y and port z.
If the address string is a string in the format "[x]:y", it is interpreted as IPv6 address x and port y. An optional interface scope (interface name or number) may be specified after a "%" symbol: "[x]:y%dev". Interface scopes are only useful with link-local addresses, because the kernel ignores them in other cases. Note that if an address is specified as IPv6, it might still make the service available via IPv4 too, depending on the BindIPv6Only= setting (see below).
If the address string is a string in the format "vsock:x:y", it is read as CID x on a port y address in the AF_VSOCK family. The CID is a unique 32-bit integer identifier in AF_VSOCK analogous to an IP address. Specifying the CID is optional, and may be set to the empty string. "vsock" may be replaced with "vsock-stream", "vsock-dgram" or "vsock-seqpacket" to force usage of the corresponding socket type.
Note that SOCK_SEQPACKET (i.e. ListenSequentialPacket=) is only available for AF_UNIX sockets. SOCK_STREAM (i.e. ListenStream=) when used for IP sockets refers to TCP sockets, SOCK_DGRAM (i.e. ListenDatagram=) to UDP.
These options may be specified more than once, in which case incoming traffic on any of the sockets will trigger service activation, and all listed sockets will be passed to the 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 to listen on is reset, all prior uses 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 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.
ListenFIFO=
ListenSpecial=
ListenNetlink=
ListenMessageQueue=
ListenUSBFunction=
Added in version 227.
SocketProtocol=
Added in version 229.
BindIPv6Only=
Backlog=
BindToDevice=
SocketUser=, SocketGroup=
Added in version 214.
SocketMode=
DirectoryMode=
Accept=
Note that depending on this setting the services activated by units of this type are either regular services (in case of Accept=no) or instances of templated services (in case of Accept=yes). See the Description section above for a more detailed discussion of the naming rules of triggered services.
For IPv4 and IPv6 connections, the $REMOTE_ADDR environment variable will contain the remote IP address, and $REMOTE_PORT will contain the remote port. This is the same as the format used by CGI.
For AF_UNIX socket connections, the $REMOTE_ADDR environment variable will contain either the remote socket's file system path starting with a slash ("/") or its address in the abstract namespace starting with an at symbol ("@"). If the socket is unnamed, $REMOTE_ADDR will not be set.
It is recommended to set CollectMode=inactive-or-failed for service instances activated via Accept=yes, to ensure that failed connection services are cleaned up and released from memory, and do not accumulate.
Writable=
Added in version 227.
FlushPending=
Added in version 247.
MaxConnections=
MaxConnectionsPerSource=
Added in version 232.
KeepAlive=
KeepAliveTimeSec=
Added in version 216.
KeepAliveIntervalSec=
Added in version 216.
KeepAliveProbes=
Added in version 216.
NoDelay=
Added in version 216.
Priority=
DeferAcceptSec=
If the client also uses the TCP_DEFER_ACCEPT option, the latency of the initial connection may be reduced, because the kernel will send data in the final packet establishing the connection (the third packet in the "three-way handshake").
Disabled by default.
Added in version 216.
ReceiveBuffer=, SendBuffer=
IPTOS=
IPTTL=
Mark=
ReusePort=
Added in version 206.
SmackLabel=, SmackLabelIPIn=, SmackLabelIPOut=
Added in version 196.
SELinuxContextFromNet=
Added in version 217.
PipeSize=
MessageQueueMaxMessages=, MessageQueueMessageSize=
FreeBind=
Transparent=
Broadcast=
PassCredentials=
PassSecurity=
PassPacketInfo=
Added in version 246.
Timestamping=
Added in version 247.
TCPCongestion=
ExecStartPre=, ExecStartPost=
ExecStopPre=, ExecStopPost=
TimeoutSec=
Service=
RemoveOnStop=
Added in version 214.
Symlinks=
Added in version 214.
FileDescriptorName=
Added in version 227.
TriggerLimitIntervalSec=, TriggerLimitBurst=
If the limit is hit, the socket unit is placed into a failure mode, and will not be connectible anymore until restarted. Note that this limit is enforced before the service activation is enqueued.
Compare with PollLimitIntervalSec=/PollLimitBurst= described below, which implements a temporary slowdown if a socket unit is flooded with incoming traffic, as opposed to the permanent failure state TriggerLimitIntervalSec=/TriggerLimitBurst= results in.
Added in version 230.
PollLimitIntervalSec=, PollLimitBurst=
If the polling limit is hit polling is temporarily disabled on it until the specified time window passes. The polling limit hence slows down connection attempts if hit, but unlike the trigger limit will not cause permanent failures. It's the recommended mechanism to deal with DoS attempts through packet flooding.
The polling limit is enforced per file descriptor to listen on, as opposed to the trigger limit which is enforced for the entire socket unit. This distinction matters for socket units that listen on multiple file descriptors (i.e. have multiple ListenXYZ= stanzas).
These setting defaults to 150 (in case of Accept=yes) and 15 (otherwise) polling events per 2s. This is considerably lower than the default values for the trigger limit (see above) and means that the polling limit should typically ensure the trigger limit is never hit, unless one of them is reconfigured or disabled.
Added in version 255.
PassFileDescriptorsToExec=
Added in version 256.
Check systemd.unit(5), systemd.exec(5), and systemd.kill(5) for more settings.
SEE ALSO
systemd(1), systemctl(1), systemd-system.conf(5), systemd.unit(5), systemd.exec(5), systemd.kill(5), systemd.resource-control(5), systemd.service(5), systemd.directives(7), sd_listen_fds(3), sd_listen_fds_with_names(3)
For more extensive descriptions see the "systemd for Developers" series: Socket Activation[4], Socket Activation, part II[5], Converting inetd Services[6], Socket Activated Internet Services and OS Containers[7].
NOTES
- 1.
USB FunctionFS
- 2.
TCP Keepalive HOWTO
- 3.
Smack
- 4.
Socket Activation
- 5.
Socket Activation, part II
- 6.
Converting inetd Services
- 7.
Socket Activated Internet Services and OS Containers