Subscribers

A subscriber is a reusable UE identity — SUPI, key material, sequence number — that flows draw from a CLI file, in-memory synthesis, or the console pool, across NGAP, Diameter S6a, and SBI.

What a subscriber is

A subscriber is a first-class object in the model: one stored UE identity, plus the cryptographic material a core needs to authenticate it. It is not tied to a single flow or protocol. The same subscriber row drives a 5G registration over NGAP, an authentication-information request over Diameter S6a, and a Nudm or Nausf call over SBI. You define subscribers once; flows reference them at run time.

This separation matters because most procedures need a real identity to be meaningful. A registration flow has to present a SUPI the simulated core recognizes; an authentication exchange has to derive the right response from the right key and sequence number. Keeping that identity in one place — instead of baking it into each flow — lets you point the same flow catalog at different identity sets without editing a line of YAML.

The fields

A subscriber carries three groups of fields: identity, authentication material, and serving-network context. Here is a single entry as it appears in a subscribers YAML file.

YAML

Identity

The identity fields name the UE on the wire.

supi — the Subscription Permanent Identifier, in IMSI form imsi-MCC-MNC-MSIN. This is the only identity field you must supply; the engine parses it to derive MCC, MNC, MSIN, and IMSI. Anything else is rejected with an expected imsi-MCC-MNC-MSIN error.
imsi — the 15-digit IMSI (MCC + MNC + MSIN). Diameter flows read this directly for the User-Name AVP on S6a; when an entry carries no IMSI, the engine falls back to a UE-stable synthetic identifier so load runs still produce a unique identity per UE.
MCC, MNC, MSIN, SUCI, and IMSISV are also part of the model. MCC, MNC, and MSIN are derived from the SUPI; the rest are optional.

Authentication material

These fields let the engine answer an authentication challenge the way a real UE would.

key — the permanent subscriber key K, a 32-character hex string. Stored on the model as ki. Required.
opc — the operator-variant algorithm configuration field for Milenage, also 32-character hex. Required. (If your provisioning uses the operator key OP instead of the derived OPc, the model carries an op field as well.)
sqn — the authentication sequence number, 12-character hex. Optional; defaults to 000000000000.

Serving-network context

These fields describe the network the UE belongs to and the security algorithms it negotiates.

snn — the Serving Network Name, used in 5G key derivation. Inherited from the top-level config.snn when an entry omits it.
ciphering — the NAS ciphering algorithm, one of NEA0 through NEA3. Defaults to NEA0.
integrity — the NAS integrity algorithm, one of NIA0 through NIA3. Defaults to NIA2.

The top-level config block sets mcc, mnc, and snn defaults that apply to every entry below it, so a homogeneous set stays compact.

Note

The test keys above (K and OPc from the 3GPP test vectors) are safe to commit and reuse. Real network keys are secrets — keep them out of version control and out of shared environments.

Where subscribers live

The runner binary is stateless. It never opens a local subscriber database. Identities for a run come from one of three places:

CLI file — d3x-run run-flow -s subscribers.yaml loads the YAML into a process-local slice. Each UE takes the next row in order. When the slice is exhausted, further UEs fail fast; they do not wait on a queue and they do not share a lock with other processes.
CLI synthesis — -gen-subscriber builds a fresh identity per UE in memory. No file, no pool.
Control plane — durable inventory for fleets lives in the console. Agent-mode jobs receive an inline subscriber set on the job payload; the agent materializes it in memory, runs the job, and drops it. See Agent mode.

There is no runner HTTP endpoint for the pool. Durable inventory lives in the control plane when agents are attached — see Agent mode.

How flows draw a subscriber

A flow does not name a specific subscriber. The engine binds one to each UE as the UE spawns, then every action in that flow reads identity from the bound subscriber:

NGAP and NAS actions take the SUPI, K, OPc, SQN, and algorithm fields to build registration and authentication messages.
Diameter S6a actions take the IMSI for the User-Name AVP.
SBI actions take the SUPI in imsi-<digits> form for the request path and body.

Whether a flow draws a subscriber at all depends on the procedure. UE-associated flows — registration, PDU session establishment, authentication — each pull one identity per UE. Flows that are not bound to a UE, such as an NG setup between a gNB and an AMF, skip acquisition entirely, so they never block on an empty pool.

Use -gen-subscriber when you need thousands of distinct UEs and the AMF does not validate auth — lab AMFs and dev proxies. Real AMFs reject synthetic SUPIs they have never seen.

Model versus recipe

This page describes what a subscriber is and how flows consume it. Generating identity files, loading them with -s, and the console import APIs are operational steps — they live in the how-to guide.

Managing subscribers — generate YAML, load it on the CLI, and how agent-mode jobs receive a set.
Configuring environments — the NFs a flow run talks to, which determine the PLMN a synthetic subscriber inherits.

Where to go next

Managing subscribers — the recipe for filling and maintaining the pool.
Flows — how a flow binds a subscriber to each UE it spawns.