Part of: OCUDU on COSMOS · 4G / 5G & O-RAN · Step 1 of the OCUDU learning path · Next: ocudu-ota
Build a complete 5G Standalone network — the OCUDU base station, the Open5GS core and the srsue software UE — on a single COSMOS server, with no radio. Register the UE, give it an IP address, reach the internet through it, and measure its throughput.
This is the first hands-on step and the fastest way to see a 5G network work end to end. With the radio replaced by software, only the configuration and the protocol stack can go wrong. Once you have seen a healthy registration here, you will recognise the same milestones when a real radio is involved in the next tutorial.
Concepts
- gNB — the 5G base station. Here it is OCUDU's
gnbprogram, with the central and distributed units (CU and DU) in one process.- Core (5GC) — the network functions that admit the UE and carry its traffic. The AMF handles registration; the UPF forwards user data. Here they are Open5GS services.
- UE — the phone. Here it is
srsue, a software UE from the srsRAN 4G project.- ZMQ — a software message transport. The gNB and
srsueexchange radio samples over two ZMQ sockets instead of over the air.- PDU session — the UE's data connection; establishing it gives the UE an IP address in
192.168.100.0/22.
srsue in the right order, and why the order matters.iperf3, and what that number does and does not tell you.Everything runs on one server:
| Link | Between | Carried over |
|---|---|---|
| Radio (simulated) | gNB ↔ srsue |
two ZMQ TCP sockets: the gNB transmits on port 2000 and receives on 2001, srsue does the reverse |
| N2 — control | gNB ↔ AMF | NGAP over SCTP port 38412 on the loopback interface; the UE's registration messages travel inside it |
| N3 — user data | gNB ↔ UPF | GTP-U on the loopback interface |
| N6 — data network | UPF → internet | the core's ogstun interface (192.168.100.1/22) and a NAT rule on the server |
The cell is configured as band 3, 10 MHz, 15 kHz subcarrier spacing, but no RF is ever generated. The UE's data interface is placed in its own network namespace, ue1, so a ping from the UE really crosses the radio stack, the gNB and the UPF before it leaves the server.
| Domains | any domain - the node checks below decide |
| Nodes | 1, named in OMF_NODES |
| On the console | python3, ansible-playbook, ssh |
cosmos-tutorial check ocudu-soft verifies, on each node:
Not in the package - you provide:
You will also need:
No radio, no radio reservation and no licence are involved.
On the console of your domain, name your node and ask whether the tutorial can run. The check is read-only: it changes nothing on the node.
export OMF_NODES="<node>"
cosmos-tutorial check ocudu-soft
It ends with RUNNABLE or NOT RUNNABLE and the reasons. It verifies that the node carries the OCUDU and srsue builds and the Open5GS launcher, and that no other gNB or soft UE is already running there. If the image is missing, load it first:
omf load -i ocudu.ndz -t <node> -r 0 -o 2400 -b 600
omf tell -a on -t <node>
-r 0 resizes the root partition to the whole disk.
export OMF_NODES=<node>
cosmos-tutorial check ocudu-soft
cosmos-tutorial run ocudu-soft # ansible
cosmos-tutorial run ocudu-soft --mode manual # manual
cosmos-tutorial jupyter ocudu-soft # jupyter
cosmos-tutorial run ocudu-soft --mode parity # parity
cosmos-tutorial run ocudu-soft --mode teardown # teardown
The tutorial ships the same experiment three ways. All three read one parameter file, use one log parser, and write the same JSON result into ~/cosmos-runs/ocudu-soft/<UTC>-<mode>/ on the console. OMF_NODES is required: the inventory refuses to run without it, so a run can never touch a node you did not name. This tutorial takes exactly one node.
The playbook runs a preflight check, starts Open5GS, starts the gNB and srsue as named systemd units (ocudu-gnb, ocudu-srsue), measures ping and throughput, and writes the result. Named units are what let the teardown stop exactly your processes and nothing else.
The manual mode runs the commands below for you. Run them yourself, step by step, to see what each part does. Log in to the node first:
ssh root@<node>
Step 1 — Start the Open5GS core. The core must be up before the gNB starts, because the gNB sends its NG Setup Request to the AMF only once, at start-up. The launcher starts the core's network functions, creates ogstun for the UE pool, adds NAT, and writes the test subscriber (001010123456780) into the core's database.
/root/open5gs/start.sh # NFs + ogstun 192.168.100.1/22 + NAT + provisions subscribers
ss -lnp -A sctp | grep 38412 # AMF listening for the gNB
Step 2 — Start the gNB. The gNB connects to the AMF (NG Setup) and then activates its cell, which here means it starts streaming samples on the ZMQ socket. It writes its own log to /tmp/gnb.log and a short console summary, so send the console to a different file. Keep its standard input open with sleep infinity |: the gNB exits when standard input closes, for example when your SSH session ends.
cd /opt/ocudu/build
setsid bash -c 'sleep infinity | ./apps/gnb/gnb -c /root/gnb-zmq.yml' >/tmp/gnb-console.log 2>&1 &
sleep 10
grep -aE 'NG Setup Procedure" finished|Cell was activated|gNB started' /tmp/gnb.log
The configuration fixes where the UE looks for the first control channel and when it may send its random-access preamble (pdcch.common.coreset0_index: 6, ss0_index: 0, prach.prach_config_index: 1, tx_gain/rx_gain: 0). srsue only decodes the combinations it supports, so leave these values as shipped.
Step 3 — Attach the UE. srsue searches for the cell, performs random access, sets up an RRC connection, registers with the core and requests a PDU session, all on its own. Its configuration puts the UE's data interface in the network namespace ue1, which nothing on the image creates, so create it first.
ip netns add ue1
cd /opt/srsran4g/build/srsue/src
setsid bash -c './srsue /root/ue-zmq.conf' >/tmp/ue.log 2>&1 &
sleep 8
grep -aE '^Random Access|^RRC Connected|^PDU Session' /tmp/ue.log
Step 4 — Send traffic through the UE. The UE's interface lives in the ue1 namespace, so run the UE side with ip netns exec ue1. The first ping reaches the core's gateway; the second leaves the server through NAT and proves the whole user plane.
ip netns exec ue1 ip -br addr show tun_srsue
ip netns exec ue1 ip route replace default dev tun_srsue # the internet is reached through the UE
ip netns exec ue1 ping -c 4 192.168.100.1 # core gateway
ip netns exec ue1 ping -c 4 8.8.8.8 # the internet
Step 5 — Measure throughput. Start an iperf3 server on the core's gateway address and run the client inside the UE namespace, so every byte crosses the UE stack, ZMQ, the gNB and the UPF. -R reverses the direction, so the server sends and you measure the downlink.
iperf3 -s -B 192.168.100.1 -D
ip netns exec ue1 iperf3 -c 192.168.100.1 # UL
ip netns exec ue1 iperf3 -c 192.168.100.1 -R # DL
The notebook runs on the console and drives the node over SSH. It performs the same steps and plots downlink and uplink throughput. It can also be run non-interactively with papermill, which writes an executed copy to a new file.
The parity mode runs Ansible, manual and Jupyter one after the other on the same node and compares their results. It passes when every mode attaches and reports RRC connected, ping loss is at most 5 %, downlink is in 5–60 and uplink in 1–20 Mbit/s, and the modes agree within 35 % (downlink) and 40 % (uplink). The parity harness does not tear down after itself; run the teardown afterwards.
After Step 1, the AMF is listening for the gNB:
LISTEN 0 0 127.0.0.5:38412 0.0.0.0:* users:(("open5gs-amfd",...))
No such line means the AMF did not start, and the gNB will fail NG Setup.
After Step 2, the gNB has registered with the core and its cell is active:
2026-09-10T10:25:27.621293 [NGAP ] [I] "NG Setup Procedure" finished successfully
2026-09-10T10:25:27.676279 [MAC ] [I] [ 0.0] cell=0: Cell was activated
2026-09-10T10:25:27.676455 [GNB ] [I] ==== gNB started ===
After Step 3, the UE has attached. The three lines appear in this order; if output stops after one of them, the next milestone is the one that failed:
Random Access Complete. c-rnti=0x4601, ta=0
RRC Connected
PDU Session Establishment successful. IP: 192.168.100.2
After Step 4, both pings succeed:
tun_srsue UNKNOWN 192.168.100.2/24
4 packets transmitted, 4 received, 0% packet loss, time 3003ms # 192.168.100.1
rtt min/avg/max/mdev = 19.416/29.450/37.841/6.679 ms
4 packets transmitted, 4 received, 0% packet loss, time 3004ms # 8.8.8.8
rtt min/avg/max/mdev = 20.931/29.084/37.069/6.363 ms
A parity run ends with PARITY: PASS and the two spread lines inside their tolerances:
=== ocudu-soft parity ===
mode ue_ipv4 ping_rtt_ms dl_mbps ul_mbps node
----------------------------------------------------
ansible 192.168.100.229.41 26.2 4.82 srv18
manual 192.168.100.231.75 26.1 5.02 srv18
jupyter 192.168.100.230.99 26.2 4.72 srv18
dl_mbps spread max/min = 1.00 (tol 1.35)
ul_mbps spread max/min = 1.06 (tol 1.40)
PARITY: PASS (same experiment in all modes; all checks green)
(Real output from 2026-09-14. The table runs the UE address into the RTT column: 192.168.100.2, 29.41 ms.)
Change any of these with cosmos-tutorial run ocudu-soft --params my.yml. An unknown key or a wrong type is refused. cosmos-tutorial params ocudu-soft prints the file.
| Key | Default | Meaning |
|---|---|---|
ocudu_gnb_bin |
/opt/ocudu/build/apps/gnb/gnb |
|
ocudu_ue_bin |
/opt/srsran4g/build/srsue/src/srsue |
|
ocudu_gnb_cfg |
/root/gnb-zmq.yml |
|
ocudu_ue_cfg |
/root/ue-zmq.conf |
|
ocudu_core_start |
/root/open5gs/start.sh |
|
ocudu_plmn |
00101 |
PLMN 00101 (2-digit MNC) is MANDATORY, not a preference: srsUE splits its IMSI as MCC(3)+MNC(2)+MSIN(10) and cannot form a 3-digit-MNC identity. |
ocudu_imsi |
001010123456780 |
|
ocudu_ue_netns |
ue1 |
srsUE puts its tun in this netns (see [gw] netns) |
ocudu_ue_subnet |
192.168.100 |
The UE pool as ACTUALLY configured in this image's smf.yaml (subnet 192.168.100.0/22, gateway 192.168.100.1) -- NOT the 10.45.0.0/24 that the upstream srsRAN tutorial assets assume. |
ocudu_sst |
1 |
S-NSSAI: bare SST-1, no SD. |
ocudu_ping_count |
10 |
|
ocudu_iperf_secs |
10 |
|
ocudu_iperf_port |
5201 |
|
ocudu_gnb_settle_s |
12 |
How long to wait for N2/NGSetup before starting the UE. |
ocudu_attach_timeout_s |
60 |
How long to wait for the UE to reach "PDU Session Establishment successful". |
To change a parameter, put only the keys you change in a file of your own and pass it to any mode. A key the tutorial does not have, or a value of the wrong type, is refused before anything starts:
cat > my.yml <<'EOF'
ocudu_iperf_secs: 20
EOF
cosmos-tutorial run ocudu-soft --params my.yml
To change the tutorial itself, cosmos-tutorial copy ocudu-soft puts an editable copy in the current directory, which then takes precedence over the installed one.
Random Access Complete means the gNB heard the preamble and gave the UE a temporary identity (C-RNTI); RRC Connected means the radio connection is up; PDU Session Establishment successful means registration, authentication and the session all succeeded.192.168.100.1 points at the radio stack or the UPF; loss to 8.8.8.8 alone points at the NAT on the server.| Symptom | Cause | Fix |
|---|---|---|
srsue loops "No cells found" |
the UE's carrier settings or ZMQ ports do not match the gNB | use the shipped /root/ue-zmq.conf unchanged (nof_carriers=1, max_nof_prb=52, srate 11.52e6) |
srsue reports RF backend <none> |
the ZMQ plugin is not built | cd /opt/srsran4g; cmake -B build -GNinja -DENABLE_ZMQ=ON -DENABLE_RF_PLUGINS=OFF && ninja -C build srsue |
srsue attaches, then Failed to setup/configure GW interface, no IP |
the ue1 network namespace does not exist |
ip netns add ue1 before starting srsue (Step 3) |
| A second UE attach after a detach never completes random access | a stale ZMQ stream from the previous UE; ZMQ is stateful | restart the gNB as well as the UE |
| The gNB exits as soon as the SSH session ends | the gNB exits when its standard input closes | launch it behind sleep infinity \| inside setsid (Step 2) |
/tmp/gnb-console.log is empty while the gNB runs |
the console summary is block-buffered when redirected | read readiness from /tmp/gnb.log |
| Relaunching the gNB ends your SSH session with exit 255 | pkill -f apps/gnb/gnb matched your own shell's command line |
stop the gNB as shown under Teardown, never with pkill |
The SMF crashes on a missing freeDiameter/smf.conf |
a quirk of the 5G-only Open5GS build | comment out the freeDiameter: line in /opt/open5gs/etc/smf.yaml |
A gNB, srsue or iperf3 is still running long after a parity run |
the parity harness ends without a teardown | run the teardown below |
After any mode, and always after a parity run, run the teardown from the console. It stops the tutorial's named systemd units (ocudu-srsue, ocudu-gnb, ocudu-iperf), removes the UE namespace and stops Open5GS:
OMF_NODES=<node> cosmos-tutorial run ocudu-soft --mode teardown
After the manual steps the gNB and srsue have no systemd unit. Stop them by the binary they are executing, never with pkill: pkill -f matches your own shell's command line, and a name match such as pkill -x gnb would also stop another user's gNB on a shared host. On the node, define this helper once, then stop the UE and the gNB, remove the namespace and stop the core:
stop_exe() { # signal the process GROUP of every process executing exactly $1 (default TERM)
local exe sig=${2:-TERM} d st pgid
exe=$(readlink -f "$1")
for d in /proc/[0-9]*; do
[ "$(readlink "$d/exe" 2>/dev/null)" = "$exe" ] || continue
st=$(cat "$d/stat" 2>/dev/null) || continue
st=${st##*) } # drop "pid (comm) ", safe for any comm
pgid=$(echo "$st" | awk '{print $3}') # remaining fields: state ppid pgrp
kill -"$sig" -- "-$pgid" 2>/dev/null
done
}
stop_exe /opt/srsran4g/build/srsue/src/srsue
stop_exe /opt/ocudu/build/apps/gnb/gnb
ip netns del ue1; /root/open5gs/stop.sh
The helper identifies a process by /proc/<pid>/exe, which a command line cannot fake, and signals its whole process group. Each manual launch used setsid, so the group is exactly that launch. If something is still running after a few seconds, repeat the call with KILL as the second argument. Then power the node off from the console:
omf tell -a offh -t <node>
Package cosmos-experiments-ocudu 0.1.0-31 - on every console it is released to (cosmos-tutorial list shows the installed version). The code is installed on the console in /usr/share/cosmos-experiments/ocudu-soft/. To change anything, cosmos-tutorial copy ocudu-soft puts an editable copy in the current directory, and cosmos-tutorial run ocudu-soft then runs that copy instead of the installed one (cosmos-tutorial which ocudu-soft shows which will run). Repository (GitLab account needed, not needed to run or change it): packages/cosmos-experiments-ocudu/usr/share/cosmos-experiments/ocudu-soft.
Last verified 2026-11-02 from the installed cosmos-experiments-ocudu 0.1.0-25 package on ocudu-20261020, cold start (all devices off) after a fresh ocudu.ndz load, on osc (2× Intel Xeon Gold 6126): three-mode parity PASS, downlink 26 and uplink 4.7–4.9 Mbit/s. Three-mode parity also passed on 2026-10-28 (cold start, sb1 2× Intel Xeon Gold 6226 and osc) and on 2026-09-14 on all three CPU platforms. Results by build are on OCUDU performance by build.
References: srsRAN Project documentation · srsRAN 4G documentation (srsue and its ZMQ radio) · Open5GS documentation · 3GPP TS 23.501 and TS 23.502 (5G architecture and procedures) · iperf3 · on this wiki: OCUDU on COSMOS · Open5GS.
Author(s): COSMOS team · Package: cosmos-experiments-ocudu (cosmos-tutorial run ocudu-soft) · Tags: ocudu, srsran, srsue, open5gs, 5g, sa, zmq, soft