Server Configuration

The server is configured through a combination of command-line arguments and environment variables. Environment variables are loaded from a .env file via dotenvy (see .env.example).

Command-line arguments

ferrite-server [OPTIONS] [COMMAND]

Global options

Flag	Default	Description
`--http <ADDR>`	`0.0.0.0:4000`	HTTP listen address (ip:port)
`--db <PATH>`	`./ferrite.db`	SQLite database file path
`--evidence-db <PATH>`	`evidence.db` next to `--db`	Append-only evidence log; never purged (see Evidence log)
`--credentials-db <PATH>`	`credentials.db` next to `--db`	Device keys and replay state; mode `0600`, never purged (see Per-device credentials)
`--elf-dir <PATH>`	`./elfs`	Directory for uploaded ELF files
`--addr2line <PATH>`	Auto-detect	Path to `arm-none-eabi-addr2line` binary

Subcommands

Command	Description
`serve`	Start the HTTP server (default if no command given)
`report`	Print a summary of all devices to stdout
`faults`	List recent fault events to stdout
`metrics`	List recent metrics to stdout

Environment variables

Authentication

Variable	Default	Description
`KEYCLOAK_URL`	—	Keycloak base URL (enables OIDC mode)
`KEYCLOAK_REALM`	—	Keycloak realm name
`KEYCLOAK_CLIENT_ID`	—	Dashboard SPA client ID
`KEYCLOAK_CLIENT_SECRET`	—	(Optional) Confidential client secret
`BASIC_AUTH_USER`	`admin`	Primary basic auth username
`BASIC_AUTH_PASS`	— (required in Basic mode)	Primary basic auth password. Without it, `serve` refuses to start
`BASIC_AUTH_USERS`	—	Additional users (format below)

BASIC_AUTH_USERS format: user1:pass1:role,user2:pass2:role

Roles: admin, provisioner, viewer, auditor (evidence log only).

API security

Variable	Default	Description
`INGEST_API_KEY`	—	API key for `/ingest/*` endpoints
`CORS_ORIGIN`	`*` (all)	Allowed CORS origin
`CHUNK_ENCRYPTION_KEY`	—	32-char hex AES-128 key shared by the fleet (chunks sealed without a device credential)
`DEVICE_AUTH_REQUIRED`	off	`1`: accept only chunks sealed with a device credential. Off: only devices that have a credential must use it
`RATE_LIMIT_RPS`	disabled	Per-IP rate limit (requests/second)
`OTA_TRUSTED_KEYS`	—	Comma-separated hex Ed25519 public keys allowed to sign OTA manifests. When set, firmware uploads must carry a valid signed manifest. See Signed OTA updates

Alerting

Variable	Default	Description
`ALERT_WEBHOOK_URL`	—	Webhook URL for fault/offline alerts (Slack/Discord compatible)
`ALERT_OFFLINE_MINUTES`	`10`	Minutes before a device is marked offline

Evidence anchoring

Variable	Default	Description
`EVIDENCE_ANCHOR_TSA_URL`	—	RFC 3161 timestamp authority for the evidence head hash (e.g. `http://timestamp.digicert.com`)
`EVIDENCE_ANCHOR_WEBHOOK_URL`	—	Webhook that receives the head hash as JSON
`EVIDENCE_ANCHOR_WEBHOOK_TOKEN`	—	Bearer token for the webhook
`EVIDENCE_ANCHOR_INTERVAL_SECS`	`0`	Seconds between scheduled anchors; `0` = only `POST /evidence/anchor`

See Anchoring the head.

Data retention

Variable	Default	Description
`RETENTION_DAYS`	`90`	Auto-purge data older than N days (0 = disabled)

Retention never touches the evidence log.

HTTP API endpoints

Health & discovery

Method	Path	Auth	Description
GET	`/health`	Public	Server health check
GET	`/auth/mode`	Public	Auth mode discovery
GET	`/metrics/prometheus`	Public	Prometheus metrics
GET	`/events/stream`	User	SSE live event stream

Data ingest

Method	Path	Auth	Description
POST	`/ingest/chunks`	API key (if configured)	Accept binary chunks
POST	`/ingest/elf`	Provisioner+ or API key	Upload ELF for symbolication (max 50 MB)

Device management

Method	Path	Auth	Description
GET	`/devices`	User	List all devices
POST	`/devices/register`	Provisioner+	Register a device
POST	`/devices/register/bulk`	Provisioner+	Bulk register devices
GET	`/devices/:key`	User	Get device by key
PUT	`/devices/:key`	Provisioner+	Update device metadata
DELETE	`/devices/:key`	Admin	Delete a device
POST	`/devices/:id/credential`	Provisioner+	Issue or rotate the device's credential; the key is in this response only
GET	`/devices/:id/credential`	User	Key ID, issued and last used (never the key)
DELETE	`/devices/:id/credential`	Admin	Revoke the device's credential

Device data

Method	Path	Auth	Description
GET	`/devices/:id/faults`	User	Device fault events
GET	`/devices/:id/metrics`	User	Device metrics
GET	`/faults`	User	All fault events
GET	`/metrics`	User	All metrics

Groups (fleet management)

