From 06a9f2793c52c0108962e1cf66e01db55ae3bf4a Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 28 Oct 2026 04:08:41 +0000 Subject: [PATCH] 2.1.0: local API (phase 1) and the input box's status through the diode - status channel: the input box sends its status every lidi.heartbeat on the lidi endpoint after the last module, signed; the output box keeps it and warns when it goes silent or the transport hash differs - stats registry fed by transfer.jsonl events and the supervisor; status files in /run/dyode and 'dyode status [--json]' - API (feature api, default): /v1/health, /v1/status, /metrics, /v1/check, /v1/openapi.json over rustls TLS with per-box bearer tokens; refuses the diode NIC; 'dyode api-token', 'dyode api-cert' - guided setup: Local API screen (address, certificate, first token) - install.sh: openssl when missing; nftables drops the API port on the diode NIC; units get RuntimeDirectory=dyode - docs/API.md and docs/api/openapi.yaml (a test keeps the routes in step) - tests: status through real lidi + forged status refused + API over TLS Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01QXjQsiWnwLMndr5XU9g5LJ --- CHANGELOG.md | 28 + Cargo.toml | 10 +- README.md | 3 + config.example.yaml | 14 + docs/API.md | 139 ++++ docs/api/openapi.yaml | 183 ++++++ install.sh | 4 + .../systemd/reference/dyode-in-serial.service | 3 + packaging/systemd/reference/dyode-in.service | 3 + .../reference/dyode-out-serial.service | 3 + packaging/systemd/reference/dyode-out.service | 3 + src/api.rs | 421 ++++++++++++ src/apitoken.rs | 212 ++++++ src/check.rs | 150 +++++ src/config.rs | 138 +++- src/lib.rs | 6 + src/logging.rs | 2 + src/main.rs | 283 +++++--- src/netutil.rs | 1 + src/runtime.rs | 50 +- src/setup.rs | 103 +++ src/stats.rs | 615 ++++++++++++++++++ src/status.rs | 96 +++ src/supervisor.rs | 2 + src/transport.rs | 51 +- src/wizard/mod.rs | 128 +++- src/wizard/model.rs | 82 +++ tests/api.rs | 257 ++++++++ tests/loopback.rs | 6 +- tools/build_debs.sh | 3 +- 30 files changed, 2896 insertions(+), 103 deletions(-) create mode 100644 docs/API.md create mode 100644 docs/api/openapi.yaml create mode 100644 src/api.rs create mode 100644 src/apitoken.rs create mode 100644 src/check.rs create mode 100644 src/stats.rs create mode 100644 src/status.rs create mode 100644 tests/api.rs diff --git a/CHANGELOG.md b/CHANGELOG.md index 6b3a044..bb86451 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,33 @@ # Changelog +## [2.1.0] - unreleased + +### Added + +- **Local API** (phase 1, read-only; docs/API.md, docs/api/openapi.yaml): + `/v1/health`, `/v1/status`, `/metrics` (Prometheus), `/v1/check` and + `/v1/openapi.json` on each box's management network card, over TLS + (rustls, built in; cargo feature `api`, on by default), with per-box + bearer tokens. It refuses to listen on the diode NIC. +- **Status through the diode**: every `lidi.heartbeat` seconds the input + box sends its status (modules, restarts, event counts, bytes, free space, + static ARP entry, transport hash) on its own lidi endpoint, signed. The + output box serves both boxes, warns when the input box goes silent or + runs a different configuration, and `dyode_status_age_seconds{side="in"}` + is the alert that catches a dead input box, diode or link. +- `dyode status [--json]` (from /run/dyode, no API needed), `dyode + api-token add|list|revoke`, `dyode api-cert` (self-signed, via openssl). +- Guided setup: a "Local API" screen that writes `api:`, makes the + certificate and a first token. +- install.sh installs openssl when missing (also in the offline bundle); + the output box's nftables rules drop the API port on the diode NIC; the + units get `RuntimeDirectory=dyode`. + +### Changed + +- `lidi.max_clients` defaults to one more (the status channel). Both boxes + must run 2.1.0. + ## [2.0.2] - 2026-10-27 ### Added diff --git a/Cargo.toml b/Cargo.toml index a4cf15a..ec6d235 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "dyode" -version = "2.0.2" +version = "2.1.0" edition = "2024" rust-version = "1.85" license = "GPL-3.0-or-later" @@ -16,7 +16,10 @@ name = "dyode" path = "src/main.rs" [features] -default = [] +# The local API (docs/API.md): TLS through rustls, tokens. Build with +# --no-default-features for a dyode that never listens for API requests. +default = ["api"] +api = ["dep:rustls", "dep:httparse"] # mimalloc as the global allocator (through lidi), for the release binaries. mimalloc = ["lidi-send/mimalloc", "lidi-receive/mimalloc"] # Prometheus metrics from the embedded lidi engines (lidi.prometheus_listen). @@ -43,6 +46,9 @@ serde_yaml = "0.9" sha2 = "0.10" tar = { version = "0.4", default-features = false } toml = "1" +# --- the local API (feature "api") --- +rustls = { version = "0.23", default-features = false, features = ["ring", "std", "tls12"], optional = true } +httparse = { version = "1", optional = true } [profile.release] opt-level = 3 diff --git a/README.md b/README.md index 1b1c20f..0eff357 100644 --- a/README.md +++ b/README.md @@ -75,6 +75,9 @@ lidi parameters must match. | `dyode in` / `dyode out` | run the input / output side (v1, lidi) | | `dyode serial-in` / `serial-out` | run DYODE v2 (Modbus over serial) | | `dyode setup` | guided setup in dialog boxes (or `--plain` questions) | +| `dyode status [--json]` | this box's status (and the input box's, on the output box) | +| `dyode api-token add\|list\|revoke` | tokens for this box's local API ([docs/API.md](docs/API.md)) | +| `dyode api-cert` | a self-signed TLS certificate for the local API | | `dyode new-key` | create the shared message key | | `dyode check` | validate config.yaml, the key and the installed unit; throughput hints | | `dyode lidi-config` | print the lidi parameters derived from config.yaml | diff --git a/config.example.yaml b/config.example.yaml index f6f0051..d818077 100644 --- a/config.example.yaml +++ b/config.example.yaml @@ -57,6 +57,20 @@ lidi: # log_level: warn # lidi's own messages: off|error|warn|info|debug # send_bind: 10.0.1.1:0 # source of the UDP packets (default dyode_in.ip:0) +# The local API (docs/API.md): each box serves its own status, read-only, +# on its MANAGEMENT network card (never the diode card), over TLS, to token +# holders. The output box also reports the input box, from the status the +# input box sends through the diode. Each box uses only its own side. +# Certificate: sudo dyode api-cert --ip ADDRESS; tokens: sudo dyode api-token +# add NAME (stored hashed in api-tokens beside this file, per box). +# api: +# in: +# listen: 10.20.0.5:8443 # input box, OT management NIC +# tls: {cert: api.crt, key: api.key} +# out: +# listen: 192.168.50.4:8443 # output box, IT NIC +# tls: {cert: api.crt, key: api.key} + # Logs always go to stderr as well, so journalctl still works. Rotation is # logrotate's job -- see packaging/logrotate/dyode-transfer. logging: diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 0000000..d2540ac --- /dev/null +++ b/docs/API.md @@ -0,0 +1,139 @@ +# The local API + +From 2.1.0 each DYODE box can serve its own status, read-only, to +Prometheus, Zabbix or anything that speaks HTTPS. This is phase 1 of the +API plan; sending data from OT to IT through the input box's API comes in +2.2.0. + +The diode stays the only link between the boxes: + +- each box's API listens on that box's **management** network card, never on + the diode card (DYODE refuses to start otherwise); +- the output box reports the input box from the **status message** the + input box sends through the diode every `lidi.heartbeat` seconds, signed + like everything else. Nothing on the IT side ever reaches the input box. + +The full description is [api/openapi.yaml](api/openapi.yaml), also served by +every box at `/v1/openapi.json`. + +## Endpoints + +| Path | Token | What | +|---|---|---| +| `GET /v1/health` | none | up, side, version, uptime | +| `GET /v1/status` | read | this box; on the output box, the input box too, with the age of its last status, and warnings | +| `GET /metrics` | read | the same as Prometheus text | +| `GET /v1/check` | read | `dyode check` for this box, as JSON | +| `GET /v1/openapi.json` | none | the API description | + +Every answer closes the connection. `HEAD` works on every path. + +## Setting it up + +The guided setup (`dyode setup`, run by install.sh) asks for it on its +"Local API" screen: it writes the `api:` section, makes a certificate and a +first token, and shows the token once at the end. By hand: + +```bash +# on the box, as root +sudo dyode api-cert --name dyode-out --ip 192.168.50.4 # /etc/dyode/api.crt, api.key +sudo dyode api-token add prometheus --scope read # prints the token once +``` + +```yaml +# config.yaml (the same file on both boxes; each box uses its own side) +api: + in: + listen: 10.20.0.5:8443 # input box, OT management NIC + tls: {cert: api.crt, key: api.key} + out: + listen: 192.168.50.4:8443 # output box, IT NIC + tls: {cert: api.crt, key: api.key} + # tokens: api-tokens # default: beside config.yaml + # max_clients: 32 # simultaneous connections +``` + +Restart DYODE (`systemctl restart dyode-out`) and check: + +```bash +curl --cacert api.crt https://192.168.50.4:8443/v1/health +curl --cacert api.crt -H "Authorization: Bearer $TOKEN" https://192.168.50.4:8443/v1/status +sudo dyode check -c /etc/dyode/config.yaml --side out # lists the API and its tokens +``` + +Rules the loader enforces: + +- `listen` names one address: not `0.0.0.0`, and not the box's diode address. + At start, an address that belongs to the diode NIC is refused as well. +- `tls` is required. `tls: off` is allowed only on `127.0.0.1`, behind your + own reverse proxy. +- The output box's nftables rules (install.sh) also drop the API port on the + diode NIC. + +## Tokens + +`dyode api-token add NAME --scope read | list | revoke NAME`. Tokens are +stored as SHA-256 hashes in `api-tokens` beside config.yaml (mode 600) and +are sent as `Authorization: Bearer `. The file is per box: it is not +part of config.yaml and is never copied to the other box, so an IT token is +worthless on the OT box. Refused requests become `api_refused` records in +transfer.jsonl and count in `dyode_counter_total{counter="api_refused"}`. +Client certificates come in a later phase. + +## Certificates + +`dyode api-cert` makes a self-signed P-256 certificate with openssl (an OS +package install.sh installs), valid 825 days, and prints its SHA-256 +fingerprint. Give clients the certificate itself (`--cacert`, Prometheus +`tls_config.ca_file`, Zabbix "SSL certificate" settings). A certificate +from your own CA works the same way: point `tls.cert` at the chain and +`tls.key` at the key. + +## Metrics + +Every series has `side="in"` or `side="out"`. On the output box both sides +appear; on the input box only `in`. + +| Metric | Type | Meaning | +|---|---|---| +| `dyode_info{version,transport_hash,config}` | gauge | 1 per box known | +| `dyode_status_age_seconds` | gauge | seconds since the box's status was taken (the input box's, as seen from the output box) | +| `dyode_status_received` | gauge | 0 until the output box has heard from the input box | +| `dyode_uptime_seconds` | gauge | since DYODE started | +| `dyode_config_match` | gauge | 1 when both boxes run the same transport configuration | +| `dyode_module_up{module,type}` | gauge | 1 running, 0 restarting | +| `dyode_module_restarts_total{module}` | counter | module restarts | +| `dyode_events_total{module,event}` | counter | transfer.jsonl events: `file_sent`, `file_stored`, `file_rejected`, `file_missing`, `logs_gap`, ... | +| `dyode_bytes_total{module,direction}` | counter | file bytes sent (in) or stored (out) | +| `dyode_last_activity_timestamp_seconds{module}` | gauge | time of the module's last event | +| `dyode_free_bytes{module,dir}` | gauge | free space under the module's folder | +| `dyode_counter_total{counter}` | counter | `lidi_transfers_aborted`, `api_refused`, `api_busy`, ... | +| `dyode_static_arp_ok` | gauge | the input box's static ARP entry is in place | + +Counters start at zero when DYODE starts; use `rate()` / `increase()`. + +The alert that matters most: the input box's status stops arriving, which +means the input box, its NIC, the diode or the output box's receiver has +failed. + +```yaml +- alert: DyodeInputSilent + expr: dyode_status_age_seconds{side="in"} > 30 or dyode_status_received{side="in"} == 0 + for: 1m +``` + +Ready-made rules, a Grafana dashboard and a Zabbix 7 template are in +[nc-intezra/dyode_monitoring](https://github.com/nc-intezra/dyode_monitoring). + +## `dyode status` + +Each box also writes its status (and on the output box the input box's) to +`/run/dyode/status-.json` every heartbeat. `dyode status` prints it, +`dyode status --json` gives it to scripts. No API needed. + +## Upgrading + +Both boxes need 2.1.0: the status channel uses one more lidi endpoint (the +one after the last module), which a 2.0.x output box does not know. With +the default `lidi.max_clients`, DYODE adds a slot for it; an explicit +`max_clients` should be raised by one (`dyode check` says so). diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml new file mode 100644 index 0000000..30b97a7 --- /dev/null +++ b/docs/api/openapi.yaml @@ -0,0 +1,183 @@ +openapi: 3.1.0 +info: + title: DYODE local API + version: 2.1.0 + summary: Each DYODE box serves its own status on its own management network. + description: | + Phase 1, read-only. The input box (OT) and the output box (IT) each run + this API on their management network card, never on the diode card. + Nothing here crosses the diode: the output box reports the input box + from the status message the input box sends through the diode every + `lidi.heartbeat` seconds. + + Tokens are per box (`dyode api-token add NAME --scope read`) and are + sent as `Authorization: Bearer `. See docs/API.md. + license: + name: GPL-3.0 +servers: + - url: https://{address}:{port} + variables: + address: {default: 192.168.50.4, description: "api..listen address"} + port: {default: "8443"} +security: + - bearer: [] +components: + securitySchemes: + bearer: + type: http + scheme: bearer + description: A token from `dyode api-token add`, valid on this box only. + schemas: + Error: + type: object + required: [error] + properties: + error: {type: string} + Module: + type: object + properties: + name: {type: string} + type: {type: string, enum: [folder, modbus, screen, logs]} + endpoint: {type: integer, description: lidi endpoint id (position in config.yaml)} + state: {type: string, enum: [starting, running, restarting]} + restarts: {type: integer} + last_activity: {type: [string, "null"], format: date-time} + events: + type: object + additionalProperties: {type: integer} + description: transfer.jsonl events counted since start, by event name. + bytes_sent: {type: integer} + bytes_stored: {type: integer} + free: + type: array + items: + type: object + properties: + dir: {type: string} + path: {type: string} + free_bytes: {type: integer} + BoxStatus: + type: object + properties: + side: {type: string, enum: [in, out]} + version: {type: string} + config_name: {type: string} + transport_hash: + type: string + description: Hash of what both boxes must agree on (lidi parameters, module names and types). + time: {type: string, format: date-time} + uptime_s: {type: integer} + status_age_s: + type: number + description: 0 for the box answering; for the input box seen from the output box, seconds since its status arrived. + received: {type: string, format: date-time} + static_arp_ok: {type: boolean} + modules: + type: array + items: {$ref: "#/components/schemas/Module"} + counters: + type: object + additionalProperties: {type: integer} + description: Box-wide counters (lidi_transfers_aborted, api_refused, api_busy, ...). + Status: + type: object + required: [boxes, warnings] + properties: + boxes: + type: object + properties: + in: + oneOf: [{$ref: "#/components/schemas/BoxStatus"}, {type: "null"}] + out: {$ref: "#/components/schemas/BoxStatus"} + warnings: + type: array + items: {type: string} + Check: + type: object + properties: + notes: {type: array, items: {type: string}} + errors: {type: array, items: {type: string}} + warnings: {type: array, items: {type: string}} + responses: + Unauthorized: + description: No token, or an unknown one. + content: + application/json: + schema: {$ref: "#/components/schemas/Error"} + Forbidden: + description: The token lacks the read scope. + content: + application/json: + schema: {$ref: "#/components/schemas/Error"} +paths: + /v1/health: + get: + summary: Is DYODE up on this box? + security: [] + responses: + "200": + description: Up. + content: + application/json: + schema: + type: object + properties: + status: {type: string, const: ok} + side: {type: string, enum: [in, out]} + version: {type: string} + uptime_s: {type: integer} + /v1/status: + get: + summary: Status of this box and, on the output box, of the input box. + description: | + On the output box, `boxes.in` is the input box's last status as + received through the diode, with `status_age_s`. It is `null` until + the first one arrives. `warnings` names a silent input box (no + status for 3 heartbeats) and differing configurations. + responses: + "200": + description: Status. + content: + application/json: + schema: {$ref: "#/components/schemas/Status"} + "401": {$ref: "#/components/responses/Unauthorized"} + "403": {$ref: "#/components/responses/Forbidden"} + /metrics: + get: + summary: Prometheus metrics for this box (and the input box, on the output box). + description: | + dyode_info, dyode_status_age_seconds, dyode_status_received, + dyode_uptime_seconds, dyode_config_match, dyode_module_up, + dyode_module_restarts_total, dyode_events_total, + dyode_bytes_total, dyode_last_activity_timestamp_seconds, + dyode_free_bytes, dyode_counter_total, dyode_static_arp_ok. + Every series carries side="in" or side="out". + responses: + "200": + description: Prometheus text exposition format 0.0.4. + content: + text/plain: + schema: {type: string} + "401": {$ref: "#/components/responses/Unauthorized"} + "403": {$ref: "#/components/responses/Forbidden"} + /v1/check: + get: + summary: "`dyode check` for this box, as JSON." + responses: + "200": + description: Notes, errors and warnings. + content: + application/json: + schema: {$ref: "#/components/schemas/Check"} + "401": {$ref: "#/components/responses/Unauthorized"} + "403": {$ref: "#/components/responses/Forbidden"} + /v1/openapi.json: + get: + summary: This description, as JSON. + security: [] + responses: + "200": + description: OpenAPI 3.1 document. + content: + application/json: + schema: {type: object} diff --git a/install.sh b/install.sh index 1970584..78e07ba 100755 --- a/install.sh +++ b/install.sh @@ -179,6 +179,10 @@ if [ "$SKIP_OS" -eq 0 ] && [ "$FIREWALL_ONLY" -eq 0 ] && [ "$TUNING_ONLY" -eq 0 if [ "$SIDE" = in ] && [ "$VARIANT" = v1 ] && ! command -v ip >/dev/null 2>&1; then PKGS+=(iproute2) fi + # openssl: 'dyode api-cert' and the guided setup make the API's TLS certificate with it. + if [ "$VARIANT" = v1 ] && ! command -v openssl >/dev/null 2>&1; then + PKGS+=(openssl) + fi for svc in $WITH; do for pkg in $(service_pkgs "$svc"); do pkg_installed "$pkg" || PKGS+=("$pkg"); done done diff --git a/packaging/systemd/reference/dyode-in-serial.service b/packaging/systemd/reference/dyode-in-serial.service index 34ec93b..0b9adce 100644 --- a/packaging/systemd/reference/dyode-in-serial.service +++ b/packaging/systemd/reference/dyode-in-serial.service @@ -18,6 +18,9 @@ StandardInput=null # Creates /var/log/dyode-transfer with the right mode before start. LogsDirectory=dyode-transfer LogsDirectoryMode=0750 +# /run/dyode: the status file read by 'dyode status'. +RuntimeDirectory=dyode +RuntimeDirectoryMode=0750 # root is needed for the static ARP entry. User=root diff --git a/packaging/systemd/reference/dyode-in.service b/packaging/systemd/reference/dyode-in.service index a6369eb..9c915f6 100644 --- a/packaging/systemd/reference/dyode-in.service +++ b/packaging/systemd/reference/dyode-in.service @@ -22,6 +22,9 @@ StandardInput=null # Creates /var/log/dyode-transfer with the right mode before start. LogsDirectory=dyode-transfer LogsDirectoryMode=0750 +# /run/dyode: the status file read by 'dyode status'. +RuntimeDirectory=dyode +RuntimeDirectoryMode=0750 # root is needed for the static ARP entry. User=root diff --git a/packaging/systemd/reference/dyode-out-serial.service b/packaging/systemd/reference/dyode-out-serial.service index 4969a9b..8a26f3c 100644 --- a/packaging/systemd/reference/dyode-out-serial.service +++ b/packaging/systemd/reference/dyode-out-serial.service @@ -18,6 +18,9 @@ StandardInput=null # Creates /var/log/dyode-transfer with the right mode before start. LogsDirectory=dyode-transfer LogsDirectoryMode=0750 +# /run/dyode: the status file read by 'dyode status'. +RuntimeDirectory=dyode +RuntimeDirectoryMode=0750 # root is needed for binding the Modbus server to port 502. User=root diff --git a/packaging/systemd/reference/dyode-out.service b/packaging/systemd/reference/dyode-out.service index 973603c..e53ca99 100644 --- a/packaging/systemd/reference/dyode-out.service +++ b/packaging/systemd/reference/dyode-out.service @@ -22,6 +22,9 @@ StandardInput=null # Creates /var/log/dyode-transfer with the right mode before start. LogsDirectory=dyode-transfer LogsDirectoryMode=0750 +# /run/dyode: the status file read by 'dyode status'. +RuntimeDirectory=dyode +RuntimeDirectoryMode=0750 # root is needed for binding the Modbus server to port 502. User=root diff --git a/src/api.rs b/src/api.rs new file mode 100644 index 0000000..589efba --- /dev/null +++ b/src/api.rs @@ -0,0 +1,421 @@ +//! The local API (cargo feature `api`): each box serves its own status on +//! its own management network, over TLS, to holders of a token. +//! +//! Phase 1 is read-only: +//! +//! | path | token | what | +//! |--------------------|--------|--------------------------------------------| +//! | `/v1/health` | none | up, side, version, uptime | +//! | `/v1/openapi.json` | none | this API's description (docs/api/) | +//! | `/v1/status` | read | this box, and on the output box the input | +//! | | | box's last status, with warnings | +//! | `/metrics` | read | the same, in Prometheus text format | +//! | `/v1/check` | read | `dyode check` as JSON | +//! +//! Requests are parsed by `httparse`; each connection gets a thread, up to +//! `max_clients`, and one request (`Connection: close`). Nothing here can +//! reach the other box: the output box only reports what the input box +//! already sent through the diode. + +use crate::config::{ApiListen, Config, Side}; +use crate::logging::Event; +use rustls::pki_types::pem::PemObject; +use rustls::pki_types::{CertificateDer, PrivateKeyDer}; +use serde_json::{Value, json}; +use std::io::{Read, Write}; +use std::net::{IpAddr, SocketAddr, TcpListener}; +use std::sync::Arc; +use std::sync::atomic::{AtomicUsize, Ordering}; +use std::time::{Duration, Instant}; + +const MAX_REQUEST: usize = 16 * 1024; +const IO_TIMEOUT: Duration = Duration::from_secs(10); + +/// The OpenAPI description, built in so an air-gapped box carries its own. +pub const OPENAPI_YAML: &str = include_str!("../docs/api/openapi.yaml"); + +pub fn openapi_json() -> Value { + serde_yaml::from_str::(OPENAPI_YAML).unwrap_or(Value::Null) +} + +/// The TLS server configuration from PEM files. +pub fn tls_config( + cert: &std::path::Path, + key: &std::path::Path, +) -> Result, String> { + let certs: Vec> = CertificateDer::pem_file_iter(cert) + .map_err(|e| format!("cannot read {}: {e}", cert.display()))? + .collect::>() + .map_err(|e| format!("{}: {e}", cert.display()))?; + if certs.is_empty() { + return Err(format!("{} holds no certificate", cert.display())); + } + let key = PrivateKeyDer::from_pem_file(key).map_err(|e| format!("{}: {e}", key.display()))?; + let provider = Arc::new(rustls::crypto::ring::default_provider()); + let cfg = rustls::ServerConfig::builder_with_provider(provider) + .with_safe_default_protocol_versions() + .map_err(|e| e.to_string())? + .with_no_client_auth() + .with_single_cert(certs, key) + .map_err(|e| format!("TLS certificate and key do not work together: {e}"))?; + Ok(Arc::new(cfg)) +} + +/// Refuse to listen on the diode NIC, whatever address it was given. +fn check_not_diode(cfg: &Config, side: Side, listen: SocketAddr) -> Result<(), String> { + let diode_if = match side { + Side::In => &cfg.network.in_interface, + Side::Out => &cfg.network.out_interface, + }; + if let IpAddr::V4(ip) = listen.ip() { + if crate::netutil::interface_addresses().get(diode_if) == Some(&ip) { + return Err(format!( + "api.{}.listen {ip} is on the diode NIC {diode_if}: the API must listen on the management NIC", + side.as_str() + )); + } + } + Ok(()) +} + +struct Ctx { + cfg: Arc, + side: Side, + api: ApiListen, + started: Instant, +} + +/// Serve for ever (under the supervisor). +pub fn serve(cfg: &Arc, side: Side, api: &ApiListen) -> Result<(), String> { + check_not_diode(cfg, side, api.listen)?; + let tls = match &api.tls { + Some((c, k)) => Some(tls_config(c, k)?), + None => None, + }; + let listener = TcpListener::bind(api.listen) + .map_err(|e| format!("API: cannot listen on {}: {e}", api.listen))?; + log::info!( + "API listening on {} ({}, tokens in {})", + api.listen, + if tls.is_some() { + "TLS" + } else { + "plain HTTP, loopback only" + }, + api.tokens.display() + ); + let ctx = Arc::new(Ctx { + cfg: Arc::clone(cfg), + side, + api: api.clone(), + started: Instant::now(), + }); + serve_on(listener, tls, ctx) +} + +fn serve_on( + listener: TcpListener, + tls: Option>, + ctx: Arc, +) -> Result<(), String> { + let active = Arc::new(AtomicUsize::new(0)); + for conn in listener.incoming() { + let Ok(stream) = conn else { continue }; + if active.load(Ordering::Relaxed) >= ctx.api.max_clients { + crate::stats::count("api_busy"); + drop(stream); + continue; + } + active.fetch_add(1, Ordering::Relaxed); + let (ctx, tls, mine) = (Arc::clone(&ctx), tls.clone(), Arc::clone(&active)); + let spawned = std::thread::Builder::new() + .name("api-conn".into()) + .spawn(move || { + let peer = stream.peer_addr().ok(); + let _ = stream.set_read_timeout(Some(IO_TIMEOUT)); + let _ = stream.set_write_timeout(Some(IO_TIMEOUT)); + let r = match tls { + Some(cfg) => match rustls::ServerConnection::new(cfg) { + Ok(conn) => handle(&mut rustls::StreamOwned::new(conn, stream), peer, &ctx), + Err(e) => Err(e.to_string()), + }, + None => { + let mut s = stream; + handle(&mut s, peer, &ctx) + } + }; + if let Err(e) = r { + log::debug!("API connection from {peer:?}: {e}"); + } + mine.fetch_sub(1, Ordering::Relaxed); + }); + if spawned.is_err() { + active.fetch_sub(1, Ordering::Relaxed); + } + } + Err("API listener closed".into()) +} + +struct Request { + method: String, + path: String, + bearer: Option, +} + +fn read_request(s: &mut S) -> Result, String> { + let mut buf = Vec::with_capacity(1024); + let mut chunk = [0u8; 2048]; + loop { + let n = s.read(&mut chunk).map_err(|e| e.to_string())?; + if n == 0 { + return Ok(None); + } + buf.extend_from_slice(&chunk[..n]); + let mut headers = [httparse::EMPTY_HEADER; 32]; + let mut req = httparse::Request::new(&mut headers); + match req.parse(&buf) { + Ok(httparse::Status::Complete(_)) => { + let bearer = req + .headers + .iter() + .find(|h| h.name.eq_ignore_ascii_case("authorization")) + .and_then(|h| std::str::from_utf8(h.value).ok()) + .and_then(|v| { + v.strip_prefix("Bearer ") + .or_else(|| v.strip_prefix("bearer ")) + }) + .map(|t| t.trim().to_string()); + return Ok(Some(Request { + method: req.method.unwrap_or("").to_string(), + path: req.path.unwrap_or("").to_string(), + bearer, + })); + } + Ok(httparse::Status::Partial) if buf.len() < MAX_REQUEST => continue, + Ok(httparse::Status::Partial) => return Err("request headers too large".into()), + Err(e) => return Err(format!("bad request: {e}")), + } + } +} + +fn respond( + s: &mut S, + code: u16, + ctype: &str, + body: &[u8], + head: bool, + extra: &str, +) -> Result<(), String> { + let reason = match code { + 200 => "OK", + 400 => "Bad Request", + 401 => "Unauthorized", + 403 => "Forbidden", + 404 => "Not Found", + 405 => "Method Not Allowed", + _ => "Error", + }; + let hdr = format!( + "HTTP/1.1 {code} {reason}\r\nServer: DYODE\r\nContent-Type: {ctype}\r\nContent-Length: {}\r\n\ + Cache-Control: no-store\r\nX-Content-Type-Options: nosniff\r\nConnection: close\r\n{extra}\r\n", + body.len() + ); + s.write_all(hdr.as_bytes()).map_err(|e| e.to_string())?; + if !head { + s.write_all(body).map_err(|e| e.to_string())?; + } + s.flush().map_err(|e| e.to_string()) +} + +fn json_body(v: &Value) -> Vec { + let mut b = serde_json::to_vec_pretty(v).unwrap_or_default(); + b.push(b'\n'); + b +} + +fn error(s: &mut S, code: u16, msg: &str, head: bool, extra: &str) -> Result<(), String> { + respond( + s, + code, + "application/json", + &json_body(&json!({"error": msg})), + head, + extra, + ) +} + +/// Logged to transfer.jsonl, and counted there (events without a module +/// are box-wide counters). +fn refused(ctx: &Ctx, peer: Option, path: &str, reason: &str) { + Event::new("api_refused") + .field("peer", peer.map(|p| p.ip().to_string())) + .field("path", path) + .field("reason", reason) + .field("side", ctx.side.as_str()) + .emit(); +} + +fn handle(s: &mut S, peer: Option, ctx: &Ctx) -> Result<(), String> { + let req = match read_request(s) { + Ok(Some(r)) => r, + Ok(None) => return Ok(()), + Err(e) => return error(s, 400, &e, false, ""), + }; + let head = req.method == "HEAD"; + if req.method != "GET" && !head { + return error(s, 405, "only GET and HEAD", false, "Allow: GET, HEAD\r\n"); + } + let path = req.path.split('?').next().unwrap_or("").to_string(); + let stale = crate::status::stale_after(&ctx.cfg); + // Open endpoints. + match path.as_str() { + "/v1/health" => { + let v = json!({ + "status": "ok", + "side": ctx.side.as_str(), + "version": env!("CARGO_PKG_VERSION"), + "uptime_s": ctx.started.elapsed().as_secs(), + }); + return respond(s, 200, "application/json", &json_body(&v), head, ""); + } + "/v1/openapi.json" => { + return respond( + s, + 200, + "application/json", + &json_body(&openapi_json()), + head, + "", + ); + } + "/v1/status" | "/metrics" | "/v1/check" => {} + _ => return error(s, 404, "no such endpoint (see /v1/openapi.json)", head, ""), + } + // Everything else needs a token with the read scope. + let tokens = match crate::apitoken::list(&ctx.api.tokens) { + Ok(t) => t, + Err(e) => { + log::error!("API: {e}"); + return error(s, 500, "token file unreadable", head, ""); + } + }; + let Some(presented) = req.bearer else { + refused(ctx, peer, &path, "no token"); + return error( + s, + 401, + "a bearer token is required", + head, + "WWW-Authenticate: Bearer realm=\"dyode\"\r\n", + ); + }; + let Some(token) = crate::apitoken::verify(&tokens, &presented) else { + refused(ctx, peer, &path, "unknown token"); + return error( + s, + 401, + "unknown token", + head, + "WWW-Authenticate: Bearer realm=\"dyode\", error=\"invalid_token\"\r\n", + ); + }; + if !token.allows("read") { + refused(ctx, peer, &path, "scope"); + return error(s, 403, "this token lacks the read scope", head, ""); + } + match path.as_str() { + "/v1/status" => respond( + s, + 200, + "application/json", + &json_body(&crate::stats::combined(stale)), + head, + "", + ), + "/metrics" => respond( + s, + 200, + "text/plain; version=0.0.4; charset=utf-8", + crate::stats::prometheus(stale).as_bytes(), + head, + "", + ), + _ => { + let r = crate::check::report(&ctx.cfg, Some(ctx.side.as_str()), false); + respond( + s, + 200, + "application/json", + &json_body(&serde_json::to_value(&r).unwrap_or(Value::Null)), + head, + "", + ) + } + } +} + +/// For tests: serve on an already bound listener. +#[doc(hidden)] +pub fn serve_listener( + listener: TcpListener, + tls: Option>, + cfg: Arc, + side: Side, + api: ApiListen, +) -> Result<(), String> { + let ctx = Arc::new(Ctx { + cfg, + side, + api, + started: Instant::now(), + }); + serve_on(listener, tls, ctx) +} + +/// The routes this server answers, for the test that keeps +/// docs/api/openapi.yaml in step. +pub const ROUTES: [&str; 5] = [ + "/v1/health", + "/v1/status", + "/metrics", + "/v1/check", + "/v1/openapi.json", +]; + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn openapi_lists_exactly_the_routes() { + let v = openapi_json(); + let paths: Vec = v["paths"] + .as_object() + .expect("paths") + .keys() + .cloned() + .collect(); + let mut want: Vec = ROUTES.iter().map(|s| s.to_string()).collect(); + let mut got = paths.clone(); + want.sort(); + got.sort(); + assert_eq!(got, want, "docs/api/openapi.yaml and api::ROUTES differ"); + assert_eq!(v["info"]["version"], env!("CARGO_PKG_VERSION")); + } + + #[test] + fn request_parsing() { + let mut r: &[u8] = + b"GET /metrics?x=1 HTTP/1.1\r\nHost: a\r\nAuthorization: Bearer abc \r\n\r\n"; + let q = read_request(&mut r).unwrap().unwrap(); + assert_eq!( + (q.method.as_str(), q.path.as_str(), q.bearer.as_deref()), + ("GET", "/metrics?x=1", Some("abc")) + ); + let mut bad: &[u8] = b"GE\x01T / HTTP/1.1\r\n\r\n"; + assert!(read_request(&mut bad).is_err()); + let big = format!("GET / HTTP/1.1\r\nX: {}\r\n", "a".repeat(MAX_REQUEST)); + let mut b = big.as_bytes(); + assert!(read_request(&mut b).is_err()); + } +} diff --git a/src/apitoken.rs b/src/apitoken.rs new file mode 100644 index 0000000..d96a586 --- /dev/null +++ b/src/apitoken.rs @@ -0,0 +1,212 @@ +//! Bearer tokens for the local API, one file per box (`/etc/dyode/api-tokens` +//! by default). Only a SHA-256 of each token is stored; the token itself +//! is printed once, by `dyode api-token add`. +//! +//! ```text +//! # name scopes sha256 of the token +//! grafana read 9c1f...e04a +//! ``` +//! +//! The file is never part of config.yaml and is never copied to the other +//! box: a token from the IT side means nothing on the OT side. + +use sha2::{Digest, Sha256}; +use std::path::Path; + +/// Scopes this version understands. +pub const SCOPES: [&str; 1] = ["read"]; + +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Token { + pub name: String, + pub scopes: Vec, + hash: [u8; 32], +} + +impl Token { + pub fn allows(&self, scope: &str) -> bool { + self.scopes.iter().any(|s| s == scope) + } +} + +fn digest(token: &str) -> [u8; 32] { + Sha256::digest(token.as_bytes()).into() +} + +fn parse_hex32(s: &str) -> Option<[u8; 32]> { + if s.len() != 64 { + return None; + } + let mut out = [0u8; 32]; + for (i, b) in out.iter_mut().enumerate() { + *b = u8::from_str_radix(s.get(2 * i..2 * i + 2)?, 16).ok()?; + } + Some(out) +} + +/// The tokens in the file; a missing file is an empty list. +pub fn list(path: &Path) -> Result, String> { + let text = match std::fs::read_to_string(path) { + Ok(t) => t, + Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(vec![]), + Err(e) => return Err(format!("cannot read {}: {e}", path.display())), + }; + let mut out = Vec::new(); + for (n, line) in text.lines().enumerate() { + let line = line.trim(); + if line.is_empty() || line.starts_with('#') { + continue; + } + let f: Vec<&str> = line.split_whitespace().collect(); + let bad = || { + format!( + "{}:{}: expected 'name scopes sha256'", + path.display(), + n + 1 + ) + }; + if f.len() != 3 { + return Err(bad()); + } + let hash = parse_hex32(f[2]).ok_or_else(bad)?; + out.push(Token { + name: f[0].to_string(), + scopes: f[1].split(',').map(String::from).collect(), + hash, + }); + } + Ok(out) +} + +/// The token's entry, compared in constant time against every entry. +pub fn verify(tokens: &[Token], presented: &str) -> Option { + let d = digest(presented); + let mut found = None; + for t in tokens { + let diff = t + .hash + .iter() + .zip(d.iter()) + .fold(0u8, |acc, (a, b)| acc | (a ^ b)); + if diff == 0 && found.is_none() { + found = Some(t.clone()); + } + } + found +} + +fn check_name(name: &str) -> Result<(), String> { + if name.is_empty() + || name.len() > 64 + || !name + .chars() + .all(|c| c.is_ascii_alphanumeric() || "-_.".contains(c)) + { + return Err("a token name is 1 to 64 letters, digits, '-', '_' or '.'".into()); + } + Ok(()) +} + +fn write(path: &Path, lines: &[String]) -> Result<(), String> { + use std::io::Write; + use std::os::unix::fs::OpenOptionsExt; + if let Some(d) = path.parent() { + std::fs::create_dir_all(d).map_err(|e| format!("cannot create {}: {e}", d.display()))?; + } + let tmp = path.with_extension("tmp"); + let mut f = std::fs::OpenOptions::new() + .write(true) + .create(true) + .truncate(true) + .mode(0o600) + .open(&tmp) + .map_err(|e| format!("cannot write {}: {e}", tmp.display()))?; + let mut text = + String::from("# DYODE API tokens (dyode api-token): name, scopes, SHA-256 of the token.\n"); + for l in lines { + text.push_str(l); + text.push('\n'); + } + f.write_all(text.as_bytes()).map_err(|e| e.to_string())?; + std::fs::rename(&tmp, path).map_err(|e| format!("cannot write {}: {e}", path.display())) +} + +fn line(t: &Token) -> String { + format!( + "{:<20} {:<12} {}", + t.name, + t.scopes.join(","), + crate::hex::encode(t.hash) + ) +} + +/// Add a token; returns the token itself, which is not stored. +pub fn add(path: &Path, name: &str, scopes: &[String]) -> Result { + check_name(name)?; + if scopes.is_empty() { + return Err("give at least one scope".into()); + } + for s in scopes { + if !SCOPES.contains(&s.as_str()) { + return Err(format!( + "unknown scope {s:?} (known: {})", + SCOPES.join(", ") + )); + } + } + let mut tokens = list(path)?; + if tokens.iter().any(|t| t.name == name) { + return Err(format!("a token named {name:?} exists; revoke it first")); + } + let mut raw = [0u8; 32]; + crate::auth::random_bytes(&mut raw); + let token = format!("dyode_{}", crate::hex::encode(raw)); + tokens.push(Token { + name: name.into(), + scopes: scopes.to_vec(), + hash: digest(&token), + }); + write(path, &tokens.iter().map(line).collect::>())?; + Ok(token) +} + +/// Remove a token by name. False when there was none. +pub fn revoke(path: &Path, name: &str) -> Result { + let tokens = list(path)?; + let kept: Vec = tokens.iter().filter(|t| t.name != name).cloned().collect(); + if kept.len() == tokens.len() { + return Ok(false); + } + write(path, &kept.iter().map(line).collect::>())?; + Ok(true) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn add_verify_revoke() { + let d = crate::testutil::TempDir::new(); + let p = d.path().join("api-tokens"); + assert!(list(&p).unwrap().is_empty()); + let t = add(&p, "grafana", &["read".into()]).unwrap(); + assert!(t.starts_with("dyode_") && t.len() == 70); + let text = std::fs::read_to_string(&p).unwrap(); + assert!(!text.contains(&t), "the token itself must not be stored"); + let all = list(&p).unwrap(); + assert_eq!(verify(&all, &t).unwrap().name, "grafana"); + assert!(verify(&all, "dyode_wrong").is_none()); + assert!(add(&p, "grafana", &["read".into()]).is_err()); + assert!(add(&p, "x y", &["read".into()]).is_err()); + assert!(add(&p, "z", &["write".into()]).is_err()); + assert!(revoke(&p, "grafana").unwrap()); + assert!(!revoke(&p, "grafana").unwrap()); + assert!(verify(&list(&p).unwrap(), &t).is_none()); + use std::os::unix::fs::PermissionsExt; + assert_eq!( + std::fs::metadata(&p).unwrap().permissions().mode() & 0o777, + 0o600 + ); + } +} diff --git a/src/check.rs b/src/check.rs new file mode 100644 index 0000000..b01b83f --- /dev/null +++ b/src/check.rs @@ -0,0 +1,150 @@ +//! `dyode check`, as data: printed by the command and served by the API's +//! `/v1/check`. + +use crate::config::{Config, Side}; +use serde::Serialize; +use std::path::PathBuf; + +#[derive(Debug, Default, Serialize)] +pub struct Report { + /// Things that are fine and worth saying. + pub notes: Vec, + /// DYODE will not work like this. + pub errors: Vec, + /// Probably wrong, or worth improving. + pub warnings: Vec, +} + +/// Check what can be checked without starting anything. `side` limits the +/// unit and API checks to one box; `serial` means DYODE v2 (no key, no lidi). +pub fn report(cfg: &Config, side: Option<&str>, serial: bool) -> Report { + let mut r = Report::default(); + unit_checks(cfg, side, serial, &mut r); + if serial { + return r; + } + match crate::auth::load_key(&cfg.auth) { + Ok(Some(_)) => r + .notes + .push(format!("key: {} OK", cfg.auth.key_file.display())), + Ok(None) => r + .warnings + .push("no key: auth.required is false, so nothing is authenticated".into()), + Err(e) => r.errors.push(format!("key: {e}")), + } + if let Err(e) = crate::transport::new_receiver_config_check(cfg) { + r.errors.push(format!("lidi: {e}")); + } + if side == Some("in") && cfg.network.out_mac.is_none() { + r.warnings.insert( + 0, + "dyode_out.mac is not set: the input box cannot reach the output box through a diode" + .into(), + ); + } + r.warnings.extend(throughput_hints(cfg)); + api_checks(cfg, side, &mut r); + r +} + +fn sides(side: Option<&str>) -> Vec { + match side { + Some("in") => vec![Side::In], + Some("out") => vec![Side::Out], + _ => vec![Side::In, Side::Out], + } +} + +/// Compare the installed systemd unit(s) with config.yaml. +fn unit_checks(cfg: &Config, side: Option<&str>, serial: bool, r: &mut Report) { + let dir = PathBuf::from( + std::env::var("DYODE_SYSTEMD_DIR").unwrap_or_else(|_| "/etc/systemd/system".into()), + ); + for s in sides(side) { + let path = dir.join(crate::setup::unit_name(s)); + match std::fs::read_to_string(&path) { + Ok(text) => { + let found = crate::setup::check_unit(&text, s, cfg, serial); + if found.is_empty() { + r.notes.push(format!("unit: {} matches", path.display())); + } + r.warnings.extend(found); + } + Err(_) if side.is_some() => r.warnings.push(format!( + "{} is not installed: run install.sh (or dyode setup) to create it", + path.display() + )), + Err(_) => {} + } + } +} + +/// Suggestions for using the box's cores, never errors. +fn throughput_hints(cfg: &Config) -> Vec { + let mut w = Vec::new(); + let cpus = std::thread::available_parallelism().map_or(1, usize::from); + let suggested = crate::wizard::model::suggested_ports(cpus); + if cfg.lidi.ports.len() < suggested { + let first = cfg.lidi.ports.first().copied().unwrap_or(5000); + w.push(format!( + "lidi uses {} port(s) on a {cpus}-CPU box: one RaptorQ thread per port. For more throughput set \ + lidi.ports: [{}] -- in the config of BOTH boxes, and only if the other box has the cores too", + cfg.lidi.ports.len(), + crate::wizard::model::port_list(first, suggested) + )); + } + if let Some(m) = cfg.lidi.max_clients { + let need = cfg.concurrent_transfers() + 1; + if m < need { + w.push(format!( + "lidi.max_clients is {m}, but the modules and the status channel can have {need} transfers \ + in flight (parallel_files included): transfers will wait for each other. Remove \ + max_clients to get {} automatically", + cfg.concurrent_transfers() + 3 + )); + } + } + w +} + +/// The `api:` section for the box(es) being checked. +fn api_checks(cfg: &Config, side: Option<&str>, r: &mut Report) { + for s in sides(side) { + let Some(a) = cfg.api.for_side(s) else { + continue; + }; + let name = s.as_str(); + if !cfg!(feature = "api") { + r.errors.push(format!( + "api.{name} is configured, but this dyode was built without the API" + )); + } + match &a.tls { + Some((cert, key)) => { + for (what, p) in [("certificate", cert), ("key", key)] { + if !p.is_file() { + r.errors.push(format!( + "api.{name}: TLS {what} {} is missing (dyode api-cert makes one)", + p.display() + )); + } + } + } + None => r + .notes + .push(format!("api.{name}: plain HTTP on {}", a.listen)), + } + match crate::apitoken::list(&a.tokens) { + Ok(t) if t.is_empty() => r.warnings.push(format!( + "api.{name}: no tokens in {}: only /v1/health answers (dyode api-token add NAME)", + a.tokens.display() + )), + Ok(t) => r.notes.push(format!( + "api.{name}: listens on {}, {} token(s)", + a.listen, + t.len() + )), + Err(e) => r.errors.push(format!("api.{name}: {e}")), + } + } +} diff --git a/src/config.rs b/src/config.rs index 16dc8b3..6d303db 100644 --- a/src/config.rs +++ b/src/config.rs @@ -401,6 +401,33 @@ impl Module { } } +/// One box's local API (see docs/API.md). +#[derive(Clone, Debug)] +pub struct ApiListen { + pub listen: SocketAddr, + /// Certificate chain and private key (PEM). None only on loopback. + pub tls: Option<(PathBuf, PathBuf)>, + /// Hashed bearer tokens, one file per box (`dyode api-token`). + pub tokens: PathBuf, + /// Simultaneous connections. + pub max_clients: usize, +} + +#[derive(Clone, Debug, Default)] +pub struct ApiConfig { + pub input: Option, + pub output: Option, +} + +impl ApiConfig { + pub fn for_side(&self, side: Side) -> Option<&ApiListen> { + match side { + Side::In => self.input.as_ref(), + Side::Out => self.output.as_ref(), + } + } +} + #[derive(Clone, Debug)] pub struct Config { pub path: PathBuf, @@ -412,6 +439,7 @@ pub struct Config { pub logging: LoggingConfig, pub auth: AuthConfig, pub lidi: LidiConfig, + pub api: ApiConfig, pub modules: Vec, } @@ -434,12 +462,13 @@ impl Config { .sum() } - /// lidi max_clients: configured, or what the modules need plus two - /// (a batch summary and a heartbeat may overlap the transfers). + /// lidi max_clients: configured, or what the modules need plus three + /// (a batch summary, a heartbeat and a status message may overlap the + /// transfers). pub fn max_clients(&self) -> u32 { self.lidi .max_clients - .unwrap_or(self.concurrent_transfers() + 2) + .unwrap_or(self.concurrent_transfers() + 3) } } @@ -762,6 +791,7 @@ pub fn parse(text: &str, path: &Path, base_dir: &Path) -> Result { let logging = normalize_logging(key(&raw, "logging"))?; let auth = normalize_auth(key(&raw, "auth"), base_dir)?; let lidi = normalize_lidi(key(&raw, "lidi"))?; + let api = normalize_api(key(&raw, "api"), base_dir, &network)?; let cfg = Config { path: path.to_path_buf(), @@ -773,6 +803,7 @@ pub fn parse(text: &str, path: &Path, base_dir: &Path) -> Result { logging, auth, lidi, + api, modules, }; if cfg.max_clients() < 1 { @@ -781,6 +812,105 @@ pub fn parse(text: &str, path: &Path, base_dir: &Path) -> Result { Ok(cfg) } +/// `api: {in: {...}, out: {...}}`: each box's own listener. +fn normalize_api(raw: Option<&Value>, base_dir: &Path, net: &Network) -> Result { + let empty = Mapping::new(); + let m = match raw { + None => &empty, + Some(Value::Mapping(m)) => m, + Some(_) => bail!("'api' must be a mapping with 'in' and/or 'out'"), + }; + for k in m.keys().filter_map(as_text) { + if k != "in" && k != "out" { + bail!("'api': unknown key {k:?} (expected 'in' and/or 'out', one per box)"); + } + } + let side = |name: &str, diode_ip: Ipv4Addr| -> Result> { + let Some(v) = key(m, name) else { + return Ok(None); + }; + let Value::Mapping(s) = v else { + bail!("'api.{name}' must be a mapping"); + }; + let mut unknown: Vec = s + .keys() + .filter_map(as_text) + .filter(|k| !["listen", "tls", "tokens", "max_clients"].contains(&k.as_str())) + .collect(); + if !unknown.is_empty() { + unknown.sort(); + bail!("'api.{name}': unknown key(s) {}", unknown.join(", ")); + } + let listen_text = key(s, "listen").and_then(as_text).ok_or_else(|| { + ConfigError(format!( + "'api.{name}.listen' is required (address:port of the management NIC)" + )) + })?; + let listen: SocketAddr = listen_text.trim().parse().map_err(|_| { + ConfigError(format!( + "'api.{name}.listen' must be address:port, got {listen_text:?}" + )) + })?; + if listen.ip().is_unspecified() { + bail!( + "'api.{name}.listen' must name one address, not {}: listening on every interface includes the diode NIC", + listen.ip() + ); + } + if listen.ip() == std::net::IpAddr::V4(diode_ip) { + bail!( + "'api.{name}.listen' is this box's diode address {diode_ip}: the API must listen on the management NIC" + ); + } + let resolve = |p: String| { + let p = PathBuf::from(p); + if p.is_absolute() { p } else { base_dir.join(p) } + }; + let tls = match key(s, "tls") { + None => bail!( + "'api.{name}.tls' is required: {{cert: api.crt, key: api.key}} (dyode api-cert makes them)" + ), + Some(Value::Mapping(t)) => { + let file = |k: &str| { + key(t, k).and_then(as_text).map(resolve).ok_or_else(|| { + ConfigError(format!("'api.{name}.tls.{k}' is required (PEM file)")) + }) + }; + Some((file("cert")?, file("key")?)) + } + Some(v) if matches!(as_text(v).as_deref(), Some("off" | "false")) => None, + Some(other) => { + bail!("'api.{name}.tls' must be {{cert: ..., key: ...}} or off, got {other:?}") + } + }; + if tls.is_none() && !listen.ip().is_loopback() { + bail!( + "'api.{name}.tls: off' is only allowed on 127.0.0.1 (behind your own reverse proxy)" + ); + } + let tokens = key(s, "tokens") + .and_then(as_text) + .map_or_else(|| base_dir.join("api-tokens"), resolve); + let max_clients = match key(s, "max_clients") { + None => 32, + Some(v) => match as_int_trunc(v) { + Some(n) if (1..=1024).contains(&n) => n as usize, + _ => bail!("'api.{name}.max_clients' must be 1 to 1024"), + }, + }; + Ok(Some(ApiListen { + listen, + tls, + tokens, + max_clients, + })) + }; + Ok(ApiConfig { + input: side("in", net.in_ip)?, + output: side("out", net.out_ip)?, + }) +} + fn normalize_auth(raw: Option<&Value>, base_dir: &Path) -> Result { let empty = Mapping::new(); let m = match raw { @@ -1466,7 +1596,7 @@ mod tests { assert_eq!(cfg.lidi.ports, vec![5001, 5002]); assert_eq!(cfg.lidi.max_mbps, None); assert_eq!(load_text(EXAMPLE).unwrap().lidi.max_mbps, Some(100.0)); - assert_eq!(cfg.max_clients(), 3); + assert_eq!(cfg.max_clients(), 4); let t2 = "lidi:\n bogus: 1\nmodules:\n m:\n type: modbus\n ip: 1.2.3.4\n registers: [0-10]\n"; assert!(load_text(t2).is_err()); } diff --git a/src/lib.rs b/src/lib.rs index eed2069..116f7db 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -4,7 +4,11 @@ //! The input box runs `dyode in`, the output box `dyode out`; both read the //! same config.yaml. See README.md and docs/ARCHITECTURE.md. +#[cfg(feature = "api")] +pub mod api; +pub mod apitoken; pub mod auth; +pub mod check; pub mod config; pub mod envelope; pub mod folder; @@ -20,6 +24,8 @@ pub mod runtime; pub mod screen; pub mod serial; pub mod setup; +pub mod stats; +pub mod status; pub mod supervisor; pub mod timefmt; pub mod transport; diff --git a/src/logging.rs b/src/logging.rs index b27e4df..6867dab 100644 --- a/src/logging.rs +++ b/src/logging.rs @@ -259,6 +259,8 @@ impl Event { } pub fn emit(self) { + // Counted even when per-file records are not written. + crate::stats::on_event(self.name, self.module.as_deref(), &self.fields); let mut ev = EVENTS.lock().unwrap(); if self.per_file && !ev.per_file_events { return; diff --git a/src/main.rs b/src/main.rs index b0aaa9b..98f936c 100644 --- a/src/main.rs +++ b/src/main.rs @@ -35,6 +35,14 @@ Setting up: systemd-unit print a systemd unit: --side in|out [--serial] [--workdir DIR] [--binary PATH] [--interface IFACE] [-c FILE] +Status and the local API (docs/API.md): + status this box's status (and, on the output box, the input box's) + from /run/dyode: [--json] [--side in|out] + api-token tokens for this box's API: add NAME [--scope read] | + list | revoke NAME [-c FILE] [--side in|out] + api-cert a self-signed TLS certificate for the API (needs openssl): + [--dir DIR] [--name HOST] [--ip ADDR]... [--days N] [--force] + Logs: logs --archive [--dir DIR] [--keep-weeks N] [--dry-run] logs --stats [--dir DIR] [--json NAME] @@ -204,101 +212,25 @@ fn cmd_check(mut args: Args) { m.name ); } - let mut warnings = unit_warnings(&cfg, side.as_deref(), serial); if serial { println!( " serial: {} @ {} baud (v2: no key needed)", cfg.serial.device, cfg.serial.baudrate ); - print_warnings(&warnings); - return; - } - warnings.extend(throughput_hints(&cfg)); - match auth::load_key(&cfg.auth) { - Ok(Some(_)) => println!(" key: {} OK", cfg.auth.key_file.display()), - Ok(None) => println!(" key: none (auth.required is false: NOT authenticated)"), - Err(e) => { - println!(" key: {e}"); - exit(1); - } } - if let Err(e) = transport::new_receiver_config_check(&cfg) { - println!(" lidi: {e}"); - exit(1); - } - if side.as_deref() == Some("in") && cfg.network.out_mac.is_none() { - warnings.insert( - 0, - "dyode_out.mac is not set: the input box cannot reach the output box through a diode" - .into(), - ); + let r = dyode::check::report(&cfg, side.as_deref(), serial); + for n in &r.notes { + println!(" {n}"); } - print_warnings(&warnings); -} - -fn print_warnings(w: &[String]) { - for l in w { - println!(" warning: {l}"); + for e in &r.errors { + println!(" error: {e}"); } -} - -/// Compare the installed systemd unit(s) with config.yaml: the side asked -/// for, or every DYODE unit present. -fn unit_warnings(cfg: &config::Config, side: Option<&str>, serial: bool) -> Vec { - let dir = PathBuf::from( - std::env::var("DYODE_SYSTEMD_DIR").unwrap_or_else(|_| "/etc/systemd/system".into()), - ); - let sides: Vec = match side { - Some("in") => vec![Side::In], - Some("out") => vec![Side::Out], - _ => vec![Side::In, Side::Out], - }; - let mut w = Vec::new(); - for s in sides { - let path = dir.join(setup::unit_name(s)); - match std::fs::read_to_string(&path) { - Ok(text) => { - let found = setup::check_unit(&text, s, cfg, serial); - if found.is_empty() { - println!(" unit: {} matches", path.display()); - } - w.extend(found); - } - Err(_) if side.is_some() => w.push(format!( - "{} is not installed: run install.sh (or dyode setup) to create it", - path.display() - )), - Err(_) => {} - } + for w in &r.warnings { + println!(" warning: {w}"); } - w -} - -/// Suggestions for using the box's cores, never errors. -fn throughput_hints(cfg: &config::Config) -> Vec { - let mut w = Vec::new(); - let cpus = std::thread::available_parallelism().map_or(1, usize::from); - let suggested = dyode::wizard::model::suggested_ports(cpus); - if cfg.lidi.ports.len() < suggested { - let first = cfg.lidi.ports.first().copied().unwrap_or(5000); - w.push(format!( - "lidi uses {} port(s) on a {cpus}-CPU box: one RaptorQ thread per port. For more throughput set \ - lidi.ports: [{}] -- in the config of BOTH boxes, and only if the other box has the cores too", - cfg.lidi.ports.len(), - dyode::wizard::model::port_list(first, suggested) - )); - } - if let Some(m) = cfg.lidi.max_clients { - let need = cfg.concurrent_transfers(); - if m < need { - w.push(format!( - "lidi.max_clients is {m}, but the modules can have {need} transfers in flight (parallel_files \ - included): transfers will wait for each other. Remove max_clients to get {} automatically", - need + 2 - )); - } + if !r.errors.is_empty() { + exit(1); } - w } fn cmd_unit(mut args: Args) { @@ -524,6 +456,184 @@ fn cmd_setup(mut args: Args) { } } +fn cmd_status(mut args: Args) { + let json = args.flag(&["--json"]); + let side = args.value(&["--side"]); + args.done(); + let sides: Vec<&str> = match side.as_deref() { + Some("in") => vec!["in"], + Some("out") => vec!["out"], + None => vec!["in", "out"], + Some(o) => die_usage(&format!("--side must be in or out, not {o:?}")), + }; + let mut found = false; + for s in sides { + let path = dyode::stats::status_path(s); + let Ok(text) = std::fs::read_to_string(&path) else { + continue; + }; + found = true; + let age = std::fs::metadata(&path) + .and_then(|m| m.modified()) + .ok() + .and_then(|t| t.elapsed().ok()) + .map_or(0, |d| d.as_secs()); + if json { + println!("{text}"); + continue; + } + match serde_json::from_str::(&text) { + Ok(v) => { + print!("{}", dyode::stats::describe(&v)); + if age > 90 { + println!( + "warning: {} is {age}s old: is dyode-{s} running?", + path.display() + ); + } + } + Err(e) => eprintln!("{}: {e}", path.display()), + } + } + if !found { + eprintln!( + "no status in {}: DYODE is not running on this box (or not as root)", + dyode::stats::run_dir().display() + ); + exit(1); + } +} + +/// The token file of the side asked for, or of the only side configured. +fn tokens_path(cfg: &config::Config, side: Option) -> PathBuf { + let pick = |s: Side| cfg.api.for_side(s).map(|a| a.tokens.clone()); + let found = match side.as_deref() { + Some("in") => pick(Side::In), + Some("out") => pick(Side::Out), + None => pick(Side::Out).or_else(|| pick(Side::In)), + Some(o) => die_usage(&format!("--side must be in or out, not {o:?}")), + }; + found.unwrap_or_else(|| { + cfg.path + .canonicalize() + .ok() + .and_then(|p| p.parent().map(|d| d.join("api-tokens"))) + .unwrap_or_else(|| PathBuf::from("api-tokens")) + }) +} + +fn cmd_api_token(mut args: Args) { + let cfg_path = args.value(&["-c", "--config"]); + let side = args.value(&["--side"]); + let scopes: Vec = args + .value(&["--scope"]) + .unwrap_or_else(|| "read".into()) + .split(',') + .map(|s| s.trim().to_string()) + .collect(); + if args.items.is_empty() { + die_usage("api-token needs add NAME, list or revoke NAME"); + } + let action = args.items.remove(0); + let name = (!args.items.is_empty()).then(|| args.items.remove(0)); + args.done(); + logging::init(log::LevelFilter::Warn); + let cfg = load(cfg_path); + let path = tokens_path(&cfg, side); + match (action.as_str(), name) { + ("add", Some(n)) => match dyode::apitoken::add(&path, &n, &scopes) { + Ok(token) => { + println!("{token}"); + eprintln!( + "token {n:?} ({}) added to {}. It is shown only now: store it in the client's secrets.", + scopes.join(","), + path.display() + ); + } + Err(e) => { + eprintln!("{e}"); + exit(1); + } + }, + ("list", None) => match dyode::apitoken::list(&path) { + Ok(t) if t.is_empty() => println!("no tokens in {}", path.display()), + Ok(t) => { + for tok in t { + println!("{:<20} {}", tok.name, tok.scopes.join(",")); + } + } + Err(e) => { + eprintln!("{e}"); + exit(1); + } + }, + ("revoke", Some(n)) => match dyode::apitoken::revoke(&path, &n) { + Ok(true) => println!("revoked {n:?} in {}", path.display()), + Ok(false) => { + eprintln!("no token named {n:?} in {}", path.display()); + exit(1); + } + Err(e) => { + eprintln!("{e}"); + exit(1); + } + }, + _ => die_usage("api-token needs add NAME, list or revoke NAME"), + } +} + +fn cmd_api_cert(mut args: Args) { + let dir = PathBuf::from( + args.value(&["--dir"]) + .unwrap_or_else(|| "/etc/dyode".into()), + ); + let mut ips = Vec::new(); + while let Some(ip) = args.value(&["--ip"]) { + if ip.parse::().is_err() { + die_usage(&format!("--ip {ip:?} is not an IP address")); + } + ips.push(ip); + } + let name = args.value(&["--name"]).unwrap_or_else(|| { + std::fs::read_to_string("/etc/hostname") + .map(|s| s.trim().to_string()) + .unwrap_or_else(|_| "dyode".into()) + }); + let days = args.value(&["--days"]).unwrap_or_else(|| "825".into()); + if days.parse::().map_or(true, |d| d == 0) { + die_usage("--days needs a positive number"); + } + let force = args.flag(&["--force"]); + args.done(); + if !name + .chars() + .all(|c| c.is_ascii_alphanumeric() || "-.".contains(c)) + { + die_usage("--name must be a host name"); + } + match setup::make_api_cert(&dir, &name, &ips, days.parse().unwrap_or(825), force) { + Ok(c) => { + println!( + "wrote {} and {} (valid {days} days, {})", + c.cert.display(), + c.key.display(), + c.names.join(", ") + ); + println!("{}", c.fingerprint); + println!( + "Give clients this certificate (or pin the fingerprint), then set in config.yaml:" + ); + println!( + " api: {{: {{listen: ADDRESS:8443, tls: {{cert: api.crt, key: api.key}}}}}}" + ); + } + Err(e) => { + eprintln!("{e}"); + exit(1); + } + } +} + fn cmd_interfaces(mut args: Args) { let all = args.flag(&["--all"]); args.done(); @@ -623,6 +733,9 @@ fn main() { } "interfaces" => cmd_interfaces(args), "setup" => cmd_setup(args), + "status" => cmd_status(args), + "api-token" => cmd_api_token(args), + "api-cert" => cmd_api_cert(args), "firewall-rules" => { let p = args.value(&["-c", "--config"]); let iface_only = args.flag(&["--interface"]); diff --git a/src/netutil.rs b/src/netutil.rs index 0c8d815..9583a21 100644 --- a/src/netutil.rs +++ b/src/netutil.rs @@ -102,6 +102,7 @@ pub fn run_arp_keeper(net: &Network) -> Result<(), String> { let mut healthy: Option = None; loop { let ok = set_static_arp(net); + crate::stats::set_arp_ok(ok); if Some(ok) != healthy { if ok { log::info!( diff --git a/src/runtime.rs b/src/runtime.rs index 78fccdf..f1293e4 100644 --- a/src/runtime.rs +++ b/src/runtime.rs @@ -4,11 +4,12 @@ use crate::config::{Config, ModuleKind, Side}; use crate::envelope::Inbound; use crate::transport::{self, Lifecycle, ModuleLink, Uplink}; -use crate::{auth, folder, logstream, modbus, netutil, screen, serial, supervisor}; +use crate::{auth, folder, logstream, modbus, netutil, screen, serial, status, supervisor}; use std::collections::HashMap; use std::sync::Arc; fn banner(cfg: &Config, side: Side) { + crate::stats::init(cfg, side.as_str()); log::info!( "DYODE {} ({} side), configuration {:?}, version {}, dated {}", env!("CARGO_PKG_VERSION"), @@ -98,6 +99,19 @@ pub fn run_in(cfg: Config) -> ! { let n = net.clone(); supervisor::spawn("arp-keeper", Box::new(move || netutil::run_arp_keeper(&n))); } + let status_link = ModuleLink::for_endpoint( + Arc::clone(&uplink), + transport::status_endpoint(&cfg), + transport::status_tag(), + key.clone(), + None, + ); + let c = Arc::clone(&cfg); + supervisor::spawn( + "status", + Box::new(move || status::run_reporter(&c, Some(&status_link))), + ); + start_api(&cfg, Side::In); supervisor::park_forever() }) } @@ -168,7 +182,18 @@ pub fn run_out(cfg: Config) -> ! { } }; lifecycle.register(m, key.clone(), inbound); + if matches!(m.kind, ModuleKind::Folder(_)) { + // Its work happens in lidi's threads; there is no module + // thread to report it running. + crate::stats::module_started(&m.name); + } } + lifecycle.register_endpoint( + transport::status_endpoint(&cfg), + transport::status_tag(), + key.clone(), + Arc::new(status::StatusInbound::new()), + ); let receiver = match transport::new_receiver(&cfg, lifecycle) { Ok(r) => &*Box::leak(Box::new(r)), Err(e) => { @@ -176,6 +201,10 @@ pub fn run_out(cfg: Config) -> ! { std::process::exit(1); } }; + let cfg = Arc::new(cfg); + let c = Arc::clone(&cfg); + supervisor::spawn("status", Box::new(move || status::run_reporter(&c, None))); + start_api(&cfg, Side::Out); std::thread::scope(|scope| { if let Err(e) = receiver.start(scope) { log::error!("cannot start lidi: {e}"); @@ -185,6 +214,25 @@ pub fn run_out(cfg: Config) -> ! { }) } +/// The local API, when configured for this side (and built in). +fn start_api(cfg: &Arc, side: Side) { + let Some(api) = cfg.api.for_side(side).cloned() else { + return; + }; + #[cfg(feature = "api")] + { + let c = Arc::clone(cfg); + supervisor::spawn("api", Box::new(move || crate::api::serve(&c, side, &api))); + } + #[cfg(not(feature = "api"))] + { + let _ = api; + log::error!( + "an api: section is configured, but this dyode was built without the API (cargo feature \"api\")" + ); + } +} + fn modbus_modules(cfg: &Config) -> Vec<(String, crate::config::ModbusConfig)> { let mut out = Vec::new(); for m in &cfg.modules { diff --git a/src/setup.rs b/src/setup.rs index 05bc964..4017fd5 100644 --- a/src/setup.rs +++ b/src/setup.rs @@ -140,6 +140,9 @@ pub fn systemd_unit_text( "# Creates /var/log/dyode-transfer with the right mode before start.".into(), "LogsDirectory=dyode-transfer".into(), "LogsDirectoryMode=0750".into(), + "# /run/dyode: the status file read by 'dyode status'.".into(), + "RuntimeDirectory=dyode".into(), + "RuntimeDirectoryMode=0750".into(), format!("# root is needed for {reason}."), "User=root".into(), String::new(), @@ -223,6 +226,99 @@ pub fn check_unit( w } +pub struct ApiCert { + pub cert: std::path::PathBuf, + pub key: std::path::PathBuf, + pub names: Vec, + /// As openssl prints it: "sha256 Fingerprint=AB:CD:...". + pub fingerprint: String, +} + +/// A self-signed TLS certificate for the local API, made with openssl +/// (present on every supported system): api.crt and api.key in `dir`. +pub fn make_api_cert( + dir: &Path, + name: &str, + ips: &[String], + days: u32, + force: bool, +) -> Result { + use std::process::{Command, Stdio}; + if name.is_empty() + || !name + .chars() + .all(|c| c.is_ascii_alphanumeric() || "-.".contains(c)) + { + return Err(format!("{name:?} is not a host name")); + } + for ip in ips { + if ip.parse::().is_err() { + return Err(format!("{ip:?} is not an IP address")); + } + } + let (crt, key) = (dir.join("api.crt"), dir.join("api.key")); + if !force && (crt.exists() || key.exists()) { + return Err(format!( + "{} or {} exists; --force replaces them", + crt.display(), + key.display() + )); + } + fs::create_dir_all(dir).map_err(|e| format!("cannot create {}: {e}", dir.display()))?; + let mut names = vec![format!("DNS:{name}")]; + names.extend(ips.iter().map(|i| format!("IP:{i}"))); + let out = Command::new("openssl") + .args([ + "req", + "-x509", + "-newkey", + "ec", + "-pkeyopt", + "ec_paramgen_curve:P-256", + "-nodes", + ]) + .arg("-keyout") + .arg(&key) + .arg("-out") + .arg(&crt) + .args([ + "-days", + &days.to_string(), + "-subj", + &format!("/CN={name}/O=DYODE"), + ]) + .args(["-addext", &format!("subjectAltName={}", names.join(","))]) + .args(["-addext", "basicConstraints=critical,CA:FALSE"]) + .args(["-addext", "keyUsage=critical,digitalSignature"]) + .args(["-addext", "extendedKeyUsage=serverAuth"]) + .stdout(Stdio::null()) + .output() + .map_err(|e| { + format!("cannot run openssl ({e}): install it, or use a certificate from your CA") + })?; + if !out.status.success() { + return Err(format!( + "openssl failed: {}", + String::from_utf8_lossy(&out.stderr).trim() + )); + } + use std::os::unix::fs::PermissionsExt; + let _ = fs::set_permissions(&key, fs::Permissions::from_mode(0o600)); + let fingerprint = Command::new("openssl") + .args(["x509", "-noout", "-fingerprint", "-sha256", "-in"]) + .arg(&crt) + .output() + .ok() + .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string()) + .unwrap_or_default(); + Ok(ApiCert { + cert: crt, + key, + names, + fingerprint, + }) +} + /// Copy a key file after checking it, readable by root only. pub fn install_key_copy(source: &Path, dest: &Path) -> Result<(), String> { crate::auth::read_key_file(source).map_err(|e| e.to_string())?; @@ -265,6 +361,12 @@ pub fn firewall_rules(cfg: &crate::config::Config) -> Result { .collect::>() .join(", "); let in_ip = cfg.network.in_ip; + let api_rule = cfg.api.output.as_ref().map_or(String::new(), |a| { + format!( + "\t\ttcp dport {} iifname \"{iface}\" counter drop comment \"DYODE: the API never on the diode NIC\"\n", + a.listen.port() + ) + }); Ok(format!( "# Managed by DYODE install.sh (rewritten on each run; --no-firewall to skip).\n\ # Diode ports {plist}: accepted only on {iface} from the input box {in_ip}.\n\ @@ -277,6 +379,7 @@ pub fn firewall_rules(cfg: &crate::config::Config) -> Result { \t\tmeta nfproto ipv6 udp dport {{ {plist} }} counter drop comment \"DYODE: diode ports are IPv4 only\"\n\ \t\tudp dport {{ {plist} }} iifname != \"{iface}\" counter drop comment \"DYODE: diode ports only on the diode NIC\"\n\ \t\tudp dport {{ {plist} }} ip saddr != {in_ip} counter drop comment \"DYODE: diode ports only from the input box\"\n\ + {api_rule}\ \t}}\n\ }}\n" )) diff --git a/src/stats.rs b/src/stats.rs new file mode 100644 index 0000000..5b12b36 --- /dev/null +++ b/src/stats.rs @@ -0,0 +1,615 @@ +//! What each box knows about itself, for `dyode status`, the status message +//! the input box sends through the diode, and the API's `/v1/status` and +//! `/metrics`. +//! +//! Everything is counted where it already happens: every [`Event`] that +//! goes to transfer.jsonl is also counted here (before the per-file switch, +//! so `per_file_events: false` does not hide counts), and the supervisor +//! reports module starts and restarts. Nothing in the modules changes. +//! +//! [`Event`]: crate::logging::Event + +use crate::config::{Config, ModuleKind}; +use serde_json::{Map, Value, json}; +use std::collections::BTreeMap; +use std::path::{Path, PathBuf}; +use std::sync::Mutex; +use std::time::Instant; + +/// Seconds since the Unix epoch, as f64. +fn now() -> f64 { + crate::timefmt::unix_now_f64() +} + +#[derive(Clone, Debug, Default)] +pub struct ModuleStats { + pub name: String, + pub kind: String, + pub endpoint: u16, + /// "starting", "running" or "restarting". + pub state: String, + pub restarts: u64, + pub last_activity: Option, + /// transfer.jsonl events by name. + pub events: BTreeMap, + pub bytes_sent: u64, + pub bytes_stored: u64, + /// Folders whose free space is reported: (label, path). + dirs: Vec<(String, PathBuf)>, +} + +/// The last status the other box sent through the diode. +#[derive(Clone, Debug)] +pub struct Peer { + pub status: Value, + pub received: f64, +} + +struct Registry { + side: String, + config_name: String, + transport_hash: String, + started: Option, + modules: Vec, + global: BTreeMap, + peer: Option, + arp_ok: Option, +} + +static REG: Mutex = Mutex::new(Registry { + side: String::new(), + config_name: String::new(), + transport_hash: String::new(), + started: None, + modules: Vec::new(), + global: BTreeMap::new(), + peer: None, + arp_ok: None, +}); + +fn reg() -> std::sync::MutexGuard<'static, Registry> { + REG.lock().unwrap_or_else(|p| p.into_inner()) +} + +/// A short hash of everything both boxes must agree on: the lidi +/// parameters and every module's name and type. Two boxes with different +/// hashes refuse at least some of each other's traffic. +pub fn transport_hash(cfg: &Config) -> String { + use sha2::{Digest, Sha256}; + let mut h = Sha256::new(); + h.update(crate::transport::lidi_toml(cfg).as_bytes()); + for m in &cfg.modules { + h.update(m.tag()); + } + crate::hex::encode(&h.finalize()[..6]) +} + +/// Set up the registry for this box. Called once at start. +pub fn init(cfg: &Config, side: &str) { + let mut r = reg(); + r.side = side.to_string(); + r.config_name = cfg.config_name.clone().unwrap_or_default(); + r.transport_hash = transport_hash(cfg); + r.started = Some(Instant::now()); + r.modules = cfg + .modules + .iter() + .map(|m| { + let dirs = match (&m.kind, side) { + (ModuleKind::Folder(f), "in") => vec![("in".to_string(), f.input.clone())], + (ModuleKind::Folder(f), _) => vec![("out".to_string(), f.output.clone())], + (ModuleKind::Screen(s), "in") => vec![("in".to_string(), s.input.clone())], + (ModuleKind::Screen(s), _) => vec![("out".to_string(), s.output.clone())], + (ModuleKind::Logs(l), "out") => l + .out + .iter() + .map(|p| ("out".to_string(), p.clone())) + .collect(), + _ => vec![], + }; + ModuleStats { + name: m.name.clone(), + kind: m.kind.type_name().to_string(), + endpoint: m.index, + state: "starting".into(), + dirs, + ..Default::default() + } + }) + .collect(); +} + +fn with_module(name: &str, f: impl FnOnce(&mut ModuleStats)) { + let mut r = reg(); + if let Some(m) = r.modules.iter_mut().find(|m| m.name == name) { + f(m); + } +} + +/// Every transfer.jsonl event passes through here. +pub fn on_event(event: &str, module: Option<&str>, fields: &Map) { + let Some(name) = module else { + *reg().global.entry(event.to_string()).or_default() += 1; + return; + }; + let bytes = fields.get("bytes").and_then(Value::as_u64).unwrap_or(0); + with_module(name, |m| { + *m.events.entry(event.to_string()).or_default() += 1; + m.last_activity = Some(now()); + match event { + "file_sent" => m.bytes_sent += bytes, + "file_stored" => m.bytes_stored += bytes, + _ => {} + } + }); +} + +/// From the supervisor: a module (re)started or stopped. +pub fn module_started(name: &str) { + with_module(name, |m| m.state = "running".into()); +} + +pub fn module_stopped(name: &str) { + with_module(name, |m| { + m.state = "restarting".into(); + m.restarts += 1; + }); +} + +/// A counter that belongs to no module (lidi aborts, API refusals). +pub fn count(what: &str) { + *reg().global.entry(what.to_string()).or_default() += 1; +} + +/// The input box's static ARP entry, as last checked. +pub fn set_arp_ok(ok: bool) { + reg().arp_ok = Some(ok); +} + +/// The output box received the input box's status. +pub fn set_peer(status: Value) { + reg().peer = Some(Peer { + status, + received: now(), + }); +} + +pub fn peer() -> Option { + reg().peer.clone() +} + +fn free_bytes(path: &Path) -> Option { + use std::os::unix::ffi::OsStrExt; + let c = std::ffi::CString::new(path.as_os_str().as_bytes()).ok()?; + let mut s: libc::statvfs = unsafe { std::mem::zeroed() }; + // SAFETY: a valid C string and an out-pointer to a statvfs. + (unsafe { libc::statvfs(c.as_ptr(), &mut s) } == 0) + .then(|| s.f_bavail.saturating_mul(s.f_frsize)) +} + +/// This box's status, as JSON (the same shape is sent through the diode). +pub fn snapshot() -> Value { + let r = reg(); + let modules: Vec = r + .modules + .iter() + .map(|m| { + let free: Vec = m + .dirs + .iter() + .filter_map(|(label, p)| { + free_bytes(p).map(|b| json!({"dir": label, "path": p, "free_bytes": b})) + }) + .collect(); + json!({ + "name": m.name, + "type": m.kind, + "endpoint": m.endpoint, + "state": m.state, + "restarts": m.restarts, + "last_activity": m.last_activity.map(crate::timefmt::iso_utc), + "events": m.events, + "bytes_sent": m.bytes_sent, + "bytes_stored": m.bytes_stored, + "free": free, + }) + }) + .collect(); + let mut v = json!({ + "side": r.side, + "version": env!("CARGO_PKG_VERSION"), + "config_name": r.config_name, + "transport_hash": r.transport_hash, + "time": crate::timefmt::utc_now(), + "uptime_s": r.started.map_or(0, |s| s.elapsed().as_secs()), + "modules": modules, + "counters": r.global, + }); + if let Some(a) = r.arp_ok { + v["static_arp_ok"] = a.into(); + } + v +} + +/// Seconds since the peer's status arrived; None if it never did. +pub fn peer_age() -> Option { + peer().map(|p| (now() - p.received).max(0.0)) +} + +/// Both boxes, as the output box's API serves them. `stale_after` is +/// when the input box counts as silent. +pub fn combined(stale_after: f64) -> Value { + let me = snapshot(); + let mut warnings: Vec = Vec::new(); + let mut boxes = Map::new(); + let side = me["side"].as_str().unwrap_or("").to_string(); + if side == "out" { + match peer() { + Some(p) => { + let age = (now() - p.received).max(0.0); + if age > stale_after { + warnings.push(format!( + "no status from the input box for {age:.0}s: the input box, the diode or the link may be down" + )); + } + if p.status["transport_hash"] != me["transport_hash"] { + warnings.push( + "the input box runs a different configuration (transport hash differs): some traffic will be refused".into(), + ); + } + let mut s = p.status; + s["status_age_s"] = json!((age * 10.0).round() / 10.0); + s["received"] = crate::timefmt::iso_utc(p.received).into(); + boxes.insert("in".into(), s); + } + None => { + warnings.push("no status received from the input box yet".into()); + boxes.insert("in".into(), Value::Null); + } + } + } + let mut me = me; + me["status_age_s"] = json!(0); + boxes.insert(side, me); + json!({"boxes": boxes, "warnings": warnings}) +} + +// -------------------------------------------------------------------------- +// The status file and `dyode status` +// -------------------------------------------------------------------------- + +pub fn run_dir() -> PathBuf { + std::env::var_os("DYODE_RUN_DIR").map_or_else(|| PathBuf::from("/run/dyode"), PathBuf::from) +} + +pub fn status_path(side: &str) -> PathBuf { + run_dir().join(format!("status-{side}.json")) +} + +/// Write this box's status (and, on the output box, the input box's) for +/// `dyode status`. Atomic, readable by root only. +pub fn write_status_file(side: &str, stale_after: f64) -> std::io::Result<()> { + use std::io::Write; + use std::os::unix::fs::OpenOptionsExt; + let dir = run_dir(); + std::fs::create_dir_all(&dir)?; + let path = status_path(side); + let tmp = path.with_extension("tmp"); + let text = serde_json::to_vec_pretty(&combined(stale_after)).unwrap_or_default(); + let mut f = std::fs::OpenOptions::new() + .write(true) + .create(true) + .truncate(true) + .mode(0o640) + .open(&tmp)?; + f.write_all(&text)?; + std::fs::rename(&tmp, &path) +} + +/// Render the status file for a person. +pub fn describe(v: &Value) -> String { + let mut out = String::new(); + let boxes = v["boxes"].as_object().cloned().unwrap_or_default(); + for side in ["in", "out"] { + let Some(b) = boxes.get(side) else { continue }; + let label = if side == "in" { + "input box" + } else { + "output box" + }; + if b.is_null() { + out.push_str(&format!("{label}: no status received yet\n")); + continue; + } + let age = b["status_age_s"].as_f64().unwrap_or(0.0); + let as_of = if age > 0.0 { + format!(", as of {age:.0}s ago") + } else { + String::new() + }; + out.push_str(&format!( + "{label}: DYODE {} up {}s, config {:?} ({}){as_of}\n", + b["version"].as_str().unwrap_or("?"), + b["uptime_s"].as_u64().unwrap_or(0), + b["config_name"].as_str().unwrap_or(""), + b["transport_hash"].as_str().unwrap_or("?"), + )); + if let Some(a) = b["static_arp_ok"].as_bool() { + out.push_str(&format!( + " static ARP entry: {}\n", + if a { "in place" } else { "MISSING" } + )); + } + for m in b["modules"].as_array().into_iter().flatten() { + let ev = m["events"].as_object().cloned().unwrap_or_default(); + let mut parts: Vec = ev.iter().map(|(k, n)| format!("{k} {n}")).collect(); + parts.truncate(6); + out.push_str(&format!( + " {:<20} {:<7} {:<10} restarts {}{}\n", + m["name"].as_str().unwrap_or(""), + m["type"].as_str().unwrap_or(""), + m["state"].as_str().unwrap_or(""), + m["restarts"].as_u64().unwrap_or(0), + if parts.is_empty() { + String::new() + } else { + format!(" [{}]", parts.join(", ")) + } + )); + } + } + for w in v["warnings"].as_array().into_iter().flatten() { + out.push_str(&format!("warning: {}\n", w.as_str().unwrap_or(""))); + } + out +} + +// -------------------------------------------------------------------------- +// Prometheus text +// -------------------------------------------------------------------------- + +fn esc(s: &str) -> String { + s.replace('\\', "\\\\") + .replace('"', "\\\"") + .replace('\n', "\\n") +} + +/// `/metrics`: this box, and on the output box the input box too. +pub fn prometheus(stale_after: f64) -> String { + let all = combined(stale_after); + let mut o = String::new(); + let help = |o: &mut String, name: &str, ty: &str, text: &str| { + o.push_str(&format!("# HELP {name} {text}\n# TYPE {name} {ty}\n")); + }; + let boxes = all["boxes"].as_object().cloned().unwrap_or_default(); + let present: Vec<(&str, &Value)> = ["in", "out"] + .iter() + .filter_map(|s| boxes.get(*s).map(|v| (*s, v))) + .collect(); + + help( + &mut o, + "dyode_info", + "gauge", + "DYODE version and transport hash of each box (1 when known).", + ); + for (side, b) in &present { + if b.is_null() { + continue; + } + o.push_str(&format!( + "dyode_info{{side=\"{side}\",version=\"{}\",transport_hash=\"{}\",config=\"{}\"}} 1\n", + esc(b["version"].as_str().unwrap_or("")), + esc(b["transport_hash"].as_str().unwrap_or("")), + esc(b["config_name"].as_str().unwrap_or("")) + )); + } + help( + &mut o, + "dyode_status_age_seconds", + "gauge", + "Seconds since this box's status was taken; for the input box, as seen by the output box.", + ); + for (side, b) in &present { + // A box never heard from has no age: absent rather than 0. + if let Some(a) = b["status_age_s"].as_f64() { + o.push_str(&format!( + "dyode_status_age_seconds{{side=\"{side}\"}} {a}\n" + )); + } + } + help( + &mut o, + "dyode_status_received", + "gauge", + "1 when the box's status is known, 0 when the output box has never heard from the input box.", + ); + for (side, b) in &present { + o.push_str(&format!( + "dyode_status_received{{side=\"{side}\"}} {}\n", + u8::from(!b.is_null()) + )); + } + help( + &mut o, + "dyode_uptime_seconds", + "gauge", + "Seconds since DYODE started on the box.", + ); + for (side, b) in &present { + if let Some(u) = b["uptime_s"].as_u64() { + o.push_str(&format!("dyode_uptime_seconds{{side=\"{side}\"}} {u}\n")); + } + } + if let (Some(i), Some(out)) = (boxes.get("in"), boxes.get("out")) { + if !i.is_null() { + help( + &mut o, + "dyode_config_match", + "gauge", + "1 when both boxes run the same transport configuration.", + ); + o.push_str(&format!( + "dyode_config_match {}\n", + u8::from(i["transport_hash"] == out["transport_hash"]) + )); + } + } + let modules = |b: &Value| b["modules"].as_array().cloned().unwrap_or_default(); + help( + &mut o, + "dyode_module_up", + "gauge", + "1 when the module is running, 0 while it restarts.", + ); + for (side, b) in &present { + for m in modules(b) { + o.push_str(&format!( + "dyode_module_up{{side=\"{side}\",module=\"{}\",type=\"{}\"}} {}\n", + esc(m["name"].as_str().unwrap_or("")), + esc(m["type"].as_str().unwrap_or("")), + u8::from(m["state"] == "running") + )); + } + } + help( + &mut o, + "dyode_module_restarts_total", + "counter", + "Times the module stopped and was restarted.", + ); + for (side, b) in &present { + for m in modules(b) { + o.push_str(&format!( + "dyode_module_restarts_total{{side=\"{side}\",module=\"{}\"}} {}\n", + esc(m["name"].as_str().unwrap_or("")), + m["restarts"].as_u64().unwrap_or(0) + )); + } + } + help( + &mut o, + "dyode_events_total", + "counter", + "transfer.jsonl events by module and event name.", + ); + for (side, b) in &present { + for m in modules(b) { + for (ev, n) in m["events"].as_object().cloned().unwrap_or_default() { + o.push_str(&format!( + "dyode_events_total{{side=\"{side}\",module=\"{}\",event=\"{}\"}} {}\n", + esc(m["name"].as_str().unwrap_or("")), + esc(&ev), + n.as_u64().unwrap_or(0) + )); + } + } + } + help( + &mut o, + "dyode_bytes_total", + "counter", + "File bytes sent (input box) or stored (output box).", + ); + for (side, b) in &present { + for m in modules(b) { + let (dir, n) = if *side == "in" { + ("sent", &m["bytes_sent"]) + } else { + ("stored", &m["bytes_stored"]) + }; + o.push_str(&format!( + "dyode_bytes_total{{side=\"{side}\",module=\"{}\",direction=\"{dir}\"}} {}\n", + esc(m["name"].as_str().unwrap_or("")), + n.as_u64().unwrap_or(0) + )); + } + } + help( + &mut o, + "dyode_last_activity_timestamp_seconds", + "gauge", + "Unix time of the module's last event.", + ); + for (side, b) in &present { + for m in modules(b) { + if let Some(t) = m["last_activity"].as_str().and_then(parse_iso) { + o.push_str(&format!( + "dyode_last_activity_timestamp_seconds{{side=\"{side}\",module=\"{}\"}} {t}\n", + esc(m["name"].as_str().unwrap_or("")) + )); + } + } + } + help( + &mut o, + "dyode_free_bytes", + "gauge", + "Free space under a module's folder.", + ); + for (side, b) in &present { + for m in modules(b) { + for f in m["free"].as_array().cloned().unwrap_or_default() { + o.push_str(&format!( + "dyode_free_bytes{{side=\"{side}\",module=\"{}\",dir=\"{}\"}} {}\n", + esc(m["name"].as_str().unwrap_or("")), + esc(f["dir"].as_str().unwrap_or("")), + f["free_bytes"].as_u64().unwrap_or(0) + )); + } + } + } + help( + &mut o, + "dyode_counter_total", + "counter", + "Box-wide counters: lidi transfers aborted, API requests refused, and events without a module.", + ); + for (side, b) in &present { + for (k, n) in b["counters"].as_object().cloned().unwrap_or_default() { + o.push_str(&format!( + "dyode_counter_total{{side=\"{side}\",counter=\"{}\"}} {}\n", + esc(&k), + n.as_u64().unwrap_or(0) + )); + } + } + if let Some(b) = boxes.get("in") { + if let Some(a) = b["static_arp_ok"].as_bool() { + help( + &mut o, + "dyode_static_arp_ok", + "gauge", + "1 when the input box's static ARP entry for the output box is in place.", + ); + o.push_str(&format!("dyode_static_arp_ok {}\n", u8::from(a))); + } + } + o +} + +/// '2026-10-28T09:14:02.123Z' -> Unix seconds. +fn parse_iso(s: &str) -> Option { + let d = crate::timefmt::Date::parse(s.get(..10)?)?; + let h: f64 = s.get(11..13)?.parse().ok()?; + let m: f64 = s.get(14..16)?.parse().ok()?; + let sec: f64 = s.get(17..).map(|x| x.trim_end_matches('Z'))?.parse().ok()?; + Some(d.days() as f64 * 86400.0 + h * 3600.0 + m * 60.0 + sec) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn iso_round_trip() { + let t = 1_793_150_042.25; + let s = crate::timefmt::iso_utc(t); + assert!((parse_iso(&s).unwrap() - t).abs() < 0.01, "{s}"); + } + + #[test] + fn label_escaping() { + assert_eq!(esc("a\"b\\c\nd"), "a\\\"b\\\\c\\nd"); + } +} diff --git a/src/status.rs b/src/status.rs new file mode 100644 index 0000000..7626a14 --- /dev/null +++ b/src/status.rs @@ -0,0 +1,96 @@ +//! The status channel: every `lidi.heartbeat` seconds each box writes its +//! status to /run/dyode, and the input box also sends it through the diode +//! on its own lidi endpoint (the one after the last module), signed like +//! everything else. The output box keeps the last one it received, so its +//! API can serve both boxes while nothing on the IT side ever reaches the +//! input box. + +use crate::config::Config; +use crate::envelope::{Body, Failure, Header, Inbound, Kind}; +use crate::transport::ModuleLink; +use std::time::Duration; + +/// A status message is a few KB; refuse anything absurd before reading it. +const MAX_STATUS: u64 = 1024 * 1024; + +/// How often status is taken and sent, and when the input box counts as +/// silent on the output box. +pub fn interval(cfg: &Config) -> f64 { + (cfg.lidi.heartbeat as f64).clamp(1.0, 60.0) +} + +pub fn stale_after(cfg: &Config) -> f64 { + interval(cfg) * 3.0 +} + +/// Input box: write the status file and send the status through the diode, +/// for ever. Send errors are logged once and retried at the next tick. +pub fn run_reporter(cfg: &Config, link: Option<&ModuleLink>) -> Result<(), String> { + let every = Duration::from_secs_f64(interval(cfg)); + let stale = stale_after(cfg); + let side = if link.is_some() { "in" } else { "out" }; + let mut file_err = crate::logging::FailureLog::new(format!( + "writing {}", + crate::stats::status_path(side).display() + )); + let mut send_err = crate::logging::FailureLog::new("sending status through the diode"); + loop { + match crate::stats::write_status_file(side, stale) { + Ok(()) => file_err.ok(), + Err(e) => file_err.fail(e), + } + if let Some(link) = link { + let body = serde_json::to_vec(&crate::stats::snapshot()).unwrap_or_default(); + match link.send_message(br#"{"kind":"status"}"#, &body) { + Ok(()) => send_err.ok(), + Err(e) => send_err.fail(e), + } + } + std::thread::sleep(every); + } +} + +/// Output box: the receiving end of the status channel. +pub struct StatusInbound(crate::logging::RefusalLog); + +impl StatusInbound { + pub fn new() -> Self { + Self(crate::logging::RefusalLog::new("dyode-status")) + } +} + +impl Default for StatusInbound { + fn default() -> Self { + Self::new() + } +} + +impl Inbound for StatusInbound { + fn module_name(&self) -> &str { + "dyode-status" + } + + fn open_body(&self, hdr: &Header) -> Result { + if hdr.kind != Kind::Message || hdr.body_len > MAX_STATUS { + return Err("not a status message".into()); + } + Ok(Body::Memory(Vec::with_capacity(hdr.body_len as usize))) + } + + fn deliver(&self, _hdr: Header, body: Body, _digest: [u8; 32]) { + let Body::Memory(b) = body else { return }; + match serde_json::from_slice::(&b) { + Ok(v) if v["side"] == "in" => crate::stats::set_peer(v), + Ok(_) => log::warn!("status message from something that is not an input box; ignored"), + Err(_) => log::warn!("undecodable status message; ignored"), + } + } + + fn failed(&self, _hdr: Option<&Header>, _body: Option, why: Failure) { + match why { + // The next one comes in a few seconds. + Failure::Incomplete { .. } => log::debug!("a status message was lost in the diode"), + other => self.0.refused(&other), + } + } +} diff --git a/src/supervisor.rs b/src/supervisor.rs index a37d8fc..893d343 100644 --- a/src/supervisor.rs +++ b/src/supervisor.rs @@ -23,8 +23,10 @@ pub fn spawn(name: &str, task: Task) { .spawn(move || { loop { log::info!("started module {name:?}"); + crate::stats::module_started(&name); let started = Instant::now(); let result = catch_unwind(AssertUnwindSafe(&*task)); + crate::stats::module_stopped(&name); match result { Ok(Ok(())) => log::error!("module {name:?} exited"), Ok(Err(e)) => log::error!("module {name:?} failed: {e}"), diff --git a/src/transport.rs b/src/transport.rs index 6541ce4..c4503d3 100644 --- a/src/transport.rs +++ b/src/transport.rs @@ -34,6 +34,21 @@ fn endpoint_label(index: u16) -> String { format!("unix:dyode-endpoint-{index}") } +/// The lidi endpoint that carries the input box's status: the one after +/// the last module, so both boxes agree on it from the same config.yaml. +pub fn status_endpoint(cfg: &Config) -> u16 { + cfg.modules.len() as u16 +} + +/// Identifies status messages in their envelopes, as a module tag does. +pub fn status_tag() -> [u8; 8] { + use sha2::{Digest, Sha256}; + let d = Sha256::digest(b"dyode-module-v1\0status\0dyode-status"); + let mut t = [0u8; 8]; + t.copy_from_slice(&d[..8]); + t +} + /// The lidi TOML for this config (the same text on both boxes). /// /// It is what DYODE feeds to lidi's own configuration parser, and what @@ -45,7 +60,9 @@ pub fn lidi_toml(cfg: &Config) -> String { let endpoints: Vec = cfg .modules .iter() - .map(|m| format!("\"{}\"", endpoint_label(m.index))) + .map(|m| m.index) + .chain(std::iter::once(status_endpoint(cfg))) + .map(|i| format!("\"{}\"", endpoint_label(i))) .collect(); let send_bind = l .send_bind @@ -146,11 +163,22 @@ impl ModuleLink { module: &crate::config::Module, key: Option>, mbps: Option, + ) -> Self { + Self::for_endpoint(uplink, module.index, module.tag(), key, mbps) + } + + /// A link for an endpoint that is not a module (the status channel). + pub fn for_endpoint( + uplink: Arc, + endpoint: u16, + module_tag: [u8; 8], + key: Option>, + mbps: Option, ) -> Self { Self { uplink, - endpoint: module.index, - module_tag: module.tag(), + endpoint, + module_tag, sealer: Arc::new(Sealer::new(key)), pacer: mbps.map(|m| Arc::new(TokenBucket::from_mbps(m))), } @@ -222,12 +250,22 @@ impl Lifecycle { key: Option>, inbound: Arc, ) { - let label = PathBuf::from(endpoint_label(module.index).trim_start_matches("unix:")); + self.register_endpoint(module.index, module.tag(), key, inbound); + } + + pub fn register_endpoint( + &mut self, + endpoint: u16, + module_tag: [u8; 8], + key: Option>, + inbound: Arc, + ) { + let label = PathBuf::from(endpoint_label(endpoint).trim_start_matches("unix:")); self.by_label.insert( label, Arc::new(Registration { - endpoint: module.index, - module_tag: module.tag(), + endpoint, + module_tag, inbound, verifier: Mutex::new(Verifier::new(key)), }), @@ -288,6 +326,7 @@ impl lidi_receive::ClientLifecycle for Lifecycle { ) -> Result<(), lidi_receive::Error> { if !ok { self.aborted.fetch_add(1, Ordering::Relaxed); + crate::stats::count("lidi_transfers_aborted"); } // Dropping the parser settles the transfer: delivered if complete // and genuine, reported otherwise. diff --git a/src/wizard/mod.rs b/src/wizard/mod.rs index f758d8f..eb1733d 100644 --- a/src/wizard/mod.rs +++ b/src/wizard/mod.rs @@ -52,6 +52,8 @@ enum Step { Baud, Modules, Key, + Api, + ApiAddr, Unit, Review, } @@ -181,6 +183,7 @@ impl Wizard<'_, U> { v.push(Modules); if self.d.variant == model::Variant::V1 { v.push(Key); + v.push(Api); } if self.env.write_unit { v.push(Unit); @@ -198,6 +201,7 @@ impl Wizard<'_, U> { fn major_of(s: Step) -> Step { match s { Step::ImportPath => Step::Start, + Step::ApiAddr => Step::Api, Step::IfaceManual => Step::Iface, Step::PeerIp | Step::PeerMac | Step::PeerIface => Step::Peer, Step::PortsManual => Step::Ports, @@ -251,6 +255,7 @@ impl Wizard<'_, U> { Step::Start }), Step::Unit if !self.env.write_unit => Some(Step::Review), + Step::Api | Step::ApiAddr if self.d.variant == Variant::V2 => Some(Step::Unit), Step::PeerMac if self.d.side == Side::Out => Some(Step::PeerIface), _ => None, } @@ -757,6 +762,80 @@ impl Wizard<'_, U> { } Step::Modules => self.modules(), Step::Key => self.key(), + Step::Api => { + let side = self.d.side.as_str(); + if self.d.api_listen.is_empty() { + if let Some((_, l)) = self.d.api_imported.iter().find(|(s, _)| s == side) { + self.d.api_listen = l.clone(); + } + } + let opts = [ + Opt::new("Off", "no API on this box"), + Opt::new("On", "HTTPS on the management network card, with tokens"), + ]; + let body = vec![ + "The local API serves this box's status and Prometheus metrics, for Prometheus or Zabbix. \ + On the output box it covers the input box too, from the status it sends through the diode." + .into(), + "It listens on the management network card, never the diode card. A TLS certificate and a \ + first token are created when you write the configuration." + .into(), + ]; + let def = usize::from(!self.d.api_listen.is_empty()); + self.ui.choose("Local API", &body, &opts, def).map(|i| { + if i == 0 { + self.d.api_listen.clear(); + Step::Unit + } else { + Step::ApiAddr + } + }) + } + Step::ApiAddr => { + let me = self.d.my_iface().to_string(); + let my_ip = self.d.my_ip().to_string(); + let def = if self.d.api_listen.is_empty() { + env.interfaces + .iter() + .filter(|i| i.name != me) + .find_map(|i| { + i.ipv4 + .as_deref() + .map(|a| a.split('/').next().unwrap_or(a).to_string()) + }) + .map_or_else(String::new, |a| format!("{a}:8443")) + } else { + self.d.api_listen.clone() + }; + let check = move |s: &str| -> Result<(), String> { + let a: std::net::SocketAddr = s + .parse() + .map_err(|_| "address:port, like 192.168.50.4:8443".to_string())?; + if a.ip().is_unspecified() { + return Err( + "one address, not 0.0.0.0: that would include the diode card".into(), + ); + } + if a.ip().to_string() == my_ip { + return Err( + "that is this box's diode address; use the management card's".into(), + ); + } + Ok(()) + }; + let body = vec![ + format!( + "The address and port to listen on. This box's diode card is {me}; the API must not use it." + ), + "Prometheus and Zabbix connect here.".into(), + ]; + self.ui + .text("Local API address", &body, "Address:port", &def, &check) + .map(|v| { + self.d.api_listen = v; + Step::Unit + }) + } Step::Unit => { let unit = crate::setup::unit_name(self.d.side); let body = vec![ @@ -1183,7 +1262,7 @@ impl Wizard<'_, U> { ]; self.ui.choose("Message key", &body, &opts, def).map(|i| { self.d.key = plans[i]; - Step::Unit + Step::Api }) } @@ -1229,6 +1308,13 @@ impl Wizard<'_, U> { d.serial_device, d.baudrate ))); } + if d.variant == Variant::V1 { + lines.push(Line::Text(if d.api_listen.is_empty() { + "API: off".to_string() + } else { + format!("API: https://{}", d.api_listen) + })); + } for (i, m) in d.modules.iter().enumerate() { lines.push(Line::Text(format!( "module {i}: {} ({}) {}", @@ -1358,7 +1444,7 @@ mod tests { const FULL: &str = "enter enter enter enter ctrl-u 'Line 3' enter enter enter enter enter \ 'b8:27:eb:b1:ff:ab' enter enter enter enter enter enter enter enter enter \ down down enter '5' enter enter \ - enter enter enter enter"; + enter enter enter enter enter"; #[test] fn full_run_writes_a_config_dyode_accepts() { @@ -1378,6 +1464,41 @@ mod tests { assert!(dir.path().join("dyode.key").is_file()); } + #[test] + fn api_on_writes_listen_cert_and_token() { + if std::process::Command::new("openssl") + .arg("version") + .output() + .is_err() + { + return; + } + let dir = crate::testutil::TempDir::new(); + // As FULL, but "On" at the API screen, then an address on wlan0's + // network (the demo box's management card). + let script = "enter enter enter enter ctrl-u 'Line 3' enter enter enter enter enter \ + 'b8:27:eb:b1:ff:ab' enter enter enter enter enter enter enter enter enter \ + enter enter enter down enter ctrl-u '192.168.1.23:8443' enter enter enter enter"; + let (out, frames) = run_script(script, dir.path(), Preset::default()); + let Outcome::Written { done, .. } = out else { + panic!("did not finish: {}", frames.last().unwrap()) + }; + let cfg = crate::config::load(&dir.path().join("config.yaml")).unwrap(); + let api = cfg.api.input.expect("api.in"); + assert_eq!(api.listen.to_string(), "192.168.1.23:8443"); + assert!(dir.path().join("api.crt").is_file() && dir.path().join("api.key").is_file()); + let line = done + .iter() + .find(|l| l.contains("shown only now")) + .expect("token line"); + let token = line.rsplit(' ').next().unwrap(); + let tokens = crate::apitoken::list(&dir.path().join("api-tokens")).unwrap(); + assert_eq!( + crate::apitoken::verify(&tokens, token).unwrap().name, + "monitoring" + ); + } + #[test] fn esc_goes_back_and_bad_input_is_refused() { let dir = crate::testutil::TempDir::new(); @@ -1430,7 +1551,8 @@ mod tests { env.dry_run = false; env.write_unit = false; // v1, out side: the out box's MAC comes from its own card. - let answers = "\n1\n2\n1\nPiped\n1\n10.0.1.2\n\n\n\n\n\n1\n1\n\n/srv/a\n/srv/b\n\n\n1\n\n"; + let answers = + "\n1\n2\n1\nPiped\n1\n10.0.1.2\n\n\n\n\n\n1\n1\n\n/srv/a\n/srv/b\n\n\n1\n\n\n"; let mut out = Vec::new(); let res = run( &mut ui::PlainUi::new(answers.as_bytes(), &mut out), diff --git a/src/wizard/model.rs b/src/wizard/model.rs index aca31fc..bb26230 100644 --- a/src/wizard/model.rs +++ b/src/wizard/model.rs @@ -888,6 +888,10 @@ pub struct Draft { pub modules: Vec, pub key: KeyPlan, pub write_unit: bool, + /// This box's API address ("10.20.0.5:8443"); empty = no API. + pub api_listen: String, + /// api.in.listen / api.out.listen as imported. + pub api_imported: Vec<(String, String)>, /// The imported config.yaml, as read: kept underneath the answers. pub base: Mapping, pub imported_from: Option, @@ -911,6 +915,8 @@ impl Draft { modules: Vec::new(), key: KeyPlan::Later, write_unit: true, + api_listen: String::new(), + api_imported: Vec::new(), base: Mapping::new(), imported_from: None, } @@ -976,6 +982,18 @@ impl Draft { }); } } + if let Some(Value::Mapping(api)) = raw.get("api") { + // Remembered for both sides; the wizard shows the one for this box. + d.api_imported = ["in", "out"] + .iter() + .filter_map(|s| { + api.get(*s) + .and_then(Value::as_mapping) + .and_then(|m| m.get("listen")) + .map(|v| ((*s).to_string(), scalar_text(v))) + }) + .collect(); + } d.base = raw; d.imported_from = Some(path.to_path_buf()); Ok(d) @@ -1102,6 +1120,28 @@ impl Draft { let mut serial = sub(&mut doc, "serial"); let logging = sub(&mut doc, "logging"); let auth = sub(&mut doc, "auth"); + let mut api = sub(&mut doc, "api"); + if self.variant == Variant::V1 { + let side = self.side.as_str(); + if self.api_listen.is_empty() { + api.remove(side); + } else { + // Keep options the wizard does not ask about (tokens, max_clients). + let mut mine = api + .get(side) + .and_then(Value::as_mapping) + .cloned() + .unwrap_or_default(); + set(&mut mine, "listen", self.api_listen.clone().into()); + if !mine.contains_key("tls") { + let mut tls = Mapping::new(); + set(&mut tls, "cert", "api.crt".into()); + set(&mut tls, "key", "api.key".into()); + set(&mut mine, "tls", tls.into()); + } + api.insert(side.into(), mine.into()); + } + } let _ = sub(&mut doc, "modules"); // Fixed order, the same as config.example.yaml; anything else the // imported file had stays after it. @@ -1128,6 +1168,9 @@ impl Draft { if !auth.is_empty() { out.insert("auth".into(), auth.into()); } + if !api.is_empty() { + out.insert("api".into(), api.into()); + } for (k, v) in rest { if !out.contains_key(&k) { out.insert(k, v); @@ -1290,6 +1333,17 @@ impl Draft { KeyPlan::Later => {} } } + if self.variant == Variant::V1 && !self.api_listen.is_empty() { + if !env.etc.join("api.crt").exists() { + p.push(format!( + "create a TLS certificate {} for the API", + env.etc.join("api.crt").display() + )); + } + if crate::apitoken::list(&env.etc.join("api-tokens")).map_or(true, |t| t.is_empty()) { + p.push("create an API token \"monitoring\" (shown once, at the end)".into()); + } + } if self.write_unit && env.write_unit { p.push(format!( "write /etc/systemd/system/{}", @@ -1372,6 +1426,34 @@ pub fn apply(d: &Draft, env: &Env) -> Result, String> { KeyPlan::Keep | KeyPlan::Later => {} } } + if d.variant == Variant::V1 && !d.api_listen.is_empty() { + if !env.etc.join("api.crt").exists() { + let ip = d + .api_listen + .rsplit_once(':') + .map(|(h, _)| h.trim_matches(['[', ']']).to_string()); + let host = std::fs::read_to_string("/etc/hostname") + .map(|s| s.trim().to_string()) + .ok() + .filter(|s| !s.is_empty()) + .unwrap_or_else(|| format!("dyode-{}", d.side.as_str())); + let c = crate::setup::make_api_cert( + &env.etc, + &host, + &ip.into_iter().collect::>(), + 825, + false, + )?; + done.push(format!("created {} ({})", c.cert.display(), c.fingerprint)); + } + let tokens = env.etc.join("api-tokens"); + if crate::apitoken::list(&tokens).map_or(true, |t| t.is_empty()) { + let t = crate::apitoken::add(&tokens, "monitoring", &["read".into()])?; + done.push(format!( + "API token \"monitoring\" (read), shown only now: {t}" + )); + } + } if d.write_unit && env.write_unit { let cmd = match (d.variant, d.side) { (Variant::V1, Side::In) => "in", diff --git a/tests/api.rs b/tests/api.rs new file mode 100644 index 0000000..9a3f4fa --- /dev/null +++ b/tests/api.rs @@ -0,0 +1,257 @@ +//! The status channel and the API end to end: the input box's status goes +//! through a real embedded lidi engine over loopback, and the output box's +//! API serves it over TLS to a token holder. +#![cfg(feature = "api")] + +use dyode::config::{self, Side}; +use dyode::testutil::TempDir; +use dyode::transport::{self, Lifecycle, ModuleLink, Uplink}; +use rustls::pki_types::pem::PemObject; +use rustls::pki_types::{CertificateDer, ServerName}; +use std::io::{Read, Write}; +use std::net::{TcpListener, TcpStream}; +use std::path::Path; +use std::sync::Arc; +use std::time::{Duration, Instant}; + +fn wait_for(what: &str, secs: u64, mut ok: impl FnMut() -> bool) { + let until = Instant::now() + Duration::from_secs(secs); + while Instant::now() < until { + if ok() { + return; + } + std::thread::sleep(Duration::from_millis(50)); + } + panic!("timed out waiting for {what}"); +} + +/// A self-signed certificate for 127.0.0.1, or None without openssl. +fn make_cert(dir: &Path) -> Option<()> { + let ok = std::process::Command::new("openssl") + .args([ + "req", + "-x509", + "-newkey", + "ec", + "-pkeyopt", + "ec_paramgen_curve:P-256", + "-nodes", + ]) + .arg("-keyout") + .arg(dir.join("api.key")) + .arg("-out") + .arg(dir.join("api.crt")) + .args([ + "-days", + "2", + "-subj", + "/CN=test", + "-addext", + "subjectAltName=IP:127.0.0.1", + ]) + .args([ + "-addext", + "basicConstraints=critical,CA:FALSE", + "-addext", + "keyUsage=critical,digitalSignature", + "-addext", + "extendedKeyUsage=serverAuth", + ]) + .output() + .ok()? + .status + .success(); + ok.then_some(()) +} + +fn get(port: u16, cert: &Path, path: &str, token: Option<&str>) -> (u16, String) { + let mut roots = rustls::RootCertStore::empty(); + for c in CertificateDer::pem_file_iter(cert).unwrap() { + roots.add(c.unwrap()).unwrap(); + } + let provider = Arc::new(rustls::crypto::ring::default_provider()); + let cfg = rustls::ClientConfig::builder_with_provider(provider) + .with_safe_default_protocol_versions() + .unwrap() + .with_root_certificates(roots) + .with_no_client_auth(); + let conn = + rustls::ClientConnection::new(Arc::new(cfg), ServerName::try_from("127.0.0.1").unwrap()) + .unwrap(); + let sock = TcpStream::connect(("127.0.0.1", port)).unwrap(); + let mut tls = rustls::StreamOwned::new(conn, sock); + let auth = token.map_or(String::new(), |t| format!("Authorization: Bearer {t}\r\n")); + write!(tls, "GET {path} HTTP/1.1\r\nHost: x\r\n{auth}\r\n").unwrap(); + let mut out = Vec::new(); + let _ = tls.read_to_end(&mut out); + let text = String::from_utf8_lossy(&out).to_string(); + let code = text.get(9..12).and_then(|c| c.parse().ok()).unwrap_or(0); + let body = text + .split_once("\r\n\r\n") + .map(|(_, b)| b.to_string()) + .unwrap_or_default(); + (code, body) +} + +#[test] +fn input_status_reaches_the_output_api() { + let d = TempDir::new(); + if make_cert(d.path()).is_none() { + eprintln!("openssl not available: skipped"); + return; + } + let port = 20000 + (dyode::auth::random_u32() % 20000) as u16; + let api_port = { + let l = TcpListener::bind("127.0.0.1:0").unwrap(); + l.local_addr().unwrap().port() + }; + let yaml = format!( + "dyode_in: {{ip: 127.0.0.2, interface: lo}}\n\ + dyode_out: {{ip: 127.0.0.3, interface: lo}}\n\ + lidi: {{ports: [{port}], heartbeat: 1}}\n\ + logging: {{dir: ''}}\n\ + api:\n out: {{listen: '127.0.0.1:{api_port}', tls: {{cert: api.crt, key: api.key}}}}\n\ + modules:\n files: {{type: folder, in: {d}/in, out: {d}/out}}\n", + d = d.path().display() + ); + let mut cfg = config::parse(&yaml, &d.path().join("config.yaml"), d.path()).unwrap(); + // lidi over loopback: both ends on 127.0.0.1. + cfg.network.in_ip = "127.0.0.1".parse().unwrap(); + cfg.network.out_ip = "127.0.0.1".parse().unwrap(); + let api = cfg.api.output.clone().expect("api.out"); + assert_eq!( + cfg.max_clients(), + 4, + "1 module + summary + heartbeat + status" + ); + let key = Some(vec![9u8; 32]); + dyode::stats::init(&cfg, "out"); + dyode::stats::module_started("files"); + + // Output side: the folder module and the status channel. + let config::ModuleKind::Folder(fc) = &cfg.modules[0].kind else { + panic!() + }; + let mut lc = Lifecycle::new(); + lc.register( + &cfg.modules[0], + key.clone(), + Arc::new(dyode::folder::FolderInbound::new(&cfg.modules[0], fc).unwrap()), + ); + lc.register_endpoint( + transport::status_endpoint(&cfg), + transport::status_tag(), + key.clone(), + Arc::new(dyode::status::StatusInbound::new()), + ); + let receiver: &'static transport::LidiReceiver = + Box::leak(Box::new(transport::new_receiver(&cfg, lc).unwrap())); + std::thread::spawn(move || { + std::thread::scope(|s| { + if let Err(e) = receiver.start(s) { + panic!("lidi receiver: {e}"); + } + loop { + std::thread::park(); + } + }) + }); + let sender: &'static transport::LidiSender = + Box::leak(Box::new(transport::new_sender(&cfg).unwrap())); + std::thread::spawn(move || { + std::thread::scope(|s| { + if let Err(e) = sender.start(s) { + panic!("lidi sender: {e}"); + } + loop { + std::thread::park(); + } + }) + }); + std::thread::sleep(Duration::from_millis(300)); + + // The input box's status, as the reporter would send it. + let uplink = Arc::new(Uplink::new(sender, &cfg)); + let link = ModuleLink::for_endpoint( + uplink, + transport::status_endpoint(&cfg), + transport::status_tag(), + key.clone(), + None, + ); + let mut st = dyode::stats::snapshot(); + st["side"] = "in".into(); + st["static_arp_ok"] = true.into(); + link.send_message(br#"{"kind":"status"}"#, &serde_json::to_vec(&st).unwrap()) + .unwrap(); + wait_for("the status message", 10, || dyode::stats::peer().is_some()); + + // A forged status (other key) is refused and changes nothing. + let before = dyode::stats::peer().unwrap().received; + let uplink2 = Arc::new(Uplink::new(sender, &cfg)); + let forged = ModuleLink::for_endpoint( + uplink2, + transport::status_endpoint(&cfg), + transport::status_tag(), + Some(vec![1u8; 32]), + None, + ); + forged + .send_message(b"", br#"{"side":"in","version":"666"}"#) + .unwrap(); + std::thread::sleep(Duration::from_millis(500)); + assert_eq!(dyode::stats::peer().unwrap().received, before); + + // The API, over TLS. + let token = dyode::apitoken::add(&api.tokens, "prometheus", &["read".into()]).unwrap(); + let (c, k) = api.tls.clone().unwrap(); + let tls = dyode::api::tls_config(&c, &k).unwrap(); + let listener = TcpListener::bind(api.listen).unwrap(); + let cfg = Arc::new(cfg); + let (cfg2, api2) = (Arc::clone(&cfg), api.clone()); + std::thread::spawn(move || { + dyode::api::serve_listener(listener, Some(tls), cfg2, Side::Out, api2) + }); + std::thread::sleep(Duration::from_millis(100)); + let cert = d.path().join("api.crt"); + + let (code, body) = get(api_port, &cert, "/v1/health", None); + assert_eq!(code, 200, "{body}"); + assert!(body.contains("\"side\": \"out\""), "{body}"); + + let (code, _) = get(api_port, &cert, "/v1/status", None); + assert_eq!(code, 401); + let (code, _) = get(api_port, &cert, "/v1/status", Some("dyode_wrong")); + assert_eq!(code, 401); + + let (code, body) = get(api_port, &cert, "/v1/status", Some(&token)); + assert_eq!(code, 200, "{body}"); + let v: serde_json::Value = serde_json::from_str(&body).unwrap(); + assert_eq!(v["boxes"]["in"]["side"], "in"); + assert_eq!(v["boxes"]["out"]["side"], "out"); + assert!(v["boxes"]["in"]["status_age_s"].as_f64().unwrap() < 10.0); + assert_eq!(v["warnings"].as_array().unwrap().len(), 0, "{body}"); + + let (code, body) = get(api_port, &cert, "/metrics", Some(&token)); + assert_eq!(code, 200); + for want in [ + "dyode_status_age_seconds{side=\"in\"}", + "dyode_config_match 1", + "dyode_module_up{side=\"out\",module=\"files\",type=\"folder\"} 1", + "dyode_static_arp_ok 1", + "dyode_counter_total{side=\"out\",counter=\"api_refused\"} 2", + ] { + assert!(body.contains(want), "missing {want} in\n{body}"); + } + + let (code, body) = get(api_port, &cert, "/v1/check", Some(&token)); + assert_eq!(code, 200, "{body}"); + assert!(body.contains("\"notes\""), "{body}"); + + let (code, body) = get(api_port, &cert, "/v1/openapi.json", None); + assert_eq!(code, 200); + assert!(body.contains("\"openapi\": \"3.1.0\"")); + + let (code, _) = get(api_port, &cert, "/v1/nothing", Some(&token)); + assert_eq!(code, 404); +} diff --git a/tests/loopback.rs b/tests/loopback.rs index 12257ba..1b6401b 100644 --- a/tests/loopback.rs +++ b/tests/loopback.rs @@ -175,7 +175,11 @@ fn folder_parallel_files_through_lidi() { d = d.path().display() ); let cfg = config::parse(&yaml, Path::new("config.yaml"), d.path()).unwrap(); - assert_eq!(cfg.max_clients(), 6, "4 files + summary + heartbeat"); + assert_eq!( + cfg.max_clients(), + 7, + "4 files + summary + heartbeat + status" + ); let key = Some(vec![7u8; 32]); let ModuleKind::Folder(fc) = &cfg.modules[0].kind else { panic!() diff --git a/tools/build_debs.sh b/tools/build_debs.sh index 0fee6e5..51de6ce 100755 --- a/tools/build_debs.sh +++ b/tools/build_debs.sh @@ -9,6 +9,7 @@ # DYODE itself is one self-contained binary and needs no OS packages beyond: # nftables the output box's diode-port firewall (install.sh) # iproute2 'ip neigh', for the input box's static ARP entry +# openssl the local API's TLS certificate (dyode api-cert) # plus the optional services for serving received files that # `install.sh --with ssh,nfs,smb` installs. # @@ -37,7 +38,7 @@ ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" OUT_BASE="${OUT_BASE:-$ROOT/packaging/debs}" TARGETS="${TARGETS:-ubuntu-24.04/amd64 ubuntu-24.04/arm64 ubuntu-26.04/amd64 ubuntu-26.04/arm64 debian-12/amd64 debian-12/arm64 debian-13/amd64 debian-13/arm64}" # Keep in step with core_pkgs()/service_pkgs() in install.sh. -CORE_PKGS="nftables iproute2" +CORE_PKGS="nftables iproute2 openssl" SERVICE_PKGS="openssh-server openssh-sftp-server openssh-client nfs-common nfs-kernel-server samba cifs-utils smbclient" PKGS="$CORE_PKGS $SERVICE_PKGS"