### Build and Install dbus-broker with Meson

Source: https://github.com/bus1/dbus-broker/blob/main/README.md

Standard commands to set up, compile, test, and install dbus-broker using the meson build system. Refer to meson_options.txt for custom configurations.

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

--------------------------------

### Install Dependencies and Build dbus-broker with Meson

Source: https://context7.com/bus1/dbus-broker/llms.txt

Installs mandatory build dependencies for Fedora/RHEL and configures the build with optional features like SELinux and documentation. Then, it builds and installs the package.

```sh
# Install mandatory build dependencies (Fedora/RHEL example)
dnf install meson gcc rust bindgen \
    libcdvar-devel libcini-devel libclist-devel \
    libcrbtree-devel libcshquote-devel libcstdaux-devel

# Configure – enable launcher, SELinux support, and man-pages
meson setup build \
    -Dlauncher=true \
    -Dselinux=true \
    -Daudit=true \
    -Ddocs=true \
    -Dtests=true

# Build and install
ninja -C build
ninja -C build install

# Verify installed binaries
dbus-broker --version
# dbus-broker 37
dbus-broker-launch --version
# dbus-broker-launch 37
```

--------------------------------

### XML D-Bus Bus Configuration Example

Source: https://context7.com/bus1/dbus-broker/llms.txt

This XML snippet demonstrates the structure of a D-Bus bus configuration file, compatible with dbus-daemon. It includes settings for user, type, included directories, resource limits, and policy definitions.

```xml
<!-- /usr/share/dbus-1/system.conf (abbreviated example) -->
<!DOCTYPE busconfig PUBLIC
  "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
  "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
<busconfig>
  <!-- Run broker as this user after startup -->
  <user>messagebus</user>
  <type>system</type>

  <!-- Include all per-package policy fragments -->
  <includedir>/etc/dbus-1/system.d</includedir>
  <includedir>/usr/share/dbus-1/system.d</includedir>
  <standard_system_servicedirs/>

  <!-- Resource limits (mirrors dbus-daemon defaults) -->
  <limit name="max_incoming_bytes">268435456</limit>
  <limit name="max_outgoing_bytes">268435456</limit>
  <limit name="max_message_size">134217728</limit>
  <limit name="max_match_rules_per_connection">512</limit>

  <!-- Default deny-all, then selectively allow -->
  <policy context="default">
    <deny send_destination="*" eavesdrop="true"/>
    <deny receive_sender="*" eavesdrop="true"/>
    <deny send_type="method_call"/>
    <allow send_destination="org.freedesktop.DBus"/>
  </policy>

  <!-- Allow root to do everything -->
  <policy user="root">
    <allow send_destination="*"/>
    <allow receive_sender="*"/>
    <allow own="*"/>
  </policy>

  <!-- Per-service policy fragment (drop into /etc/dbus-1/system.d/) -->
  <!-- /etc/dbus-1/system.d/org.example.Service.conf -->
  <!--
  <busconfig>
    <policy user="exampleuser">
      <allow own="org.example.Service"/>
      <allow send_destination="org.example.Service"
             send_interface="org.example.Service.Interface"/>
    </policy>
    <policy context="default">
      <allow send_destination="org.example.Service"
             send_interface="org.freedesktop.DBus.Introspectable"/>
    </policy>
  </busconfig>
  -->
</busconfig>
```

--------------------------------

### Programmatic Signal Subscription with sd-bus (C)

Source: https://context7.com/bus1/dbus-broker/llms.txt

Example of how to programmatically subscribe to signals using the sd-bus library in C. This involves calling sd_bus_add_match with specific parameters.