Method	Path	Auth	Description
GET	`/groups`	User	List groups
POST	`/groups`	Admin	Create group
GET	`/groups/:id`	User	Get group details
PUT	`/groups/:id`	Admin	Update group
DELETE	`/groups/:id`	Admin	Delete group
GET	`/groups/:id/devices`	User	List group devices
POST	`/groups/:id/devices/:device_id`	Admin	Add device to group
DELETE	`/groups/:id/devices/:device_id`	Admin	Remove device from group

OTA firmware updates

Method	Path	Auth	Description
GET	`/ota/targets`	User	List OTA targets
POST	`/ota/targets`	Admin	Set OTA target for a device
GET	`/ota/targets/:device_id`	User	Get target for device
DELETE	`/ota/targets/:device_id`	Admin	Remove OTA target
GET	`/ota/firmware`	User	List firmware artifacts
POST	`/ota/firmware`	Admin	Upload firmware (`X-Firmware-Manifest` header; required with `OTA_TRUSTED_KEYS`)
GET	`/ota/firmware/:id`	User	Firmware artifact metadata
GET	`/ota/firmware/:id/download`	User or device	Firmware binary, with `X-Firmware-Manifest` header
GET	`/ota/firmware/:id/manifest`	User or device	Signed manifest (raw bytes)
DELETE	`/ota/firmware/:id`	Admin	Delete firmware artifact

"Device" means a valid X-API-Key when INGEST_API_KEY is set; it opens GET /ota/targets/:device_id and the two firmware reads above. See Signed OTA updates.

Update-reach reports

Method	Path	Auth	Description
GET	`/reports/fleet/builds`	User	Devices per firmware build (`?group_id=`, `?tag=`)
GET	`/reports/campaigns/:id`	User	Campaign reach: on target, unreachable, time to patch
GET	`/reports/devices/:device_id/firmware-history`	User	Builds a device reported over time

All accept ?format=csv. See Update-reach reports.

Evidence log

Method	Path	Auth	Description
GET	`/evidence`	Admin or auditor	Hash-chained release/update record (`from`, `to`, `kind`, `subject`, `limit`)
GET	`/evidence/verify`	Admin or auditor	Recompute the chain and report the head hash
POST	`/evidence/anchor`	Admin	Anchor the head now (timestamp authority / webhook)

See Evidence log.

Admin

Method	Path	Auth	Description
GET	`/admin/backup`	Admin	Download database backup
GET	`/admin/retention`	Admin	View retention policy status

Ingest endpoint details

`POST /ingest/chunks`

Accepts a raw binary body containing one or more concatenated wire-format chunks.

Headers:

X-Device-Id (optional): Fallback device ID if no DeviceInfo chunk is present
X-API-Key (required if INGEST_API_KEY is set): API key for authentication

Response:

json

{
  "ok": true,
  "chunks_received": 4,
  "errors": []
}

`POST /ingest/elf`

Accepts a raw binary ELF file (max 50 MB). Requires a provisioner or admin user, or the ingest API key when INGEST_API_KEY is set.

Headers:

X-Firmware-Version (recommended): Version string for the ELF file
Authorization: Bearer token or Basic auth (provisioner or admin), or
X-API-Key: the ingest API key

bash

curl -X POST http://localhost:4000/ingest/elf \
  -H "X-Firmware-Version: 1.2.3" \
  -H "Authorization: Basic $(echo -n admin:admin | base64)" \
  --data-binary @target/thumbv7em-none-eabihf/release/my-firmware

Prometheus metrics

The /metrics/prometheus endpoint exposes:

ferrite_devices_total — total registered devices
ferrite_devices_online — currently online devices
ferrite_faults_total — total fault events
ferrite_metrics_total — total metric data points
ferrite_reboots_total — total reboot events
ferrite_groups_total — number of device groups
ferrite_ingest_requests_total — ingest request counter
ferrite_chunks_processed_total — chunk processing counter
ferrite_auth_failures_total — authentication failure counter
ferrite_sse_connections — active SSE connections

Server-Sent Events (SSE)

The /events/stream endpoint provides real-time updates to signed-in users (viewer role and up):

bash

curl -N -u admin:<password> http://localhost:4000/events/stream

A browser EventSource can't send an Authorization header; use fetch() with a streamed response body instead.

Event types: heartbeat, fault, metric, reboot, device_registered, ota_available.

SQLite schema

The server creates these tables:

devices — device_id, name, status, firmware_version, device_key, tags, provisioned_by/at
fault_events — fault_type, pc, lr, cfsr, hfsr, mmfar, bfar, sp, stack_snapshot, symbol
metrics — key, metric_type, value_json, timestamp_ticks
reboot_events — reason, extra, boot_sequence, uptime_before_reboot
groups — name, description
group_memberships — group_id, device_id
ota_targets — device_id, target_version, build_id, firmware_url

All tables use SQLite WAL mode. Foreign keys are enabled.

Server Configuration ​

Command-line arguments ​

Global options ​

Subcommands ​

Environment variables ​

Authentication ​

API security ​

Alerting ​

Evidence anchoring ​

Data retention ​

HTTP API endpoints ​

Health & discovery ​

Data ingest ​

Device management ​

Device data ​

Groups (fleet management) ​

OTA firmware updates ​

Update-reach reports ​

Evidence log ​

Admin ​

Ingest endpoint details ​

POST /ingest/chunks ​

POST /ingest/elf ​

Prometheus metrics ​

Server-Sent Events (SSE) ​

SQLite schema ​