5GC-Bench

December 28, 2025 · View on GitHub

5GC-Bench is a benchmarking and stress-testing framework for the 5G Core (5GC). It provides a reproducible environment to evaluate the performance, scalability, and resilience of 5GC Virtual Network Functions (VNFs) under diverse workloads. The framework integrates the OpenAirInterface (OAI) 5GC and gNBSIM UE/RAN simulator, enabling both control-plane and user-plane experiments.

With 5GC-Bench, researchers and practitioners can:

  • Stress-test core components (AMF, SMF, UPF, etc.) using configurable workloads.
  • Benchmark CPU, memory, and networking overheads with telemetry at fine-grained resolution.
  • Reproduce experiments easily with containerized deployments and automated scripts.

This README provides instructions for downloading, setting up, and running 5GC-Bench, along with details on environment requirements and experiment execution.

0) Prerequisites

  • Docker and Docker Compose v2 (e.g., docker compose version works)
  • Python 3.10+ with pip
  • git, curl, and basic build tools
  • Sudo access (for Docker)

Quick sanity checks:

docker --version
docker compose version
python3 --version

1) Clone the OAI 5GC repo and 5GC-Bench

cd ~
git clone https://gitlab.eurecom.fr/oai/cn5g/oai-cn5g-fed.git
cd ~
git clone https://github.com/panitsasi/5GC-Bench.git

2) Override compose files

Copy the override files from this repo into the OAI compose folder.

cp 5GC-Bench/code/docker/docker-compose-mini-nonrf.yaml         ~/oai-cn5g-fed/docker-compose/
cp 5GC-Bench/code/docker/docker-compose-gnbsim.yaml             ~/oai-cn5g-fed/docker-compose/
cp 5GC-Bench/code/docker/docker-compose-basic-vpp-nrf.yaml      ~/oai-cn5g-fed/docker-compose/

3) Clone gNBSIM

cd
git clone https://gitlab.eurecom.fr/kharade/gnbsim.git

4) Build the images

# Copy the updated Dockerfiles
cp ~/5GC-Bench/code/docker/Dockerfile.ubuntu.22.04_updated ~/gnbsim/docker/Dockerfile.ubuntu.22.04_updated
cp ~/5GC-Bench/code/docker/Dockerfile.traffic.generator.ubuntu_updated ~/oai-cn5g-fed/ci-scripts/Dockerfile.traffic.generator.ubuntu_updated

# Build the updated images
cd ~/gnbsim
docker build --tag gnbsim_updated:latest --target gnbsim --file docker/Dockerfile.ubuntu.22.04_updated .

cd ~/oai-cn5g-fed/
docker build --target trf-gen-cn5g --tag trf-gen-cn5g-updated:latest --file ci-scripts/Dockerfile.traffic.generator.ubuntu_updated ci-scripts

5) Fetch the user plane traffic traces