```c
#include <sys/socket.h>
#include <unistd.h>

/*
 * Minimal private bus setup:
 * 1. Create a socketpair for the controller channel
 * 2. Create a Unix listener for bus clients
 * 3. Fork + exec dbus-broker, passing in FDs
 * 4. Call AddListener over the controller socket
 * 5. Pass a permissive policy (allow all) for the private bus
 */

int setup_private_bus(void) {
    int ctrl[2], rc;

    // Controller channel (broker inherits ctrl[1] as FD 3)
    socketpair(AF_UNIX, SOCK_STREAM | SOCK_CLOEXEC, 0, ctrl);

    // Listening socket for bus clients
    int listen_fd = socket(AF_UNIX, SOCK_STREAM | SOCK_NONBLOCK | SOCK_CLOEXEC, 0);
    struct sockaddr_un addr = { AF_UNIX, "/run/myapp/bus.socket" };
    bind(listen_fd, (struct sockaddr *)&addr, sizeof(addr));
    listen(listen_fd, SOMAXCONN);

    pid_t pid = fork();
    if (pid == 0) {
        // Child: become the broker
        dup2(ctrl[1], 3);            // controller FD → 3
        close(ctrl[0]); close(ctrl[1]);

        char machine_id[33];
        read_machine_id(machine_id); // read /etc/machine-id

        execl("/usr/bin/dbus-broker",
              "dbus-broker",
              "--controller", "3",
              "--machine-id", machine_id,
              NULL);
        _exit(1);
    }

    close(ctrl[1]); // parent keeps ctrl[0]

    // Parent: act as controller
    // Call AddListener on /org/bus1/DBus/Broker via ctrl[0]
    // (wire format: D-Bus P2P method call with FD passing)
    controller_call_add_listener(ctrl[0], listen_fd, build_allow_all_policy());

    return ctrl[0]; // return controller FD for ongoing management
}

```

--------------------------------

### Handle Service Activation Request

Source: https://context7.com/bus1/dbus-broker/llms.txt

This C code demonstrates how a controller receives an Activate signal for an unowned but activatable name. It shows pseudocode for looking up a systemd unit and starting it. If starting fails, it calls Reset to signal the broker.

```c
/*
 * Signal received by the controller on the private socket:
 *
 * node     /org/bus1/DBus/Name/<escaped-name>
 * signal   org.bus1.DBus.Name.Activate(t serial)
 *
 * The controller must then either:
 *   a) spawn/start the service and wait for it to claim the name, then
 *      let the broker auto-dispatch pending messages, OR
 *   b) call Reset() to cancel the activation with an error.
 */

// Systemd-based controller example (pseudocode):
void on_activate_signal(const char *name_path, uint64_t serial) {
    const char *unit = lookup_unit_for_name(name_path); // e.g. "org.example.Service.service"

    int rc = sd_bus_call_method(systemd_bus,
        "org.freedesktop.systemd1",
        "/org/freedesktop/systemd1",
        "org.freedesktop.systemd1.Manager",
        "StartUnit",
        NULL, NULL,
        "ss", unit, "replace");

    if (rc < 0) {
        // Signal the broker that activation failed
        // busctl call ... org.bus1.DBus.Name Reset "ts"
        //   <serial> "org.bus1.DBus.Name.Error.StartupFailure"
        controller_name_reset(name, serial, CONTROLLER_NAME_ERROR_STARTUP_FAILURE);
    }
    // On success the service will acquire the name; broker delivers pending messages.
}
```

--------------------------------

### Example Log Output Fields

Source: https://context7.com/bus1/dbus-broker/llms.txt

Illustrates the structure of log messages from dbus-broker when using journal logging. Shows fields like MESSAGE, DBUS_BROKER_NAME, and DBUS_BROKER_ERROR for activation failures, and sender/destination/rule for policy violations.

```text
# Example log output (journal fields):
# MESSAGE=Activation request for name org.example.Service failed: unit is masked
# DBUS_BROKER_NAME=org.example.Service
# DBUS_BROKER_ERROR=org.bus1.DBus.Name.Error.MaskedUnit

# Policy violation example:
# MESSAGE=Peer :1.42 is not allowed to send to org.example.Service
# DBUS_BROKER_SENDER=:1.42
# DBUS_BROKER_DESTINATION=org.example.Service
# DBUS_BROKER_RULE=send_destination=org.example.Service
```

--------------------------------

### Display Help for dbus-broker-launch

Source: https://context7.com/bus1/dbus-broker/llms.txt

Shows the help message and available options for the dbus-broker-launch utility.

```bash
dbus-broker-launch --help
```

--------------------------------

### Build-time Software Requirements

Source: https://github.com/bus1/dbus-broker/blob/main/README.md

Lists the software needed at build-time, such as linux-api-headers, meson, pkg-config, and Rust toolchain components.

```text
  linux-api-headers >= 4.13
  meson >= 1.3
  pkg-config >= 0.29
  rust >= 1.84
  rust-bindgen >= 0.60
  dbus >= 1.10                (optional: only for tests)
  python-docutils >= 0.13     (optional: only for docs)
```

--------------------------------

### Launch D-Bus Broker with Custom Config

Source: https://context7.com/bus1/dbus-broker/llms.txt

