Architecture
Where dflux Runner sits, what the binary contains, and how the two front-ends (CLI one-shot vs control-plane agent) relate.
System shape
dflux Runner sits between a CI agent (or an engineer at a terminal) and one or more 5G/4G NFs under test. It carries no production traffic — it is a tester's instrument.
The runner is a stateless execution engine. Durable state (flow/suite/env catalog, report history, schedules, subscriber pool) lives in the control plane when you run agents continuously. The CLI path never needs a control plane.
The receiver-side server uspace / server dpdk terminates GTP-U traffic on the data network so user-plane tests can close the loop without an external traffic terminator.
CLI vs agent
Two front-ends, same engine, same FSM dispatcher, same protocol stacks, same JSON report shape.
| CLI one-shot | Agent mode | |
|---|---|---|
| Lifecycle | One-shot process | Long-lived agent |
| Trigger | d3x-run run-flow … / run-suite … | d3x-run daemon -console <addr> |
| Reads environment from | YAML file (-c <file>) | Job payload from the control plane |
| Reports | stdout / -output-file (json, junit, text) | Streamed back to the control plane |
| Persistence in runner | None (stateless) | None between jobs (stateless) |
| Auth | None | Join token to the control plane |
| Scheduler / catalog | No | Owned by the control plane |
| CI shape | Exit code + JSON/JUnit | Jobs dispatched to free agents |
CI usually wants the CLI — deterministic, no infra. Continuously running test planes attach agents to the control plane for catalog, scheduling, and report history.
See Agent mode for startup flags and the control-plane handshake.
Single-binary nature
The binary embeds:
- The full engine and protocol stacks (NGAP, Diameter, SBI from 3GPP OpenAPI specs, PFCP, REST)
- The DPDK user-plane traffic generator (extracted to a temp dir on first use when used)
- Default Diameter dictionaries, NAS codec, and SCTP/UDP/TCP transport plumbing
- The gRPC agent that dials the control plane (daemon mode)
There are no shared libraries to ship. Drop the static binary on the host and run.
What runs in agent mode
When d3x-run daemon starts, it:
- Dials the control plane at
-console host:port(outbound only — NAT-friendly) - Registers with an agent id (default: hostname) and optional scheduler labels
- Waits for jobs over a reverse-tunnel stream
- Executes each job entirely in memory (flow/suite + environment + subscribers inline)
- Streams events and the final report back, then holds nothing
The engine itself is the same code as the CLI. The difference is lifecycle (one-shot vs continuous) and where inputs come from (local YAML vs job payload).
What stays out
dflux Runner is intentionally not a 3GPP simulator. It does not implement the full state machines of any NF — it implements the FSM model the test author declares. That is the point: deterministic test flows beat realistic simulator state for conformance and load work.
If you need a working AMF, run an AMF; the shipped registration_amf flow is a wiring stub, not a replacement.
Where to go next
- Quickstart — install, license, and run the registration flow.
- Agent mode — attach
d3x-run daemonto the control plane. - Flows — the FSM model the engine executes.