Setting Up Open5GS: A Step-by-Step Guide
… or how we set our lab environment.
Advantages of stand-alone fifth generation cellular networks compared to older cellular networks is decisive. Therefore, for the whole year, this was the goal in our lab — to own our standalone network for research and education purposes. Even though the community made huge progress on open-source solutions in the last two years, there are still some bumps on the road. But finally, we manage to build our own, simple and cost-effective solution. Following article may help you to set up your own environment — and to avoid the painful process of not knowing what you are doing and learning from mistakes. Whole environment is based on open-source technologies and is vendor-free.
After some research and helpful advice from our cellular network provider partners we decided to use following setup:
- Open5gs — open-source core network project — https://open5gs.org/open5gs/docs/guide/01-quickstart/
- UERANSIM — simulator of baseband units and user equipment for large-scale scenarios — https://github.com/aligungr/UERANSIM/wiki/Installation/
- srsRAN-project — solution for gNodeB (gNB) and radio access network (RAN) implementation — https://github.com/srsran/srsran_project
- DragonOS — operating system with preinstalled software defined radio capabilities — https://www.rtl-sdr.com/dragonos-debian-linux-with-preinstalled-open-source-sdr-software/
- SDR - USRP B210 — https://www.ettus.com/all-products/ub210-kit/
As for the hardware, we recommend following machines:
- Intel i5 NUC for Open5gs !do not try to use the Celeron one — we`ve learned this the hard way ! — OS: Ubuntu 22 LTS
- Intel Celeron NUC for UERANSIM — OS: Ubuntu 22 LTS
- Intel i5 with 16 GB RAM for srsRAN-project (this is definitely overkill, you could also use basic Celeron NUC, but in the future, we want to use this pc as mobile edge computing unit) — OS: DragonOS
Open5gs installation
The installation of Open5gs is straight-forward. We used quick start guide provided with the Open5gs documentation, but we hope that following step-by-step explained guide will enhance your understanding of the technology.
The two prerequisites for running Open5GS are the Open5GS core and MongoDB. We use MongoDB, a document-based database, for user equipment registration. MongoDB uses some weird special processor instruction, which is not provided in intel Celeron processor. We tried many approaches with Celeron NUC but after hours of searching forums and, of course stackoverflow, we ended up using NUC with intel i5 to just avoid the problems.
Step 1: Instal Open5Gs
Nowadays on Ubuntu, you can simply install Open5GS via a package manager or, if you want, you can build it from source. This guide uses the package manager for simplicity. Debian version like Debian 10(Buster) and also Ubuntu, you need to install MongoDB first. If so, check our second step in
Ubuntu makes it easy to install Open5GS as shown below
sudo add-apt-repository ppa:open5gs/latest
sudo apt update
sudo apt install open5gsDebian
The Open5GS packages for Debian are available on OBS.
sudo apt update
wget -qO - https://download.opensuse.org/repositories/home:/acetcom:/open5gs:/latest/Debian_10/Release.key | sudo apt-key add -
sudo sh -c "echo 'deb http://download.opensuse.org/repositories/home:/acetcom:/open5gs:/latest/Debian_10/ ./' > /etc/apt/sources.list.d/open5gs.list"
sudo apt update
sudo apt install open5gsOther distributions can be installed by changing the path. Available paths can be found on in quickstart guide on open5gs
Step 2: Installation of MongoDB
For communication with user plane machines, we need to registred this devices in database. Open5gs can only communicate with registred devices and these devices is stored in MongoDb. If you have problem with MongoDB installation see official installation guide here.
Steps to install:
Be sure, that you have install curl command on your machine. If not install it as first
sudo apt-get install gnupg curl- Import the public key used by the package management system.
curl -fsSL https://pgp.mongodb.com/server-6.0.asc | \ sudo gpg -o /usr/share/keyrings/mongodb-server-6.0.gpg \ - dearmor2. Create a list file for MongoDB.
This is command for Ubuntu 22.04. For previous version of ubuntu see oficial installation guide.
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.list3. Update packages
sudo apt-get update4. Install packages
sudo apt-get install -y mongodb-org5. Check if mongo was installed
mongod --versionIf you have output with MongoDB version, you have successfully installed MongoDb and you can install WebUI.
Step 3: Install WebUI of open5gs
WebUI is running web application, from where we can manage users and devices which our 5g core accepts. Without registration user equiment will not be this device accepted by core.
- Install Node.js
It is web application therefore we need to install Nodejs first.
sudo apt update
sudo apt install curl
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install nodejsThis version coud be depracated or you are prefering another way to install Node.js you can use these guides:
https://www.freecodecamp.org/news/node-version-manager-nvm-install-guide/
2. Install WebUI itself
curl -fsSL https://open5gs.org/open5gs/assets/webui/install | sudo -E bash -Now when you run WebUI it will be run on port 3000.
Step 4: Configuration of open5gs
We installed software and now we need to configure it to work with our network and other devices.
Out of the box, the default configurations see all of the Open5GS components fully configured for use on a single computer. They are set to communicate with each other using the local loopback address space (127.0.0.X). The default addresses for each of the bind interfaces for these components and functions are as follows:
MongoDB = 127.0.0.1 (subscriber data) — http://localhost:3000
MME-s1ap = 127.0.0.2 :36412 for S1-MME
MME-gtpc = 127.0.0.2 :2123 for S11
AMF-ngap = 127.0.0.5 :38412 for N2
AMF-sbi = 127.0.0.5 :7777 for 5G SBI (N8,N12,N11)
We listed only some of addresses. rest you can see here.
This means that default communication of open5gs is on localhost. If we want to have communication with other devices in the network(for example with UERANSIM on other pc) we need to change some addresses to be publicly accessible. We need to set exposed addresses as secondary IP addresses of our core machine to be accessible from outside as well.
For example we can set open5gs AMF function in config to run on the IP address of our machine(192.168.50.5 for example) and need to set a secondary IP address of the pc to be able connect to AMF from another device in the network. It is good practice to set static IP address last digit of exposed functions as are default, for example AMF is default on 127.0.0.5 so our static IP of AMF should be 192.168.50.5 so they both end with 5. Functions are default set to run on predefined ports so we don’t need to change that.
Step 5: Setup a 4G/ 5G NSA Core
You will need to modify your 4G MME config to support your PLMN and TAC. The international test PLMN is 001/01, and the international private network PLMN is 999/99. You should stick to using either of these PLMNs unless you have been issued a PLMN by your national regulator. (This PLMN will need to be configured in your eNB).
If you are aiming to connect an external eNB to your core, you will also need to change the S1AP bind address of the MME and the GTP-U bind address of the SGWU. If you are running an eNB stack locally, you will not need to make these changes.
Modify /etc/open5gs/mme.yaml to set the S1AP IP address, PLMN ID, and TAC.
We want to access functions from other devices so we need to change the IP to IP of the machine for example 192.168.50.x. Don’t forget to set up these changed URLs as secondary URLs in your interface!
mme:
s1ap:
s1ap:
- - addr: 127.0.0.2
+ - addr: 192.168.50.2
gtpc:
- addr: 127.0.0.2
metrics:
addr: 127.0.0.2
port: 9090
gummei:
plmn_id:
- mcc: 999
- mnc: 70
+ mcc: 001
+ mnc: 01
mme_gid: 2
mme_code: 1
tai:
plmn_id:
- mcc: 999
- mnc: 70
+ mcc: 001
+ mnc: 01
tac: 1
security:
integrity_order : [ EIA2, EIA1, EIA0 ]Modify /etc/open5gs/sgwu.yaml to set the GTP-U IP address.
pfcp:
- addr: 127.0.0.6
gtpu:
- - addr: 127.0.0.6
+ - addr: 192.168.50.6After changing config files, please restart Open5GS daemons.
sudo systemctl restart open5gs-mmed
sudo systemctl restart open5gs-sgwudStep 6: Set Up a 5G Core
You will need to modify your 5G AMF config to support your PLMN and TAC. The international test PLMN is 001/01, and the international private network PLMN is 999/99. You should stick to using either of these PLMNs unless you have been issued a PLMN by your national regulator. (This PLMN will need to be configured in your gNB).
If you are aiming to connect an external gNB to your core, you will also need to change the NGAP bind address of the AMF and the GTPU bind address of the UPF. If you are running an gNB stack locally, you will not need to make these changes.
Modify /etc/open5gs/amf.yaml to set the NGAP IP address, PLMN ID, TAC and NSSAI.
ngap:
- - addr: 127.0.0.5
+ - addr: 192.168.50.5
metrics:
addr: 127.0.0.5
port: 9090
guami:
- plmn_id:
- mcc: 999
- mnc: 70
+ mcc: 001
+ mnc: 01
amf_id:
region: 2
set: 1
tai:
- plmn_id:
- mcc: 999
- mnc: 70
+ mcc: 001
+ mnc: 01
tac: 1
plmn_support:
- plmn_id:
- mcc: 999
- mnc: 70
+ mcc: 001
+ mnc: 01
s_nssai:
- sst: 1
security:Modify /etc/open5gs/upf.yaml to set the GTP-U address.
pfcp:
- addr: 127.0.0.7
gtpu:
- - addr: 127.0.0.7
+ - addr: 192.168.50.7
subnet:
- addr: 10.45.0.1/16
- addr: 2001:db8:cafe::1/48After changing config files, please restart Open5GS daemons.
sudo systemctl restart open5gs-amfd
sudo systemctl restart open5gs-upfdStep 7:Adding a route for the UE to have WAN connectivity
In order to bridge between the PGWU/UPF and WAN (Internet), you must enable IP forwarding and add a NAT rule to your IP Tables.
To enable forwarding and add the NAT rule, enter
### Enable IPv4/IPv6 Forwarding
sudo sysctl -w net.ipv4.ip_forward=1
sudo sysctl -w net.ipv6.conf.all.forwarding=1### Add NAT Rule
sudo iptables -t nat -A POSTROUTING -s 10.45.0.0/16 ! -o ogstun -j MASQUERADE
sudo ip6tables -t nat -A POSTROUTING -s 2001:db8:cafe::/48 ! -o ogstun -j MASQUERADEWe can see that the IP address that we are using is the subnet adress from UPF config changed previously.
Configure the firewall correctly. Some operating systems (Ubuntu) by default enable firewall rules to block traffic.
sudo ufw status
Status: active
sudo ufw disable
Firewall stopped and disabled on system startup
sudo ufw status
Status: inactiveOptionally, you may consider the settings below for security purposes.
### Ensure that the packets in the `INPUT` chain to the `ogstun` interface are accepted
sudo iptables -I INPUT -i ogstun -j ACCEPT### Prevent UE's from connecting to the host on which UPF is running
sudo iptables -I INPUT -s 10.45.0.0/16 -j DROP
sudo ip6tables -I INPUT -s 2001:db8:cafe::/48 -j DROP### If your core network runs over multiple hosts, you probably want to block
### UE originating traffic from accessing other network functions.
### Replace x.x.x.x/y with the VNFs IP/subnet
sudo iptables -I FORWARD -s 10.45.0.0/16 -d x.x.x.x/y -j DROP
Step 7: Run open5gs core
As we setup everything as we needed we need to start open5gs core. As we know, 5g core is setup from functions. These functions are represented as containers so we need to run every service(every container) to run whole core network.
We can do it directly in terminal, we can also services start, restart or check their status
sudo systemctl stop open5gs-mmed
sudo systemctl stop open5gs-sgwcd
sudo systemctl stop open5gs-smfd
sudo systemctl stop open5gs-amfd
sudo systemctl stop open5gs-sgwud
sudo systemctl stop open5gs-upfd
sudo systemctl stop open5gs-hssd
sudo systemctl stop open5gs-pcrfd
sudo systemctl stop open5gs-nrfd
sudo systemctl stop open5gs-scpd
sudo systemctl stop open5gs-ausfd
sudo systemctl stop open5gs-udmd
sudo systemctl stop open5gs-pcfd
sudo systemctl stop open5gs-nssfd
sudo systemctl stop open5gs-bsfd
sudo systemctl stop open5gs-udrd
sudo systemctl stop open5gs-webuiThese containers and services are run asynchronously but it depends on others. Therefore it could happen that some service in status logs has an error because it depends on a service which was not running in time this function needed to which ends with error. However, the service tries to run later and if the service is on, it runs without problem. That means one error in the log could not mean that there is something wrong. In this scenario you can check if everything is finally up:
sudo systemctl is-active open5gs-*If everything is active, your core is working
UERANSIM Installation
As we continue our exploration into 5G/4G network infrastructure, we now turn our focus to setting up UERANSIM. UERANSIM is a comprehensive open-source simulator for 5G and beyond. This post builds upon the instructions found on the UERANSIM repository.
Before we begin, it’s important to remember that UERANSIM and Open5GS are two parts of the same puzzle. To fully understand and successfully set up your 5G/4G core network infrastructure, you should have completed the Open5GS setup as guided in our previous post.
Now, let’s proceed with the UERANSIM installation process.
Ensure that you have the most recent version of UERANSIM. You can obtain the source code directly from the provided link, or clone the repository using the appropriate commands.
In the next sections, we’ll take you step-by-step through the UERANSIM setup process, making sure you’re well-equipped to build and operate your very own 5G/4G core network infrastructure.
Step 1: Download UERANSIM
cd ~
git clone https://github.com/aligungr/UERANSIMRequirements
- Ubuntu 16.04 or later
- CMake 3.17 or later
- gcc 9.0.0 or later
- g++ 9.0.0 or laterOther Linux distributions are likely to work in general. But unfortunately Windows is not supported since Microsoft didn’t implement SCTP protocol. You would need a virtual machine for a workaround.
NOTE: Windows Subsystem for Linux (WSL) cannot be used as a virtual machine as well. Also guest to host NAT based network configurations may not work on Windows because of the same reason. However VirtualBox with a bridged adapter setting should work fine on Windows.
Dependencies
Firstly it’s better to update your apt repositories and upgrade the programs.
sudo apt update
sudo apt upgradeThen here’s the list of dependencies: (Built-in dependencies shipped with Ubuntu are not listed herein.)
sudo apt install make
sudo apt install gcc
sudo apt install g++
sudo apt install libsctp-dev lksctp-tools
sudo apt install iproute2
sudo snap install cmake - classicNOTE: Don’t install cmake with sudo apt-get install cmake, because it installs a very old version of cmake by default. You can use sudo snap install cmake — classic or build cmake directly from sources.
NOTE: make, gcc/g++, cmake packages are only required for building UERANSIM. However libsctp-dev, lksctp-tools, and iproute2 packages are also required at runtime.
Step 2: Building
And here’s command for building:
cd ~/UERANSIM
makeAnd that’s it. After successfully compiling the project, output binaries will be copied to ~/UERANSIM/build folder. And you should see the following files:
nr-gnb | Main executable for 5G gNB (RAN)
nr-ue | Main executable for 5G UE
nr-cli | CLI tool for 5G gNB and UE
nr-binder | A tool for utilizing UE’s internet connectivity.
libdevbnd.so | A dynamic library for nr-binder
Run nr-gnb and nr-ue to start using UE and gNB. More details about them can be found in the next steps.
nr-binder and libdevbnd.so are only required for binding UEs internet connectivity to an arbitrary application, and generally not used.
NOTE: If the compilation process takes too long, you can use make -j instead of make.
Step 3: Configuration
We need to set up 2 things in this step, for every config explanation see this repo.
First is set up secondary IPs adress for our gnb for comunication with other devices in our network. For example setup IP adress of our machine with UERANSIM to 192.168.50.102. gNB is our gnb can be set to adress 192.168.50.51
Add this addreses to staic adress in your network interface, dont forget to set default mask to 24
Second we need to setup 2 files Go to UERANSIM file, and find config
cd ~/UERANSIM/configIn this config is for us interesting 2 files: open5gs-gnb.yaml and open5gs-ue.yaml
open5gs-gnb.yaml is setup file for our base station and simulate gNb, in this config we need to change
mcc: '999' # Mobile Country Code value
mnc: '70' # Mobile Network Code value (2 or 3 digits)
nci: '0x000000010' # NR Cell Identity (36-bit)
idLength: 32 # NR gNB ID length in bits [22…32]
tac: 1 # Tracking Area Code
# This is our setuped static IP which we defined in network interface
linkIp: 192.168.50.51 # gNB's local IP address for Radio Link Simulation (Usually same with local IP)
ngapIp: 192.168.50.51 # gNB's local IP address for N2 Interface (Usually same with local IP)
gtpIp: 192.168.50.51 # gNB's local IP address for N3 Interface (Usually same with local IP)# List of AMF address information
amfConfigs:
- address: 192.168.50.5
port: 38412
# List of supported S-NSSAIs by this gNB
slices:
- sst: 1
# Indicates whether or not SCTP stream number errors should be ignored.
ignoreStreamIds: trueAs we have set gNB lets setup simulator of user. Edit open5gs-ue.yaml as follows:
# IMSI number of the UE. IMSI = [MCC|MNC|MSISDN] (In total 15 digits)
supi: 'imsi-999700000000001'
# Mobile Country Code value of HPLMN
mcc: '999'
# Mobile Network Code value of HPLMN (2 or 3 digits)
mnc: '70'
# Permanent subscription key
key: '465B5CE8B199B49FAA5F0A2EE238A6BC'
# Operator code (OP or OPC) of the UE
op: 'E8ED289DEBA952E4283B54E88E6183CA'
# This value specifies the OP type and it can be either 'OP' or 'OPC'
opType: 'OPC'
# Authentication Management Field (AMF) value
amf: '8000'
# IMEI number of the device. It is used if no SUPI is provided
imei: '356938035643803'
# IMEISV number of the device. It is used if no SUPI and IMEI is provided
imeiSv: '4370816125816151'
# List of gNB IP addresses for Radio Link Simulation
gnbSearchList:
- 192.168.50.51
# UAC Access Identities Configuration
uacAic:
mps: false
mcs: false
# UAC Access Control Class
uacAcc:
normalClass: 0
class11: false
class12: false
class13: false
class14: false
class15: false
# Initial PDU sessions to be established
sessions:
- type: 'IPv4'
apn: 'internet'
slice:
sst: 1
# Configured NSSAI for this UE by HPLMN
configured-nssai:
- sst: 1
# Default Configured NSSAI for this UE
default-nssai:
- sst: 1
# Supported integrity algorithms by this UE
integrity:
IA1: true
IA2: true
IA3: true
# Supported encryption algorithms by this UE
ciphering:
EA1: true
EA2: true
EA3: true
# Integrity protection maximum data rate for user plane
integrityMaxRate:
uplink: 'full'
downlink: 'full'For our setup is importatnt gnbSearchList that is list on which is find our gnb. To that array we need to set IP of our gNB from config of linkIp before.
We also need to have SST and mcc and mnc same as in core config.
Step 4: Run it
We can run gNB and then user equiment
cd ~/UERANSIM/build
nr-gnb -c ../config/open5gs-gnb.yaml
nr-ue -c ../config/open5gs-ue.yamlYou have setup UERANSIM.
Summary
In this article, we detailed the setup process for Open5GS, a core network framework, and UERANSIM, an open-source simulator for 5G. Together, these tools provide the foundation for building and testing 5G/4G network infrastructures. We hope this guide empowers you to dive deeper into the realm of modern mobile networks.
In the next article, we will explain how to use SDR and register your physical phone towards your private 5G core.
… to be continued.
