Katharina Kohls, PhD

Assistant Professor
Radboud University, Nijmegen, NL


Open5GS Virtual Setup



This guide combines different existing tutorials on Open5GS and UERANSIM. After finishing it, you should be able to run a 5G core network and a simulated SA/NSA 5G access network on two different Ubuntu VMs.

Want to skip all this? You can download both VMs here.

Last updated: 20.07.2021

Preparation

VirtualBox Install

Network Settings

After the above steps, you are ready to set up both machines individually.

Machine 1: Open5Gs

Update the machine:

sudo apt update

Install and enable mongodb:

sudo apt install mongodb
sudo systemctl start mongodb
sudo systemctl enable mongodb

Install requirements:

sudo apt install python3-pip python3-setuptools python3-wheel ninja-build build-essential flex bison git libsctp-dev libgnutls28-dev libgcrypt-dev libssl-dev libidn11-dev libmongoc-dev libbson-dev libyaml-dev libnghttp2-dev libmicrohttpd-dev libcurl4-gnutls-dev libnghttp2-dev libtins-dev meson
Build Open5Gs and test

We will build Open5Gs from source so we can make changes later on:

git clone https://github.com/open5gs/open5gs
cd open5gs
meson build --prefix=`pwd`/install
ninja -C build

Run the tun script right after install (we will prepare this script later on):

sudo ./../Desktop/5gs_tun_setup.sh

To test the compilation, run:

cd build
meson test -v

When all tests succeeded, you can proceed with the install step:

ninja install
Setup of the WebUI

The WebUI allows us to register new users. We need to set it up once, later on we can simply start it from the correct folder.

sudo apt install curl
curl -fsSL https://deb.nodesource.com/setup_14.x | sudo -E bash -
sudo apt install nodejs
cd open5gs/webui/
npm ci --no-optional

Run the WebUI via

npm run dev

You have now finished the build procedure. We will continue with setting up the second VM and UERANSIM.

Machine 2: UERANSIM

Install the requirements:

sudo apt install git make gcc g++ libsctp-dev lksctp-tools iproute2

UERANSIM does not work with the apt version of cmake, that's why we need to install snap and the snap version of cmake:

sudo apt install snap
sudo snap install cmake --classic

Build

Get the sources and build:

cd ~
git clone https://github.com/aligungr/UERANSIM
cd UERANSIM
make

Network Configuration

Machine 1: Open5Gs

Get the IP address of the Open5Gs machine, for example using net-tools:

sudo apt install net-tools
ifconfig

Example:

fiveg@fiveg-VirtualBox:~/open5gs$ ifconfig
enp0s3: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
        inet 10.0.2.4  netmask 255.255.255.0  broadcast 10.0.2.255

Make a backup of the original configuration:

cp /home/fiveg/open5gs/build/configs/sample.yaml /home/fiveg/open5gs/build/configs/sample.yaml.backup

Then adjust the IP of the AMF NGAP

amf:
    sbi:
      - addr: 127.0.0.5
        port: 7777
    ngap:
      - addr: 10.0.2.4

Put in the address we found via ifconfig

Machine 2: UERANSIM

Go to the config directory and create a copy of the configs:

cd /home/fiveg/UERANSIM/config
cp open5gs-gnb.yaml virtualbox_open5gs-gnb.yaml
cp open5gs-ue.yaml virtualbox_open5gs-ue.yaml

Make the following changes to the files:

nano virtualbox_open5gs-gnb.yaml

First, put in the IP of this machine:

linkIp: 10.0.2.15
ngapIp: 10.0.2.15
gtpIp: 10.0.2.15

In the same file, put in the IP of the AMF in the Open5Gs box

amfConfigs:
  - address: 10.0.2.4
    port: 38412

Start the gNB and UE with our adjusted config files:

./build/nr-gnb -c config/virtualbox_open5gs-gnb.yaml

Continue with the UE configuration:

nano config/virtualbox_open5gs-ue.yaml

Put in our own IP address to make sure that the UE finds the gNB during the cell search:

gnbSearchList:
  - 10.0.2.15

Finally, we need to register the UE in the core network. You can access the required information from the UE configuration file, which should by default contain the following pieces:

cat config/virtualbox_open5gs-ue.yaml

...

imsi: 901700000000001
key: 465B5CE8B199B49FAA5F0A2EE238A6BC
AMF: 8000
USIM: OPc
Operator Key: E8ED289DEBA952E4283B54E88E6183CA

Possible Error
Connecting to 10.0.2.4:38412 failed. SCTP could not connect: Connection refused

This might be fixed with port forwarding in the global NAT configuration.

Startup

Machine 1: Open5Gs

Needs to be done after each reboot: Put the following commands in a bash script, for example 5gs_tun_setup.sh on Desktop:

ip tuntap add name ogstun mode tun
ip addr add 10.45.0.1/16 dev ogstun
ip addr add 2001:230:cafe::1/48 dev ogstun
ip link set ogstun up

Make the script executable:

sudo chmod +x Desktop/5gs_tun_setup.sh

