Docs / dflux Runner
ContactGet started

Quickstart

By the end of this guide you will have installed dflux Runner, activated your license, run the canonical registration flow against an AMF you reach over the lab network, and captured a machine-readable report. About 10 minutes start to finish, assuming you already have an AMF reachable over SCTP (NGAP, 3GPP TS 38.413).

If you want the conceptual model before the hands-on walk-through, read the architecture overview first. The rest of this page assumes you're happy to learn by doing.

This guide assumes a lab AMF at 192.168.1.139:38412 with PLMN MCC=901, MNC=70 (the defaults in the shipped lab.yaml). Substitute your own AMF address and PLMN wherever they appear.

What dflux gives you
dflux Runner ships as a single prebuilt binary (d3x-run). You'll have received a download link and a license file from d3x — keep both handy. The download link is time-limited; the license file is yours to keep.

Prerequisites

  • A Linux host (amd64 or arm64). dflux Runner drives NGAP and Diameter over kernel SCTP, which is Linux-only.
  • git — to fetch the monorepo (flow templates and sample configs live there).
  • An AMF reachable on SCTP port 38412 — Open5GS, free5GC, or any vendor AMF that admits the gNB defined in lab.yaml.
  • The PLMN MCC=901, MNC=70 provisioned on that AMF, or a lab.yaml you've edited to match your AMF's PLMN.

Step 1 — Download and install

Download the release archive using the link dflux gave you, then verify and unpack it:

Bash

The archive contains the single d3x-run binary. Install it onto your PATH:

Bash

Confirm the binary runs. The same entrypoint is also invocable as d3x run when the d3x wrapper is on your PATH:

Bash

Step 2 — Activate your license

dflux Runner resolves its license file in this order (first match wins):

  1. D3X_LICENSE_FILE — explicit path override when set
  2. $HOME/.dflux/d3x.lic — per-user compound license, when present
  3. $HOME/.dflux/runner.lic — per-user product file, when present
  4. /etc/dflux/d3x.lic — system compound license (grants every product on the host), when present
  5. /etc/dflux/runner.lic — system product fallback

Drop the license file dflux gave you at a product path (or use a compound file if you have one):

Bash

To keep the file elsewhere:

Bash
License is fail-closed
Licensed entrypoints (run-flow, run-suite, daemon, check, …) refuse to start without a valid license. Inside the grace window after expiry, startup still proceeds but prints a banner warning. Verification is fully offline; nothing phones home. See Licensing for the full policy.

Step 3 — Get the flow templates

Flow and suite YAML live in the public d3x-templates repo (Apache-2.0). Sample environments and subscriber files stay in the d3x monorepo under runner/config. Clone both:

Bash

When you run a flow, d3x-run walks -templates recursively and loads every kind: flow / kind: suite YAML into an in-memory catalog for that process. You'll see a line like:

Code

Look for the flow named registration under the gNB templates — that's the one you'll run. For the full breakdown, see the flow and suite catalog.

Step 4 — Point at your AMF

The shipped runner/config/lab.yaml declares one gNB (GNBENF) on PLMN 901/70 dialing one AMF at 192.168.1.139:38412 over SCTP. If your AMF lives elsewhere, edit the peers: block (and PLMN fields) now:

Bash

Step 5 — Check transport connectivity

Bash

Expected output (one row per gNB→AMF pair):

Code

If you see FAIL, your AMF isn't reachable on SCTP — fix that before continuing. The error column shows whether the SCTP handshake or the NGSetup procedure failed.

Step 6 — Run the registration flow

Bash

-trace prints every TX/RX hex dump plus a JSON trace of each FSM step. Strip it for production. -s loads subscribers into an in-memory set for this process only — nothing is written to a local database.

Expected tail:

Code

Step 7 — Re-run as a small load test

Bash

10 UEs at 5 starts/s. Each UE takes the next subscriber from the in-memory set. The summary at the end aggregates per-flow latency.

Step 8 — Capture a report

dflux Runner is stateless: the CLI does not write a local SQLite catalog and has no report list command. Capture the run you just executed with -output / -output-file:

Bash

Formats: text (default human summary), json, or junit. With -output-file, the structured report goes to the file and the human summary still prints to stdout.

run-flow exits on the flow verdict (the same answer printed at the top of the report), not merely on whether in-flow checks passed:

  • 0 — verdict pass
  • 1 — verdict fail, or the run errored (the report is still written first so CI can ingest it)
  • 2 — usage error (bad flags or an unusable -output format)
  • 3 — verdict unsupported: the core answered coherently that it does not implement the scenario. Not a failure; a third outcome so a gate can treat missing features as skip rather than red.

What you did

You've installed and licensed dflux Runner, validated SCTP and NGSetup against a real AMF, run a 5G UE registration with full authentication and security activation, and written a JSON report for the run — all without a local database.

Where to go next

For a continuous on-prem test plane, attach Runner as an agent to the control plane — see Agent mode. From there, the rest of the surface is two more concepts: describing different procedures with your own flows, and composing them into suites.