Active Agent Worker Grid
No active agents registered
The 5G Load Generator & Emulator is a carrier-grade performance validation platform. It is designed to simulate high-scale control-plane and user-plane traffic to evaluate the capacity, liveness, and performance bounds of 5G Core (5GC) and IP Multimedia Subsystem (IMS) Core network elements.
The system utilizes a distributed signaling and user-plane media architecture that allows operators to generate tens of thousands of concurrent subscriber sessions and benchmark packets-per-second (PPS) and signaling metrics.
The platform separates test coordination logic from the execution plane to ensure clean horizontal scalability:
+-------------------------------------------------------------+
| MANAGER NODE |
| |
| +------------------+ +----------------------------+ |
| | Web HUD Console | < > | Northbound REST API | |
| +------------------+ +----------------------------+ |
| | |
| v |
| +----------------------------+ |
| | Test Coordinator | |
| +----------------------------+ |
+-----------------------------------------|-------------------+
|
Orchestration | (Control Loop)
+----------------+-----------------+
| |
v v
+------------------------+-----------+ +------------------+----------------+
| LOAD AGENT | | LOAD AGENT |
| - 5GMM / 5GSM state container | | - 5GMM / 5GSM state container |
| - GTP-U User-plane engine | | - GTP-U User-plane engine |
| - Dynamic Scenario runner | | - Dynamic Scenario runner |
+------------------------------------+ +------------------------------------+All signaling layers are implemented directly against 3GPP and IETF specifications to guarantee compliance with live core network standards:
The platform supports modular deployment options to accommodate diverse testing topologies - ranging from small-scale software verification labs to large-scale hardware benchmarking infrastructures.
Regardless of the deployment model, host systems and guest engines must configure shared storage volumes. This ensures that scenario JSON files, execution logs, and diagnostic capture files are synchronized dynamically and are instantly available to the host operating system or version control.
The Manager Node enforces capacity controls dynamically at runtime via a cryptographically signed license file (typically named license.key). License checks operate in a fully offline model to prevent dependency on external licensing servers in secure laboratory networks.
When the Manager Node initializes, it reads the license file and verifies its digital signature using an embedded public key (ECDSA signature validation). If the signature is invalid or fails verification, the Manager Node immediately halts startup.
The verified license contains the following parameters enforced at runtime:
| Property | Description | Enforcement Policy |
|---|---|---|
customer_name |
Name of the licensed entity/organization. | Displayed on the Web HUD dashboard for compliance tracking. |
max_tps |
The maximum Transaction Per Second signaling rate allowed globally. | If a scenario workflow configures a target rate higher than this value, the Manager rejects the run with a Forbidden error. |
max_nodes |
The maximum number of parallel Load Agent workers allowed to register. | Any additional Load Agent attempting to register beyond this node limit is blocked from joining the active cluster. |
expiry |
The expiration date and timestamp of the license key. | If the current system time exceeds this timestamp, the Manager disables scenario initiation and marks the license status as expired. |
For enhanced security when running in production mode, the Manager Node performs a strict self-integrity check on startup. It calculates the SHA-256 hash of its own executable and validates it against a cryptographically signed signature file (named <executable_name>.sig) using the embedded public key. If the signature is missing or verification fails, the binary halts immediately with exit status 9.
To start the Manager Node with a specific license key file, run the binary with the license flag:
# Start Manager Node with a custom license key
./manager -license /path/to/my_license.keyThe signaling engine emulates the complete Non-Access-Stratum (NAS) and NG Application Protocol (NGAP) stacks to register virtual User Equipments (UEs) with the Access and Mobility Management Function (AMF).
The Load Agent acts as a gNodeB base station, establishing physical Stream Control Transmission Protocol (SCTP) associations with target AMFs (standard port 38412). The SCTP engine binds to a single local IP address to establish standard 1-to-1 associations.
Each virtual UE tracks its independent 5G Mobility Management state machine, progressing through the following states:
Idle: The UE session is unattached. No SCTP binding or NAS context exists.Registering: The UE has initiated registration and is completing the handshake.Authenticated: The 5G-AKA authentication challenge has been computed and answered successfully.SecurityActive: Security Mode Control (SMC) has completed, and the NAS security context is active.Registered: The UE has successfully established a security context and completed registration.PduSessionRequested: PDU session establishment request has been transmitted.PduSessionActive: PDU session has been established, and user-plane data paths are active.The control plane handler coordinates sequential message exchanges, including Registration Request, handling the AMF's Authentication Challenge, executing Security Mode Control, and responding with Registration Complete.
To attach to commercial cores, the platform implements robust security standards:
0x00), forwarding the SUPI in plaintext inside the SUCI payload container for testing compliance.The platform features two distinct traffic routing modes. This choice determines whether user-plane data routes through the host operating system kernel or executes entirely in user space.
KERNEL TUNNELED MODE (enable_tun: true)
+-----------------------+ +------------------+ +-------------------------+
| Sockets / Application | ---> | TUN Interface | ---> | Load Agent User-space |
| (e.g., Ping, Curl) | | (tun0000, 1520B) | | (GTP-U Encapsulation) |
+-----------------------+ +------------------+ +------------|------------+
| (UDP 2152)
v
[ Physical Network / N3 ]
USER-SPACE TUNNEL-LESS MODE (enable_tun: false)
+-------------------------------------------------+ +-------------------------+
| Dynamic Scenario Engine / Virtual Socket | ---> | Load Agent User-space |
| (Inline UDP & TCP parsing in dynamic memory) | | (GTP-U Encapsulation) |
+-------------------------------------------------+ +------------|------------+
| (UDP 2152)
v
[ Physical Network / N3 ]enable_tun: true)In this mode, the Load Agent requests the operating system kernel to configure virtual network interfaces and Policy-Based Routing tables:
tun0000 or ims0000) for each active subscriber PDU session, assigning it the IP address received from the core network.# Rule: Route traffic originating from the UE's IP through its custom routing table
ip rule add from <UE_IP_ADDRESS> table <TABLE_ID>
# Route: Default gateway for this custom table points to the UE's TUN interface
ip route add default dev <TUN_INTERFACE_NAME> table <TABLE_ID>ping or curl bound directly to the interface name).enable_tun: false or default)For high-throughput signaling and media load testing, tunnel-less mode bypasses kernel interaction completely:
Regardless of the routing mode, the Load Agent inspects 3GPP QoS rules returned during PDU Session negotiation and maps user plane traffic to target QoS Flow Identifiers (QFIs) on the GTP-U header:
The platform emulates VoNR (Voice over New Radio) and ViNR (Video over New Radio) user-plane traffic alongside active call signaling.
The agent establishes IPsec Security Associations (SAs) over the Gm interface to secure IMS registrations and calling sessions. SAs are configured via Linux kernel XFRM frameworks, using ESP encapsulation. If administrative permissions are absent, the system falls back to plain SIP-Digest signaling.
The SIP transaction engine manages dialog lifecycles: REGISTER, INVITE, 180 Ringing, 200 OK, ACK, and BYE. During handshakes, Session Description Protocol (SDP) payloads negotiate media definitions (AMR-WB or AMR-NB voice profiles; H.264 video profiles).
Upon call establishment, the media engine initiates bidirectional RTP or SRTP transmission loops. SRTP keys are derived dynamically from IMS-AKA security association keys. To simulate realistic media traffic, the RTP engine sends media packets at fixed intervals matching the codec specifications, maintaining jitter under 2ms.
Rather than using hardcoded compiled logic, supplementary services are emulated dynamically inside the DYNAMIC_FLOW engine using flexible SIP message templates and variables:
scenario.hold.resume.json) by transmitting re-INVITE templates with SDP media lines toggled to a=sendonly (to hold) and a=sendrecv (to resume), combined with start_media and stop_media action blocks.scenario.forward.json) using SIP redirection, where a forwarder UE intercepts the INVITE and returns a 302 Moved Temporarily response, directing the caller to initiate a new call leg.scenario.barring.json) by matching call details against local context variables and terminating blocked INVITEs with client failure responses.Orchestration runs are defined using structured JSON files. Scenarios specify targets, credentials, workload pacing, and the sequence of workflow steps.
The system utilizes a stratified configuration model to resolve settings. Values are loaded in the following order: pre-configured defaults -> JSON scenario parameters -> environment variables (e.g. AMF_ADDR, USIM_K, USIM_OPC).
A standard scenario file is structured into the following sections:
targets: Core network ingress addresses (AMF IP/ports and P-CSCF endpoints).subscribers: Configures IMSI/MSISDN ranges and USIM credentials ($K$, $OPc$, $AMF$).workload: Rate limits (target TPS), concurrent UE limits, run duration limits, and the `enable_tun` toggle.workflow: An ordered list of steps executed independently by each UE session.The top-level workflow supports the following step definitions:
| Step Type | Parameters | Description |
|---|---|---|
5G_REGISTER |
None | Performs 5G SA registration, executing authentication and security mode SMC loops. |
5G_DEREGISTER |
None | Detaches the UE from the 5G Core, releasing all session parameters. |
PDU_SESSION_ESTABLISH |
pdu_session_id (int), dnn (string) |
Requests a PDU session. Sets up a TUN interface and PBR rules if enable_tun is true. |
PDU_SESSION_RELEASE |
pdu_session_id (int) |
Releases the specified PDU session and cleans up routing mappings. |
ICMP_PING |
destination (string), count (int) |
Runs a ping validation through the UE's PDU session (requires enable_tun: true). |
HTTP_CURL |
url (string) |
Invokes a curl command bound to the UE's TUN interface to verify external HTTP connectivity (requires enable_tun: true). |
WAIT |
duration (string) |
Pauses step execution for the UE (e.g. "5s", "100ms"). |
DYNAMIC_FLOW |
group_size (int), role_mapping (object), workflows (object) |
Spawns a dynamic, multi-role signaling/media flow (e.g. VoNR calls). |
Dynamic scenarios allow operators to model custom signaling and media call flows using message templates and variables, rather than modifying compile-time code.
A DYNAMIC_FLOW step groups UEs into logical clusters (using group_size) and maps them to distinct roles (e.g. one UE acts as the "caller", another as the "callee"). The workflows for each role execute in parallel, using variables to exchange parameters (such as contact URIs, media ports, and tags).
Inside a role's workflow, you can define the following structural steps:
send: Transmits a raw message template (e.g. SIP REGISTER or INVITE). Supports dynamic variable interpolation using square brackets (e.g. [domain], [local_ip], [supi]).recv: Blocks until a packet matching specific criteria (like status code 200 or 401) is received. Supports capture rules using regular expressions to extract parameters from headers or the message body and save them as variables.wait: Pauses execution for the current role.if: Evaluates a variable value and branches workflow execution dynamically.comment: Adds text annotations within scenario files.The action step executes specialized built-in modules. Below are the supported actions:
| Action Name | Parameters | Description |
|---|---|---|
generate_uuid |
None | Generates a unique UUID and saves it to a specified variable (commonly used to populate Call-ID or branch strings). |
generate_sip_auth / calc_auth_header |
method, uri, nonce, realm, algorithm, www_auth |
Calculates SIP authorization headers, resolving MD5 or USIM Milenage AKAv1-MD5 challenges. |
setup_ipsec |
nonce, security_server, ipsec_mode |
Parses security parameters, derives keying material, and installs IPsec Security Associations in the kernel. |
cleanup_ipsec |
None | Uninstalls active IPsec SAs from the kernel routing table. |
start_media |
remote_port, codec (AMR-WB / H264), use_srtp (true / false) |
Launches conversational audio or video media transmission and reception. Under enable_tun: false, traffic is routed through virtual sockets. |
stop_media |
None | Tears down all active audio and video media streams for the UE session. |
set_variable |
name, value |
Binds a static or interpolated value to a local context variable. |
The platform aggregates real-time performance data and offers diagnostic logs to help operators verify system liveness and troubleshoot failures.
The Manager Node's web dashboard displays live operational telemetry. Key metrics tracked on the dashboard include:
All nodes write structured logs in JSON format to stdout. This enables operators to ingest logs directly into standard log aggregation stacks (e.g. Elasticsearch, Grafana Loki). Each log entry contains a timestamp, level (INFO, WARN, ERROR, DEBUG), component, and a contextual message.
Key logging components include:
scenario_runner: Logs overall scenario progress and state transitions.nas: Logs 5G Mobility and Session management packet decoding and states.sip: Logs SIP Gm transaction handshakes, registrations, and calling events.transport: Logs SCTP socket statuses and GTP-U interface events.When verifying signaling flows or troubleshooting connection drops, operators can capture traffic directly on the Load Agent interfaces using standard utilities. Capturing files to the shared workspace automatically syncs them back to the host system for analysis:
# Capture SCTP signaling traffic on eth0 and write to a file
tcpdump -i eth0 -w /workspace/loadgen/diagnostics_control.pcap sctp
# Capture GTP-U user plane traffic on eth0
tcpdump -i eth0 -w /workspace/loadgen/diagnostics_media.pcap udp port 2152Load Agent Nodes (Interface: net1/eth0)