Stop Booting Daemons Just to Listen: Practical systemd.socket Activation on Linux

You have a small internal API that gets hit a few times a day. Or a debug endpoint. Or a homelab tool that only matters when someone actually connects. The usual pattern is still:

# enable the service at boot so the port is open systemctl enable --now myapp.service 

That works. It also means the process, its language runtime, and its memory footprint sit warm forever — even at 3 a.m. when nobody is talking to it. Worse, if the daemon crashes hard enough to lose its listening socket, clients get Connection refused until something restarts it.

systemd already solved this. A .socket unit owns the listening file descriptor. The matching .service starts when traffic arrives (or in parallel at boot, sharing the pre-opened sockets). Same journal, cgroup, and sandbox knobs you already use for services.

This guide is operational. Behavior and defaults come from systemd.socket(5), systemd.service(5), sd_listen_fds(3), systemd-socket-proxyd(8), and stock units on systemd 257 (verified on Debian 13).

What a socket unit is (and is not)

A socket unit does not replace:

• services that must do heavy work before they can usefully accept clients (unless you also start them explicitly),
• full reverse proxies / L7 load balancers,
• apps that insist on binding and owning the port themselves with no FD-passing support (use systemd-socket-proxyd or fix the app).

It does replace most “always-on listener for rarely used ports” and pairs naturally with on-demand tools.

Mental model

1. You install foo.socket and foo.service (same basename by default).
2. You enable and start the socket unit, not necessarily the service.
3. systemd binds and listens before (or without) the service process.
4. On incoming traffic, systemd starts the service and passes listening FDs (or one accepted connection).
5. If the service exits and the socket unit stays up, the port keeps listening. The next connection can start the service again.
6. There is no implicit WantedBy= from socket → service. The service can still be started alone; if you need “service requires its socket”, add an explicit Requires= / After= on the service (or use Sockets=).

That last point is why ssh.socket + ssh.service style pairs are common: the socket is the always-on edge; the daemon is optional until needed (or started in parallel sharing the FD).

Prerequisites

systemctl --version | head -n 1 # systemd 257 (socket activation is long-standing; details below note version gates) man systemd.socket man sd_listen_fds systemctl list-units --type=socket --all 

On a typical host you already have stock examples:

• ssh.socket — ListenStream=22, Accept=no
• dbus.socket — ListenStream=/run/dbus/system_bus_socket
• systemd-hostnamed.socket — Varlink UNIX socket + FileDescriptorName=varlink
• systemd-journald.socket — multiple Listen* stanzas, PassCredentials=yes

systemctl cat ssh.socket # [Socket] # ListenStream=22 # Accept=no 

Accept=no vs Accept=yes

This is the fork in the road. Get it wrong and either naming or FD semantics will surprise you.

From systemd.socket(5):

• Performance-sensitive services prefer Accept=no.
• Sporadic tools prefer Accept=yes (simpler code, stronger per-connection sandboxing).
• With Accept=yes, set CollectMode=inactive-or-failed on the template so failed instances do not pile up in memory.

How FDs are passed (Accept=no)

Native protocol (sd_listen_fds(3)):

• FDs start at SD_LISTEN_FDS_START = 3 (after stdin/stdout/stderr).
• Count is in $LISTEN_FDS.
• $LISTEN_PID must match the receiving process (since 259, $LISTEN_PIDFDID is also checked when set).
• Optional $LISTEN_FDNAMES colon-separated names from FileDescriptorName= or defaults.
• systemd sets FD_CLOEXEC on the passed FDs.
• Do not shutdown(2) listening sockets you got with Accept=no — the manager keeps a duplicate and you would break it.
• Do not unlink AF_UNIX paths the manager owns.

inetd-style alternative: StandardInput=socket in the service. Then $LISTEN_FDS is not set; the connection (or listener, depending on Accept) is stdin. That path is ideal for Accept=yes helpers.

Lab 1 — Per-connection echo (Accept=yes)

inetd-mode is the fastest way to prove socket activation without linking libsystemd.

