mesh-catalog/modules/dbus/README.md

dbus

A machine's message bus (novox/hq ADR 0215). This module holds node-message-bus on every machine, servers included, because every machine runs a D-Bus system bus. It owns the bus implementation's packages and declares its system service running. It publishes what matters about the bus on the mesh's bus, and serves tools to look at the system bus and at the operator's session bus.

What it owns

package dbus-broker	the bus every machine runs
package dbus-broker-units	dbus.service as an alias of dbus-broker.service, for the system and for each user
package dbus	the bus's configuration (system.conf, session.conf), dbus.socket, which starts the bus at boot, and libdbus
service dbus-broker.service	declared running, with no boot state and no restart or reload trigger (below)

All four machines were found with dbus-broker 37 behind dbus.service and dbus 1.16.2, from the distribution. One server also has an old dbus-units package, an empty package that depends on dbus-broker-units. It is not declared: nothing needs it, and removing it is a choice for its operator.

The bus is never restarted live

On 2026-10-04 a full upgrade on a workstation restarted the system bus while the upgrade was still running. From then on every login hung, sshd answered nothing and the machine's host stopped reporting, until someone rebooted it at its keyboard. Every program that speaks on the bus (the service manager, logind, the network manager, the keyring, the power module's sleep lock) holds a connection to it. A restart takes all of them away at once, and not all of them come back.

So the module never restarts or reloads the bus, for any change. Its service has no restart-on and no reload-on, and the host never restarts a service that has neither. A new bus takes effect at the next boot. dbus_check says when the running bus is older than an installed package, which is the sign that a reboot is due. The distribution's own upgrade can still restart the bus. This rule covers what the mesh does, not what pacman does.

Why state: running and no boot. dbus.service is an alias (systemctl is-enabled says alias), so it cannot be declared enabled: the host would run systemctl enable and read back something other than enabled. The real unit, dbus-broker.service, reads disabled on three machines and enabled on one. It needs no enabling. At boot dbus.socket, which the dbus package links into sockets.target, pulls in dbus.service, and dbus-broker-units ships that name as a link to dbus-broker.service. On the three machines where it reads disabled, enabling it would only write a second alias link into /etc, and a module's apply would change something on a running machine for no gain. The service is declared so that the mesh knows the bus is the module's and says so when it is not running. A host finding it stopped would start it, which can only help a machine whose bus is down. ADR 0215 §1 says "running and enabled". On these machines the package's own socket link is what makes it start at boot.

A policy change a module needs in the future uses the bus's own reload (dbus-broker.service is Type=notify-reload), which keeps every connection. No module needs one today (below).

Events

The watcher runs beside the tools in the same process, on its own connection to the system bus as the operator's account. It reads only the bus driver's answers, the driver's NameOwnerChanged signal and the bus unit's journal.

event	when	carries
bus.stalled	the bus does not answer the driver's GetId within 3 s, or cannot be reached	the reason
bus.recovered	a stalled bus answers again	since when it was stalled, and for how long
bus.restarted	after reconnecting, the bus's id or the driver's pid has changed within the same boot (after a boot both change, and power says booted)	the old and new id and pid, the unit
service.appeared	a well-known name appears and is still there 10 s later	the name, the owner's pid, process and unit, whether it is activatable
service.left	a well-known name is gone and still gone 10 s later	the name and what held it
policy.denied	the bus logged a policy denial, at most once per 5 minutes	how many since the last one, and up to 5 distinct examples: the refused message's type, sender, destination, path, interface and member

Unique names (:1.42) come and go with every client and are never published. A service restarted within the 10 s, or one that came and went, publishes nothing. Activatable services that exit when idle, such as hostnamed, do appear and leave, and their events say activatable: true.

Why traffic never leaves the machine. The bus carries secrets from the keyring, notification text and the clipboard. The watcher never becomes a monitor, so it never sees another peer's messages. Its events are built from names, pids, units and the header fields the broker logs with a denial. The log line itself is not passed on. The tests hold every event's body to those fields.

Events the mesh's bus does not take wait in order and go out when it answers again, as power's do. At most 1000 events wait. When there are more, the oldest are dropped and counted.

The watcher's ping is GetId, not org.freedesktop.DBus.Peer.Ping. The system policy refuses the peer ping to an account that is not root and logs a denial each time, which the watcher would then publish.

Tools

tool
dbus_names	bus: system or session. Every well-known name with its owner's pid, process, user and unit, the activatable names that are not running, and the number of connections
dbus_introspect	bus, service, path. The object's interfaces with their methods, properties (type and access, never values) and signals, and its children. Uses --auto-start=no, so looking never starts a service
dbus_monitor	bus, seconds (at most 15), optional match rule and names. The headers of what passed (type, sender, destination, path, interface, member, error name), at most 500. Never a body: each line is decoded into the header alone. On the system bus only root may monitor, so it runs through sudo -n
dbus_check	the packages are installed. dbus.service is dbus-broker.service and active. The running bus is not older than the installed dbus-broker or dbus (otherwise a reboot is due). Every activatable service file's SystemdService exists. Policy denials in the last hour. The watcher is connected, not stalled, and has nothing stuck
dbus_health	the round trip of a ping on the watcher's connection, the connection count (from Debug.Stats through sudo -n, else the unique names), and the bus's unit, pid, start and uptime

Every command is bounded at 20 s and its output read up to 1 MiB. Lists stop at 500 entries. Debug.Stats is asked only as root: asked as the account it is refused and logged as a denial.

The session bus is the runtime's DBUS_SESSION_BUS_ADDRESS, else $XDG_RUNTIME_DIR/bus, else /run/user/<uid>/bus. On a machine where the account has no session, the tools say so.

The check notes, without failing, systemd's own services whose dbus-org.* alias is missing because they are not enabled, such as resolved, networkd and homed on the workstations. Activating them fails by design.

Assignment

On every machine, as the first holder of node-message-bus. The module needs nothing set: no settings, no secrets, no ports.

What comes later

ADR 0215 §4: the seat receives nothing yet. Packages ship their own D-Bus policy and service files, and no module writes one of its own. When one does, that file will be a contribution to this seat, and this module will list the kind and reload the bus's policy for it, without a restart.