dbus-broker

The dbus-broker process is designed to be isolated. It performs no file-system access, no nss calls, and no external process communication. It only interacts with resources passed to it via command-line arguments or the Controller interface.

The Controller's Role

The Controller (e.g., dbus-broker-launch) owns a unix socket passed to the broker via --controller. The broker uses this socket to receive control commands. The Controller is responsible for:

• Creating listener sockets.
• Specifying bus policies.
• Creating activatable names.
• Reacting to bus events.
• Performing all external resource acquisitions on behalf of the broker.

The Broker's Role

The Broker is a pure message mediator. It starts with an empty list of bus-sockets and no way for clients to connect until the Controller uses the interface to set them up.

Socket Activation

The socket for client connections must be created and passed to dbus-broker-launch by its parent process. It must follow the systemd.socket protocol. Only a single socket is supported. Note that <listen>%path%</listen> attributes in the configuration file are ignored.

Privileges

• Configuration: The launcher requires read-access to its configuration file.
• Privilege Dropping: If the <user>%user%</user> configuration attribute is used, the launcher will drop privileges when executing dbus-broker.
• Systemd Access: If activatable services are declared, the launcher must have access to the corresponding systemd instance and be allowed to spawn transient units and manage units declared in service definitions.

Unlike dbus-daemon, dbus-broker-launch activates all services as systemd units.

• Services with an existing systemd unit are activated normally.
• Services without a systemd unit are activated as transient units via an ad-hoc unit-file generated at runtime. This ensures all services run in a well-defined environment.

The --scope parameter determines which systemd instance is used for activation:

• system: Uses the system instance of systemd.
• user: Uses the user instance of systemd.

Note: The scope also determines the default configuration file used if --config-file is not provided. If no activatable services are declared, the scope has no effect.

dbus-broker uses the Meson build system. To build and install the project from source, use the following sequence of commands:

$ meson setup build
$ meson compile -C build
$ meson test -C build
$ meson install -C build

The following software is required to build dbus-broker from source:

• linux-api-headers: >= 6.5
• meson: >= 1.3
• pkg-config: >= 0.29
• rust: >= 1.84
• rust-bindgen: >= 0.60

Optional build dependencies:

• dbus: >= 1.10 (required only for running tests)
• python-docutils: >= 0.13 (required only for generating documentation)

dbus-broker-launch is a launcher for dbus-broker that spawns and manages a D-Bus Message Bus. It is designed to be fully compatible with the dbus-daemon configuration syntax and runtime environment. Each instance of the launcher manages exactly one independent message bus.

To run the launcher, you can specify a configuration file or rely on the defaults. If no configuration is provided, it defaults to /usr/share/dbus-1/system.conf for system scope or /usr/share/dbus-1/session.conf for user scope.

# Example: Launching with a specific configuration file
dbus-broker-launch --config-file=/path/to/your/bus.conf

If you are using the compatibility launcher, the following additional dependencies are required:

• expat: >= 2.2
• systemd: >= 230

To run dbus-broker, your Linux system must meet the following requirements:

• glibc: >= 2.16
• linux kernel: >= 4.17

Optional runtime dependencies:

• libaudit: >= 3.0
• libcap-ng: >= 0.6
• libselinux: >= 3.2

Logging is enabled by providing a file-descriptor via the --log FD option. The broker supports two logging formats based on the type of the unix socket:

1. SOCK_STREAM: Information is logged as human-readable, line-based chunks.
2. SOCK_DGRAM: Information is logged as key/value based annotated data blocks (compatible with systemd-journal format). This mode is more verbose and provides extensive metadata for tracing.

When the broker logs

• Startup/Shutdown: A single message providing metadata about the environment and setup.
• Policy Denials: When a client request is denied by the policy (includes affected client and policies).
• Resource Exhaustion: When a client exceeds its allocated quota.

The dbus-broker-launch utility relies on inheriting specific Unix domain sockets from its parent process (typically systemd) via sd_listen_fds. It specifically looks for sockets with the following names:

• dbus.socket: The primary listener socket for D-Bus messages.
• dbus-metrics.socket: A socket used for exporting metrics.

If the launcher does not find a suitable dbus.socket among the inherited file descriptors, it will fail with the error: No suitable listener socket inherited.

A Session consists of a message broker (either dbus-broker or dbus-daemon) and a session controller.

Lifecycle behavior:

• Initiation: The session spawns the broker and the controller. If dbus-daemon is used, it sets the DBUS_SESSION_BUS_ADDRESS environment variable.
• Monitoring: The session waits for the controller to exit. If the message broker exits unexpectedly before the controller, a warning is issued, but the session continues to monitor the controller.
• Termination: If the session controller exits, the message broker is immediately terminated. If the Session object is dropped (e.g., the parent process crashes or exits), SIGTERM is sent to both the broker and the controller to ensure a clean teardown. The listener socket (if any) is also removed from the filesystem.

Implemented on nodes matching /org/bus1/DBus/Metrics/%.