Launches the dbus-broker as a user bus, specifying a custom configuration file.

```bash
dbus-broker-launch --scope user --config-file /etc/dbus-1/session.conf
```

--------------------------------

### Minimal dbus-broker Invocation

Source: https://context7.com/bus1/dbus-broker/llms.txt

Demonstrates the minimal command-line invocation for the dbus-broker process, specifying essential parameters like the controller file descriptor, machine ID, and logging level. It also shows how to view all supported options.

```sh
# Minimal invocation (controller FD is 3 by convention, machine-id is mandatory)
MACHINE_ID=$(cat /etc/machine-id)
dbus-broker \
    --controller 3 \
    --machine-id "$MACHINE_ID" \
    --log 4 \
    --max-bytes $((16 * 1024 * 1024)) \
    --max-fds 64 \
    --max-matches 16384 \
    --max-objects 16384 \
    --audit

# Show all supported options
dbus-broker --help
# dbus-broker [GLOBALS...] ...
#
# Linux D-Bus Message Broker
#
#   -h --help                     Show this help
#      --version                  Show package version
#      --audit                    Log to the audit subsystem
#      --controller FD            Specify controller file-descriptor
#      --log FD                   Provide logging socket
#      --machine-id MACHINE_ID    Machine ID of the current machine
#      --max-bytes BYTES          Maximum number of bytes each user may allocate
#      --max-fds FDS              Maximum number of file descriptors each user may allocate
#      --max-matches MATCHES      Maximum number of match rules each user may allocate
#      --max-objects OBJECTS      Maximum total number of objects each user may allocate
```

--------------------------------

### Meson Build Options for dbus-broker

Source: https://context7.com/bus1/dbus-broker/llms.txt

Configure the build of dbus-broker using Meson. Options control features like launcher, audit, SELinux, AppArmor, documentation, and testing.

```sh
# Full-featured build for a typical Linux distribution
meson setup build \
    -Dlauncher=true \
    -Daudit=true \
    -Dselinux=true \
    -Dapparmor=true \
    -Ddocs=true \
    -Dtests=true \
    -Dreference-test=true \
    -Dsystem-console-users='["gdm","sddm"]'

# Minimal embedded build (no launcher, no LSM, no audit)
Meson setup build \
    -Dlauncher=false \
    -Daudit=false \
    -Dselinux=false \
    -Dapparmor=false

ninja -C build
```

--------------------------------

### Spawn D-Bus Broker with Custom Resource Limits

Source: https://context7.com/bus1/dbus-broker/llms.txt

This shell command demonstrates how to spawn the dbus-broker directly with custom per-user resource limits for memory, file descriptors, match rules, and objects. Exceeding these limits will result in errors or disconnections.

```sh
# Set custom per-user resource limits when spawning dbus-broker directly
dbus-broker \
    --controller 3 \
    --machine-id "$(cat /etc/machine-id)" \
    --max-bytes $((32 * 1024 * 1024))   `# 32 MiB memory per UID` \
    --max-fds 128                        `# 128 Unix FDs per UID` \
    --max-matches 32768                  `# 32k match rules per UID` \
    --max-objects $((32 * 1024 * 1024))  `# 32M objects per UID`
```

--------------------------------

### Attach OpenMetrics Endpoint Socket to Broker

Source: https://context7.com/bus1/dbus-broker/llms.txt

Shows how to attach a listening socket to the broker for exposing internal metrics in OpenMetrics format using the AddMetrics method. Includes the D-Bus method signature and a busctl equivalent.

```c
/*
 * Interface: org.bus1.DBus.Broker
 * Method:    AddMetrics(o path, h socket) -> ()
 */

// busctl equivalent:
// busctl call --address=unix:fd=3 \
//     org.bus1.DBus.Broker /org/bus1/DBus/Broker \
//     org.bus1.DBus.Broker AddMetrics "oh" \
//     /org/bus1/DBus/Metrics/0  <metrics_fd>

// Once connected a client receives, e.g.:
// # HELP dbus_broker_matches_peak Peak number of match rules
// # TYPE dbus_broker_matches_peak gauge
// dbus_broker_matches_peak 42
// # EOF

```

```bash
busctl call --address=unix:fd=3 \
    org.bus1.DBus.Broker /org/bus1/DBus/Broker \
    org.bus1.DBus.Broker AddMetrics "oh" \
    /org/bus1/DBus/Metrics/0  <metrics_fd>