# Move all user plane CSV traces from 5GC_Bench/data into ~/gnbsim and ci-scripts folder
mv ~/5GC-Bench/data/*.csv ~/gnbsim/
mv ~/5GC-Bench/data/*.csv ~/oai-cn5g-fed/ci-scripts/

# Move the gnbsim client and server scripts into ~/gnbsim and rename them
mv ~/5GC-Bench/code/user_plane/gnbsim_client.py ~/gnbsim/client.py
mv ~/5GC-Bench/code/user_plane/gnbsim_server.py ~/gnbsim/server.py
# Move the traffic_dn_client and server scripts into ~/oai-cn5g-fed/ci-scripts and rename them
mv ~/5GC-Bench/code/user_plane/traffic_dn_client.py ~/oai-cn5g-fed/ci-scripts/client.py
mv ~/5GC-Bench/code/user_plane/traffic_dn_server.py ~/oai-cn5g-fed/ci-scripts/server.py

6) Deploy the OAI 5G Core

cd ~/oai-cn5g-fed/docker-compose
python3 ./core-network.py --type start-basic-vpp --scenario 1
  • Wait ~20 seconds for VNFs to become healthy.

If something fails to start, run docker compose ls and docker logs <container> to diagnose. Ensure no port conflicts and that previous runs are fully stopped.

7) Start the Telemetry Collector

From the 5GC-Bench repo:

cd ~/5GC-Bench/code/control_plane/
python3 collect_metrics_core.py
  • Collects Docker-level metrics at 1s granularity for AMF, SMF, NRF, AUSF, UDM, UDR, UPF, etc.
  • Outputs analysis-ready CSVs aligned to experiment timestamps.

Keep this running in a separate terminal while you execute scenarios below.

8) Launch gNBSIM

Use the pre-configured compose file:

cd ~/oai-cn5g-fed/docker-compose
docker compose -f docker-compose-omec-gnbsim-vpp.yaml up -d
  • Important: Starting gNBSIM will immediately execute the scenario specified in your omec-gnbsim-config.yaml. Review/edit that config before starting to ensure you run the intended procedure and UE load.

9) Add subscribers (optional, for large scale experiments)

You can quickly provision many UEs in the 5G Core using the helper script:

cd ~/5GC-Bench/code/control_plane
./add_subscribers.sh 208950000000132 100
  • The example above adds 100 subscribers starting at IMSI 208950000000132, incrementing by 1.
  • Adjust the starting IMSI and count as needed.

Re-run with different ranges to build large pools for stress tests.

10) Control-Plane VNF Micro-Benchmarks (Targeted)

Before running full service chains, you can stress individual control-plane VNFs with the helper scripts in code/control_plane/. Example (AUSF authentication vector generation):

cd ~/5GC-Bench/code/control_plane
./ausf_generate_auth.sh 200 --mode par --concurrency 8
  • 200: total HTTP requests to issue
  • --mode par: parallel mode
  • --concurrency 8: number of workers/threads

Other available scripts (examples; names may vary by release):

./nrf_discovery_requests.sh 300 --mode par --concurrency 16   # Stress NRF discovery
./udm_get_auth_sub.sh 200 --mode par --concurrency 8          # Query UDM for auth/subscription
./nrf_register_vnfs.sh 50 --mode par --concurrency 4          # Registration bursts to NRF

More scripts will be released shortly. Check code/control_plane/ for the latest set and usage.

11) Control-Plane Experiments (Service Chains)

For service chain stressing, we used gNBSIM, a UE/RAN emulator that includes standards-compliant procedures such as:

  1. Registration
  2. UE-initiated PDU Session Establishment
  3. UE-initiated De-registration

11.1 Configure procedure & load

Edit omec-gnbsim-config.yaml to set:

  • Procedure (registration / session establish / de-registration)
  • Number of UEs (e.g., 100, 200, 500)
  • Arrival pattern (sequential, bursty)

Note: As soon as you (re)start gNBSIM, it will execute whatever is configured here.

11.2 Run the scenario

# Apply your desired gNBSIM config (already mounted via compose)
cd ~/oai-cn5g-fed/docker-compose
docker compose -f docker-compose-omec-gnbsim-vpp.yaml up -d
  • Tail core VNFs to observe chain behavior: 
    docker logs -f oai-amf   # and/or oai-smf, oai-udm, oai-ausf, oai-nrf
  • Collect telemetry CSVs while the scenario runs; stop gNBSIM when finished (see §11).

12) User-Plane Experiments (UPF stress / realistic traffic)

You can also stress the UPF with synthetic or trace-driven traffic. Keep the telemetry collector running.

  • Synthetic sanity check: run iperf3 server in the DN and clients from UEs.
  • Trace-driven: use the UPLI helpers in code/user_plane/ to replay YouTube/Instagram/Browsing/Gaming or mixed profiles derived from TelecomTS/NetMob.

Examples:

# 1. Terminate the gnbsim and the core network
cd ~/oai-cn5g-fed/docker-compose
docker-compose -f docker-compose-gnbsim.yaml down -t 0
python3 ./core-network.py --type stop-basic-vpp --scenario 1

# 2. Start minimalist core (UPF + DN + helpers only)
docker compose -f docker-compose-mini-nonrf.yaml up -d

# 3. Launch gnbsim with trace-driven traffic
docker compose -f docker-compose-gnbsim.yaml up -d gnbsim

# 4. Synthetic: DN-side iperf3 server
docker exec -it oai-ext-dn iperf3 -s

# Create and Use 4 different terminals

# 5. Trace-driven: per-UE replay (uplink)
docker exec -it gnbsim python3 client.py \
  --schedule /gnbsim/bin/high_load_connections.csv \
  --slot-min 1 --days 1 --mux \
  --app-mix '{"youtube":1,"instagram":0,"facebook":0,"browsing":0,"mixed_traffic":0}'

docker exec -it gnbsim python3 server.py

# 6. Trace-driven: DN replay (downlink)
docker exec -it oai-ext-dn python3 client.py \
  --schedule /tmp/high_load_connections.csv \
  --slot-min 1 --days 1 --mux \
  --app-mix '{"youtube":1,"instagram":0,"facebook":0,"browsing":0,"mixed_traffic":0}'

docker exec -it oai-ext-dn python3 server.py

13) Stopping & Cleanup

Stop gNBSIM (choose the file you used):

# If you used the 'omec' variant during start:
docker compose -f docker-compose-omec-gnbsim-vpp.yaml down -t 0

Stop the Core:

python3 ./core-network.py --type stop-basic-vpp --scenario 1

Data

If you plan to use this setup, please send an email to ioannis.panitsas@yale.edu to receive the user-plane data and traffic traces. Github does not allow files bigger than 25 MB. Here we added only a sample of them.

Citation

If you use this setup, please cite our paper:

I. Panitsas, T. O. Atalay, D. Stojadinovic, A. Stavrou, and L. Tassiulas,
5GC-Bench: A Framework for Stress-Testing and Benchmarking 5G Core VNFs,
arXiv preprint arXiv:2509.18443, 2025.
doi: https://doi.org/10.48550/arXiv.2509.18443