Part of: Duranta on COSMOS · 4G / 5G & O-RAN · Step 1 of the Duranta learning path · Next: duranta-ota · Optional branch: duranta-ntn
Build a complete 5G Standalone network — the Duranta gNB (nr-softmodem), the OAI CN5G core and the Duranta software UE (nr-uesoftmodem) — on a single COSMOS server, connected by a radio simulator instead of a 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 on the Duranta path. Every later tutorial adds hardware — a USRP, a fronthaul link, a commercial radio unit — and each piece of hardware brings its own failure modes. Here only the protocol stack and the core can go wrong, so you learn what a healthy registration looks like before any radio effect can blur it. When a later tutorial fails, this one is the reference to compare against.
Concepts
- gNB — the 5G base station. Here it is
nr-softmodem, 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 (registration), the SMF (sessions) and the UPF (user data). Here they are OAI CN5G Docker containers.
- UE — the phone. Here it is
nr-uesoftmodem, Duranta's software UE.- RFsim — OAI's radio simulator. The gNB writes radio samples to a TCP socket and the UE reads them, so nothing is transmitted.
- PDU session — the UE's data connection; establishing it gives the UE an IP address in
192.168.100.0/22.
LD_LIBRARY_PATH, and why the UE needs the carrier on its command line.iperf3, and why the result here depends on the CPU.Everything runs on one server:
| Link | Between | Carried over |
|---|---|---|
| Radio (simulated) | gNB ↔ UE | RFsim: the gNB is the server on TCP port 4043, the UE connects to it on 127.0.0.1 |
| N2 — control | gNB ↔ AMF container | SCTP over the Docker bridge demo-oai; the UE's registration messages travel inside it |
| N3 — user data | gNB ↔ UPF container | GTP-U over the same bridge |
| N6 — data network | UPF → internet | the oai-ext-dn container, which stands in for the data network and NATs UE traffic to the internet |
The cell is configured as band n78, 106 PRB, 30 kHz subcarrier spacing. On the UE side the PDU session appears as a Linux tunnel interface, oaitun_ue1, which is what you ping and run iperf3 through.
| Domains | any domain - the node checks below decide |
| Nodes | 1, named in OMF_NODES |
| On the console | python3, ansible-playbook, ssh |
cosmos-tutorial check duranta-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 duranta-soft
It ends with RUNNABLE or NOT RUNNABLE and the reasons. It verifies that the node carries the Duranta gNB and UE builds, the OAI CN5G compose files, Docker, the RFsim configurations and the subscriber SQL, that the CPU has AVX-512, and that no other gNB or soft UE is already running. If the image is missing, load it first:
omf load -i duranta.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; without it the build tree and logs fill a small partition.
export OMF_NODES=<node>
cosmos-tutorial check duranta-soft
cosmos-tutorial run duranta-soft # ansible
cosmos-tutorial run duranta-soft --mode manual # manual
cosmos-tutorial jupyter duranta-soft # jupyter
cosmos-tutorial run duranta-soft --mode parity # parity
cosmos-tutorial run duranta-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/duranta-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 the core, then starts the gNB and the UE as named systemd units (duranta-gnb, duranta-ue) with LD_LIBRARY_PATH set. It writes the AMF's current address into the gNB configuration, takes the UE's carrier arguments from the gNB log, and waits for oaitun_ue1 to carry an address — a readiness check, not a fixed sleep. It then measures ping and iperf3 to the core's data network and ping to the internet.
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 OAI CN5G core. The core must be up before the gNB starts, because the gNB's first action is an NG Setup towards the AMF. This starts the network-function containers and seeds the subscriber database with the software UE's identity (001010123456780), so the core will accept its registration.
cd /opt/oai-cn5g/oai-cn5g-fed/docker-compose
docker compose -f docker-compose-basic-nrf.yaml up -d
docker exec -i mysql sh -c 'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" oai_db' < /root/duranta/provision.sql
docker compose -f docker-compose-basic-nrf.yaml ps # all NFs "healthy"
Step 2 — Start the gNB. Two addresses in the gNB configuration are known only once the containers run: the AMF's address (Docker assigns it at start) and the gNB's own address on the demo-oai bridge. The block reads both, writes them into the configuration, and starts the gNB as the RFsim server with its log in /tmp/oai-gnb.log. The Duranta build was moved to /opt/duranta after it was compiled, and it loads its libraries from the original build path, so every launch must set LD_LIBRARY_PATH to the build directory.
B=/opt/duranta/cmake_targets/ran_build/build
AMFIP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' oai-amf)
sed -i "s#amf_ip_address.*ipv4.*#amf_ip_address = ({ ipv4 = \"$AMFIP\"; });#" /root/duranta/gnb-rfsim.conf 2>/dev/null || true
GNBIP=$(ip -4 -o addr show demo-oai | grep -oE '192\.168\.70\.[0-9]+' | head -1) # the gNB must bind N2/N3 on the demo-oai bridge
sed -i "s/GNB_IPV4_ADDRESS_FOR_NG_AMF *= *\"[0-9.]*\"/GNB_IPV4_ADDRESS_FOR_NG_AMF = \"$GNBIP\"/; s/GNB_IPV4_ADDRESS_FOR_NGU *= *\"[0-9.]*\"/GNB_IPV4_ADDRESS_FOR_NGU = \"$GNBIP\"/" /root/duranta/gnb-rfsim.conf
cd "$B"
setsid bash -c "export LD_LIBRARY_PATH=$B; exec ./nr-softmodem -O /root/duranta/gnb-rfsim.conf --rfsim" >/tmp/oai-gnb.log 2>&1 &
sleep 10
grep -aE 'is in service|NGAP_REGISTER_GNB_CNF' /tmp/oai-gnb.log | tail -2
Step 3 — Attach the UE. The UE connects to the gNB's RFsim socket, decodes the broadcast, performs random access and registers. A phone searches for cells on its own, but nr-uesoftmodem must be told the carrier frequency, bandwidth, numerology, band and SSB position on its command line, or it stops at start-up. The gNB prints exactly that set in its log, and this block reuses it.
B=/opt/duranta/cmake_targets/ran_build/build
cd "$B"
UEARGS=$(grep -a "Command line parameters for OAI UE" /tmp/oai-gnb.log | head -1 | sed -E 's/.*OAI UE: *//; s/\x1b\[[0-9;]*m//g')
echo "$UEARGS" # e.g. -C 3319680000 -r 106 --numerology 1 --band 78 --ssb 516
setsid bash -c "export LD_LIBRARY_PATH=$B; exec ./nr-uesoftmodem -O /root/duranta/ue-rfsim.conf --rfsim --rfsimulator.serveraddr 127.0.0.1 $UEARGS" >/tmp/oai-ue.log 2>&1 &
sleep 12
grep -aiE 'PDU Session|oaitun|192.168.100' /tmp/oai-ue.log | tail -3
ip -br addr show oaitun_ue1
Step 4 — Send traffic through the UE. Pinging through oaitun_ue1 proves the user plane end to end: UE → gNB → UPF → data network. The first target is the core's data-network container, whose address Docker assigns at start; the second proves the NAT to the internet.
DN=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' oai-ext-dn)
ping -I oaitun_ue1 -c 4 $DN # OAI ext-DN
ping -I oaitun_ue1 -c 4 8.8.8.8 # the internet
Step 5 — Measure throughput. Start an iperf3 server inside the oai-ext-dn container and run the client from the UE's tunnel address. -R reverses the direction, so the server sends and you measure the downlink.
docker exec -d oai-ext-dn iperf3 -s; sleep 2 # give the server a moment before the first client
DN=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' oai-ext-dn)
iperf3 -c $DN -B 192.168.100.2 -R -t 12 # DL
iperf3 -c $DN -B 192.168.100.2 -t 12 # UL
Use the UE's actual address from Step 3 after -B if it is not 192.168.100.2.
The notebook runs on the console and drives the node over SSH. It performs the same steps; its last cell plots downlink and uplink throughput and prints the result. 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 back to back on one node and compares their results. It passes when every mode reaches cell in service, RRC connected and a PDU-session address; local ping loss is at most 5 %; downlink is in 30–400 and uplink in 10–200 Mbit/s; and the modes agree within 35 % (downlink) and 40 % (uplink). It runs the teardown on every exit.
After Step 1, every container in the ps listing reports healthy.
After Step 2, the cell is in service, which means the NG Setup with the AMF succeeded and the cell is broadcasting:
[NR_RRC] cell PLMN 001.01 Cell ID ... is in service
After Step 3, the UE holds a PDU session and its tunnel carries the address:
[NAS] PDU Session Establishment Accept, UE IPv4 192.168.100.2
oaitun_ue1 UNKNOWN 192.168.100.2/22
After Step 4, both pings succeed:
4 packets transmitted, 4 received, 0% packet loss
A parity run ends with PARITY: PASS:
=== duranta-soft parity ===
mode ue_ipv4 ping_rtt_ms ping_remote_loss_pct dl_mbps ul_mbps node
ansible 192.168.100.2 12.5 0.0 138.0 82.8 srv1-lg1
manual 192.168.100.3 12.62 0.0 137.0 83.2 srv1-lg1
jupyter 192.168.100.4 12.47 0.0 137.0 83.3 srv1-lg1
dl_mbps spread max/min = 1.01 (tol 1.35)
ul_mbps spread max/min = 1.01 (tol 1.40)
PARITY: PASS (same experiment in all modes; all checks green)
(Real output from sb1, 2026-10-22, image duranta-w42-20261021.)
Change any of these with cosmos-tutorial run duranta-soft --params my.yml. An unknown key or a wrong type is refused. cosmos-tutorial params duranta-soft prints the file.
| Key | Default | Meaning |
|---|---|---|
duranta_build_dir |
/opt/duranta/cmake_targets/ran_build/build |
The build was relocated to /opt/duranta: OAI dlopen()s its lib*.so with an rpath to the ORIGINAL build dir, so every launch must carry LD_LIBRARY_PATH=build dir. |
duranta_gnb_cfg |
/root/duranta/gnb-rfsim.conf |
|
duranta_ue_cfg |
/root/duranta/ue-rfsim.conf |
|
duranta_core_dir |
/opt/oai-cn5g/oai-cn5g-fed/docker-compose |
|
duranta_core_compose |
docker-compose-basic-nrf.yaml |
|
duranta_provision_sql |
/root/duranta/provision.sql |
|
duranta_node_log_dir |
/tmp/duranta-soft |
Per-run logs ON THE NODE (the console copies them into the run dir). |
duranta_plmn |
00101 |
COSMOS standard PLMN 001/01; the soft UE's USIM is in ue-rfsim.conf and the matching subscriber is seeded in the core's mysql (oai_db) by the image. |
duranta_imsi |
001010123456780 |
|
duranta_dnn |
oai |
|
duranta_ue_tun |
oaitun_ue1 |
|
duranta_remote_target |
8.8.8.8 |
Dual-target data-plane standard: a LOCAL target (the core's ext-DN container, resolved at run time) AND a REMOTE one (public internet via the host NAT). |
duranta_ping_count |
10 |
|
duranta_iperf_secs |
10 |
|
duranta_iperf_port |
5201 |
|
duranta_core_timeout_s |
150 |
How long to wait for the core NFs to report healthy (docker health checks). |
duranta_gnb_timeout_s |
90 |
How long to wait for "cell ... is in service" (N2 up + cell configured). |
duranta_attach_timeout_s |
120 |
How long to wait for the UE tun to carry a PDU-session address. |
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'
duranta_iperf_secs: 20
EOF
cosmos-tutorial run duranta-soft --params my.yml
To change the tutorial itself, cosmos-tutorial copy duranta-soft puts an editable copy in the current directory, which then takes precedence over the installed one.
is in service and PDU Session Establishment Accept bracket the whole attach. The first says the gNB reached the core and is broadcasting. The second is the last step of the UE's attach, so it implies that random access, the RRC connection, registration, authentication and security all succeeded before it. The full sequence is on 5G SA fundamentals.8.8.8.8 does not, the problem is the container's NAT, not the RAN.| Symptom | Cause | Fix |
|---|---|---|
dlopen(libparams_libconfig.so) … No such file, then exit |
the build was relocated and its library path is stale | export LD_LIBRARY_PATH=/opt/duranta/cmake_targets/ran_build/build before every launch |
gNB: sctp_bindx … Cannot assign requested address, then No AMF is associated; the UE stalls after RRCSetupComplete |
the gNB configuration binds N2/N3 to an address the server does not have | set GNB_IPV4_ADDRESS_FOR_NG_AMF and GNB_IPV4_ADDRESS_FOR_NGU to the server's demo-oai bridge address (Step 2) |
gNB: NG Setup fails / AMF not associated |
the AMF container's address changes every time the core starts | re-read docker inspect oai-amf and set amf_ip_address in the gNB configuration (Step 2) |
The UE exits at start with Assertion (0) failed! … get_freq_range_from_freq() |
the UE was not given the carrier on its command line | append the gNB log's Command line parameters for OAI UE: set, as in Step 3 |
The UE reaches RRC_CONNECTED, then Authentication Reject |
the UE's SIM settings in ue-rfsim.conf differ from the subscriber provision.sql seeded |
use the shipped ue-rfsim.conf, which matches the shipped provision.sql (IMSI 001010123456780) |
ping to one container address works but iperf3 says connection refused |
Docker assigns the demo-oai addresses in start order, so a fixed address is not always oai-ext-dn |
always target the address from docker inspect … oai-ext-dn, as in Steps 4 and 5 |
iperf3: unable to connect to server right after starting it |
the server is not up yet | run docker exec -d oai-ext-dn iperf3 -s again and wait 2 s |
The UE registers but gets no oaitun_ue1, or uplink works and downlink replies never arrive |
stale session state in the UPF | docker compose restart oai-upf oai-smf |
The UE cannot ping 8.8.8.8 but the data-network container answers |
the container's NAT is stale | check docker exec oai-ext-dn ping 8.8.8.8; the container's UE_NETWORK must be 192.168.100.0/22 |
After any mode, run the teardown from the console. It stops the tutorial's named systemd units and the core:
OMF_NODES=<node> cosmos-tutorial run duranta-soft --mode teardown
After the manual steps the UE and gNB have no systemd unit. Stop the UE first, then the gNB, then the core. Stop them by the binary they are executing, never with pkill -x or pkill -f, which match by name or command line and can hit another user's process or your own shell. On the node, define this helper once:
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/duranta/cmake_targets/ran_build/build/nr-uesoftmodem
stop_exe /opt/duranta/cmake_targets/ran_build/build/nr-softmodem
docker compose -f /opt/oai-cn5g/oai-cn5g-fed/docker-compose/docker-compose-basic-nrf.yaml down
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-duranta 0.1.0-25 - 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/duranta-soft/. To change anything, cosmos-tutorial copy duranta-soft puts an editable copy in the current directory, and cosmos-tutorial run duranta-soft then runs that copy instead of the installed one (cosmos-tutorial which duranta-soft shows which will run). Repository (GitLab account needed, not needed to run or change it): packages/cosmos-experiments-duranta/usr/share/cosmos-experiments/duranta-soft.
Last verified 2026-11-02 from the installed cosmos-experiments-duranta 0.1.0-20 package on duranta-w44-20261101 (Duranta 2026.w44), cold start (all devices off) after a fresh duranta.ndz load, on osc (2× Intel Xeon Gold 6126): three-mode parity PASS, downlink 132–138 and uplink 65 Mbit/s. Earlier: three-mode parity PASS on 2026-10-28 from the installed cosmos-experiments-duranta package on sb1 (2× Intel Xeon Gold 6226), on 2026-10-25 with duranta-w43-20261024 (Duranta 2026.w43) and on 2026-10-22 with duranta-w42-20261021. Results by build are on Duranta performance by build.
References: Duranta source · Duranta at LF Networking · OAI RAN documentation · OAI CN5G · 3GPP TS 23.501 and TS 23.502 (5G architecture and procedures) · iperf3 · on this wiki: Duranta on COSMOS · OAI CN5G.
Author(s): COSMOS team · Package: cosmos-experiments-duranta (cosmos-tutorial run duranta-soft) · Tags: duranta, oai, oai-cn5g, 5g, sa, rfsim, soft