Operations¶

This page covers running a switchyardd gateway day to day: starting the daemon, talking to its admin API and switchyardctl client, reloading configuration live, reading metrics, and reading logs. For the config file format see Configuration; for the access-control model behind the admin socket see Security & Sealed Routing; for the full machine-readable API contract see API Reference.

Running switchyardd¶

switchyardd --config /etc/relayfabric/relayfabric.yaml

switchyardd takes exactly two flags:

switchyardd --config docs/relayfabric.example.yaml --check-config
# configuration valid: 1 route(s), 1 plugin(s)

There is no --data-dir flag: the data directory comes entirely from node.data_dir in the config file. switchyardd creates that directory if it doesn't exist (and tightens its permissions to 0700 if it already exists with looser ones), then keeps everything the daemon needs to persist inside it:

• admin.sock — the admin API, bound fresh on every start (any stale socket file from a previous run is removed first) and hardened to 0600 immediately after bind().
• plugins.sock — the CBOR-over-Unix-socket plugin IPC endpoint, bound and hardened the same way. Plugins switchyardd spawns itself connect to it automatically; a plugin run out-of-process instead is pointed at it via the RELAYFABRIC_SOCKET environment variable.
• A SQLite-backed store for the message/delivery queue, dedup state, and identity links.
• Node identity keys, under their own subdirectory.
• relayfabric.yaml / relayfabric.yaml.prev / relayfabric.yaml.prev.2 … .prev.5 — the applied config and up to five rotated backups, when config is managed through the admin API rather than edited on disk directly (see Config hot-reload).

The admin API¶

switchyardd exposes an HTTP admin API only over the admin.sock Unix domain socket in data_dir — there is no TCP listener, and none is planned. Reaching that socket at all is equivalent to full admin access: there is no authentication, no per-route authorization, and no read-only tier at this layer.

Endpoints¶

The table below is a curated subset for day-to-day operation. The authoritative, always-in-sync contract is the generated OpenAPI 3.1 document — see API Reference for the full endpoint list, request/response schemas, and status codes.

Every endpoint reaches the same socket. A few examples with curl:

sock=<data_dir>/admin.sock

curl --unix-socket "$sock" http://localhost/v1/status
curl --unix-socket "$sock" http://localhost/v1/routes
curl --unix-socket "$sock" 'http://localhost/v1/queue?state=dead_letter&limit=50'
curl --unix-socket "$sock" http://localhost/metrics

Browsing /docs¶

There's no URL to open directly — /docs lives behind the same Unix socket as everything else. Forward a local TCP port to it with socat:

socat TCP-LISTEN:8099,fork UNIX-CONNECT:<data_dir>/admin.sock &
xdg-open http://localhost:8099/docs

Or, for a remote host, tunnel the socket over SSH (no socat needed on the remote end):

ssh -L 8099:<data_dir>/admin.sock <user>@<host>
xdg-open http://localhost:8099/docs

Headless / scripting doesn't need a browser at all — switchyardctl openapi or curl .../v1/openapi.json is enough. switchyardctl docs prints this same recipe, filled in with whatever --socket you gave it.

switchyardctl¶

switchyardctl is a thin client for the admin API. Every subcommand takes an optional --socket <path> before it (default /var/lib/relayfabric/admin.sock):

switchyardctl --socket <data_dir>/admin.sock status

curl --unix-socket <data_dir>/admin.sock \
  'http://localhost/v1/queue?state=dead_letter&limit=50'

config validate/config apply read the given file from this machine's filesystem but POST/PUT its raw text unmodified — the daemon resolves any ${env:...}/${file:...} secret references against its own environment when it receives that text, not the operator's shell. That's deliberate: it validates "would this apply cleanly on the running daemon," not "on my workstation."

Config hot-reload¶

Config changes go through the admin API rather than a SIGHUP or restart:

1. POST /v1/config/validate — runs the same parse/validate/ secret-resolution pipeline PUT uses, against the request body, and discards the result. Returns {"valid": true} (200) or {"valid": false, "errors": [...]} (422). No filesystem changes either way.
2. PUT /v1/config — validates first (422, nothing written, on failure), then writes the new config to disk (0600, atomic) and applies it live. The replaced file is kept as <path>.prev, and the previous backups rotate down one slot (.prev → .prev.2 → … → .prev.5, oldest dropped) — up to five revisions are retained, each forced to 0600. Returns {"applied": true, "restart_required": [...]}.
3. GET /v1/config/prev[?n=N] — reads a retained revision byte-verbatim (secret refs unresolved), n=1 newest (default) to n=5 oldest kept; 404 for an empty slot. To restore an older revision, read it and PUT it.
4. POST /v1/config/rollback — undoes the last apply: re-validates the newest backup (.prev) before touching anything, then swaps it back in as the live config (current becomes the new .prev) and applies it. 404 if no .prev exists yet. Same {"applied": true, "restart_required": [...]} response shape.

restart_required names any enabled plugin whose process must be restarted for the change to take full effect (e.g. its command or config: block changed) — empty for a route-only or policy-only change, which applies without touching any plugin process.

switchyardctl config validate candidate.yaml
switchyardctl config apply candidate.yaml
switchyardctl config rollback

Secret references¶

A plugin config value can be, in its entirety, ${env:NAME} or ${file:/abs/path} — never interpolated inside a longer string, the whole value must be the reference. These are resolved once, at config load time, against the daemon's environment (an unset/empty env var, or an unreadable/relative file path, is a load error). Resolved values are passed to the plugin process at spawn and never appear anywhere on the admin surface:

• GET /v1/config always serves the raw, pre-resolution YAML — the ${...} reference form, never the resolved value.
• /v1/routes and /v1/plugins don't echo plugin config: blocks at all.
• --check-config output shows the unresolved form too.

See Configuration for the full secret-reference syntax.

Metrics¶

GET /metrics serves Prometheus text exposition (not JSON) — scrape it directly, no separate metrics port. Two guarantees make it safe to scrape even with plugin-supplied gauge data mixed in:

• Bounded — custom gauges reported by any one plugin are capped at 32; extras are dropped rather than accepted unbounded.
• Finite-only — non-finite values (NaN, +inf, -inf) that a plugin reports are dropped before rendering, never passed through. A plugin-controlled value can't silently poison a PromQL query with a Prometheus-incompatible token.

The full metric name list is documented on the /metrics operation in /v1/openapi.json.

curl --unix-socket <data_dir>/admin.sock http://localhost/metrics | grep dead_letter

Logging¶

switchyardd logs via tracing, controlled by the standard RUST_LOG environment variable (defaults to info if unset).

Plugin processes that switchyardd spawns itself run with PYTHONUNBUFFERED=1 set. Python's stdout is block-buffered by default when it isn't attached to a TTY — without this, a Python plugin's diagnostic output could sit in its own buffer instead of reaching the daemon's log in real time. With it, print()/logging output from the LXMF, Signal, Meshtastic, MeshCore, Nostr, and Bitchat plugins surfaces live, interleaved with the daemon's own log lines, instead of arriving in delayed bursts.

See also¶

• API Reference — the full admin API contract
• Configuration — config file format and secret syntax
• Security & Sealed Routing — the access-control model behind the admin socket, and sealed-routing security modes