Quickstart

By the end of this guide you will have installed dflux Runner, 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 sample lab.yaml below). 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 from dflux. Community builds need no license file to start. If you have a signed commercial license, keep that file too — see Licensing.

Prerequisites

A Linux host (amd64 or arm64). dflux Runner drives NGAP and Diameter over kernel SCTP, which is Linux-only.
git — to fetch the public flow templates.
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 — License (optional)

Unsigned community builds are fail-open: no license file is required. Skip this step unless dflux gave you a signed commercial license.

If you have a signed file, resolution order (first match wins):

D3X_LICENSE_FILE — explicit path override when set
$HOME/.dflux/d3x.lic — per-user compound license, when present
$HOME/.dflux/runner.lic — per-user product file, when present
/etc/dflux/d3x.lic — system compound license, when present
/etc/dflux/runner.lic — system product fallback

Bash

To keep the file elsewhere:

Bash

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). Clone that repo only:

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 — Sample environment and subscribers

Write these two files next to your templates clone. They are the lab environment and a single subscriber — nothing else is required.

lab.yaml:

YAML

subscribers.yaml:

YAML

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 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.