Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
10 changes: 8 additions & 2 deletions Cargo.toml
Original file line number Diff line number Diff line change
@@ -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"
Expand All @@ -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).
Expand All @@ -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
Expand Down
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
14 changes: 14 additions & 0 deletions config.example.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
139 changes: 139 additions & 0 deletions docs/API.md
Original file line number Diff line number Diff line change
@@ -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 <token>`. 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-<side>.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).
Loading
Loading