Configuration and operations
This page covers running chaosd on the appliance: its configuration file, the filesystem paths it uses, the privileges it needs, and its lifecycle.
Configuration file#
chaosd reads /etc/chaos/chaosd.toml by default, or a path passed as the first argument. The schema in this release is intentionally small:
port1_interface = "enp4s0" # required — interface bound to Port1 (lower BDF)
port2_interface = "enp5s0" # required — interface bound to Port2 (higher BDF)
socket_path = "/run/chaosd/chaosd.sock" # optional, default shown
baseline_path = "/var/lib/chaos/calibration-baseline.json" # optional, default shown
port1_interfaceandport2_interfaceare the two transparent-bridge data ports.Port1must resolve to the lower PCI BDF;chaosdenforces this at startup and refuses to start on a mismatch.socket_pathis the Unix socket the API is served on.baseline_pathis the fileGET /v1/calibration/baselinereads.
Unknown keys are rejected, so a misspelled key fails at startup rather than being ignored. A missing required field fails the same way. There is no hot-reload in this release; restart the daemon to pick up a configuration change.
Filesystem layout#
| Path | Purpose |
|---|---|
/etc/chaos/chaosd.toml | Daemon configuration |
/run/chaosd/chaosd.sock | API Unix socket (default) |
/var/lib/chaos/calibration-baseline.json | Stored calibration baseline (default) |
/var/lib/chaos/dist/<name>.table | Operator-supplied distribution tables |
Privileges#
chaosd programs qdiscs through rtnetlink, which requires CAP_NET_ADMIN. On the appliance it runs as a non-root systemd service with that capability granted as an ambient capability — no sudo, no tc/ip/iproute2 at runtime. When the process lacks the capability, data-plane operations fail and the API returns 403.
Startup sequence#
On start, chaosd:
- Initializes structured logging.
- Loads the configuration file.
- Resolves the two interface names to port bindings and enforces the
Port1<Port2BDF convention, refusing to start on a mismatch. - Snapshots the port identity reported by
GET /v1/system. - Opens the netlink backend.
- Installs
SIGTERMandSIGINThandlers. - Serves the API on the configured socket until a shutdown signal.
On shutdown it stops serving, closes the backend cleanly, and unlinks the socket so the next start binds cleanly.
Logging#
chaosd logs structured events through tracing. It prefers the systemd journal when available — the appliance case — and falls back to a plain formatted layer on dev hosts without journald. The log filter is read from the environment, defaulting to info.
The API layer emits a per-request span carrying method, URI, status, and latency. Data-plane operations log at the appropriate level, including the warn-level event emitted when a zero-jitter stochastic latency is observed.
The CLI on the appliance#
The chaos CLI connects to the same socket. Set CHAOS_SOCKET or pass --socket if the daemon is configured with a non-default socket path. The CLI is also the serial-console login shell: console access presents the CHAOS command surface directly with no system shell.
Transport and security posture#
In this release the API is served only over the Unix domain socket. There is no TCP listener, no TLS, and no authentication on this surface; access is mediated by filesystem permissions on the socket. Network-facing transport, TLS, and authentication are roadmap items. See roadmap and lifecycle.
Next steps#
- Getting started — configure and run end to end.
- Roadmap and lifecycle — what is planned beyond this release.
