Part of: OCUDU on COSMOS · 4G / 5G & O-RAN · Step 4 of the OCUDU learning path · Previous: ocudu-72
Use OCUDU's own M-Plane tools to configure an O-RAN 7.2 radio unit over NETCONF, derive the DU's fronthaul configuration from what the radio reports, and move the radio's carrier to a new frequency without restarting anything. The O-RU is simulated, so this runs on any server, with no radio and no O-RU reservation.
In ocudu-72 the O-RU ran standalone from its stored configuration, because OCUDU's gnb has no M-Plane client. This tutorial shows the other way to configure an O-RU: a management client writes its fronthaul settings over the M-Plane, in the order a validating O-RU requires, and reads them back. Moving a carrier while the O-RU keeps running is the building block for dynamic spectrum use, for example moving a cell away from interference.
Concepts
- M-Plane — the O-RAN management plane. It configures the O-RU itself: VLAN and MAC addresses, IQ compression, carriers, frequency, bandwidth, gain and when they are active. It is NETCONF (RFC 6241) over SSH.
- YANG models — the O-RAN WG4 data models (
o-ran-uplane-conf,o-ran-processing-element,o-ran-module-cap,o-ran-delay-management,o-ran-supervision, …) that define what can be configured. An O-RU validates every edit against them.ocudu_o1_adapter— OCUDU's M-Plane client (src/ru_controller.py). It writes a complete fronthaul configuration, activates the carriers, and derives the matching OCUDUru_ofhconfiguration.ocudu_netconf— OCUDU's NETCONF server (netopeer2 + sysrepo) in a container. Started with--config ruit is a simulated O-RU: it loads the O-RAN WG4 models and validates every edit, but nothing behind it drives a radio.- NR-ARFCN — the channel number of an NR carrier. In 3–24.25 GHz the frequency is 3000 MHz + 15 kHz × (N − 600000), so 623334 is 3350.01 MHz.
ru_ofh section from an O-RU's M-Plane configuration.Everything runs on one server:
| Link | Between | Carried over |
|---|---|---|
| M-Plane | ru_controller.py ↔ simulated O-RU |
NETCONF over SSH to port 830 of the mock-oru container, published on 127.0.0.1 only |
| Datastore check | ocudu-mplane_probe.py ↔ simulated O-RU |
NETCONF get-config on the same port, read after every step |
| Console → server | the tutorial ↔ the server | SSH as root, as in every tutorial |
The NETCONF port is published on the loopback interface only, so the simulated O-RU and its throwaway account cannot be reached from other nodes. The probe reads what the O-RU stored, so every check looks at the O-RU rather than at the client's own report.
| 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-mplane verifies, on each node:
Not in the package - you provide:
You will also need:
docker.io, git and python3-venv, pulls a 173 MB container image and installs the client's Python packages.Nothing radiates, so no radio and no O-RU reservation are involved.
On the console of your domain, name your server and ask whether the tutorial can run. The check is read-only.
export OMF_NODES="<node>"
cosmos-tutorial check ocudu-mplane
It ends with RUNNABLE or NOT RUNNABLE and the reasons. The tutorial needs no special image: baseline.ndz is enough, and ocudu.ndz works too.
omf load -i baseline.ndz -t <node>
omf tell -a on -t <node>
export OMF_NODES=<node>
cosmos-tutorial check ocudu-mplane
cosmos-tutorial run ocudu-mplane # ansible
cosmos-tutorial run ocudu-mplane --mode manual # manual
cosmos-tutorial jupyter ocudu-mplane # jupyter
cosmos-tutorial run ocudu-mplane --mode parity # parity
cosmos-tutorial run ocudu-mplane --mode teardown # teardown
All three modes read one parameter file, use one parser, and write the same JSON result (mplane_contract_<mode>.json) into ~/cosmos-runs/ocudu-mplane/<UTC>-<mode>/ on the console. This tutorial takes exactly one node.
The playbook installs the tools if they are missing, checks out the M-Plane client at the pinned commit in its own virtual environment, starts a fresh simulated O-RU, probes it, provisions the fronthaul, reads back the derived DU configuration, moves the carrier, and writes the result.
The manual mode runs the commands below for you, from the console. Run them yourself to see what each part does. Log in to the node first; copy the probe from the tutorial's directory on the console (scp $(cosmos-tutorial which ocudu-mplane)/ocudu-mplane_probe.py root@<node>:/root/).
ssh root@<node>
Step 1 — Install the tools. Docker for the simulated O-RU, and OCUDU's M-Plane client at the commit the tutorial was verified with, in its own virtual environment.
apt-get update -qq && apt-get install -y -qq docker.io git python3-venv
git clone -q https://gitlab.com/ocudu/ocudu_elements/ocudu_oran_apps/ocudu_o1_adapter.git /opt/ocudu_o1_adapter
cd /opt/ocudu_o1_adapter && git checkout -q dc07618c401180c348ec2f10d5e61239b8981f85
python3 -m venv /opt/mplane-venv && /opt/mplane-venv/bin/pip install -q -r requirements.txt
Step 2 — Start the simulated O-RU. The container creates the NETCONF account named in the parameters at start; it exists only inside this throwaway container.
docker run -d --name mock-oru -p 127.0.0.1:830:830 \
-e NETCONF_SSH_USERNAME=oru-admin -e NETCONF_SSH_PASSWORD=tutorial-only \
registry.gitlab.com/ocudu/ocudu_elements/ocudu_oran_apps/ocudu_netconf/netconf_amd64:746ed5bc2c77af6fe098946417aa69ef8bfd3e18 --config ru
docker logs mock-oru 2>&1 | grep "Listening on"
Step 3 — Probe it: which O-RAN models does this O-RU implement? A NETCONF 1.1 server lists its YANG modules in the ietf-yang-library (RFC 8525), not in its <hello>, so the probe reads that.
/opt/mplane-venv/bin/python /root/ocudu-mplane_probe.py 127.0.0.1 830 oru-admin tutorial-only
Step 4 — Provision the fronthaul. One call writes every object, in order, with the values of a COSMOS Benetel RAN650 cell: VLAN 4, the O-RU and DU MAC addresses, BFP-9 compression, a 100 MHz carrier at NR-ARFCN 623334, and activation.
cd /opt/ocudu_o1_adapter && /opt/mplane-venv/bin/python src/ru_controller.py --host 127.0.0.1 --port 830 -u oru-admin -p tutorial-only \
--set_full_config --ru_mac_addr 8c:1f:64:d1:11:f0 --vlan 4 --du_mac_addr 00:11:22:33:44:66 \
--iq_bitwidth 9 --compression_type STATIC --rf_bandwidth_hz 100000000 \
--dl_arfcn 623334 --dl_freq 3350010000 --ul_arfcn 623334 --ul_freq 3350010000 --tx_gain 24 --carrier_state ACTIVE
Step 5 — Read back the DU configuration the O-RU implies.
cd /opt/ocudu_o1_adapter && /opt/mplane-venv/bin/python src/ru_controller.py --host 127.0.0.1 --port 830 -u oru-admin -p tutorial-only --get_config
Step 6 — Move the carrier to 3380.01 MHz. The M-Plane changes a carrier's frequency only while it is INACTIVE, so the move is three calls: deactivate, change, activate. The O-RU keeps running throughout.
C="cd /opt/ocudu_o1_adapter && /opt/mplane-venv/bin/python src/ru_controller.py --host 127.0.0.1 --port 830 -u oru-admin -p tutorial-only"
bash -c "$C --activate_carriers --carrier_state INACTIVE"
bash -c "$C --set_carriers --rf_bandwidth_hz 100000000 --dl_arfcn 625334 --dl_freq 3380010000 --ul_arfcn 625334 --ul_freq 3380010000 --tx_gain 24"
bash -c "$C --activate_carriers --carrier_state ACTIVE"
/opt/mplane-venv/bin/python /root/ocudu-mplane_probe.py 127.0.0.1 830 oru-admin tutorial-only | grep carrier
The notebook runs on the console and drives the node over SSH. It performs the same steps with explanations between them. 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, each against its own fresh simulated O-RU, so no mode can read another's configuration. It passes when every mode connects, finds all seven O-RAN WG4 models, completes the provisioning, stores and derives the expected carrier, completes the move within 30 s, and the modes agree on the module and carrier counts. The harness runs the teardown on every exit.
After Step 2, the NETCONF server is listening:
[INF]: LN: Listening on 0.0.0.0:830 for SSH connections.
After Step 3, the probe lists the models. No carriers are configured yet, so it prints none:
connected=1
n_capabilities=31
n_modules=100
has_o_ran_uplane_conf=1
has_o_ran_module_cap=1
has_o_ran_processing_element=1
has_o_ran_delay_management=1
has_o_ran_supervision=1
has_o_ran_sync=1
has_o_ran_hardware=1
After Step 4, the client reports each edit in order:
[INFO] Connected to 127.0.0.1:830 as oru-admin
[INFO] Editing IETF interfaces
[INFO] Editing ORAN processing elements
[INFO] Editing ORAN Uplane Tx endpoints elements
[INFO] Editing ORAN Uplane Rx endpoints elements
[INFO] Editing ORAN Uplane Tx array carriers
[INFO] Editing ORAN Uplane Rx array carriers
[INFO] Editing ORAN Uplane low level Tx links
[INFO] Editing ORAN Uplane low level Rx links
[INFO] Editing ORAN Uplane TDD pattern
[INFO] Editing ORAN Uplane carrier active
After Step 5, the client prints the sections of an OCUDU gnb.yml that follow from the O-RU's configuration:
# Auto-generated OFH configuration
ru_ofh:
cells:
- network_interface: uc-vlan4
ru_mac_addr: 8c:1f:64:d1:11:f0
du_mac_addr: 00:11:22:33:44:66
vlan_tag_cp: 4
vlan_tag_up: 4
compr_method_dl: bfp
compr_bitwidth_dl: 9
is_prach_cp_enabled: true
cell_cfg:
nof_antennas_dl: 4
nof_antennas_ul: 4
channel_bandwidth_MHz: 100
dl_arfcn: 623334
After Step 6, every carrier is stored at the new frequency and active:
tx_carrier=Tx-Array-Carrier-00|3380010000|100000000|ACTIVE
tx_carrier=Tx-Array-Carrier-01|3380010000|100000000|ACTIVE
tx_carrier=Tx-Array-Carrier-02|3380010000|100000000|ACTIVE
tx_carrier=Tx-Array-Carrier-03|3380010000|100000000|ACTIVE
rx_carrier=Rx-Array-Carrier-00|3380010000|100000000|ACTIVE
...
A parity run ends with PARITY: PASS and node released; the move takes about 2 s, most of it the start-up of three client processes.
Change any of these with cosmos-tutorial run ocudu-mplane --params my.yml. An unknown key or a wrong type is refused. cosmos-tutorial params ocudu-mplane prints the file.
| Key | Default | Meaning |
|---|---|---|
mplane_image |
registry.gitlab.com/ocudu/ocudu_elements/ocudu_oran_apps/ocudu_netconf/netconf_amd64:746ed5bc2c77af6fe098946417aa69ef8bfd3e18 |
|
mplane_client_repo |
https://gitlab.com/ocudu/ocudu_elements/ocudu_oran_apps/ocudu_o1_adapter.git |
|
mplane_client_commit |
dc07618c401180c348ec2f10d5e61239b8981f85 |
|
mplane_client_dir |
/opt/ocudu_o1_adapter |
|
mplane_venv |
/opt/mplane-venv |
|
mplane_container |
mock-oru |
|
mplane_port |
830 |
|
mplane_user |
oru-admin |
NETCONF/SSH account the container creates at start. |
mplane_password |
tutorial-only |
|
mplane_ru_mac |
8c:1f:64:d1:11:f0 |
|
mplane_du_mac |
00:11:22:33:44:66 |
|
mplane_vlan |
4 |
|
mplane_iq_bitwidth |
9 |
|
mplane_compression |
STATIC |
|
mplane_bandwidth_hz |
100000000 |
|
mplane_tx_gain |
24 |
|
mplane_arfcn_a |
623334 |
carrier A (provisioned first) and carrier B (the frequency move). |
mplane_arfcn_b |
625334 |
3380.010 MHz, n78 |
mplane_max_retune_ms |
30000 |
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'
mplane_arfcn_b: 630000
EOF
cosmos-tutorial run ocudu-mplane --params my.yml
In band n78 the NR-ARFCN runs from 620000 to 653333. To change the tutorial itself, cosmos-tutorial copy ocudu-mplane puts an editable copy in the current directory, which then takes precedence over the installed one.
ru_ofh section is what an OCUDU DU must use to talk to this O-RU. Against a real O-RU the client also reads its delay profile (o-ran-delay-management) and derives the DU's fronthaul timing windows; the simulated O-RU has no real delays.On an O-DU server loaded with ocudu.ndz, with the client installed as in Step 1 and the O-RU switched to M-Plane mode (benetel-ru-mode.sh mplane, at least 150 s after the O-RU booted), OCUDU's resident session provisions the O-RU and supervises it. The O-RU's address comes from the COSMOS O-RU tools, exactly as in ocudu-72:
RU_IP=$(python3 $(cosmos-tutorial which ocudu-72)/cosmos_addr.py --value auto oru benetel --du <du-node>) # on the console
# on the O-DU server, with the DU's SSH key that the O-RU trusts
MPLANE_KEY=/root/oru/ssh_keys/id_ed25519 MPLANE_BASE_INTERFACE=eth0 MPLANE_CARRIER_NAMES=arrays \
MPLANE_SCRIPT=o1_adapter.py /opt/mplane-venv/bin/python ocudu-mplane/ocudu-mplane_keyauth.py /opt/ocudu_o1_adapter \
--profile ru --ru_supervise --ru_netconf_host $RU_IP --ru_netconf_username oranbenetel \
--ru_netconf_password unused --ru_provision_config ocudu-mplane/ocudu-mplane_benetel-ran650.yaml
# ... "O-RU provisioned; carrier activation receipt: RxArray0=READY, ... TxArray3=READY"
python3 ocudu-mplane/ocudu-mplane_gnb_overlay.py gnb.yml ocudu-mplane/ocudu-mplane_gnb-ran650-overlay.yml
The gNB is the ocudu-72 Benetel configuration plus the overlay. What differs from the simulated O-RU, and what the shipped helpers do about it:
| Real-O-RU difference | Handling |
|---|---|
| The O-RU's NETCONF user logs in with the DU's SSH key; the client only does passwords | ocudu-mplane_keyauth.py runs the unchanged client with the key (MPLANE_KEY) and drops the password |
One physical port, eth0, carries management and fronthaul; the client edits a port it calls fronthaul1 |
MPLANE_BASE_INTERFACE=eth0 adds only the uc-vlan4 interface on it |
Fixed endpoint names (LowLevelTxEndpoint0-3, LowLevelRxEndpoint0-3, LowLevelRxPrachEndpoint0-3) |
listed in ocudu-mplane_benetel-ran650.yaml |
Activation is refused (Validation failed) with two carriers and the client's carrier names |
the profile uses all four branches, PRACH frame structure 188, n_ta_offset 0, and MPLANE_CARRIER_NAMES=arrays names each carrier after its array |
| In M-Plane mode the O-RU switches to dynamic compression headers and sends PRACH uncompressed | the gNB overlay: no static compression headers, PRACH none/16 |
| At metres of range the uplink saturates at the default PUSCH P0, so 64QAM fails and the UE never registers | the overlay sets p0_nominal_with_grant: -96 |
A written tx_gain is applied only at the next carrier activation |
reactivate_for_gain: true in the profile |
| Links cannot be modified once written | ocudu-mplane_cleanup.py removes the client's carriers and links before a new layout |
ocudu-mplane_keyauth.py also binds the adapter's unauthenticated state API (:5000) to the loopback interface instead of all interfaces. ocudu-mplane_dump.py saves the O-RU's running configuration and state; that file includes the O-RU's private key in cleartext, so never share it unredacted. On 2026-10-25 this path carried a Quectel modem at TCP 162 Mbit/s downlink and 77 Mbit/s uplink.
| Symptom | Cause | Fix |
|---|---|---|
docker run fails with pull access denied or a timeout |
the node cannot reach registry.gitlab.com |
check the node's internet access: curl -sI https://registry.gitlab.com |
The probe prints connected=0 … Authentication failed |
the container was started without, or with other, NETCONF_SSH_USERNAME/NETCONF_SSH_PASSWORD values than the parameters |
remove and restart the container with the values from the parameters |
The probe prints connected=0 … Connection refused right after docker run |
the NETCONF server is still starting | wait for Listening on 0.0.0.0:830 in docker logs mock-oru |
cosmos-tutorial check fails on port 830 |
another NETCONF server, or a previous mock-oru, holds the port |
run the teardown, or docker rm -f mock-oru |
has_o_ran_* = 0 from your own NETCONF client |
it checked the <hello> capabilities |
a NETCONF 1.1 server lists modules in ietf-yang-library; read that, as the probe does |
An edit is refused with an rpc-error |
a value does not satisfy the YANG model (for example a MAC or VLAN out of range) | read the error text; the simulated O-RU validates like a real one |
pip install fails building lxml |
no internet access, or an old pip | check internet access; /opt/mplane-venv/bin/pip install -U pip and retry |
Benetel: Cannot add linux [eth0.4] VLAN interface, return status: 2 |
the O-RU already has a Linux eth0.4 from its boot |
on the O-RU, once: ip link del eth0.4, then provision again |
Benetel: the gNB logs smaller than the expected IQ samples size of '7644' thousands of times a second |
PRACH decoded as BFP-9 with static headers while the O-RU sends it uncompressed with dynamic headers | apply ocudu-mplane_gnb-ran650-overlay.yml; the remaining smaller than the user data compression header length line at info level is harmless padding |
Benetel: the O-RU radiates the previous tx_gain |
the O-RU applies a written gain at the next activation | keep reactivate_for_gain: true in the profile |
Benetel: When condition ... static-config-supported = 'PRACH' not satisfied |
a static PRACH reference was written without the endpoint's own static-config-supported leaf |
use ocudu-mplane_keyauth.py, which writes both |
Benetel: Authentication failed although the key is right |
a password was passed alongside the key | use ocudu-mplane_keyauth.py, which drops it |
| Benetel: the O-RU stays dark after switching it to M-Plane mode | the mode was switched right after a cold boot | power-cycle it and switch at 150 s of O-RU uptime or later |
After any mode, run the teardown from the console. It removes the simulated O-RU container by its exact name:
OMF_NODES=<node> cosmos-tutorial run ocudu-mplane --mode teardown
After the manual steps, docker rm -f mock-oru on the node does the same. 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-mplane/. To change anything, cosmos-tutorial copy ocudu-mplane puts an editable copy in the current directory, and cosmos-tutorial run ocudu-mplane then runs that copy instead of the installed one (cosmos-tutorial which ocudu-mplane shows which will run). Repository (GitLab account needed, not needed to run or change it): packages/cosmos-experiments-ocudu/usr/share/cosmos-experiments/ocudu-mplane.
Last verified 2026-10-28: three-mode parity PASS from the installed cosmos-experiments-ocudu package, cold start (all devices off), on sb1. The real-O-RU path was verified on 2026-10-25 with the Benetel RAN650 (1× AMD EPYC 9355P), a modem attach and iperf3. OCUDU builds and their measurements are on OCUDU performance by build.
References: ocudu_o1_adapter M-Plane client and its simulator notes · ocudu_netconf · O-RAN Alliance specifications (O-RAN.WG4.MP and its YANG models) · RFC 6241 (NETCONF) · RFC 8525 (YANG library) · 3GPP TS 38.104 (NR-ARFCN, section 5.4.2.1) · on this wiki: OCUDU on COSMOS · O-RAN and the 7.2x fronthaul · O-RU pool · O-RAN SC SMO.
Author(s): COSMOS team · Package: cosmos-experiments-ocudu (cosmos-tutorial run ocudu-mplane) · Tags: ocudu, oran, m-plane, netconf, yang, o-ru, 7.2