Part of: OCUDU on COSMOS · FlexRIC on COSMOS · 4G / 5G & O-RAN tutorials
Install the FlexRIC near-real-time RIC on a COSMOS server from the cosmos-flexric package, connect
the E2 agent that is built into the OCUDU gNB to it, and read the gNB's own throughput, PRB and RLC
counters out of a live 5G SA cell with FlexRIC's KPM monitoring xApp. Everything runs on one server with
no radio: the gNB, the UE and the core are the software-only rig from the
OCUDU soft-only tutorial.
A near-real-time RAN Intelligent Controller (near-RT RIC) connects to base stations over the O-RAN
E2 interface, collects measurements from them and, where the base station allows it, sends control
actions back. Small applications called xApps run on the RIC and implement the monitoring or control
logic. The RIC page explains the architecture; the
FlexRIC page explains what FlexRIC is and how it
differs from the O-RAN SC RIC.
This tutorial uses FlexRIC (the dev branch after the v3.0.0 release), the SDK-style near-RT RIC maintained by the Duranta project
(github.com/duranta-project/flexric, formerly EURECOM's Mosaic5G FlexRIC). You install it from the
COSMOS package repository with apt-get, start its nearRT-RIC process, point OCUDU's E2 agent at it,
and run the xapp_kpm_moni xApp. The xApp subscribes to the gNB's E2SM-KPM service model and prints
one measurement report per second: the UE's downlink and uplink throughput on its data radio bearer
(DRB.UEThpDl, DRB.UEThpUl), PRB usage and RLC delay and drop counters.
Two things decide whether this works at all, and the cosmos-flexric package takes care of both:
-DE2AP_VERSION=E2AP_V2 -DKPM_VERSION=KPM_V3_00.dev branch and a one-line fix. OCUDU offers more KPM report styles than FlexRIC'sdev skips them. One small COSMOS changedev commit fbd9859 with that change; theE2 control (E2SM-RC) is not covered here. With the O-RAN SC RIC this OCUDU build answers RIC Control
Failure (see the O-RAN SC RIC tutorial); it
has not been tried with FlexRIC yet. FlexRIC's RC monitoring xApp, xapp_rc_moni, connects but finds no
REPORT style it implements in OCUDU's RC function, so it subscribes to nothing; against the Duranta gNB it
does work (see the FlexRIC + Duranta tutorial).
-p. FlexRIC has no built-in default for it, so always pass-p /usr/lib/flexric/.After completing this tutorial you will be able to:
nearRT-RIC and load its service-model plugins;iperf3 measurement taken at the UE.| Learning path | Alternative to step 6 (RAN intelligence). Previous: OCUDU soft-only. Other RIC: O-RAN SC RIC + OCUDU |
| Domain / testbed | Any COSMOS server that runs ocudu.ndz (verified on osc and sb1) |
| Duration | 30 min; installing FlexRIC takes under a minute |
| Difficulty | Intermediate |
| RAN stack | OCUDU (srsRAN) gNB, ZMQ software radio, srsUE |
| Core | Open5GS (on the same server) |
| New interface | E2 (SCTP 36421) and FlexRIC's E42 (36422) |
| Topic group | Cellular 4G/5G & O-RAN |
| Last verified | 2026-11-20 — every command on this page run verbatim on a freshly loaded ocudu.ndz with cosmos-flexric 3.0.0+40.gfbd9859e-1 from apt, soft ZMQ + Open5GS on platform A (2× Intel Xeon Gold 6226, 24C/24T) |
Background knowledge
Account & access
ocudu.ndz — seeDevices / nodes
| Resource | Role | Qty | Notes |
|---|---|---|---|
Server (e.g. srvN) |
gNB + UE + core + RIC | 1 | no radio; 24 logical CPUs are plenty for a 10 MHz cell |
Disk image
| Image | Load onto | Provides |
|---|---|---|
ocudu.ndz |
the server | OCUDU gNB, srsUE (ZMQ), Open5GS, the ZMQ configs /root/gnb-zmq.yml and /root/ue-zmq.conf, and the COSMOS package repository in its apt sources |
Software components
| Component | Version | Source |
|---|---|---|
| OCUDU gNB | in ocudu.ndz (verified with commit e0db566aac, 2026-09-30) |
OCUDU |
| srsUE (srsRAN_4G) | in ocudu.ndz |
srsRAN_4G |
| Open5GS | in ocudu.ndz |
Open5GS |
| FlexRIC | package cosmos-flexric 3.0.0+40.gfbd9859e-1: FlexRIC dev commit fbd9859 (2026-11-18, after v3.0.0) with a one-line COSMOS fix, built for E2AP_V2 + KPM_V3_00 |
COSMOS apt repository; upstream duranta-project/flexric |
Spectrum / RF — none. The gNB and the UE exchange samples over ZMQ sockets on the same server
(band 3, 10 MHz, 15 kHz SCS, PLMN 00101, TAC 7).
one server (ocudu.ndz)
┌───────────────────────────────────────────────────────────────────────┐
│ srsUE ──ZMQ 2000/2001── OCUDU gNB ──N2/N3── Open5GS (AMF 127.0.0.5) │
│ (netns ue1) │ │
│ │ E2 (SCTP 127.0.0.1:36421) │
│ ▼ │
│ FlexRIC nearRT-RIC ◄──E42 (36422)── xapp_kpm_moni │
└───────────────────────────────────────────────────────────────────────┘
The user plane is unchanged from the soft-only tutorial: the UE's traffic goes from srsUE over the ZMQ
radio to the gNB and from the gNB to the Open5GS UPF. The RIC sits beside it. The gNB's E2 agent opens an
SCTP association to the nearRT-RIC on the loopback address, and the xApp connects to the RIC over E42.
Stopping the RIC changes nothing about registration or data.
ssh <username>@console.<sandbox>.cosmos-lab.org
omf tell -a offh -t <server>
omf load -i ocudu.ndz -t <server> -r 0 -o 2400 -b 600
omf tell -a on -t <server>
ocudu.ndz is a large image: -r 0 keeps the partition layout and the longer timeouts stop the1 node successfully imaged.ssh root@<server>
apt-get update && apt-get install -y cosmos-flexric iperf3
dpkg-query -W cosmos-flexric
ls /usr/lib/flexric/
...
0 upgraded, 1 newly installed, 0 to remove and 196 not upgraded.
...
Setting up cosmos-flexric (3.0.0+40.gfbd9859e-1) ...
...
cosmos-flexric 3.0.0+40.gfbd9859e-1
libccc_sm.so
libgtp_sm.so
libkpm_sm.so
libmac_sm.so
libpdcp_sm.so
librc_sm.so
librlc_sm.so
libslice_sm.so
libtc_sm.so
The package puts FlexRIC in these places:
| Path | What |
|---|---|
/usr/bin/nearRT-RIC |
the RIC |
/usr/bin/xapp_* |
all of FlexRIC's example C xApps: xapp_kpm_moni (KPM monitoring, used here), xapp_rc_moni (RC monitoring), xapp_rc_handover, xapp_gtp_mac_rlc_pdcp_moni, ... |
/usr/bin/emu_agent_* |
E2 agent emulators (a fake gNB/eNB for testing a RIC without a RAN) |
/usr/lib/flexric/ |
the service-model plugins, lib*_sm.so; pass -p /usr/lib/flexric/ to the RIC and to every xApp |
/etc/flexric/flexric.conf |
RIC address and ports: NEAR_RIC_IP = 127.0.0.1, E2 36421, E42 36422; pass -c /etc/flexric/flexric.conf |
/usr/share/flexric/28_552_kpm_meas.txt |
the KPM measurement names and units the KPM xApps print |
/usr/share/cosmos-flexric/ |
SOURCE (the exact upstream commit and build options) and the two COSMOS patches applied to it, flexric-dev-cosmos.patch (the xApp shutdown fix) and flexric-packaging.patch (the install path of the KPM unit list) |
libkpm_sm.so is the E2SM-KPM v3.00 plugin; librc_sm.so and libccc_sm.so match the gNB's other two
RAN functions. The others are FlexRIC's own service models for OAI-based stacks and stay unused here.
/root/open5gs/start.sh
systemd-run --unit=flexric-ric --collect /usr/bin/nearRT-RIC -c /etc/flexric/flexric.conf -p /usr/lib/flexric/
sleep 2; ss -A sctp -lan | grep 36421
...
=== Open5GS started (logs in /tmp/open5gs) ===
--- AMF NGAP socket ---
sctp LISTEN 0 5 127.0.0.5:38412 0.0.0.0:* users:(("open5gs-amfd",pid=3819,fd=12))
Running as unit: flexric-ric.service; invocation ID: 5b926fae1b284141b52adbe90f751d42
LISTEN 0 32 127.0.0.1:36421 0.0.0.0:*
The RIC listens on 127.0.0.1 for both E2 (36421) and E42 (36422), as set in /etc/flexric/flexric.conf.
Copy the image's ZMQ gNB configuration and add an e2 section that points at the RIC, plus a metrics
section that turns on the scheduler, MAC and RLC counters the KPM reports are built from:
cp /root/gnb-zmq.yml /root/gnb-zmq-e2.yml
cat >> /root/gnb-zmq-e2.yml <<'EOF'
e2:
enable_du_e2: true # one E2 agent per DU
e2sm_kpm_enabled: true
e2sm_rc_enabled: true
e2sm_ccc_enabled: true
addrs: 127.0.0.1 # the FlexRIC nearRT-RIC
bind_addrs: 127.0.0.1
port: 36421
metrics:
periodicity:
du_report_period: 1000
layers:
enable_sched: true
enable_mac: true
enable_rlc: true
EOF
systemd-run --unit=ocudu-gnb --collect --working-directory=/opt/ocudu/build \
bash -c 'sleep infinity | ./apps/gnb/gnb -c /root/gnb-zmq-e2.yml'
sleep 10; grep -E "NG Setup Procedure|E2 Setup procedure|Added supported RAN function" /tmp/gnb.log
Running as unit: ocudu-gnb.service; invocation ID: 2788339d8dc24da7a9b6a9163200a7ac
2026-11-20T03:38:09.566537 [NGAP ] [I] "NG Setup Procedure" started...
2026-11-20T03:38:09.569586 [NGAP ] [I] "NG Setup Procedure" finished successfully
2026-11-20T03:38:09.626759 [E2-DU ] [I] E2 Setup procedure successful.
2026-11-20T03:38:09.626783 [E2-DU ] [I] Added supported RAN function with id 2 and OID 1.3.6.1.4.1.53148.1.2.2.2
2026-11-20T03:38:09.626784 [E2-DU ] [I] Added supported RAN function with id 3 and OID 1.3.6.1.4.1.53148.1.1.2.3
2026-11-20T03:38:09.626785 [E2-DU ] [I] Added supported RAN function with id 4 and OID 1.3.6.1.4.1.53148.1.6.2.4
What to look for: E2 Setup procedure successful and three RAN functions. Function 2 is E2SM-KPM
(OID 1.3.6.1.4.1.53148.1.2.2.2), 3 is E2SM-RC and 4 is E2SM-CCC. The sleep infinity | keeps the
gNB's standard input open: the gNB exits when its input closes.
Confirm the link from the transport side as well; an ESTAB association on port 36421 is the E2 link:
ss -A sctp -an | grep 36421
ip netns add ue1
systemd-run --unit=srsue --collect --working-directory=/opt/srsran4g/build/srsue/src \
bash -c 'sleep infinity | ./srsue /root/ue-zmq.conf'
sleep 15; UE_IP=$(ip netns exec ue1 ip -4 -o addr show tun_srsue | awk '{print $4}' | cut -d/ -f1); echo "UE $UE_IP"
ip netns exec ue1 ping -c4 192.168.100.1
Running as unit: srsue.service; invocation ID: b75d0ced163d4ef3bf515033eb078e00
UE 192.168.100.2
PING 192.168.100.1 (192.168.100.1) 56(84) bytes of data.
...
4 packets transmitted, 4 received, 0% packet loss, time 3003ms
rtt min/avg/max/mdev = 21.609/25.505/33.491/4.794 ms
The UE runs in the network namespace ue1 (set by netns = ue1 in /root/ue-zmq.conf), so its traffic
really crosses the radio link instead of being short-circuited by the host's own routing.
Start a 15 Mbit/s downlink stream to the UE and run the xApp for 20 seconds:
ip netns exec ue1 iperf3 -s -1 -B "$UE_IP" -p 5201 >/tmp/iperf-ue.log 2>&1 &
sleep 1; iperf3 -c "$UE_IP" -p 5201 -t 25 -b 15M >/tmp/iperf-dl.log 2>&1 &
sleep 2
XAPP_DURATION=20 /usr/bin/xapp_kpm_moni -c /etc/flexric/flexric.conf -p /usr/lib/flexric/ \
-a 127.0.0.1 -d /tmp/ -n xappdb > /tmp/xapp-kpm.log 2>&1
grep -E "Connected E2 nodes|Successfully subscribed|Skipping|run SUCCESSFULLY" /tmp/xapp-kpm.log
grep -E "DRB.UEThpDl|DRB.UEThpUl|RRU.PrbUsedDl" /tmp/xapp-kpm.log | tail -3
sleep 5; grep receiver /tmp/iperf-dl.log
Connected E2 nodes = 1
[xApp]: Successfully subscribed to RAN_FUNC_ID 2
[xApp]: Skipping undesired E2SM-KPM REPORT style 2
[xApp]: Skipping undesired E2SM-KPM REPORT style 3
[xApp]: Successfully subscribed to RAN_FUNC_ID 2
[xApp]: Skipping undesired E2SM-KPM REPORT style 5
Test xApp run SUCCESSFULLY
DRB.UEThpDl = 16321.42 [kbps]
DRB.UEThpUl = 422.57 [kbps]
RRU.PrbUsedDl = 24 []
[ 6] 0.00-25.02 sec 44.8 MBytes 15.0 Mbits/sec receiver
What to look for: two subscriptions (styles 1 and 4; the xApp skips 2, 3 and 5), then about one
report per second per subscription, and Test xApp run SUCCESSFULLY at the end. DRB.UEThpDl sits just
above the iperf3 rate because the gNB counts throughput at the RLC layer, headers included.
DRB.UEThpUl is a few hundred kbit/s: the TCP acknowledgements of the downlink stream. The xApp also
stores every report in the SQLite database /tmp/xappdb.
| Check | Command | Expected |
|---|---|---|
| FlexRIC installed | dpkg-query -W cosmos-flexric |
cosmos-flexric 3.0.0+40.gfbd9859e-1 |
| RIC listening | ss -A sctp -lan \| grep 36421 |
LISTEN on 127.0.0.1:36421 |
| E2 Setup | grep "E2 Setup procedure" /tmp/gnb.log |
E2 Setup procedure successful |
| E2 link | ss -A sctp -an \| grep 36421 |
an ESTAB association |
| UE attached | ip netns exec ue1 ping -c4 192.168.100.1 |
0 % loss |
| KPM subscription | grep "Successfully subscribed" /tmp/xapp-kpm.log |
two lines (styles 1 and 4) |
| KPM data | grep DRB.UEThpDl /tmp/xapp-kpm.log |
about 1 report/s per subscription, close to the iperf3 rate |
Platform A = 2× Intel Xeon Gold 6226 @ 2.70 GHz (24 cores / 24 threads); platform B = 2× Intel Xeon Gold 6126 @ 2.60 GHz (24 cores / 48 threads), matching the platform
letters on the OCUDU results page.
| Rig | Platform | iperf3 DL (receiver) | KPM DRB.UEThpDl |
KPM DRB.UEThpUl |
Reports | Date |
|---|---|---|---|---|---|---|
| OCUDU ZMQ (band 3, 10 MHz) + Open5GS, srsUE | B | 15.0 Mbit/s (offered 15) | 16.58–16.77 Mbit/s | 0.36–0.43 Mbit/s | 38–39 in 20 s (styles 1 + 4) | 2026-11-09, two runs (FlexRIC dev e047ff4c built from source) |
| OCUDU ZMQ (band 3, 10 MHz) + Open5GS, srsUE | A | 15.0 Mbit/s (offered 15) | 16.29–16.80 Mbit/s | 0.32–0.42 Mbit/s | 38–39 in 20 s (styles 1 + 4) | 2026-11-19, two runs (FlexRIC dev fbd9859 built from source) |
| OCUDU ZMQ (band 3, 10 MHz) + Open5GS, srsUE | A | 15.0 Mbit/s (offered 15) | 15.93–16.46 Mbit/s | 0.31–0.42 Mbit/s | 40 in 20 s (styles 1 + 4) | 2026-11-20, two runs (cosmos-flexric 3.0.0+40.gfbd9859e-1) |
RRU.PrbUsedDl read 24–25 of the cell's 52 PRBs during the stream. Ping from the UE to the core: 0 % loss, 22–33 ms. The ZMQ radio caps this cell at about 25 Mbit/s;
the point of the table is how closely the RIC's view follows the measurement at the UE.
systemctl stop srsue ocudu-gnb flexric-ric
/root/open5gs/stop.sh
ip netns del ue1
Then free the server from the console: omf tell -a offh -t <server>.
| Symptom | Cause | Fix |
|---|---|---|
E: Unable to locate package cosmos-flexric |
the package lists are stale, or the server runs an image without the COSMOS apt repository | apt-get update first; use ocudu.ndz |
the RIC or the xApp exits at start-up with a plugin or dlopen error, or loads no service models |
no -p option: FlexRIC has no default plugin directory |
pass -p /usr/lib/flexric/ to nearRT-RIC and to every xApp |
xapp_kpm_moni prints Cannot open the file for 28_552_kpm_meas.txt |
a source-built xApp whose build directory was moved or removed (it opens the list from there) | use the packaged /usr/bin/xapp_kpm_moni, which reads /usr/share/flexric/28_552_kpm_meas.txt |
xapp_kpm_moni crashes with Segmentation fault right after Successfully subscribed |
FlexRIC v3.0.0: the xApp subscribes to every REPORT style the E2 node offers but only implements 1 and 4; OCUDU offers 1–5 | use the packaged xApp (dev branch), which skips them (Skipping undesired E2SM-KPM REPORT style N) |
xapp_kpm_moni crashes with Segmentation fault at the end of its run, in get_meas_unit() |
an unpatched source build: main() frees the measurement-unit table while the indication worker is still printing a report |
the packaged xApp carries the fix (/usr/share/cosmos-flexric/flexric-dev-cosmos.patch) |
the xApp's KPM ind_msg latency is a huge or negative number |
the gNB's report timestamp and the xApp's clock use different conventions | ignore it with OCUDU; it is meaningful with OAI-based gNBs |
the gNB logs no E2 Setup line, ss shows no association |
the RIC is not running, or the gNB config has no e2 section |
systemctl status flexric-ric; check addrs / port in /root/gnb-zmq-e2.yml |
| E2 Setup succeeds but the KPM subscription fails or no reports arrive | the RIC and the gNB disagree on the KPM version (FlexRIC's default build is KPM v2.03) | the package is built for KPM v3.00; for a source build, configure with -DKPM_VERSION=KPM_V3_00 |
the xApp prints Connected E2 nodes = 0 and aborts |
the gNB had not completed E2 Setup when the xApp started | start the xApp after Step 3's check |
UE never attaches; srsUE logs Adding PDU session failed |
the ue1 namespace does not exist |
ip netns add ue1 before starting srsUE |
| after stopping the UE, a new UE never attaches | the ZMQ stream is stateful | restart the gNB, then the UE |
You need this only to change FlexRIC itself, for example to write your own xApp in C. The package is the
same code, so a source build behaves the same with the steps above once you point -p at your own plugin
directory. These commands were verified on ocudu.ndz and duranta.ndz on 2026-11-19 (platform A); the
two builds take about 3 minutes.
FlexRIC's monitoring xApp decodes NR RRC messages, and its build generates that code with the mouse07410
fork of asn1c at the commit FlexRIC pins, 940dd5fa (the one FlexRIC's scripts/install_asn1c.sh
and its Dockerfiles use). Neither the Ubuntu asn1c package nor a newer fork commit builds it. Install it
into its own prefix, /opt/asn1c-flexric: OpenAirInterface-based images keep their asn1c in
/opt/asn1c, and overwriting it breaks the gNB build. Then build FlexRIC dev with the COSMOS shutdown
fix (the file the package ships as /usr/share/cosmos-flexric/flexric-dev-cosmos.patch; the
KPM report-style fix is already on dev):
apt-get update && apt-get install -y libsctp-dev cmake-curses-gui libpcre2-dev libsqlite3-dev autoconf automake libtool bison flex
git clone https://github.com/mouse07410/asn1c /opt/src/asn1c
cd /opt/src/asn1c && git checkout 940dd5fa9f3917913fd487b13dfddfacd0ded06e
autoreconf -iv && ./configure --prefix=/opt/asn1c-flexric && make -j"$(nproc)" && make install
git clone https://github.com/duranta-project/flexric /opt/src/flexric
cd /opt/src/flexric && git checkout fbd9859
cat > /root/flexric-dev-cosmos.patch <<'EOF'
diff --git a/examples/xApp/c/monitor/xapp_kpm_moni.c b/examples/xApp/c/monitor/xapp_kpm_moni.c
index 6c6f1db..144ef68 100644
--- a/examples/xApp/c/monitor/xapp_kpm_moni.c
+++ b/examples/xApp/c/monitor/xapp_kpm_moni.c
@@ -615,11 +615,13 @@ int main(int argc, char* argv[])
}
free(hndl);
- free_kpm_meas_unit_hash_table();
-
// Stop the xApp
while (try_stop_xapp_api() == false)
usleep(1000);
+ // Free the unit table only after the xApp (and its indication worker) has stopped:
+ // freeing it first races a KPM callback still printing a report (use-after-free in get_meas_unit)
+ free_kpm_meas_unit_hash_table();
+
printf("Test xApp run SUCCESSFULLY\n");
}
EOF
git apply /root/flexric-dev-cosmos.patch
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DE2AP_VERSION=E2AP_V2 -DKPM_VERSION=KPM_V3_00 \
-DXAPP_MULTILANGUAGE=OFF -DASN1C_EXEC_PATH=/opt/asn1c-flexric/bin/asn1c
make -j"$(nproc)" nearRT-RIC xapp_kpm_moni kpm_sm rc_sm ccc_sm mac_sm rlc_sm pdcp_sm gtp_sm slice_sm tc_sm
mkdir -p /opt/flexric-sm && find /opt/src/flexric/build/src/sm -name '*_sm.so' -exec cp {} /opt/flexric-sm/ \;
The RIC is then /opt/src/flexric/build/examples/ric/nearRT-RIC, the xApp
/opt/src/flexric/build/examples/xApp/c/monitor/xapp_kpm_moni (it reads its KPM unit list from the build
directory, so keep that directory), the configuration /opt/src/flexric/flexric.conf and the plugin
directory /opt/flexric-sm/. Build only the listed targets: the whole tree (make alone) also builds an
F1AP example with the same asn1c needs.
| Source-build symptom | Cause | Fix |
|---|---|---|
cc1: fatal error: .../RRC_MESSAGES/ANY_aper.c: No such file or directory |
the Ubuntu asn1c package, or no asn1c at all, generated the NR RRC code |
build asn1c 940dd5fa and pass -DASN1C_EXEC_PATH=/opt/asn1c-flexric/bin/asn1c |
undefined reference to 'NULL_decode_cbor' / 'OPEN_TYPE_print_member', or sqlite3_wrapper.c: error: 'ul_msg->message' is a pointer |
an asn1c newer than the commit FlexRIC pins |
build asn1c at 940dd5fa; remove /opt/src/flexric/build and configure again |
On this wiki
External
mouse07410/asn1c — https://github.com/mouse07410/asn1cAuthor(s): COSMOS team · Last verified: 2026-11-20 (cosmos-flexric 3.0.0+40.gfbd9859e-1 = FlexRIC dev fbd9859 + one-line COSMOS fix, OCUDU e0db566aac, soft ZMQ + Open5GS, platform A) · Tested image/release: ocudu.ndz, cosmos-flexric 3.0.0+40.gfbd9859e-1 · Tags: 5g, oran, ric, e2, kpm, xapp, flexric, ocudu, srsran