From scratch to a phone browsing the internet. The installation has three independent parts; do them in order and stop wherever you want.
| Part | Result | Where | Time |
|---|---|---|---|
| 1. Core and dashboard | Open5GS + UERANSIM + dashboard, tested | core machine | 15–30 min |
| 2. free5GC (optional) | second core, switchable from the dashboard | core machine | 15 min |
| 3. Radio: OCUDU on Kubernetes | real gNB as a pod on the RAN node | both machines | ~1 h |
Next: day-to-day operation.
- Ubuntu 24.04 LTS (desktop or server), x86_64; CPU with AVX (MongoDB 8); 8 GiB of RAM; 20 GiB free.
- Internet access (apt, k3s, Helm, GitHub, Docker Hub) and
sudo. - For the radio: a dedicated network port connected to the RAN machine (fiber or copper), ideally MTU 9000.
The machine must already run the OCUDU gNB natively with your radio. InnovaNetwork moves that gNB to Kubernetes; it does not prepare the machine. First make sure you have:
- a low-latency kernel, isolated CPUs for the gNB (
isolcpus) and 1 GiB hugepages; - a NIC with a VF on
vfio-pci(DPDK) for the fronthaul and working PTP (grandmaster with GNSS or another one); - the OCUDU source in a Git folder (e.g.
~/ocudu) and the gNB.ymlfiles in~/ocudu/configs/; - Docker installed (to build the image);
- passwordless SSH from the core machine to the RAN machine (
ssh-copy-id user@fiber-ip).
The reference setup is described in hardware/e810-liteon.md.
Core machine.
git clone https://github.com/Miguelclunardi/InnovaNetwork.git ~/InnovaNetwork
cd ~/InnovaNetwork
nano config.envconfig.env is commented line by line. The minimum to review:
| Section | Variables | Example |
|---|---|---|
| PLMN | MCC, MNC, TAC, NETWORK_NAME |
001, 01, 1, InnovaOpen5GS |
| Slices | SLICES (SST:SD:DNN:pool) |
"1:111111:internet:10.45.0.0/16" |
| Fiber to the gNB | RAN_LINK_ENABLED, RAN_LINK_IFACE, RAN_LINK_CIDR, AMF_N2_IP, UPF_N3_IP |
true, enp5s0f1, 10.10.0.0/24, 10.10.0.10, 10.10.0.11 |
| gNB in the dashboard | GNB_METRICS_URL, GNB_LOG_SSH, GNB_CTL_MODE, GNB_CTL_SSH, GNB_CTL_DIR |
ws://10.10.0.1:8001, … |
| O-RU in the dashboard | RU_MGMT_IP, RU_SSH_USER, RU_MGMT_LOCAL_CIDR |
10.101.131.59 |
Without a radio, leave RAN_LINK_ENABLED=false and the gNB/O-RU variables empty.
sudo ./install.sh # 5–15 min the 1st time; log in logs/install.log
./test.sh # pods → NRF → NG Setup → registration → session → pingExpected:
RESULT: 7 checks OK, 0 failures
The installer, in steps that only act when something changed: validates the configuration → packages, modules
(SCTP) and sysctl → stable interface k3s0 → k3s → Helm and charts → Multus and the fiber network → Open5GS →
subscribers → UERANSIM → dashboard and agents → boot units → the user's ~/.kube/config.
At the end it shows the dashboard address and where the administrator password is:
sudo cat /opt/open5gs-k3s/state/dashboard-admin-passwordUseful options:
| Command | Does |
|---|---|
sudo ./install.sh --deploy-only |
re-applies only the core, UERANSIM, subscribers and dashboard (does not touch packages or k3s) |
sudo ./install.sh --dashboard-only |
reinstalls only the dashboard and the agents (does not touch the core or the gNB) |
sudo ./uninstall.sh |
removes the core (levels --k3s, --purge) |
Core details: components/open5gs.md. Guided tutorial: First test with UERANSIM.
The dashboard RU tab reads the O-RU over SSH. The password stays out of git, in a root-owned file:
printf 'RU_PASS=%s\nRU_ENABLE=%s\n' 'SSH_PASSWORD' 'ENABLE_PASSWORD' | \
sudo install -m 0640 -g "$(id -gn)" /dev/stdin /opt/open5gs-k3s/state/ru-credentials
sudo systemctl restart open5gs-k3s-ruCore machine, with part 1 installed.
sudo ./free5gc/setup-gtp5g.sh # UPF kernel module (once; DKMS)
nano free5gc/free5gc.env # IPs on the fiber, pools, network name
./free5gc/install.sh # no sudo; namespace free5gc
./free5gc/install.sh --import-open5gs # copies the SIMs registered in Open5GS
./free5gc/test.sh # "6 ok, 0 failure(s)"
sudo ./install.sh --dashboard-only # the dashboard starts offering the core switchfree5GC comes up running. To keep it as a standby, switch back to Open5GS from the dashboard (Control tab → Active core). Details: components/free5gc.md.
Depends on your setup. The values in
ran/ocudu/ocudu.envare those of the reference setup (Intel E810 + LiteOn, split 7.2). Review all of them before you start.
Each step says which machine it runs on. ./ran/ocudu/… commands run on the core machine, inside the
repository; ~/innovanetwork-ran/no-ran.sh … commands run on the RAN machine.
nano ran/ocudu/ocudu.env| Variable | Example | Meaning |
|---|---|---|
OCUDU_NODE, OCUDU_NODE_SSH |
innovaserver, innovaserver@10.10.0.1 |
node name and SSH access over the fiber |
OCUDU_NODE_IP, OCUDU_NODE_IFACE |
10.10.0.1, ens4f3np3 |
node IP and interface in the cluster (the fiber, never the fronthaul) |
OCUDU_SERVER_VIA |
10.10.0.2 |
IP of the core machine on the fiber (route to 10.254.254.1) |
OCUDU_SRC_DIR, OCUDU_CONFIG_DIR |
/home/innovaserver/ocudu, …/configs |
gNB source and .yml files on the node |
OCUDU_DEFAULT_CONFIG, OCUDU_EXTRA_CONFIG |
gnb_split_open5gs, metricas.yml |
default .yml and the 2nd -c (metrics on port 8001) |
OCUDU_CPUS |
0-17 |
gNB CPUs (taskset) |
OCUDU_HUGEPAGES_1G, OCUDU_MEMORY_REQUEST |
2Gi, 2Gi |
hugepages and memory requested by the pod |
OCUDU_IMAGE*, OCUDU_BUILD_JOBS |
innovanetwork/ocudu-gnb, 8 |
image (tag = source commit) and build |
./ran/ocudu/install.sh copyCreates ~/innovanetwork-ran/ on the node (mode 700) with no-ran.sh and ocudu.env.
sudo ~/innovanetwork-ran/no-ran.sh image 2>&1 | tee ~/innovanetwork-ran/build.logExports the current commit of the source (git archive, without the native build/ folder) and builds it with
the official OCUDU Dockerfile (target runtime-dpdk, -march=native). Result:
innovanetwork/ocudu-gnb:<commit> (~140 MB, ~15 min). It loads the machine: avoid it during experiments.
sudo ./ran/ocudu/install.sh prepareOpens the firewall for the node (UFW, if active) and creates a join token valid for 2 h, copied to the node in
~/innovanetwork-ran/join.env (mode 600). The token never shows on the screen.
sudo ~/innovanetwork-ran/no-ran.sh join 2>&1 | tee ~/innovanetwork-ran/join.logChecks for conflicts (another Kubernetes on the kubelet ports), creates the route to the server, writes the agent configuration (IP, interface, label, taint), installs the k3s agent with the same version as the server, deletes the token and imports the image. Check on the core machine:
kubectl get nodes -o wide # the RAN node "Ready", INTERNAL-IP 10.10.0.1If the image was built afterwards: sudo ~/innovanetwork-ran/no-ran.sh import.
./ran/ocudu/install.sh --dry-run # generates and validates, without applying
./ran/ocudu/install.sh # namespace ocudu + Deployment with 0 replicas (gNB stopped)Before: core running, valid PTP/GNSS, O-RU ready and no native gNB running on the node.
./ran/ocudu/gnb.sh configs # available .yml files and the AMF of each one
./ran/ocudu/gnb.sh start gnb_split_open5gs
./ran/ocudu/gnb.sh log -f # wait for "N2: Connection to AMF … completed"In config.env: GNB_CTL_MODE="k8s" (and the node's GNB_CTL_SSH, GNB_CTL_DIR). Then:
sudo ./install.sh --dashboard-onlyThe Control tab now shows the gNB (Kubernetes) card, with start/stop/restart and the choice of the .yml.
Complete tutorial with expected results: OCUDU on Kubernetes.
| What | How | Expected |
|---|---|---|
| Cluster | kubectl get nodes |
two Ready nodes |
| Core | ./test.sh |
7 checks OK |
| gNB | ./ran/ocudu/gnb.sh log |
N2: Connection to AMF … completed, gNB started |
| O-RU | dashboard → RU tab | SYNCHRONIZED, DU Ready, ~90 % of the packets on time |
| Phone | dashboard → Overview | registered, session with an IP from the pool |
| What | Command |
|---|---|
| gNB (Deployment and namespace) | ./ran/ocudu/install.sh --remove |
| RAN node | on the node: sudo ~/innovanetwork-ran/no-ran.sh leave; on the core: kubectl delete node <node> |
| free5GC | ./free5gc/uninstall.sh; module: sudo ./free5gc/setup-gtp5g.sh --remove |
| core and dashboard | sudo ./uninstall.sh (--k3s removes k3s; --purge everything the installer created) |