sudo tee /etc/systemd/system/lyra-echo@.service >/dev/null <<'EOF' [Unit] Description=Lyra per-connection echo server CollectMode=inactive-or-failed [Service] Type=oneshot ExecStart=/usr/bin/bash -c 'printf "lyra-echo ready\\n"; cat' StandardInput=socket StandardOutput=socket StandardError=journal # Optional hardening for a toy service: PrivateTmp=yes ProtectSystem=strict ProtectHome=yes EOF sudo tee /etc/systemd/system/lyra-echo.socket >/dev/null <<'EOF' [Unit] Description=Lyra echo socket (Accept=yes demo) [Socket] ListenStream=127.0.0.1:9099 Accept=yes # Defaults: MaxConnections=64 # TriggerLimitIntervalSec=2s TriggerLimitBurst=200 (Accept=yes) [Install] WantedBy=sockets.target EOF sudo systemctl daemon-reload sudo systemctl enable --now lyra-echo.socket systemctl status lyra-echo.socket --no-pager 

Test:

printf 'hello\n' | nc -q 1 127.0.0.1 9099 # lyra-echo ready # hello systemctl list-units 'lyra-echo@*' --all --no-pager journalctl -u 'lyra-echo@*' -n 20 --no-pager 

What just happened:

1. lyra-echo.socket bound 127.0.0.1:9099 and sat in listening.
2. nc connected; systemd accept()’d and spawned lyra-echo@<conn>.service.
3. The service saw the client on stdin/stdout, echoed, exited.
4. The socket unit kept listening for the next client.

$REMOTE_ADDR / $REMOTE_PORT are set for IPv4/IPv6 accepts (CGI-style; see RFC 3875). Useful for logging:

ExecStart=/usr/bin/bash -c 'echo "peer=$REMOTE_ADDR:$REMOTE_PORT" >&2; cat' 

Lab 2 — Long-running listener (Accept=no + $LISTEN_FDS)

Now the production-shaped path: one service, listening FDs inherited.

sudo tee /usr/local/bin/lyra-listen-demo >/dev/null <<'EOF' #!/usr/bin/env python3 """Minimal Accept=no socket-activated server using $LISTEN_FDS only.""" import os, socket, sys def listen_fds(): if os.environ.get("LISTEN_PID") != str(os.getpid()): return [] n = int(os.environ.get("LISTEN_FDS", "0")) # sd_listen_fds starts at FD 3 return list(range(3, 3 + n)) fds = listen_fds() if not fds: sys.stderr.write("no LISTEN_FDS; start via lyra-listen.socket\n") sys.exit(1) names = os.environ.get("LISTEN_FDNAMES", "").split(":") sys.stderr.write(f"got {len(fds)} fd(s) names={names!r}\n") listeners = [] for fd in fds: s = socket.fromfd(fd, socket.AF_INET, socket.SOCK_STREAM) # fromfd() dup's; close the passed fd number we no longer need os.close(fd) s.setblocking(True) listeners.append(s) # Single-listener demo lsock = listeners[0] sys.stderr.write("listening via systemd-passed FD\n") while True: conn, addr = lsock.accept() with conn: conn.sendall(b"lyra-listen: " + repr(addr).encode() + b"\n") while True: data = conn.recv(4096) if not data: break conn.sendall(data) EOF sudo chmod 755 /usr/local/bin/lyra-listen-demo sudo tee /etc/systemd/system/lyra-listen.service >/dev/null <<'EOF' [Unit] Description=Lyra Accept=no LISTEN_FDS demo Requires=lyra-listen.socket After=lyra-listen.socket [Service] ExecStart=/usr/local/bin/lyra-listen-demo # Type=simple is fine: the socket already holds the listener Restart=on-failure [Install] WantedBy=multi-user.target EOF sudo tee /etc/systemd/system/lyra-listen.socket >/dev/null <<'EOF' [Unit] Description=Lyra LISTEN_FDS demo socket [Socket] ListenStream=127.0.0.1:9100 Accept=no FileDescriptorName=lyra-demo # FreeBind=yes # useful when binding a specific IP before the iface is up # TriggerLimitIntervalSec=2s TriggerLimitBurst=20 (Accept=no defaults) [Install] WantedBy=sockets.target EOF sudo systemctl daemon-reload sudo systemctl enable --now lyra-listen.socket # Do NOT start the service yet — prove on-demand activation: systemctl is-active lyra-listen.service || true # inactive printf 'ping\n' | nc -q 1 127.0.0.1 9100 systemctl is-active lyra-listen.service # active journalctl -u lyra-listen.service -n 10 --no-pager 

