doc: complete and cross-link the D-Bus documentation

dbus.md was orphaned: not in dist_docs_DATA, not linked from the
user guide.  Wire it into the doc dist and link it from the index
features list, features.md, initctl.md, and plugins.md, where the
dbus.so plugin entry now disambiguates the external system bus from
the built-in org.finit API.

Document the 64-peer cap, the supported AddMatch keys, the busconfig
policy file, the legacy-parity edge semantics with the deliberate
SetRunlevel InvalidArgs divergence, the reload-signal behavior of
Service1.Reload, and the reboot family timeout.  Refresh the stale
initctl.md usage paste, add monitor and the D-Bus transport to
initctl(8), add /run/finit/bus to the filesystem layout, and flatten
the ChangeLog D-Bus entry to house style.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
This commit is contained in:
Joachim Wiberg committed 2026-08-16 22:03:41 +02:00
1 parent 39d21ca0bd
commit a814e85356
9 files changed
+89 -44

No files matched your search

+34 -3
View File
@@ -33,6 +33,17 @@ The socket is `0660`, owned by `root` and the group given to
does, so restricting one and not the other would leave the door open.
Members of that group may use it, see [Authorization](#authorization).
Finit accepts at most 64 concurrent local-bus peers; further
connections are refused until one disconnects. Match rules given to
`AddMatch` support the `type`, `interface`, `member`, and `path` keys;
`arg0` and its variants are not implemented.
For the system bus a standard busconfig policy ships in
`dbus-1/org.finit.conf`: only root may own `org.finit`, unprivileged
callers reach introspection, properties, and the read-only methods.
Finit also enforces per-method authorization itself, so a permissive
policy installed by mistake does not open state-changing methods.
The **system** bus is best-effort: Finit probes for a running `dbus-daemon`
and, when reachable, claims the well-known name `org.finit` so that standard
tooling sees Finit just like any other system service:
@@ -91,12 +102,20 @@ and the service registry.
| `Stop` | `s` | — | yes | Stop the service(s) matching the identity |
| `Restart` | `s` | — | yes | Restart (stop + start) the service(s) |
| `Reload` | — | — | yes | Re-read all `*.conf` and apply changes |
| `SetRunlevel` | `u` | — | yes | Transition to runlevel `u` (0–6) |
| `SetRunlevel` | `u` | — | yes | Transition to runlevel `u` (0–9) |
| `SetDebug` | — | — | yes | Toggle Finit's runtime debug flag |
| `Signal` | `su` | — | yes | Send signal `u` (1–31) to services matching identity `s` |
| `Suspend` | — | — | yes | `sync()` + suspend-to-RAM |
| `Reboot`, `Halt`, `Poweroff` | `u` | — | yes | Trigger the corresponding shutdown sequence; the argument arms the emergency fallback timer (seconds, 0 = none) |
Edge cases follow the legacy `initctl` protocol: `Suspend` and the
reboot family reply `WrongRunlevel` during bootstrap and shutdown,
`SetRunlevel` is a warning + no-op in runlevel 0/6 and records the
level for the end of bootstrap in runlevel S, and `Signal` fails for
stopped services. One deliberate divergence: a `SetRunlevel` argument
outside 0–9 returns `InvalidArgs`, where the legacy protocol
acknowledges silently.
### Properties
All read-only strings; observable via `Properties.Get` and
@@ -135,7 +154,7 @@ constructing it by hand.
| `Start` | — | — | yes | Equivalent to `Manager1.Start(<identity>)` for this service |
| `Stop` | — | — | yes | … |
| `Restart` | — | — | yes | … |
| `Reload` | — | — | yes | Reload (SIGHUP if supported, else restart) |
| `Reload` | — | — | yes | Send the service's `reload-signal`, default `SIGHUP`; restart when set to `"none"` |
### Properties
@@ -195,6 +214,18 @@ Lives at **`/org/finit/cond`**. Exposes Finit's
Note: non-`usr/*` paths are rejected with `InvalidArgs` -- system
conditions belong to Finit's state machine.
A service consuming such a condition:
service alarm {
description = "Foo alarm"
runlevel = "2345"
conditions = { "usr/data-ready" }
command = "alarm --arg foo"
}
asserted from any bus client with `Cond1.Set string:"data-ready"`, see
the examples below.
### Signals
| Signal | Body | Fires when |
@@ -255,7 +286,7 @@ the following subcommands use the bus first:
| `initctl poweroff` | `Manager1.Poweroff(timeout)` |
| `initctl suspend` | `Manager1.Suspend()` |
| `initctl debug` | `Manager1.SetDebug()` |
| `initctl signal` | `Manager1.Signal(svc, signo)` |
| `initctl signal` (or `kill`) | `Manager1.Signal(svc, signo)` |
| `initctl runlevel` | `Properties.Get(Manager1.Runlevel/PrevRunlevel)` |
| `initctl cond set/get/clear` | `Cond1.{Set,Get,Clear}`, `clr` is an alias |