mirror of
https://github.com/troglobit/finit.git
synced 2026-11-07 16:01:08 +00:00
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:
9 files changed
+89
-44
No files matched your search
+34
-3
@@ -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 |
|
||||
|
||||
|
||||
Reference in new issue
Block a user