Notes that matter in real daemons:

• Prefer sd_listen_fds() / sd_listen_fds_with_names() from libsystemd over hand-parsing env when you can; they set FD_CLOEXEC and validate pid/pidfd.
• With multiple ListenStream= lines, all FDs are passed, ordered as configured in that unit.
• Multiple socket units can point at one service via Service=; order across units is undefined — use FileDescriptorName= and sd_listen_fds_with_names().

Lab 3 — AF_UNIX with mode and ownership

UNIX sockets are how most local desktop/system buses do on-demand activation.

sudo tee /etc/systemd/system/lyra-unix.socket >/dev/null <<'EOF' [Unit] Description=Lyra AF_UNIX demo socket [Socket] ListenStream=/run/lyra/demo.sock SocketMode=0660 DirectoryMode=0755 # SocketUser=lyra SocketGroup=lyra # if the user/group exist Accept=yes RemoveOnStop=yes [Install] WantedBy=sockets.target EOF sudo tee /etc/systemd/system/lyra-unix@.service >/dev/null <<'EOF' [Unit] Description=Lyra AF_UNIX connection CollectMode=inactive-or-failed [Service] Type=oneshot StandardInput=socket StandardOutput=socket ExecStart=/usr/bin/bash -c 'printf "unix peer=%s\\n" "${REMOTE_ADDR:-unnamed}"; cat' PrivateTmp=yes EOF sudo systemctl daemon-reload sudo systemctl enable --now lyra-unix.socket printf 'hi-unix\n' | nc -U -q 1 /run/lyra/demo.sock ls -l /run/lyra/demo.sock 

Abstract-namespace sockets use @name instead of a filesystem path (ListenStream=@lyra-demo). No inode on disk; good for private IPC, awkward for ad-hoc nc debugging.

Listen family cheat sheet

Useful knobs when binding network listeners:

• FreeBind=yes — bind a specific IP before the address exists on an interface (IP_FREEBIND). Recommended whenever you pin a non-wildcard address.
• BindToDevice=eth0 — SO_BINDTODEVICE; adds device unit deps.
• BindIPv6Only= — default / both / ipv6-only.
• Backlog= — listen(2) backlog; silently capped by net.core.somaxconn (often 4096).
• ReusePort=, NoDelay=, KeepAlive=, DeferAcceptSec= — standard TCP tunables exposed as unit options.
• PassCredentials= / PassSecurity= — AF_UNIX ancillary creds (journald uses these).

Rate limits: trigger vs poll

Same family of knobs as .path units, with socket-specific defaults (systemd.socket(5)):

PollLimit* is the preferred flood brake. TriggerLimit* is the hard tripwire. Service StartLimitIntervalSec= / StartLimitBurst= still apply independently.

MaxConnections= (default 64) and MaxConnectionsPerSource= (default 0 = off) only apply to Accept=yes.

Parallel start and crash resilience

Lennart Poettering’s classic socket-activation write-up still holds:

• Listening sockets are created early; dependent daemons can start in parallel and talk immediately (writes queue in the socket buffer until the server catches up).
• If the service crashes but the socket unit stays up, clients do not get “connection refused” during the restart window — the backlog holds.
• Upgrades can restart the service process while keeping the same listening FDs.

Stock systemd-journald.socket is the textbook multi-listener unit: datagram + stream, credential passing, dedicated Service= name.

Bridging apps that cannot speak LISTEN_FDS

systemd-socket-proxyd(8) accepts the systemd-passed listener (Accept=no), then bidirectional-proxies each client to a backend TCP or UNIX socket. That is how you give socket activation to a daemon that only knows listen on its own path.

Sketch from the man page (nginx behind a host port):

# proxy-to-app.socket [Socket] ListenStream=80 [Install] WantedBy=sockets.target 

