Docs / dflux Runner
ContactGet started

Managing subscribers

A subscriber is one UE identity — SUPI, K, OPC, SQN, SNN, plus ciphering and integrity algorithms. NGAP/NAS authentication consumes these credentials, and Diameter S6a / Gx flows reuse the same set. This guide is the recipe for working with subscribers on the CLI and in agent mode. For the model, see the concept page.

Note
For how subscribers map to UEs, read Subscribers. This page is the practical recipe.

Two ways on the CLI

The runner CLI is stateless. Subscribers for a one-shot run never go through a local database:

  1. -s / -subscribers <file> — parse a YAML file into an in-memory slice for this process; each UE takes the next entry.
  2. -gen-subscriber — synthesize a fresh subscriber per UE entirely in memory (no file). Use when the AMF doesn't validate auth (lab AMFs / dev proxies).

Offline helper: d3x-run subscriber generate writes random credentials to YAML so you can commit them or feed a core network's provisioning UI. That subcommand only generates a file — it does not talk to Open5GS or to a runner DB.

Durable subscriber pools (shared inventory across agents, import APIs, scheduling) live in the control plane. Agent-mode jobs receive an inline subscriber set from the console; the agent holds nothing between jobs. See Agent mode.

YAML format

config/subscribers.yaml (shipped defaults use PLMN 901/70 to match lab.yaml):

YAML

SUPI format: imsi-<MCC>-<MNC>-<MSIN>. MCC is 3 digits, MNC is 2–3 digits, MSIN is digits-only. key and opc are 32 hex chars; sqn is 12 hex.

config: provides defaults applied to subscriber rows that don't override.

subscriber generate

Synthesize random credentials to YAML (offline; the only subscriber subcommand):

Bash
FlagDefaultPurpose
-count <n>10Number of subscribers to generate
-mcc <mcc>901Mobile Country Code
-mnc <mnc>070Mobile Network Code
-start-msin <n>1First MSIN; subsequent ones increment
-ciphering <alg>NEA0NEA0 / NEA1 / NEA2 / NEA3
-integrity <alg>NIA2NIA0 / NIA1 / NIA2 / NIA3
-o <path>subscribers.yamlOutput path

The MSIN sequence is deterministic — it counts up from -start-msin, so the same flags always produce the same SUPI/IMSI set. K and OPC are different: each is 16 fresh random bytes per row, generated on every invocation. Re-running with identical flags yields the same identities but new keys, so generate once and commit the output if you need a stable credential set.

Provision the generated rows into your core (Open5GS WebUI, HSS, UDM, …) with that product's tools — d3x-run does not ship a subscriber provision command.

-gen-subscriber

Skip the YAML file entirely:

Bash

The engine synthesizes a fresh subscriber per UE in memory. No file I/O, no pool acquire. This works only when the AMF doesn't actually validate the auth challenge — lab AMFs, dev proxies, or any FSM that fails before reaching authentication. Real AMFs reject auth attempts because they have no row for the SUPI.

In-memory set vs console pool

CLI one-shots (run-flow / run-suite):

  • With -s, the process loads the YAML into a process-local slice and hands entries out in order. There is no local database and no shared lock across processes.
  • When the slice is exhausted (more UEs than rows), further UEs fail fast rather than blocking on a wait queue.
  • With -gen-subscriber, each UE gets a synthetic row; the empty-set guard is skipped.
  • If neither -s nor -gen-subscriber is set, the run fails with no subscribers configured.

Agent mode (d3x-run daemon -console …):

  • The control plane owns the durable subscriber inventory and carves a disjoint set into each job.
  • The agent materializes that set in memory, runs the job, streams the report back, and drops state.

Prometheus runner_* metrics (including bus instrumentation) exist only while a process with -metrics-port is running — see Metrics.

Troubleshooting

no subscribers configured — add at least one subscriber before executing — neither -s nor -gen-subscriber was set. Pass a subscribers file or enable generation.

Slice exhausted under load — -repetitions (or suite step workload) exceeds the number of rows in the YAML. Load more subscribers or reduce the workload, or use -gen-subscriber when auth isn't validated.

SUPI rejected at auth — the K/OPC in the YAML don't match what's provisioned in the AMF/HSS. Re-provision or regenerate; the values must match exactly.

Synthetic-IMSI Diameter requests — when a subscriber has no imsi field, the Diameter S6a / Gx enrichers fall back to a UE-stable synthetic identifier (used for User-Name on S6a and Subscription-Id-Data on Gx) so load tests can run without populating IMSI per row.

Where to go next