```

--------------------------------

### dbus-broker Build Requirements

Source: https://github.com/bus1/dbus-broker/blob/main/README.md

Lists the minimum required versions for glibc, Linux kernel, and optional libraries like libaudit, libcap-ng, and libselinux.

```text
  glibc >= 2.16
  linux kernel >= 4.17
  libaudit >= 3.0               (optional)
  libcap-ng >= 0.6              (optional)
  libselinux >= 3.2             (optional)
```

--------------------------------

### AddListener

Source: https://context7.com/bus1/dbus-broker/llms.txt

Attaches a client-facing listener socket to the broker, allowing clients to connect and be served immediately. This method requires a path, a file descriptor for the listening socket, and a policy database.

```APIDOC
## AddListener – attach a client-facing listener socket

Passes an already-listening Unix socket to the broker together with a policy database. Clients connecting to this socket are immediately served.

### Interface
org.bus1.DBus.Broker

### Method
AddListener(o path, h socket, v policy) -> ()

### Parameters
- **path** (o): Object path for the listener.
- **socket** (h): File descriptor of the listening Unix socket.
- **policy** (v): A variant containing the policy database.

### Response
- **()**: Empty success tuple.
```

--------------------------------

### Compatibility Launcher Requirements

Source: https://github.com/bus1/dbus-broker/blob/main/README.md

Specifies the software versions required for the compatibility launcher, including expat and systemd.

```text
  expat >= 2.2
  systemd >= 230
```

--------------------------------

### Register Activatable Bus Name with Broker

Source: https://context7.com/bus1/dbus-broker/llms.txt

Demonstrates how to declare a well-known name as activatable using the AddName method. The broker will emit an Activate signal when the name is requested, prompting the controller to spawn the service. Includes the D-Bus method signature and a busctl equivalent.

```c
/*
 * Interface: org.bus1.DBus.Broker
 * Method:    AddName(o path, s name, u uid) -> ()
 *
 * path  – object path on the controller, e.g. /org/bus1/DBus/Name/org_example_Service
 * name  – the well-known D-Bus name, e.g. "org.example.Service"
 * uid   – UID whose resource quota the activatable name is charged against
 */

// busctl equivalent:
// busctl call --address=unix:fd=3 \
//     org.bus1.DBus.Broker /org/bus1/DBus/Broker \
//     org.bus1.DBus.Broker AddName "osu" \
//     /org/bus1/DBus/Name/org_example_Service \
//     "org.example.Service" \
//     1000

// The broker will now emit this signal when activation is requested:
// signal org.bus1.DBus.Name.Activate(t serial)
// at path /org/bus1/DBus/Name/org_example_Service

```

```bash
busctl call --address=unix:fd=3 \
    org.bus1.DBus.Broker /org/bus1/DBus/Broker \
    org.bus1.DBus.Broker AddName "osu" \
    /org/bus1/DBus/Name/org_example_Service \
    "org.example.Service" \
    1000
```

--------------------------------

### Add Client Listener Socket to Broker

Source: https://context7.com/bus1/dbus-broker/llms.txt

Pseudocode demonstrating how a controller attaches a client-facing listener socket to the broker using the AddListener method. This involves creating a Unix listener socket, binding it, listening, building a policy, and then calling AddListener via a controller D-Bus connection.

```c
/*
 * Pseudocode showing how a controller calls AddListener over the
 * private D-Bus connection (FD 3) after socketpair() + fork() + exec().
 *
 * Interface: org.bus1.DBus.Broker
 * Method:    AddListener(o path, h socket, v policy) -> ()
 */

// 1. Create the Unix listener socket
int listener_fd = socket(AF_UNIX, SOCK_STREAM | SOCK_NONBLOCK | SOCK_CLOEXEC, 0);
struct sockaddr_un addr = { .sun_family = AF_UNIX, .sun_path = "/run/dbus/system_bus_socket" };
bind(listener_fd, (struct sockaddr *)&addr, sizeof(addr));
listen(listener_fd, SOMAXCONN);

// 2. Build the policy (serialized as a D-Bus variant 'v')
//    The policy encodes connect/own/send/receive verdicts per UID/GID batch.
//    See policy_registry_import() in src/bus/policy.c for the wire format.

// 3. Call AddListener via the controller socket (fd=3)
//    busctl equivalent for testing:
//    busctl call --address=unix:fd=3 \
//        org.bus1.DBus.Broker /org/bus1/DBus/Broker \
//        org.bus1.DBus.Broker AddListener "ohv" \
//        /org/bus1/DBus/Listener/0  <listener_fd>  <policy_variant>

