Config...:Socket(3pm)

📦

version 0.260.1 · 6 versions

0.260.1 · ubuntu stonking (latest)
0.249.1 · ubuntu jammy
0.254.1 · ubuntu noble
0.252.2 · debian bookworm
0.258.1 · ubuntu resolute
0.257.2 · debian trixie, ubuntu questing

💖 `Config...:Socket(3pm)` 💖

okay bestie, real talk — this is the manual for Config::Model::models::Systemd::Section::Socket, aka the Configuration class Systemd::Section::Socket. No cap, it's systemd socket units, but they've been through the Config::Model glow-up. Let's get into it. 💅

✨ NAME ✨

Config::Model::models::Systemd::Section::Socket — Configuration class Systemd::Section::Socket

🌸 DESCRIPTION 🌸

These are configuration classes used by Config::Model. Full stop, that's the whole vibe.

A unit configuration file whose name ends in .socket encodes info about an IPC or network socket, or a file system FIFO, that systemd controls and supervises — for socket-based activation. That's the whole job. She's a socket-enabler. 💖

This man page lists the config options that are specific to this unit type. For the common options that all unit config files share, go read systemd.unit(5). Those common config items live in the generic [Unit] and [Install] sections, bestie. The socket-specific config options live in the [Socket] section. That's the split. 🎀

More options are listed in systemd.exec(5) — those define the execution environment that the ExecStartPre, ExecStartPost, ExecStopPre and ExecStopPost commands get run in. Then there's systemd.kill(5), which defines the way processes are terminated, and systemd.resource-control(5), which configures resource control settings for the processes of the socket. Three whole man pages of extra options. She's well-documented. 😭

Okay now the important part: for every socket unit, a matching service unit has to exist. That service unit describes what service to start when incoming traffic shows up on the socket (peep systemd.service(5) for the .service unit lore). The name of the .service unit is, by default, the same as the name of the .socket unit — but you can change that with the Service option (described below 👇). Depending on how the Accept option (also described below 👇) is set, this .service unit has to either:

be named like the .socket unit but with the suffix replaced — unless it's overridden with Service
or be a template unit named the same way

Example, because examples are iconic: a socket file foo.socket needs a matching service foo.service if Accept=no is set. If Accept=yes is set, then a service template foo@.service has to exist, and services get instantiated from it for each incoming connection. Slay. ✨

Heads up: no implicit WantedBy or RequiredBy dependency from the socket to the service is added. Which means the service may be started without the socket — and in that case it has to be able to open sockets all by itself. To prevent that, you can add an explicit Requires dependency.

Socket units can be used to implement on-demand starting of services, and parallelized starting of services. For an intro, see the blog stories linked at the end. 🔥

Now — note that the daemon software you 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 the details on the precise protocol used and the order the file descriptors get passed in), or via the traditional inetd(8)-style socket passing — i.e. sockets passed in via standard input and output, using StandardInput=socket in the service file.

By default, network sockets allocated through .socket units are allocated in the host's network namespace (see network_namespaces(7)). BUT — and this is the plot twist — that does not mean the service activated by a configured socket unit has to be part of the host's network namespace too. It is supported, and honestly it's 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. Lowkey profound. 🦋

Alternatively, it's possible to run a .socket unit in another network namespace by setting PrivateNetwork=yes in combination with JoinsNamespaceOf — see systemd.exec(5) and systemd.unit(5) for details. This configuration class was generated from systemd documentation. by parse-man.pl <https://github.com/dod38fr/config-model-systemd/contrib/parse-man.pl>

🔥 ELEMENTS 🔥

💜 ListenStream 💜

Specifies an address to listen on for a stream (SOCK_STREAM), datagram (SOCK_DGRAM), or sequential packet (SOCK_SEQPACKET) socket, respectively. The address can be written in various formats, and bestie, there are a lot of formats:

