# Lab 2 Open5GS & UERANSIM (Eng)
## Outline
- [1. Experiment Content](#1.-Experiment-Content)
- [2. Related Knowledge](#2.-Related-Knowledge)
- [3. Environment/Equipment Specifications](#3.-Environment/Equipment-Specifications)
- [4. Experiment Structure](#4.-Experiment-Structure)
- [5. Experiment Steps](#5.-Experiment-Steps)
- [5-1. Build Open5GS](#5-1.-Build-Open5GS)
- [Questions and Discussions (I)](#Questions-and-Discussions-(I))
- [5-2. Install and Build UERANSIM](#5-2.-Install-and-Build-UERANSIM)
- [Questions and Discussions (II)](#Questions-and-Discussions-(II))
- [5-3. UERANSIM External Network Test](#5-3.-UERANSIM-External-Network-Test)
- [Questions and Discussions (III)](#Questions-and-Discussions-(III))
-----
## 1. Experiment Content
- Build a private 5G network with an Open5GS core network, a gNB and a UE.
- Learn how to simulate a mobile device connection.
- Perform Downlink ICMP and Uplink ICMP connection tests using Iperf3.
-----
## 2. Related Knowledge
- Open5GS: An open-source 5G Core (5GC)software based on 3GPP specifications. It provides a complete and flexible platform for building and testing 5G networks. Key components included in Open5GS are: Access and Mobility Management Function (AMF), Session Management Function (SMF), User Plane Function (UPF), Network Repository Function (NRF), Service Capability Exposure Function (SCEF), Subscriber Data Management (SDM), Unified Data Management (UDM), etc.
- UERANSIM: An open-source 5G User Equipment (UE) and Radio Access Network (RAN) simulation tool, developed by the OpenAirInterface Software Alliance. Simulates 5G UE behavior in different network deployment scenarios.
- MongoDB: A popular open-source NoSQL database management system. It uses a document-oriented data model, instead of traditional relational table structures. Main features include:
- Document-oriented data model: The basic data storage units of MongoDB are documents in JSON-like format, which include various types of data. This makes MongoDB well suited for processing complex and semi-structured data.
- Flexible schema: Unlike traditional relational databases, MongoDB does not require documents to follow the same schema. This flexibility allows more agile schema design and data modeling during development, making MongoDB well suited for rapid iteration and applications facing frequent changes.
- Distributed storage: MongoDB supports horizontal scaling by distributing data across multiple servers, enabling it to meet large-scale data storage demands.
-----
## 3. Environment/Equipment Specifications
### [Ubuntu Installation](https://github.com/TTU-CWBT/Ubuntu-install-tutorial)
:warning: This experiment requires installing Ubuntu Desktop. After finishing the Unbuntu installation, enter the command to install the desktop environment. This may take some time to finish, so please be patient.
``` shell=1
sudo apt install ubuntu-desktop
```
| Software name| Software version |
|:--------: |:---------:|
| Ubuntu | 22.04 LTS |
| Open5gs | v2.7.1 |
| UERANSIM | v3.2.6 |
-----
## 4. Experiment Structure
- The current setup is entirely based on Virtual Machines(VMs).
- Core network: Open5GS.
- Radio signal simulation: UERANSIM.
-----
## 5. Experiment Steps
### 5-0. Before We Start
Since the following experiment involves a large amount of copying and pasting commands, it is recommanded to connect to the virtual machine(VM) via SSH from the local terminal. The SSH connection method is as follows.
- Connect to a remote server:
``` shell=1
ssh username@remote_host
or
ssh username@remote_IP
example
ssh open5gs@10.0.2.12
```
> Common Errors
> - If the IP cannot be found, use `ip a` to check the IP address.
> - If no IP address appears, run `sudo dhclient` to assign an IP address to the network interface, then run `ip a` to check IP again.
> - If the connection is unstable, try using the Host Only IP address instead.
### 5-1. Build Open5GS
#### Install Ubuntu Basic Packages
- Enter following commands in your terminal.
``` shell=1
sudo apt update && sudo apt upgrade
sudo apt-get install vim
sudo apt install net-tools
sudo apt install traceroute
sudo apt install tldr
sudo apt install iperf3
```
#### Install MongoDB
- During the installation process, the network may be temporarily disconnected. Simply reconnect and continue entering the commands in order.
##### x86
``` shell=1 驗證mongodb x86
sudo apt install gnupg curl
curl -fsSL https://pgp.mongodb.com/server-6.0.asc | sudo gpg -o /usr/share/keyrings/mongodb-server-6.0.gpg --dearmor
echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-6.0.gpg ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/6.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list
sudo apt update
sudo apt install -y mongodb-org
sudo systemctl start mongod
sudo systemctl enable mongod
```
##### arm64
``` shell=1 驗證mongodb m1
sudo apt install gnupg curl
sudo apt install software-properties-common gnupg apt-transport-https ca-certificates -y
curl -fsSL https://pgp.mongodb.com/server-7.0.asc | sudo gpg -o /usr/share/keyrings/mongodb-server-7.0.gpg --dearmor
echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list
echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse"
sudo apt update
sudo apt install mongodb-org -y
mongod --version
```
> Common Errors
>
> M-series Mac may encounter this issue. You can check the following link:
https://www.cherryservers.com/blog/install-mongodb-ubuntu-22-04
- Check mongoDB version.
> mongod --version
Check if mongoDB is running properly.
``` shell=1
sudo systemctl status mongod
```
> If it is running correctly, it will look like this:
#### Download and Install Open5GS & UERANSIM Related Packages
``` shell=1
sudo apt install cmake libfftw3-dev libmbedtls-dev libboost-program-options-dev libconfig++-dev libsctp-dev git
```
After Installation, enter the following commands in order.
``` shell=1
sudo add-apt-repository ppa:open5gs/latest
```
> Press Enter.
``` shell=1
sudo apt update
sudo apt install open5gs
```
> Enter `y`.
#### Install node.js
Enter the following commands in order.
``` shell=1
sudo apt install -y ca-certificates
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
NODE_MAJOR=20
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list
sudo apt update
sudo apt install nodejs -y
```
#### Install Open5GS-webUI
Enter the following command.
``` shell=1
curl -fsSL https://open5gs.org/open5gs/assets/webui/install | sudo -E bash -
```
> The following screen will show up, please wait patiently.
#### Register UE Subscriber
After installation is complete, you need to return to the virtual machine (SSH connection cannot be used here, it will fail). In the ==**virtual machine**==, open the browser and enter `127.0.0.1:9999`. The first time you open it may take some time. If it opens successfully, it means Open5GS has been installed successfully. Enter the default credentials:
> Username: admin
> Password: 1423
> After login successfully, you will see the following interface.
> Click the red ‘+’ in the bottom-right corner and begin editing the following data.
> IMSI: 001010000000000
> Type: IPv4.
### Verify Open5GS Installation
If Open5GS has been installed successfully, it will run automatically in the background after each reboot. Enter `ps aux | grep open5gs` to confirm whether the Open5GS core functions are operating correctly. If successful, the output will look like the following. (please confirm that all the listed functions are running properly; if not, do not continue to the next step.)
> The core functions are as listed:
> AMF, SMF, UPF, NRF, UDM, UDR, PCF,AUSF, NSSF
After confirming that all core functions are activated, you can continue to configure the AMF, SMF, and UPF.
#### 1. Configure amf.yaml
Enter `sudo vim /etc/open5gs/amf.yaml` to edit amf，modify the following:
> mcc, mnc: '001', '01'
> Address: the host-only IP of Open5GS.
After completion, enter `sudo systemctl restart open5gs-amfd.service` to reactivate amf.
#### 2. Configure nrf.yaml
Enter `sudo vim /etc/open5gs/nrf.yaml` to edit nrf，modify the following:
> PLMN ID: mmc='001', mnc='01'
After completion, enter `sudo systemctl restart open5gs-urfd.service` to reactivate urf.
#### 3. Configure upf.yaml
Enter `sudo vim /etc/open5gs/upf.yaml` to edit upf，modify the following:
> GTPU IP: the host-only IP of Open5GS.
After completion, enter `sudo systemctl restart open5gs-upfd.service` to reactivate upf.
#### 4. Configure Network Functions (Routing, NAT Translation, and Firewall)
Enter the following commands to configure network functions. These commands must be re-entered after every reboot. Without these settings, the core network functions will be limited or unusable.
> :warning: Before running `sudo iptables -t nat -A POSTROUTING -o enp0s1 -j MASQUERADE`, please confirm that `enp0s1` is the correct network interface name for the Shared Network in the Open5GS VM.
```
sudo sysctl -w net.ipv4.ip_forward=1
sudo iptables -t nat -A POSTROUTING -o enp0s1 -j MASQUERADE
sudo systemctl stop ufw
```
For convenience, the commands have been written into a script. Students only need to create a `.sh` file, copy and paste the content, and save it. Simply run `sh filename.sh` after booting to configure automatically.
- Network configuration shell script
``` shellscript=1
#!/bin/bash
# Program:
# this is auto setting network
# History:
# 2025/05/16 Timothy_Su_TZD First version
PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:~/bin
export PATH
sudo sysctl -w net.ipv4.ip_forward=1
sudo iptables -t nat -A POSTROUTING -o enp0s1 -j MASQUERADE
sudo systemctl stop ufw
exit 0
```
Once this configuration is complete, the setup of the core network is finished. Next, is to configure the UE & RAN.
-----
### Questions and Discussions (I)
1. Take a screenshot of the successful Open5GS Web UI registration screen.
2. Explain what IMSI and IPv4 are.
3. Explain the responsibilities of AMF, NRF, UPF, and SMF.
4. Explain what NGAP is in AMF.
-----
### 5-2. Install and Build UERANSIM
#### Preparations
Another independent virtual machine will be needed for installing UERANSIM. However, there is no need to reinstall Ubuntu. Simply copy the previously installed Open5GS VM and change the MAC address of the new virtual machine (UERANSIM) network adapter, as shown below:
> Right-click the virtual machine（UERANSIM）>> Edit >> Network >> Shared Network && Host Only >> MAC Address >> Click Random >> Save
Next, start UERANSIM (the login password is the same as the Open5GS VM) and open a terminal (using SSH is recommended here since this part also involves large amount of copying and pasting commands). For easier identification later, it is recommended that the username of the UERANSIM VM be changed to ueransim. You can read this article [Modify hostname, username, and user password in Ubuntu](https://https://blog.csdn.net/qq_34160841/article/details/106886306), and change the username of the UERANSIM VM like shown:
#### Install UERANSIM
- Clone UERANSIM from GitHub.
``` shell=1
cd ~
git clone https://github.com/aligungr/UERANSIM
sudo apt update
```
- Install UERANSIM related tools.
``` shell=1
sudo apt install make
sudo apt install gcc
sudo apt install g++
sudo apt install libsctp-dev lksctp-tools
sudo apt install iproute2
sudo apt-get install build-essential
```
> If you encounter an error due to an outdated CMake version, install a newer version as shown:
``` shell=1
sudo apt remove cmake
wget [https://cmake.org/files/v3.22/cmake-3.22.0.tar.gz]
tar xvf cmake-3.22.0.tar.gz
./configure
Make –j8
sudo make install
```
- Build UERANSIM
Enter the following commands. It is normal that it may take a while running `make`. **Do not interrupt the execution!** If it completes without errors, then the installation is successful.
``` shell=1
cd ~/UERANSIM
make
```
> Make execution screen
> The message `UERANSIM successfully built.` means success.
#### Configure UERANSIM
- Configure gNB
Enter `vim ~/UERANSIM/config/open5gs-gnb.yaml` to edit gNB，modify the following:
> mcc, mcc: '001', '01'
> linkIp, ngapIp, gtpIp: the host-only IP of UERANSIM VM.
> amfConfigs address: the host-only IP of Open5GS VM.
> 
- Configure UE
Enter `vim ~/UERANSIM/config/open5gs-ue.yaml` to edit UE，modify the following:
> Supi: 001010000000000
> mcc, mcc: '001', '01'
> gnbSearchList: the host-only IP of UERANSIM VM.
> 
After completing the configuration, we can start the gNB and UE simulations.
- Turn On the gNodeB
``` shell=1
cd ~/UERANSIM/build
sudo ./nr-gnb -c ../config/open5gs-gnb.yaml
```
> If successful, the message `NG Setup procedure is successful` will show up.
> 
- Turn On the UE
``` shell=1
cd ~/UERANSIM/build
sudo ./nr-ue -c ../config/open5gs-ue.yaml
```
> If successful, the message `Connection setup for PDU session[1] is successful, TUN interface[uesimtun0, 10.45.0.2] is up.` will show up.
> 
> At the same time, the gNB will also display a new message showing the successful connection.
- Check Open5GS Connection Logs.
- In the Open5GS VM, enter `sudo cat /var/log/open5gs/amf.log` to observe the gNB and UE connection information.
-----
### Questions and Discussions (II)
1. Take a screenshot of gNB and UE successfully connecting to Open5GS.
2. Locate and take a screenshot of the successful connection log between gNB and UE in `/var/log/open5gs/amf.log`.
-----
### 5-3. UERANSIM External Network Test
:warning: **Maintain proper connection between gNB, UE, and Open5GS**
If the UE registers successfully through the gNB and the core network, you should see a network interface named `uesimtun0` in the UERANSIM VM when checking with command `ip a` (as shown below).
This network interface is the UE’s network interface. If you stop the UE process, this interface will disappear. To enable the UE to connect to the external network, you must configure an IP route by entering the following command:
``` shell=1
sudo ip route add default dev uesimtun0
```
To verify whether the UE can connect to the external network, there are two methods. The logic behind these two methods are both: "If you can ping 'google.com' successfully then it's successful".
1. Ping
``` shell=1
ping -I uesimtun0 google.com
ping -I uesimtun0 8.8.8.8
Both of these two commands are the same, pick one as you pleased.
The command will keep executing untill stopped with Ctrl+C.
```
2. Traceroute
``` shell=1
traceroute google.com -i uesimtun0 -n
```
> :warning: If ping failed or traceroute stuck at `* * *`, it means the connection failed. Re-enter the following commands in the Open5GS VM.
> :warning: Before running `sudo iptables -t nat -A POSTROUTING -o enp0s1 -j MASQUERADE`, confirm that `enp0s1` is the correct network interface corresponding to the Shared Network in the Open5GS VM.
>``` shell=1
> sudo sysctl -w net.ipv4.ip_forward=1
> sudo iptables -t nat -A POSTROUTING -o enp0s1 -j MASQUERADE
> sudo systemctl stop ufw
> ```
#### UL/DL ICMP Connection Test
:warning: **Maintain proper connection between gNB, UE, and Open5GS**
Enter the following command in the Open5GS VM, and keep it running until the UL/DL ICMP tests are completed.
```
sudo iperf3 -s
```
> After entering the command, the result should be as shown:
> 
#### TCP
- Uplink ICMP Connection Test
Enter the following command in the UERANSIM VM, and confirm that `10.45.0.1` is the IP of the `ogstun` interface in the Open5GS VM, and `10.45.0.4` is the IP of `uesimtun0` in the UERANSIM VM.
``` shell=1
sudo iperf3 -c 10.45.0.1 -B 10.45.0.4 -b 100M -t 10
```
- Downlink ICMP Connection Test
``` shell=1
sudo iperf3 -c 10.45.0.1 -B 10.45.0.2 -b 100M -t 10 –R
```
> After entering the command, the result should be as shown:
> (Left: Open5GS VM; Right: UERANSIM VM)
> 
#### UDP
- Uplink ICMP Connection Test
``` shell=1
sudo iperf3 -c 10.45.0.1 -u -B 10.45.0.2 -b 100M -t 10
```
- Downlink ICMP Connection Test
``` shell=1
sudo iperf3 -c 10.45.0.1 -u -B 10.45.0.2 -b 100M -t 10 –R
```
> After entering the command, the result should be as shown:
> (Left: Open5GS VM; Right: UERANSIM VM)
> 
-----
### Questions and Discussions (III)
1. What is the approximate maximum measured UL and DL throughput for TCP?
2. What is the approximate maximum measured UL and DL throughput for UDP?
3. Between TCP and UDP, which one achieves higher throughput? why?
4. If you need to choose a protocol with higher reliability, should you choose TCP or UDP? Why?
Sign in with Wallet
Connect another wallet