// 4. From now on, the broker serves clients connecting to /run/dbus/system_bus_socket.
// Expected reply: () — empty success tuple

```

```bash
busctl call --address=unix:fd=3 \
    org.bus1.DBus.Broker /org/bus1/DBus/Broker \
    org.bus1.DBus.Broker AddListener "ohv" \
    /org/bus1/DBus/Listener/0  <listener_fd>  <policy_variant>
```

--------------------------------

### Launch D-Bus Broker as System Bus

Source: https://context7.com/bus1/dbus-broker/llms.txt

Launches the dbus-broker as a system bus, utilizing systemd socket activation for its listener sockets.

```bash
dbus-broker-launch --scope system --audit
```

--------------------------------

### Enable dbus-broker as System Bus

Source: https://github.com/bus1/dbus-broker/wiki/Home

Enables dbus-broker as the system bus using systemd. This replaces the default dbus.service with dbus-broker.service.

```bash
# systemctl enable dbus-broker.service
```

--------------------------------

### Enable dbus-broker as User Bus

Source: https://github.com/bus1/dbus-broker/wiki/Home

Enables dbus-broker as the user bus using systemd. This can be done for the current user or globally for all local users.

```bash
# systemctl --user enable dbus-broker.service
```

```bash
# systemctl --global enable dbus-broker.service
```

--------------------------------

### dbus-broker Systemd Unit Configuration

Source: https://context7.com/bus1/dbus-broker/llms.txt

This is the systemd unit file template for dbus-broker, defining its service type, resource limits, and dependencies. It specifies the execution command for dbus-broker-launch.

```ini
[Unit]
Description=D-Bus System Message Bus
Documentation=man:dbus-broker-launch(1)
DefaultDependencies=false
After=dbus.socket dbus-metrics.socket
Before=basic.target shutdown.target
Conflicts=shutdown.target
Requires=dbus.socket
Wants=dbus-metrics.socket

[Service]
Type=notify-reload
OOMScoreAdjust=-900
LimitNOFILE=16384
ProtectSystem=full
PrivateTmp=true
PrivateDevices=true
ExecStart=/usr/bin/dbus-broker-launch --scope system --audit

[Install]
Alias=dbus.service
```

--------------------------------

### org.bus1.DBus.Metrics

Source: https://github.com/bus1/dbus-broker/blob/main/docs/dbus-broker.rst

Interface for managing and releasing metrics listeners.

```APIDOC
## method Release()

### Description
Release this metrics listener. It will immediately be removed by the broker and no more connections will be served on it. All clients connected through this listener are forcefully disconnected.

### Method
Release

### Endpoint
/org/bus1/DBus/Metrics/%
```

--------------------------------

### AddName

Source: https://context7.com/bus1/dbus-broker/llms.txt

Registers a well-known name as activatable with the broker. When a client requests this name, the broker signals the controller to spawn the service. It requires a path, the well-known name, and the UID for resource quota.

```APIDOC
## AddName – register an activatable bus name

Declares a well-known name as activatable. When a client requests the name, the broker emits an `Activate` signal to the controller, which is then responsible for spawning the service.

### Interface
org.bus1.DBus.Broker

### Method
AddName(o path, s name, u uid) -> ()

### Parameters
- **path** (o): Object path on the controller for the activatable name.
- **name** (s): The well-known D-Bus name to register.
- **uid** (u): The UID whose resource quota the activatable name is charged against.

### Response
- **()**: Empty success tuple.

### Signal Emitted
- **org.bus1.DBus.Name.Activate**: Emitted at the specified path when activation is requested.
```

--------------------------------

### Clone dbus-broker Repository

Source: https://github.com/bus1/dbus-broker/blob/main/README.md

Use these commands to clone the dbus-broker project repository over SSH or HTTPS.

```git
  Cloning over ssh: git@github.com:bus1/dbus-broker.git
```

```git
  Cloning over https: https://github.com/bus1/dbus-broker.git
```

--------------------------------

### Enable dbus-broker as System Bus Service

Source: https://context7.com/bus1/dbus-broker/llms.txt

Enables dbus-broker as the system-wide D-Bus message bus. This replacement takes effect after a reboot. It also shows how to enable it for the current user or globally.

```sh
# Enable dbus-broker for the system bus (takes effect after reboot)
systemctl enable dbus-broker.service
# Created symlink /etc/systemd/system/dbus.service → .../dbus-broker.service