After each reboot, run the script as root:

sudo ./home/fiveg/Desktop/5gs_tun_setup.sh

Run the WebUI

cd /home/lab/open5gs/webui/ && npm run dev

After that, an admin interface shows up at 127.0.0.1:3000

Run the Open5GS Core (all of it)

cd /home/lab/open5gs/build/tests/app/ && ./5gc

Machine 2: UERANSIM

cd /home/lab/UERANSIM/build

In a first terminal, start the gNB:

./nr-gnb -c ../config/virtualbox_open5gs-gnb.yaml

In a second terminal, start the UE:

sudo ./nr-ue -c ../config/virtualbox_open5gs-ue.yaml

It's possible to start multiple UEs instead of just one with

nr-ue -c myconfig.yaml -n 10

Please note: All of the users need to be registered, the IMSIs for new users are simply incremented starting from the initial IMSI noted in the configuration.

Controlling the UE and gNB

Start the CLI for the UE using the identity of a component. Existing nodes can be displayed via

./nr-cli --dump
UERANSIM-gnb-901-70-1
imsi-901700000000001

Then use the identity to connect to the CLI of a node, e.g.,

./nr-cli imsi-901700000000001 # UE
./nr-cli imsi-901700000000001 # gNB

You can use commands to list the available commands for the UE or gNB. An example output looks like this:

lab@lab-2356gcg:~/UERANSIM/build$ ./nr-cli imsi-901700000000001
--------------------------------------------------------------------------------------------

$ commands
info           | Show some information about the UE
status         | Show some status information about the UE
timers         | Dump current status of the timers in the UE
rls-state      | Show status information about RLS
coverage       | Dump available cells and PLMNs in the coverage
ps-establish   | Trigger a PDU session establishment procedure
ps-list        | List all PDU sessions
ps-release     | Trigger a PDU session release procedure
ps-release-all | Trigger PDU session release procedures for all active sessions
deregister     | Perform a de-registration by the UE
--------------------------------------------------------------------------------------------
lab@lab-2356gcg:~/UERANSIM/build$ ./nr-cli UERANSIM-gnb-901-70-1
--------------------------------------------------------------------------------------------
$ commands
info       | Show some information about the gNB
status     | Show some status information about the gNB
amf-list   | List all AMFs associated with the gNB
amf-info   | Show some status information about the given AMF
ue-list    | List all UEs associated with the gNB
ue-count   | Print the total number of UEs connected the this gNB
ue-release | Request a UE context release for the given UE
--------------------------------------------------------------------------------------------

Internet Connection

uesimtun0 is the default network interface that gets created automatically with running UERANSIM.

You can find the PDU Session IP and TUN address in the UE logs:

[2021-07-20 11:44:41.591] [app] [info] Connection setup for PDU session[1] is successful, TUN interface[uesimtun0, 10.45.0.3] is up.

The binder tool then allows to use the IP, for example:

iveg@fiveg-VirtualBox:~/UERANSIM/build$ ./nr-binder 10.45.0.3 ping google.com
PING google.com (142.250.187.238) 56(84) bytes of data.
64 bytes from lhr25s34-in-f14.1e100.net (142.250.187.238): icmp_seq=1 ttl=112 time=12.0 ms
64 bytes from lhr25s34-in-f14.1e100.net (142.250.187.238): icmp_seq=2 ttl=112 time=12.0 ms
64 bytes from lhr25s34-in-f14.1e100.net (142.250.187.238): icmp_seq=3 ttl=112 time=12.1 ms
64 bytes from lhr25s34-in-f14.1e100.net (142.250.187.238): icmp_seq=4 ttl=112 time=11.8 ms

The tool is a bit buggy though, I could only run it with ping but not with curl.

Monitoring Network Interfaces

The default interfaces for Open5GS look as follows:

Sources

Troubleshooting

Problems with libogscrypt:

"error while loading shared libraries: libogscrypt.so.2: cannot open shared object file: No such file or directory"

Solution:

sudo sh -c "echo /home/lab/open5gs/install/lib/x86_64-linux-gnu/ > /etc/ld.so.conf.d/open5gs.conf"

Problems with address already in use:

07/20 10:31:35.458: [sock] ERROR: socket bind(2) [127.0.0.10]:7777 failed (98:Address already in use) (../lib/core/ogs-socket.c:109)

Check for the process that uses the address/port

sudo netstat -nlp | grep 7777

Example:

fiveg@fiveg-VirtualBox:~/open5gs$ sudo netstat -nlp | grep 7777
tcp        0      0 127.0.0.10:7777         0.0.0.0:*               LISTEN      12991/open5gs-nrfd  
tcp6       0      0 ::1:7777                :::*                    LISTEN      12991/open5gs-nrfd

Then kill the process and start again:

sudo kill -9 12991

Problems with a failing UE authentication:

[2021-07-16 16:07:38.192] [nas] [error] Initial Registration failed [FIVEG_SERVICES_NOT_ALLOWED]

Solution: Make sure that the UE credentials entered in the admin interface are correct. The error means that the authentication with the core failed.