-
Notifications
You must be signed in to change notification settings - Fork 8
Deploy (O‐RAN Compliant) 5G Networks based on OAI
This guide provides instructions to quickly deploy an experimental 5G network based on the OpenAirInterface (OAI) project, optionally with an O-RAN compliant E2 agent that we have developed to work with a near real-time RIC (nRT-RIC) of an O-RAN control plane.
We will use the following repositories, and they will be cross-referenced in later description.
OpenAirInterface (OAI) an open-source project that builds wireless cellular network technologies for 4G LTE and 5G New Radio (NR), including core network, base stations, and user equipments. It provides both simulation and compatibility with commodity software-defined radios (SDRs) such as USRPs.
OAI-5G (https://github.com/5GSEC/OAI-5G) is mirrored from the OpenAirInterface (OAI) project, with our extensions which implemented an O-RAN compliant E2 agent that supports communication and security telemetry collection from the gNB. It has multiple branches explained below:
- v2.1.0.secsm.osc is the enhanced version of Eurecom OAI (v2.1.0) with support of an O-RAN compliant E2 agent, allowing the OAI gNB to communicate with a near-RT RIC of an O-RAN control plane. It also supports the MobiFlow Telemetry and MobiExpert xApp (i.e., the 5G-Spector framework).
- v2.1.0 is an mirrored code branch from OAI of version v2.1.0.
- 2023.w23.secsm.sdran is the SecSM enhanced version of Eurecom OAI (2023.w23) that supports the MobiFlow Telemetry and MobiExpert xApp (i.e., the 5G-Spector framework).
- 2023.w23 is the original code branch forked from Eurecom OAI
- 2023.w23.kpm.sdran is the ONOS-RIC enhanced version that supports ONOS's basic KPM monitor xApp (https://github.com/onosproject/onos-kpimon)
- 2023.w23.secsm.flexric is an experimental branch that will extend OAI's support to SecSM on FlexRIC.
- lte.attack is the branch with a number of layer-3 exploits (see https://github.com/5GSEC/OAI-5G/blob/lte.attack/common/attacks/attack_cliopts.h and the 5G-Spector paper for the options)
- nr.attack is the branch with the layer-3 exploits implemented on 5G
With OAI-5G, you can deploy eNB / gNB / UE / nrUE. Please pick the corresponding branch based on your needs. We recommend using the latest support, i.e., v2.1.0 related branches
OAI-5G-Docker (https://github.com/5GSEC/OAI-5G-Docker). This repo contains the necessary configuration files to quickly deploy a 5G network, e.g., locally via RFSIM or USRP, or on Colosseum.
All running instructions are integrated into a single bash script run.sh. There are four different folders with the corresponding pre-defined configurations at the root of OAI-5G-Docker (to save your time):
- lte-rfsim: RF simulated LTE network (no SDR, or USRP required)
- lte-usrp: RF-based LTE network (works on USRPs)
- nr-rfsim: RF simulated NR (5G) network
- nr-usrp: RF-based NR network
It can also be used to run different attack variants (check the script for details).
Before you use this script, please make sure you have the following paths in run.sh pointing to the correct folders
_oai_root=/root/OAI-5G
_oai_config_root=/root/OAI-5G-Docker
By default, the above directories will work on Colosseum. But if you use this script on another machine, please make sure they are correct. Note that some changes may be adapted according to your actual requirement and hardware (e.g., different USRPs).
5G-Spector is the first Open Radio Access Network (O-RAN) compliant layer-3 cellular attack detection service. It is based on the revolutionary O-RAN architecture that brings unprecedented programmability that enables stakeholders (e.g., network operators) and researchers to build innovative software-defined services on cellular networks. 5G-Spector is featured in project SE-RAN and an academic publication in the Network and Distributed System Security Symposium 2024 (NDSS 2024). The full paper is available here.
To deploy a 5G network w/ RF simulation, you need to first prepare a Linux machine or VM (Ubuntu recommended). Note that OAI may have some restrictions and may not work on the latest Ubuntu versions (double-check the OAI requirements before you go).
Recommended environment:
| Env | Value |
|---|---|
| OS | Ubuntu 20.04 LTS |
| RAM | 8 GB |
| Storage | 100 GB |
Refer to: https://docs.docker.com/engine/install/ubuntu/
You can add your user to the docker group to avoid running docker with sudo:
sudo groupadd docker
sudo gpasswd -a $USER docker
Log back in to let this take effect.
Refer to: https://docs.docker.com/compose/install/standalone/
You might need to add execution permission to it:
sudo chmod +x /usr/local/bin/docker-compose
Clone the OAI-5G and OAI-5G-Docker repos.
git clone https://github.com/5GSEC/OAI-5G.git
git clone https://github.com/5GSEC/OAI-5G-Docker.git
You may also use OAI's official repositories from here.
(Note: If you wish to use Docker-based deployment for the gNB and nrUE, you can skip this part)
Check out the branch you need. This tutorial provides full guidance on deploying the 5G network with O-RAN compliance, so the following branch with be used:
cd OAI-5G
git checkout v2.1.0.secsm.osc
Enter the directory:
cd OAI-5G/cmake_targets
Run the compilation command:
./build_oai -I --gNB --nrUE --build-ric-agent -w SIMU --ninja
Explanation of the arguments:
-
-Iindicates you will install all dependencies (only when you compile for the first time) -
--gNBindicates you will compile gNodeB -
--nrUEindicates you will compile nrUE -
--build-ric-agentindicates you will compile the E2 agent (only when you choose the compatible branch) -
-w SIMUindicates you compile the RF simulation library -
--ninjato accelerate the compilation
The compilation takes a while. After a successful compilation, you will find nr-softmodem and nr-uesoftmodem under <PATH_TO_OAI-5G>/cmake_targets/ran_build/build/.
Currently it uses version v2.0.1 of the OAI's 5G core implementation. Enter OAI-5G-Docker/<config_folder>, e.g., nr-rfsim if you deploy a RF SIM 5G network. Then run:
./run_5gc.sh
Please adapt the core network configurations under OAI-5G-Docker/<config_folder> to your needs.
Wait to verify OAI 5GC deployment (all containers up and in healthy status):
$ docker ps -a
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
8f2976d7a951 oaisoftwarealliance/oai-upf:v2.0.1 "/openair-upf/bin/oa…" 2 minutes ago Up 2 minutes (healthy) 2152/udp, 8805/udp oai-upf
bab63b124a97 oaisoftwarealliance/oai-smf:v2.0.1 "/openair-smf/bin/oa…" 2 minutes ago Up 2 minutes (healthy) 80/tcp, 8080/tcp, 8805/udp oai-smf
d53123ab3c70 oaisoftwarealliance/oai-amf:v2.0.1 "/openair-amf/bin/oa…" 2 minutes ago Up 2 minutes (healthy) 80/tcp, 8080/tcp, 9090/tcp, 38412/sctp oai-amf
edbe18ff9ecb oaisoftwarealliance/oai-ausf:v2.0.1 "/openair-ausf/bin/o…" 2 minutes ago Up 2 minutes (healthy) 80/tcp, 8080/tcp oai-ausf
f1ab3cb4d704 oaisoftwarealliance/oai-udm:v2.0.1 "/openair-udm/bin/oa…" 2 minutes ago Up 2 minutes (healthy) 80/tcp, 8080/tcp oai-udm
018dbecfeec6 oaisoftwarealliance/oai-udr:v2.0.1 "/openair-udr/bin/oa…" 3 minutes ago Up 2 minutes (healthy) 80/tcp, 8080/tcp oai-udr
60a8fbe197f7 mysql:8.0 "docker-entrypoint.s…" 3 minutes ago Up 2 minutes (healthy) 3306/tcp, 33060/tcp mysql
3d51306310d4 oaisoftwarealliance/trf-gen-cn5g:jammy "/bin/bash -c ' ip r…" 3 minutes ago Up 2 minutes (healthy) oai-ext-dn
2b3e4555d296 oaisoftwarealliance/ims:latest "asterisk -fp" 3 minutes ago Up 2 minutes (healthy) ims
d975122be568 oaisoftwarealliance/oai-nrf:v2.0.1 "/openair-nrf/bin/oa…" 3 minutes ago Up 2 minutes (healthy) 80/tcp, 8080/tcp, 9090/tcp oai-nrf
To undeploy the 5GC, run:
./kill.sh
There are two deployment strategies: (1) Bare-metal deployment and (2) Docker-based deployment. Docker-based deployment will use OAI's official gNB images (so you don't have to compile the gNB binaries) while bare-metal deployment allows more flexibility such as running a locally modified gNB. Below we provide both options and will first start with bare-metal deployment using our extended OAI gNB version with E2 RIC and MobiFlow support.
First, you should create a copy of the run.sh script to your working folder with:
cp OAI-5G-Docker/run.sh ~/
Adapt the following lines to the correct system paths to OAI-5G and OAI-5G-Docker you just crawled.
_oai_root=<PATH_TO_OAI-5G>
_oai_config_root=<PATH_TO_OAI-5G-Docker>
Run
sudo ~/run.sh gnb rfsim
To verify GNB is running, you will see repeated log entries:
[NR_MAC] Frame.Slot 128.0
There will be error message like:
[RIC_AGENT] ranid 0 connecting to RIC at 192.168.84.144:36421 with IP 192.168.200.21 (my addr: 192.168.200.21)
It can be safely ignored at this momment since we haven't deployed the nRT-RIC yet.
The run-time logs and pcaps are automatically saved to the paths specified by the _log_path and _pcap_path variables in the run.sh script.
OAI also provides the option to run the gNB as separated CU and DU nodes with 7.2x split. We have also prepared corresponding configs (in the same folder with other gNB configs) for such a deployment.
To run the OAI CU node:
sudo ./run.sh gnb-cu rfsim
To run the OAI DU node:
sudo ./run.sh gnb-du rfsim
Alternatively, you could also deploy the gNB as docker containers. We use OAI's official docker images. To deploy the gNB in RF simulation mode and CU DU split, execute:
cd nr-rfsim
./run_gnb_f1.sh
This will create two docker containers for gNB CU and DU:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
c2da8c16e798 oaisoftwarealliance/oai-gnb:v2.1.0 "/opt/oai-gnb/bin/en…" 27 seconds ago Up 22 seconds (healthy) rfsim5g-oai-du
9fdcdfdf85cd oaisoftwarealliance/oai-gnb:v2.1.0 "/opt/oai-gnb/bin/en…" 28 seconds ago Up 24 seconds (healthy) rfsim5g-oai-cu
To undeploy, execute:
./kill_ran.sh
The deployment of nrUE also supports (1) bare-metal deployment and (2) docker-based deployment. Please use the same deployment method as the gNB.
Open a new terminal and run:
sudo ~/run.sh nrue* rfsim
* indicates the index of UE (chosen from 0-9)
Verify the UE is running and connected to the gNB with logs like:
[NAS] [UE] Received REGISTRATION ACCEPT message
...
[NR_PHY] ============================================
[NR_PHY] Harq round stats for Downlink: 16/0/0
[NR_PHY] ============================================
[NR_PHY] RSRP = -92 dBm
[NR_PHY] RSRP = -92 dBm
[NR_PHY] RSRP = -41 dBm
Logs and pcaps of each run will be saved at: /logs/. The configs of the UEs are available at OAI-5G-Docker/rfsim/nr-ues
To verify the UE's data traffic, use the created tunnel oaitun_ue1:
$ ping -I oaitun_ue1 -c 10 www.lemonde.fr
PING lemonde.map.fastly.net (146.75.82.217) from 12.1.1.5 oaitun_ue1: 56(84) bytes of data.
64 bytes from 146.75.82.217 (146.75.82.217): icmp_seq=1 ttl=49 time=19.6 ms
64 bytes from 146.75.82.217 (146.75.82.217): icmp_seq=2 ttl=49 time=20.8 ms
64 bytes from 146.75.82.217 (146.75.82.217): icmp_seq=3 ttl=49 time=22.8 ms
64 bytes from 146.75.82.217 (146.75.82.217): icmp_seq=4 ttl=49 time=22.8 ms
64 bytes from 146.75.82.217 (146.75.82.217): icmp_seq=5 ttl=49 time=20.2 ms
Enter the folder and execute:
cd nr-rfsim
./run_nrue.sh
This will create multiple nrUE containers with different user profiles:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
7584d6247672 oaisoftwarealliance/oai-nr-ue:v2.1.0 "/opt/oai-nr-ue/bin/…" 54 seconds ago Up 49 seconds (healthy) rfsim5g-oai-nr-ue-1
95cbbcc7a199 oaisoftwarealliance/oai-nr-ue:v2.1.0 "/opt/oai-nr-ue/bin/…" About a minute ago Up 59 seconds (healthy) rfsim5g-oai-nr-ue-0
Similarity, you could login to the UE containers through docker exec -it rfsim5g-oai-nr-ue-0 bash to verify the connectivity.
To undeploy the UE containers:
./kill_ue.sh
Follow this guide to deploy the OSC near-RT RIC and adapt the gNB config accordingly.
Run the compilation command: ./build_oai -I --gNB --nrUE --build-ric-agent -w USRP --ninja
This command has used the option -w USRP instead of -W SIMU
Similar to the RF SIM deployment, but use the nr-usrp config folder. Remove the rfsim argument when running the gNB and nrUE.
OAI-5G (https://github.com/5GSEC/OAI-5G) contains two branches for demonstrating a number of Layer-3 attacks (see https://github.com/5GSEC/OAI-5G/blob/lte.attack/common/attacks/attack_cliopts.h and the 5G-Spector paper for the options). They can run on both LTE networks and 5G networks.
To get started, clone the OAI-5G repo:
git clone https://github.com/5GSEC/OAI-5G attack-OAI
cd attack-OAI
For LTE networks:
git checkout lte.attack
cd cmake_targets
./build_oai --UE -w SIMU --ninja --noavx512
For 5G networks, run:
git checkout nr.attack.v2.1.0
cd cmake_targets
./build_oai --nrUE -w SIMU --ninja --noavx512
You can then use the run.sh script to run the attacks, by specifying the attack parameters. Before that, you need to configure the _oai_attack_root to point to the exploit OAI folder you just now cloned. Next you can run the attacks with the script, for example:
./run.sh rfsim nr-attack --bts-attack 300 --bts-delay 100
Below are the supported attack parameters:
| Attack | Example Parameters | Description |
|---|---|---|
| BTS Resource Depletion | --bts-attack <level> --bts-delay <delay> [--rrc-911] |
--bts-attack >= 5: create unique IMSI for each attack session --bts-delay <delay>: specify the delay in ms for each attack session --rrc-911: boolean argument to specify emergency attachment |
| Blind DoS | --blind-dos-attack <level> --RRC-TMSI <tmsi> |
--blind-dos-attack == 1: launch blind DoS attack --RRC-TMSI <tmsi>: specify the TMSI (decimal) value used for UE attachment |
| Downlink DoS | --dnlink-dos-attack <level> |
dnlink-dos-attack == 1: Variant 1: replace Authentication Request with Registration Reject |
| Uplink DoS | --uplink-dos-attack <level> |
uplink-dos-attack == 1: Variant 1: encode service request with invalid MAC |
| Null Cipher & Integrity | --null-cipher-integ <level> |
null-cipher-integ == 1: Variant 1: overwrite RRC security mode to null cipher & null integrity |
| Downlink IMSI Extraction | --dnlink-imsi-extr <level> |
dnlink-imsi-extr == 1: Variant 1: replacing Authentication Request with Identity Request (IMSI) |
| Uplink IMSI Extraction | --uplink-imsi-extr <level> |
uplink-imsi-extr == 1: Variant 1: insert invalid S-TMSI in registration request |
We are currently working towards a fully vendor-agnostic E2 agent that works with any gNB vendors and versions. Please stay tuned.