# Enable for the current user bus
systemctl --user enable dbus-broker.service

# Enable globally for all users
systemctl --global enable dbus-broker.service

# Verify the active implementation after reboot
busctl status
# The "Name" field will show the dbus-broker PID and service file
```

--------------------------------

### Handle Reload Requests for D-Bus Broker Configuration

Source: https://context7.com/bus1/dbus-broker/llms.txt

This C code snippet outlines the interface for handling reload requests from bus clients. The broker invokes this method when a client calls org.freedesktop.DBus.ReloadConfig(). The controller must re-read configuration and update policies.

```c
/*
 * Interface: org.bus1.DBus.Controller (implemented by the CONTROLLER, called by broker)
 * Method:    ReloadConfig() -> ()
 *
 * The broker invokes this when any bus client calls org.freedesktop.DBus.ReloadConfig().
 * The controller is responsible for re-reading configuration files and calling
 * SetPolicy() on each listener with the updated policy.
 *
 * systemd notify-reload integration (in dbus-broker-launch):
 *   1. systemd sends SIGHUP (or busctl trigger via notify-reload)
 *   2. dbus-broker-launch re-parses all XML config files
 *   3. dbus-broker-launch calls SetPolicy on each ControllerListener
 *   4. dbus-broker-launch calls sd_notify(0, "RELOADING=1") then "READY=1"
 */

// Trigger config reload via systemd (modern way, using notify-reload):
// systemctl reload dbus-broker.service

// Or via D-Bus directly:
// busctl call org.freedesktop.DBus /org/freedesktop/DBus \
//     org.freedesktop.DBus ReloadConfig
```

--------------------------------

### Reset Method - Cancel or Complete Activation Attempt

Source: https://context7.com/bus1/dbus-broker/llms.txt

This method allows the controller to cancel or complete an activation attempt for a service name. It takes a serial number from the Activate signal and an optional error string.

```APIDOC
## Reset Method - Cancel or Complete Activation Attempt

### Interface
`org.bus1.DBus.Name`

### Method
`Reset(t serial, s error) -> ()`

### Parameters

- **serial** (t) - The serial number received in the Activate signal.
- **error** (s) - One of the `org.bus1.DBus.Name.Error.*` strings, or `""` for success.

### Available Error Strings

- `org.bus1.DBus.Name.Error.DestructiveTransaction`
- `org.bus1.DBus.Name.Error.UnknownUnit`
- `org.bus1.DBus.Name.Error.MaskedUnit`
- `org.bus1.DBus.Name.Error.InvalidUnit`
- `org.bus1.DBus.Name.Error.UnitFailure`
- `org.bus1.DBus.Name.Error.StartupFailure`
- `org.bus1.DBus.Name.Error.StartupSkipped`
- `org.bus1.DBus.Name.Error.NameReleased`

### Example (busctl equivalent)

```bash
busctl call --address=unix:fd=3 \
    org.bus1.DBus.Name /org/bus1/DBus/Name/org_example_Service \
    org.bus1.DBus.Name Reset "ts" \
    <serial> "org.bus1.DBus.Name.Error.StartupFailure"
```
```

--------------------------------

### org.bus1.DBus.Listener Interface

Source: https://github.com/bus1/dbus-broker/blob/main/docs/dbus-broker.rst

Interfaces implemented by the broker on the /org/bus1/DBus/Listener/% nodes. These manage listener sockets.

```APIDOC
## Release

### Description
Release this listener. It will be immediately removed by the broker, and no more connections will be served on it. All clients connected through this listener will be forcefully disconnected.

### Method
Release

### Parameters
- None

#### Response
Success Response ()
- No return values.
```

```APIDOC
## SetPolicy

### Description
Change the policy on this listener socket to the specified policy. The syntax of the policy is subject to change and is not considered stable.

### Method
SetPolicy

### Parameters
#### Path Parameters
- **policy** (v) - The new policy to apply to the listener.

