# Free5GC and UERANSIM Installation Guide

[Preparation](#Preparation)

[Free5GC Installation](#Installation)
- [Golang](#1.-Install-Golang)
- [MongoDB](#2.-Install-MongoDB)
- [Control Plane and User Plane](#3.-Install-Control-plane,-User-plane-and-Webconsole)

[UERANSIM Installation](#UERANSIM-Installation)

[Environment Configuration](#Configuration)
- [Network Configuration](#Network-Configuration-(both-of-the-vm))
- [AMF Configuration](#AMF-Config)
- [SMF Configuration](#SMF-Config)
- [UPF Configuration](#UPF-Config)
- [gNB Config](#gNB-config-at-UERANSIM-machine)
- [Register an UE](#Register-an-UE-at-Free5GC-webconsole)

[Testing](#Test-Free5GC-against-UERANSIM)

# Preparation

### Hardware requirements

a.Mini-um Specification

* CPU : Intel I5
* RAM : 4GB
* Storage : 160GB
* NIC : 1Gbps Ethernet supported by linux kernel

b. Recommended Specification

* CPU : Intel I7
* RAM : 8GB
* Storage : 1TB
* NIC : 10Gbps Ethernet supported by linux kernel

c. General Requirements

* Operating System : Ubuntu 20.04
* Compiler : GCC 7.3.0
* Go : 1.14.4 linux/amd64

## Installation

### 1. Install Golang

a. Download the compressed golang

wget https://dl.google.com/go/go1.18.10.linux-amd64.tar.gz


Note : If you cannot downloading compressed go file consider to reconfigure network to dynamic addressing using

sudo nano /etc/netplan/$(ls /etc/netplan)

change dhcp value to `true`

b. Extract the compressed file

sudo tar -C /usr/local -zxvf go1.18.10.linux-amd64.tar.gz


c. Create empty directories

mkdir -p ~/go/{bin,pkg,src}

d. Set some environment variable

echo 'export GOPATH=$HOME/go' >> ~/.bashrc
echo 'export GOROOT=/usr/local/go' >> ~/.bashrc
echo 'export PATH=$PATH:$GOPATH/bin:$GOROOT/bin' >> ~/.bashrc
echo 'export GO111MODULE=auto' >> ~/.bashrc
source ~/.bashrc


e. Make sure that golang installed properly

go version


### 2. Install MongoDB

a. Install prerequisities package

sudo apt install -y software-properties-common gnupg apt-transport-https ca-certificates 


b. Import public key for mongodb

curl -fsSL https://pgp.mongodb.com/server-7.0.asc |  sudo gpg -o /usr/share/keyrings/mongodb-server-7.0.gpg --dearmor


c. Add mongoDB 7.0 repository to /etc/apt/sources.list.d directory

echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/7.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list


Note: consider to change `focal` to `jammy` if you try to install mongodb in ubuntu 22.04

d. Reload local package index

sudo apt update


e. Install mongoDB

sudo apt install -y mongodb-org 


f. Activate mongodb service

sudo systemctl start mongod
sudo systemctl enable mongod


Note:
If you can't install the newer version, check the CPU use the command below

cat /proc/cpuinfo | grep avx

If it doesn't emitt anything like this

then your CPU doesn't have AVX, consider installing older version of mongodb, like v4.4 or below

If the command show some output you can install newer version, here is the example

### 3. Install Control-plane, User-plane and Webconsole

a. Install Control-plane dependencies

sudo apt -y update
sudo apt install -y wget git


b. Install User-plane dependencies

sudo apt -y update
sudo apt -y install git gcc g++ cmake autoconf libtool pkg-config libmnl-dev libyaml-dev


c. Edit firewall rule

sudo sysctl -w net.ipv4.ip_forward=1
sudo iptables -t nat -A POSTROUTING -o enp0s3 -j MASQUERADE
sudo iptables -A FORWARD -p tcp -m tcp --tcp-flags SYN,RST SYN -j TCPMSS --set-mss 1400
sudo systemctl stop ufw
sudo systemctl disable ufw # prevents the firewall to wake up after a OS reboot


Modify the -o (ex. `enp0s3`) options based on the `ifconfig` output

If `ifconfig` command not found, run this command

sudo apt install -y net-tools

d. Clone control-plane repository

cd ~
git clone --recursive -b v3.3.0 -j $(nproc) https://github.com/free5gc/free5gc.git
cd free5gc


e. Build all network functions

make


f. Retrieve 5G GTP-U kernel module

git clone -b v0.8.3 https://github.com/free5gc/gtp5g.git
cd gtp5g
make
sudo make install


g. Build the UPF

cd ~/free5gc
make upf


h. Install nodejs and yarn package

curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
curl -sL https://deb.nodesource.com/setup_20.x | sudo -E bash -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
sudo apt update
sudo apt install -y nodejs yarn

>Note : Try use this command instead if you got an error that you supposed to install nodejs-12

curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -


i. Build WebConsole

cd ~/free5gc
make webconsole


j. Test Network Function

cd ~/free5gc
./run.sh


## UERANSIM Installation

## Preparation

### 1. Hardware Requirements

a. Minimum Specification

* CPU : Intel I5
* RAM : 4GB
* Storage : 160GB
* NIC : 1Gbps Ethernet supported by linux kernel

b. Recommended Specification

* CPU : Intel I7
* RAM : 8GB
* Storage : 1TB
* NIC : 10Gbps Ethernet supported by linux kernel

c. General Requirements

* Operating System : Ubuntu 20.04
* Compiler : GCC 7.3.0
* Go : 1.14.4 linux/amd64

## Installation

a. Move to home directory

cd ~

b. Clone UERANSIM repository

git clone https://github.com/aligungr/UERANSIM


c. Move to UERANSIM directory

cd UERANSIM


d. Switch working directory

git checkout 3a96298


e. Update system repositories and Upgrade installed package

sudo apt update
sudo apt upgrade -y


f. Installing required tools

sudo apt install -y make g++ libsctp-dev lksctp-tools iproute2
sudo snap install cmake --classic


g. Build UERANSIM

cd ~/UERANSIM
make

> if you encounter problem due to cmake version, you can use this command to remove and reinstall newer version of cmake, adjust the version accordingly

sudo apt -y remove cmake
pip install cmake==3.18


## Configuration

### Network Configuration (both of the vm)

a. Open file /etc/hostname

`sudo nano /etc/hostname`

b. Replace it's contain with "free5gc"


c. Save the file, click "CTRL+x" then "y" then "ENTER"


d. Checkout the network address of the host

If the VM hosted in windows type this command in command prompt

ipconfig

Here is the result


When the screenshot is taken, the computer use wireless adapter, so the network address would be `192.168.57.0` and the default gateway will be `192.168.57.250`

d. Checkout file under /etc/netplan directory

`ls /etc/netplan`

The command will produce output like

`01-network-manager-all.yaml`

e. Edit the file
`sudo nano /etc/netplan/01-network-manager-all.yaml`

Aternatives
`sudo nano /etc/netplan/$(ls /etc/netplan)`

f. At first, the file will look like

network
    version: 2
    renderer: networkd
    ethernets:
        enp0s3:
            dhcp4: no

Edit the file

network:
    version: 2
    renderer: networkd
    ethernets:
    enp0s3:
        dhcp4: no
        addresses: 
            - 192.168.56.101/24  #this is just example, your system IP address might be different
        gateway4: 192.168.56.1
        nameservers:
            addresses: [8.8.8.8, 8.8.4.4]


g. Check for syntax error in the configuration file

sudo netplan try


h. Apply the configuration

sudo netplan apply


> Important:
> Every time you reboot your system or reconnect to other network, you must reconfigure the static address as the host address is changed

> Note:
> Writer use VirtualBox to create VM, the network of Free5GC and UERANSIM are set to Bridged Adapter. Choose the similar setting if the VM created using different software such as VMWare.

### AMF Config

a. Edit file ~/free5gc/config/amfcfg.yaml

cd ~/free5gc
sudo nano ./config/amfcfg.yaml

b. Find the ngapIpList key

...
  ngapIpList:  # the IP list of N2 interfaces on this AMF
  - 127.0.0.1

c. Replace localhost address with 192.168.56.101

...
  ngapIpList:  # the IP list of N2 interfaces on this AMF
  - 192.168.56.101  # 127.0.0.1


d. Save the file and exit from text editor

### SMF Config

a. Edit file ~/free5gc/config/smfcfg.yaml

cd ~/free5gc
sudo nano ./config/smfcfg.yaml

b. Find interfaces block

...
  interfaces: # Interface list for this UPF
   - interfaceType: N3 # the type of the interface (N3 or N9)
     endpoints: # the IP address of this N3/N9 interface on this UPF
       - 127.0.0.8

c. Replace address 127.0.0.8 with your static address

...
  interfaces: # Interface list for this UPF
   - interfaceType: N3 # the type of the interface (N3 or N9)
     endpoints: # the IP address of this N3/N9 interface on this UPF
       - 192.168.56.101  # 127.0.0.8


### UPF Config

a. Edit file ~/free5gc/config/upfcfg.yaml

cd ~/free5gc
sudo nano ./config/upfcfg.yaml

b. Find gtpu IP line

...
  gtpu:
    forwarder: gtp5g
    # The IP list of the N3/N9 interfaces on this UPF
    # If there are multiple connection, set addr to 0.0.0.0 or list all the addresses
    ifList:
      - addr: 127.0.0.8
        type: N3

c. Replace address 127.0.0.8 with 192.168.56.101

...
  gtpu:
    forwarder: gtp5g
    # The IP list of the N3/N9 interfaces on this UPF
    # If there are multiple connection, set addr to 0.0.0.0 or list all the addresses
    ifList:
      - addr: 192.168.56.101
        type: N3


### gNB config at UERANSIM machine

sudo nano ~/UERANSIM/config/free5gc-gnb.yaml

Replace the linkIp, ngapIp, gtpIp with the UE/RAN SIM ip address and replace address under amfConfigs with Core Network IP address


### Register an UE at Free5GC webconsole

1. Run the server

cd ~/free5gc/webconsole
go run server.go

2. Open web browser and type `<Your static address>:5000`

3. Login using **admin** as username and **free5gc** as password


4. Open subscriber tab and click 'modify user'


5. Change 'OPc' to 'OP' and change the first column based on the last digit of SUPI column



6. Scroll down and find submit button, then click 'submit'

### Check the UE configuration, adjust the config file with the information at Free5GC webconsole

cd ~/UERANSIM
sudo nano ./config/free5gc-ue.yaml


## Test Free5GC against UERANSIM

### 1. Create a New File to automatically configure firewall before running Free5GC (Free5GC)

cd ~/free5gc
sudo nano ./script.sh

then write these lines to the file

sudo sysctl -w net.ipv4.ip_forward=1
sudo iptables -t nat -A POSTROUTING -o ens18 -j MASQUERADE
sudo systemctl stop ufw
sudo iptables -I FORWARD 1 -j ACCEPT
./run.sh


> note: change interface in -o option based on `ifconfig` command output

### 2. Change the file permission and run the script (Free5GC)

sudo chmod +x ./script.sh
./script.sh


### 3. Build gnb in (UERANSIM)

cd ~/UERANSIM
sudo build/nr-gnb -c config/free5gc-gnb.yaml


### 4. Open new terminal and build ue (UERANSIM)

> to change terminal in ubuntu server, use CTRL+ALT+F2

in new terminal, issue command:

cd ~/UERANSIM
sudo build/nr-ue -c config/free5gc-ue.yaml


### 5. Check if tunnel created.

> to change terminal in ubuntu server, use CTRL+ALT+F3

ifconfig

Make sure the interface `uesimtun0` exist


### 6. Ping from uesimtun0 to DN, represented by google.com

ping -c 5 I uesimtun0 google.com