# proxy-to-app.service [Unit] Requires=app.service After=app.service Requires=proxy-to-app.socket After=proxy-to-app.socket [Service] Type=notify ExecStart=/usr/lib/systemd/systemd-socket-proxyd /run/app.sock PrivateTmp=yes 

Useful options:

• --connections-max= (default 256)
• --exit-idle-time= so the proxy (and a StopWhenUnneeded= backend) can idle down
• --proxy-protocol=v1 (261+) when the backend should see the real client IP
• JoinsNamespaceOf= when the backend uses PrivateNetwork= / PrivateTmp=

Caveat: side channels (SCM_RIGHTS, SO_PEERCRED, …) are not forwarded.

Service wiring checklist

[Unit] Requires=myapp.socket After=myapp.socket # optional: Sockets=myapp.socket # pulls socket via Wants+After from the service side  [Service] # Accept=no native daemon: ExecStart=/usr/local/bin/myapp # OR inetd-style: # StandardInput=socket # StandardOutput=socket  # Accept=yes template extras: # CollectMode=inactive-or-failed 

Install section belongs on the socket for on-demand:

[Install] WantedBy=sockets.target 

sudo systemctl enable --now myapp.socket # multi-user pull-in of sockets.target starts your listeners at boot 

Verification and debugging

systemctl status myapp.socket systemctl show myapp.socket -p Listen -p Accept -p NAccepted -p NConnections ss -ltnp | grep 9100 # or ss -xlp for UNIX journalctl -u myapp.socket -u myapp.service -b --no-pager # See what stock units look like when something already works: systemctl cat dbus.socket systemd-hostnamed.socket 

Common failures:

Cleanup the labs

sudo systemctl disable --now \ lyra-echo.socket lyra-listen.socket lyra-unix.socket 2>/dev/null || true sudo systemctl stop lyra-listen.service 2>/dev/null || true sudo rm -f \ /etc/systemd/system/lyra-echo.socket \ /etc/systemd/system/lyra-echo@.service \ /etc/systemd/system/lyra-listen.socket \ /etc/systemd/system/lyra-listen.service \ /etc/systemd/system/lyra-unix.socket \ /etc/systemd/system/lyra-unix@.service \ /usr/local/bin/lyra-listen-demo sudo systemctl daemon-reload 

Boundaries (what this post is not)

• Not .path drop-directory activation — that is filesystem inotify, covered separately.
• Not .timer schedules.
• Not a deep dive on busctl / Varlink method calls (those are APIs over sockets).
• Not full SSH hardening or nginx design — only the activation edge.
• Not kqueue/launchd on macOS; same idea, different unit language.

When to use which activation unit

Takeaways

1. Enable the .socket, keep the service on-demand (or share FDs for parallel boot).
2. Choose Accept=no for real daemons and Accept=yes for inetd-style one-shot connections.
3. Teach apps sd_listen_fds / $LISTEN_FDS, or put StandardInput=socket in front of simple helpers.
4. Use FreeBind=, FileDescriptorName=, and PollLimit* deliberately on network edges.
5. For stubborn legacy listeners, systemd-socket-proxyd is the supported bridge — not a home-grown socat unit without notify/cgroup integration.

Once the listening FD lives in systemd, “is the port up?” stops meaning “is the whole app up?” — and that is a much calmer way to run rarely used services on a Linux host.

References

• systemd.socket(5) — socket unit options, Accept=, Listen*, limits (man systemd.socket)
• systemd.service(5) — service templates, Sockets=, activation ordering
• sd_listen_fds(3), sd_listen_fds_with_names(3) — FD passing protocol ($LISTEN_FDS, FD 3+)
• systemd-socket-proxyd(8) — proxy helper for non-native socket activation
• systemd.unit(5), systemd.exec(5) — dependencies, sandboxing, StandardInput=
• Stock units: ssh.socket, dbus.socket, systemd-hostnamed.socket, systemd-journald.socket
• Lennart Poettering, Socket Activation (systemd for Developers): https://0pointer.net/blog/projects/socket-activation.html
• Debian manpages mirror: https://manpages.debian.org/testing/systemd/systemd.socket.5.en.html
• Arch man pages: https://man.archlinux.org/man/systemd.socket.5