#### Response
Success Response ()
- No return values.
```

--------------------------------

### Cancel Activation Attempt with Reset Method

Source: https://context7.com/bus1/dbus-broker/llms.txt

This section describes the Reset method of the org.bus1.DBus.Name interface. It is used to cancel an activation attempt, either successfully or with a specific error. The available error strings are listed.

```text
/*
 * Interface: org.bus1.DBus.Name
 * Method:    Reset(t serial, s error) -> ()
 *
 * serial – the serial number received in the Activate signal
 * error  – one of the org.bus1.DBus.Name.Error.* strings, or "" for success
 *
 * Available error strings:
 *   org.bus1.DBus.Name.Error.DestructiveTransaction
 *   org.bus1.DBus.Name.Error.UnknownUnit
 *   org.bus1.DBus.Name.Error.MaskedUnit
 *   org.bus1.DBus.Name.Error.InvalidUnit
 *   org.bus1.DBus.Name.Error.UnitFailure
 *   org.bus1.DBus.Name.Error.StartupFailure
 *   org.bus1.DBus.Name.Error.StartupSkipped
 *   org.bus1.DBus.Name.Error.NameReleased
 */

// busctl equivalent to cancel a failed activation:
// busctl call --address=unix:fd=3 \
//     org.bus1.DBus.Name /org/bus1/DBus/Name/org_example_Service \
//     org.bus1.DBus.Name Reset "ts" \
//     <serial> "org.bus1.DBus.Name.Error.StartupFailure"
```

--------------------------------

### org.bus1.DBus.Name

Source: https://github.com/bus1/dbus-broker/blob/main/docs/dbus-broker.rst

This interface provides signals related to name activation requests on the D-Bus.

```APIDOC
## signal Activate(t serial)

### Description
This signal is sent whenever a client requests activation of a name. Multiple activation requests are coalesced by the broker. The serial number represents the activation request and must be used when reacting to the request with methods like Reset(). A serial number of 0 is never sent and considered invalid.

### Signal
Activate

### Parameters
- **serial** (t) - Description: A unique serial number for the activation request.
```

--------------------------------

### org.bus1.DBus.Controller

Source: https://github.com/bus1/dbus-broker/blob/main/docs/dbus-broker.rst

Interface implemented by the controller to handle broker requests.

```APIDOC
## method ReloadConfig()

### Description
This function is called for each client-request of *org.freedesktop.DBus.ReloadConfig()*. The broker calls this method on the controller when a configuration reload is requested.

### Method
ReloadConfig

### Endpoint
/org/bus1/DBus/Controller
```

--------------------------------

### Monitor All D-Bus Messages

Source: https://context7.com/bus1/dbus-broker/llms.txt

Use dbus-monitor to monitor all messages on the system bus. This requires special privileges, typically root access.

```bash
dbus-monitor --system
```

--------------------------------

### AddMetrics

Source: https://context7.com/bus1/dbus-broker/llms.txt

Attaches an OpenMetrics endpoint socket to the broker. Clients connecting to this socket receive a dump of internal broker metrics in OpenMetrics format before the connection is closed. Requires a path and a file descriptor for the listening socket.

```APIDOC
## AddMetrics – attach an OpenMetrics endpoint socket

Passes a listening socket to the broker. Any client that connects receives an OpenMetrics-format dump of internal broker metrics, then the connection is closed.

### Interface
org.bus1.DBus.Broker

### Method
AddMetrics(o path, h socket) -> ()

### Parameters
- **path** (o): Object path for the metrics endpoint.
- **socket** (h): File descriptor of the listening socket for metrics.

### Response
- **()**: Empty success tuple.
```

--------------------------------

### Monitor Specific Interface Signal with dbus-monitor

Source: https://context7.com/bus1/dbus-broker/llms.txt

Use dbus-monitor to subscribe to a specific interface signal on the system bus. This requires specifying the type, interface, and member of the signal.

```bash
dbus-monitor --system \
  "type='signal',interface='org.freedesktop.DBus',member='NameOwnerChanged'"
```

--------------------------------

### org.bus1.DBus.Name Interface

Source: https://github.com/bus1/dbus-broker/blob/main/docs/dbus-broker.rst

Interfaces implemented by the broker on the /org/bus1/DBus/Name/% nodes. These manage activatable names.

```APIDOC
## Release

### Description
Release this activatable name. It will be removed with immediate effect by the broker. The name remains valid for acquisition by clients, but no activation features will be supported on it.

### Method
Release

### Parameters
- None

#### Response
Success Response ()
- No return values.
```

```APIDOC
## Reset

### Description
Reset the activation state of this name. Any pending activation requests are cancelled. This call requires the serial number from the last activation event on this name. Calls with other serial numbers are silently ignored.

### Method
Reset