If the address starts with a slash (/), it is read as a file system socket in the AF_UNIX socket family.
If the address starts with an at symbol (@), it is read as an abstract namespace socket in the AF_UNIX family. That @ gets replaced with a NUL character before binding. For details, see unix(7).
If the address string is a single number, it is read as a 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 (that's the default) or just via IPv6.
If the address string is in the format v.w.x.y:z, it's interpreted as IPv4 address v.w.x.y and port z.
If the address string is in the format [x]:y, it's 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 in the format vsock:x:y, it's 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, and SOCK_DGRAM (i.e. ListenDatagram) refers 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's 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, and all prior uses of any of these options will have no effect.

fr fr: empty string = full reset. Everything you listed before? Gone. Ghosted. 💀

It's 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's often desirable to listen on it before the interface it's configured on is up and running — and even regardless of whether it will ever be up and running at any point. To deal with this, it's recommended to set the FreeBind option described below. Optional. Type list of uniline.

💜 ListenDatagram 💜

If the address starts with a slash (/), it is read as a file system socket in the AF_UNIX socket family.
If the address starts with an at symbol (@), it is read as an abstract namespace socket in the AF_UNIX family. That @ is replaced with a NUL character before binding. For details, see unix(7).
If the address string is a single number, it's read as a 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 in the format v.w.x.y:z, it's interpreted as IPv4 address v.w.x.y and port z.
If the address string is in the format [x]:y, it's 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 in the format vsock:x:y, it's 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, while SOCK_DGRAM (i.e. ListenDatagram) refers 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's 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, and 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's often desirable to listen on it before the interface it's 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's recommended to set the FreeBind option described below. Optional. Type list of uniline.

💜 ListenSequentialPacket 💜

Specifies an address to listen on for a stream (SOCK_STREAM), datagram (SOCK_DGRAM), or sequential packet (SOCK_SEQPACKET) socket, respectively. The address can be written in various formats:

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).

Okay so if the address string is literally just one single number, bestie, that's read as the port number to listen on via IPv6. And depending on whatever BindIPv6Only is set to (peep below 👇) you might end up with the service reachable over both IPv6 and IPv4 (that's the default, periodt) or IPv6 only. No in-between.

If the address string looks like the format v.w.x.y:z? It's read as IPv4 address v.w.x.y and port z. Iconic, classic, we been knew.

If it's in the format [x]:y, that's read as IPv6 address x and port y. And you can optionally tack an interface scope on after a % symbol — interface name or number, either one: [x]:y%dev. Here's the tea though 🫖: interface scopes are only actually useful with link-local addresses, because the kernel just ignores them in every other case. Also note — even if you specified an address as IPv6, it might still make the service available via IPv4 too, depending on the BindIPv6Only setting (again, see below).

If the address string is in the format vsock:x:y, it's 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, loosely analogous to an IP address. Specifying the CID is optional and you can even set it to the empty string. And FYI, vsock may be replaced with vsock-stream, vsock-dgram or vsock-seqpacket to force usage of the corresponding socket type. Slay 💅

Heads up bestie: SOCK_SEQPACKET (aka ListenSequentialPacket) is only available for AF_UNIX sockets. And SOCK_STREAM (aka ListenStream), when used for IP sockets, refers to TCP sockets — while SOCK_DGRAM (aka ListenDatagram) refers to UDP. Write that down, it's on the exam 😭

Now, these options may be specified more than once, and in that case incoming traffic on any of the sockets will trigger service activation, and all listed sockets get passed to the service — regardless of whether there's incoming traffic on them or not. Group chat behavior, honestly. And if the empty string is assigned to any of these options, the whole list of addresses to listen on is reset, and all prior uses of any of these options will have no effect. Poof. Gone. 💨

It's also possible to have more than one socket unit for the same service when you're using Service, and then the service will receive all the sockets configured across all the socket units. Sockets configured within one unit are passed in the order of configuration, but no ordering between socket units is specified. Respectfully, don't count on the order. 🙈

If an IP address is used here, it's often desirable to listen on it before the interface it's configured on is even up and running — and even regardless of whether it will ever be up and running at any point. To deal with that, the recommendation is to set the FreeBind option described below. 💖