go-systemd

go-systemd is a collection of Go packages maintained by CoreOS/Red Hat that let Go programs talk directly to systemd, the init system and service manager used on most modern Linux distributions. Rather than shelling out to systemctl or journalctl, services written in Go can use these bindings to participate natively in the systemd ecosystem: accepting sockets systemd hands them via activation, reporting readiness and health via the sd_notify protocol, writing structured entries straight into the journal, and starting, stopping, or introspecting units over D-Bus.

The module is organized as eight independent, single-purpose packages (activation, daemon, dbus, journal, sdjournal, login1, machine1, unit) so consumers only import what they need. It underlies infrastructure tooling across the Go ecosystem, including container runtimes and orchestration systems that need to interoperate with systemd-managed hosts, and is the de facto standard library for this kind of systemd integration in Go.

What You Get

• Socket activation (activation) - retrieve listener sockets systemd already opened and passed to your process via file descriptors, including net.Listener and net.PacketConn helpers.
• sd_notify support (daemon) - send READY, STOPPING, RELOADING, and WATCHDOG state notifications to the service manager, plus watchdog interval helpers.
• D-Bus unit management (dbus) - start, stop, restart, reload, and inspect systemd units, subscribe to unit state-change signals, and query job/unit properties over the systemd D-Bus API.
• Journal writing (journal) - a pure-Go client that writes structured, indexed key/value log entries directly to journald over its Unix socket, no cgo required.
• Journal reading (sdjournal) - cgo bindings around the native sd-journal C API for reading and following journal entries, including filtering by match fields.
• logind and machined integration (login1, machine1) - interact with the systemd logind session-management API and the machined API for registering containers/VMs.
• Unit file parsing (unit) - serialize and deserialize systemd unit files and compare unit option sets programmatically.

Common Use Cases

• Zero-downtime socket handoff - a long-running network service lets systemd own and pre-bind its listening socket via .socket units, then picks it up through activation.Listeners() on start, enabling socket-based restarts with no dropped connections.
• Health-checked systemd services - a daemon calls daemon.SdNotify to tell systemd exactly when startup finished and periodically pings the watchdog, letting systemd auto-restart it if it hangs.
• Infrastructure tooling that drives systemd - container runtimes, VM managers, and cluster agents use the dbus package to start/stop/inspect systemd units on the host as part of orchestrating workloads.
• Structured logging into journald - a Go service writes leveled, tagged log entries directly to the journal via the journal package instead of writing to stdout/files, so they show up correctly in journalctl with metadata.
• Building systemd-aware CLIs and agents - operational tools parse and edit .service/.socket unit files programmatically with the unit package, or query login1/machine1 for session and container state.

Under The Hood

Architecture The module is organized as eight independent, single-purpose packages rather than one monolithic client, so consumers import only the subsystem they need. The dbus package centers on a Conn type wrapping github.com/godbus/dbus/v5, with a mutex-guarded job-listener map (in methods.go/subscription.go) that turns async D-Bus signals into blocking Go calls via channels; subscription.go runs a dedicated signal-dispatch loop for Subscribe/SubscribeUnits. The daemon and journal packages are largely stateless — daemon.SdNotify writes directly to a Unix datagram socket named by an environment variable, while journal lazily initializes and atomically caches a shared Unix socket connection for structured writes. sdjournal takes a different path entirely, wrapping the native sd-journal C API via cgo for reading rather than writing. There is no shared global state or DI framework across packages — composition is left entirely to the caller, and each package can be vendored independently.

Tech Stack A Go 1.24+ module with exactly two runtime dependencies: github.com/godbus/dbus/v5 for the D-Bus wire protocol and golang.org/x/sys for low-level syscalls. Most packages (activation, daemon, journal, dbus, unit) are pure Go; only sdjournal requires cgo and the libsystemd-dev headers at build time to link against journald’s native library. CI (GitHub Actions) builds and tests across Go 1.24–1.26 and, in a separate workflow, inside multiple Linux distro containers (Debian, Ubuntu, Fedora) to catch platform-specific journal/D-Bus behavior.

Code Quality 26 _test.go files exercise every package, including the D-Bus connection lifecycle, journal writing, unit serialization round-trips, and socket activation edge cases. .golangci.yml enables gofumpt formatting and staticcheck with nearly all checks turned on (only two relaxed for stylistic reasons), and govet’s nilness check is explicitly enabled. Error handling follows idiomatic Go — plain error returns via fmt.Errorf/errors.New, no custom error hierarchy. Naming and doc-comment style are consistent and exported-symbol documentation is thorough throughout.

What Makes It Unique go-systemd doesn’t attempt novel abstractions over systemd’s interfaces — it’s a faithful, comprehensive Go implementation of existing protocols (the sd_notify text protocol, the D-Bus wire format, journald’s socket protocol, and the sd-journal C API). Its value is completeness and correctness as the de facto standard integration surface for Go programs that need to be well-behaved systemd citizens, used as a dependency by container runtimes and cluster tooling across the ecosystem rather than competing on novel design.