### Parameters
#### Path Parameters
- **serial** (t) - The serial number of the last activation event.
- **error** (s) - A string hint about the reason for resetting the activation.

#### Response
Success Response ()
- No return values.
```

--------------------------------

### Release Listener Socket

Source: https://context7.com/bus1/dbus-broker/llms.txt

The Release method on the org.bus1.DBus.Listener interface stops accepting new connections on a listener socket and forcibly disconnects all currently connected clients.

```text
/*
 * Interface: org.bus1.DBus.Listener
 * Method:    Release() -> ()
 *
 * Immediately stops accepting new connections on the listener.
 * All clients connected through this listener are forcibly disconnected.
 */

// busctl equivalent:
// busctl call --address=unix:fd=3 \
//     org.bus1.DBus.Listener /org/bus1/DBus/Listener/0 \
//     org.bus1.DBus.Listener Release
```

--------------------------------

### org.bus1.DBus.Broker Interface

Source: https://github.com/bus1/dbus-broker/blob/main/docs/dbus-broker.rst

Interfaces implemented by the broker on the /org/bus1/DBus/Broker node. These are intended to be called by a trusted controller.

```APIDOC
## AddName

### Description
Create a new activatable name on the bus. The name is accounted for by the specified user ID and will be exposed by the controller at the provided path.

### Method
AddName

### Parameters
#### Path Parameters
- **path** (o) - The controller-exposed path for the name.
- **name** (s) - The name to add.
- **uid** (u) - The user ID under which the name should be accounted.

#### Response
Success Response ()
- No return values.
```

```APIDOC
## AddListener

### Description
Add a listener socket to the bus. The broker will start serving incoming client connections on this socket. The listener is exposed by the controller at the specified path.

### Method
AddListener

### Parameters
#### Path Parameters
- **path** (o) - The controller-exposed path for the listener.
- **socket** (h) - The listener socket, which must be in listening mode.
- **policy** (v) - The policy to apply to clients connecting through this socket.

#### Response
Success Response ()
- No return values.
```

```APIDOC
## AddMetrics

### Description
Add a metrics listener socket to the bus. Clients connecting to this socket will receive a dump of the broker's internal metrics in OpenMetrics format, followed by a client socket shutdown.

### Method
AddMetrics

### Parameters
#### Path Parameters
- **path** (o) - The controller-exposed path for the metrics listener.
- **socket** (h) - The metrics listener socket, which must be in listening mode.

#### Response
Success Response ()
- No return values.
```

```APIDOC
## SetActivationEnvironment

### Description
Signal raised according to client requests for `org.freedesktop.DBus.UpdateActivationEnvironment()`. This signal provides the updated activation environment.

### Method
SetActivationEnvironment

### Parameters
#### Path Parameters
- **environment** (a{ss}) - A dictionary of strings representing the activation environment.

#### Response
Success Response ()
- No return values.
```

--------------------------------

### Activate Signal - Receive Service Activation Requests

Source: https://context7.com/bus1/dbus-broker/llms.txt

When a D-Bus client sends a message to an unowned but activatable name, the broker coalesces pending requests and emits this signal to the controller. The controller must then either spawn the service or cancel the activation.

```APIDOC
## Activate Signal - Receive Service Activation Requests

When a D-Bus client sends a message to an unowned but activatable name, the broker coalesces pending requests and emits this signal to the controller.

### Signal Details

- **Node**: `/org/bus1/DBus/Name/<escaped-name>`
- **Signal**: `org.bus1.DBus.Name.Activate(t serial)`

### Controller Actions

The controller must then either:
  a) Spawn/start the service and wait for it to claim the name, then let the broker auto-dispatch pending messages, OR
  b) Call `Reset()` to cancel the activation with an error.

### Example (Pseudocode)

```c
void on_activate_signal(const char *name_path, uint64_t serial) {
    const char *unit = lookup_unit_for_name(name_path); // e.g. "org.example.Service.service"

    int rc = sd_bus_call_method(systemd_bus,
        "org.freedesktop.systemd1",
        "/org/freedesktop/systemd1",
        "org.freedesktop.systemd1.Manager",
        "StartUnit",
        NULL, NULL,
        "ss", unit, "replace");

    if (rc < 0) {
        // Signal the broker that activation failed
        controller_name_reset(name, serial, CONTROLLER_NAME_ERROR_STARTUP_FAILURE);
    }
    // On success the service will acquire the name; broker delivers pending messages.
}
```
```