Try   HackMD

free5GC Installation on KVM

Minimum Requirement

  • Software

    • OS: Ubuntu 18.04
    • Linux kernel: 4.15.0-43-generic
    • gcc 7.3.0
    • Go 1.11.4
    • QEMU emulator 2.11.1

  • Hardware

    • CPU: Intel i5 processor
    • RAM: 4GB
    • Hard drive: 160G
    • NIC card: 1Gbps ethernet card

  • Hardware recommended

    • CPU: Intel i7 processor
    • RAM: 8GB
    • Hard drive: 160G
    • NIC card: 10Gbps ethernet card

Hardware Tested

eNB

  • GemTek WLTGFC-101 (4G LTE Small Cell)

UE

  • LG C90 cellular phone
  • D-Link DWR-932C dongle via USB cable

Preparation

KVM Environment Setup

  • VM NIC Cards
    1. NIC for connecting to the Internet
      • Network source: Virtual network - NAT
      • Interface name in VM: ens3 (in this example)
    2. NIC for connecting to eNB:
      • Network source: Host device <Host Interface Name>
      • Interface name in VM: ens4 (in this example)

Collect eNodeB and USIM Information

  • eNodeB information (in this example)

    ​​​​IP Address: 192.188.2.1
​​​​Gateway:    192.188.2.2 (IP of NIC connected to eNB)
​​​​PLMN:
​​​​  MCC: 208
​​​​  MNC: 93
​​​​MME GID:  1
​​​​MME Code: 1
​​​​TAC: 1

  • USIM information (in this example)

    ​​​​IMSI 208930000000003
​​​​K    8baf473f2f8fd09487cccbd7097c6862
​​​​OPc  8e27b6af0e692e750f32667a3b14605d

Installation

You can either follow the instructions from Part A ~ Part C or simply run the shell listed in the end of this document.

Part A. Compile Source Code

Prerequisites

Install MongoDB 3.6.3, Golang 1.11.4.

sudo apt-get update
sudo apt-get -y install mongodb wget git
sudo systemctl start mongodb (if '/usr/bin/mongod' is not running)

# Check if golang is installed
go version

# If not, run commands below
wget -q https://storage.googleapis.com/golang/getgo/installer_linux
chmod +x installer_linux
./installer_linux
source ~/.bash_profile
rm -f installer_linux

go get -u -v "github.com/gorilla/mux"
go get -u -v "golang.org/x/net/http2"
go get -u -v "golang.org/x/sys/unix"

To run free5GC with least privilege, TUN device permission should be a crw-rw-rw-(666).

ls -al /dev/net/tun
crw-rw-rw- 1 root root 10, 200 Jan 14 13:09 /dev/net/tun

Write the configuration file for the TUN device.

sudo sh -c "cat << EOF > /etc/systemd/network/99-free5gc.netdev
[NetDev]
Name=uptun
Kind=tun
EOF"

sudo systemctl enable systemd-networkd
sudo systemctl restart systemd-networkd

Check IPv6 Kernel Configuration. Although you can skip this step, we suggest that you set this up to support IPv6-enabled UE.

sysctl -n net.ipv6.conf.uptun.disable_ipv6

(if the output is 0 and IPv6 is enabled, skip the followings)
sudo sh -c "echo 'net.ipv6.conf.uptun.disable_ipv6=0' > /etc/sysctl.d/30-free5gc.conf"
sudo sysctl -p /etc/sysctl.d/30-free5gc.conf

You are now ready to set the IP address on TUN device. If IPv6 is disabled for TUN device, please remove Address=cafe::1/64 from below.

sudo sh -c "cat << EOF > /etc/systemd/network/99-free5gc.network
[Match]
Name=uptun
[Network]
Address=45.45.0.1/16
Address=cafe::1/64
EOF"

sudo systemctl enable systemd-networkd
sudo systemctl restart systemd-networkd

Add the following lines into /etc/network/interfaces for network-manager service

auto uptun
iface uptun inet static
	address 45.45.0.1
	netmask 255.255.0.0

iface uptun inet6 static
	pre-up modprobe ipv6
	address cafe::1
	netmask 64

Restart uptun interface

sudo ip a flush uptun
sudo systemctl restart networking

# Check if uptun is up
sudo apt-get -y install net-tools
ifconfig uptun

AMF, SMF, UPF, HSS, and PCRF

Install the depedencies for building the source

sudo apt-get -y install autoconf libtool gcc pkg-config git flex bison libsctp-dev libgnutls28-dev libgcrypt-dev libssl-dev libidn11-dev libmongoc-dev libbson-dev libyaml-dev

Git clone and compile

git clone https://bitbucket.org/nctu_5g/free5gc.git
cd free5gc
autoreconf -iv
./configure --prefix=`pwd`/install
make -j `nproc`
make install

Part B. VM Internal Network Environment Setting

[Option 1] Need to run on every boot

sudo ifconfig ens4 192.188.2.2
sudo sh -c 'echo 1 > /proc/sys/net/ipv4/ip_forward'
sudo iptables -t nat -A POSTROUTING -o ens3 -j MASQUERADE
sudo iptables -I INPUT -i uptun -j ACCEPT

[Option 2] or configure as auto run on boot

sudo sh -c "cat << EOF > /etc/init.d/ngc-network-setup
#!/bin/sh
### BEGIN INIT INFO 
# Provides:          ngc-network-setup 
# Required-Start:    networkd 
# Required-Stop:     networkd 
# Default-Start:     networkd 
# Default-Stop:      networkd 
# Short-Description: 
# Description:       
# 
### END INIT INFO

ifconfig ens4 192.188.2.2
sh -c 'echo 1 > /proc/sys/net/ipv4/ip_forward'
iptables -t nat -A POSTROUTING -o ens3 -j MASQUERADE
iptables -I INPUT -i uptun -j ACCEPT
EOF"

sudo chmod 755 /etc/init.d/ngc-network-setup
sudo /etc/init.d/ngc-network-setup

sudo ln -s /etc/init.d/ngc-network-setup /etc/rc3.d/S99ngc-network-setup
sudo ln -s /etc/init.d/ngc-network-setup /etc/rc4.d/S99ngc-network-setup
sudo ln -s /etc/init.d/ngc-network-setup /etc/rc5.d/S99ngc-network-setup

Part C. Run

Run in all-in-one mode

The daemon free5gc-ngcd includes AMF, SMF, UPF, HSS, and PCRF. Thus, instead of running all 5 daemons, you can just run free5gc-ngcd in your development environment.

./free5gc-ngcd
  • While running free5gc-ngcd
    • All logs for AMF, SMF, UPF, HSS, and PCRF are written to ./install/var/log/free5gc/free5gc.log.
    • All settings are managed in one place for ./install/etc/free5gc/free5gc.conf.
    • You can find the log/conf path at the beginning of the running screen.
    • You can user -f argument to specify config file to be used.

Run functions separately

We also provide 5GC functions running separately.

./free5gc-upfd
./free5gc-amfd
./free5gc-smfd
./nextepc-hssd
./nextepc-pcrfd

Note: We also provide a reference for 5GC functions running in separate machines.

[Optional] Self-test

We provide a program that checks whether the installation is correct.
After running the wireshark, select loopback interface, and then filter s1ap || diameter || gtpv2 || gtp and run ./test/testngc. You can see the packets virtually created.

./test/testngc -f install/etc/free5gc/test/free5gc.testngc.conf

Part D. Web User Interface

Install Node.js and NPM

sudo apt-get -y install curl
curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
sudo apt-get -y install nodejs

Install the dependencies to run WebUI (first time)

cd webui
npm install

Run WebUI

cd webui
npm run dev

Now the web server is running on http://localhost:3000.
The default username and password are "admin" and "1423".

Core Network Configuration

free5GC configuration file

Modify ./install/etc/free5gc/free5gc.conf

  1. amf-slap address (line 67)

    ​​​​amf:
​​​​  s1ap:
​​​​    addr: <IP of GW NIC to eNB: 192.188.2.2>

  2. upf-gtpu address (line 162)

    ​​​​smf:
​​​​  upf:
​​​​    addr: <IP of GW NIC to eNB: 192.188.2.2>

  3. AMF GUMMEI (line 91)

    ​​​​amf:
​​​​  gummei:
​​​​    plmn_id:
​​​​      mcc: <eNB MCC: 208>
​​​​      mnc: <eNB MNC: 93>
​​​​    mme_gid: <eNB MME GID: 1>
​​​​    mme_code: <eNB MME Code: 1>

  4. AMF TAI (line 130)

    ​​​​amf:
​​​​  tai:
​​​​    plmn_id:
​​​​      mcc: <eNB MCC: 208>
​​​​      mnc: <eNB MNC: 93>
​​​​    tac: <eNB TAC: 1>

Add subscriber (UE)

  • Add a subscriber by the Web UI 
    ​​​​  - Username : admin
​​​​  - Password : 1423
    • Add a subscriber with IMSI, K, OPc
    ​​​​  - Go to Subscriber Menu.
​​​​  - Click `+` Button to add a new subscriber.
​​​​  - Fill the IMSI, security context(K, OPc, AMF), and APN of the subscriber.
​​​​  - Click `SAVE` Button
    • This addition will take effect immediately on free5GC without restaring any daemon.

Rebuild Project

To completely rebuild the project after modifying source code

(Control-C kill free5gc-ngcd)
make maintainer-clean
rm -rf ./install
git pull
autoreconf -iv
./configure --prefix=`pwd`/install
make -j `nproc`
make install
./free5gc-ngcd

Troubleshooting

Note for modifying configuration file

  1. Use space for indent. DO NOT use tab.
  2. A white space must be added between the colon and value after the item name, e.g. addr: 192.188.2.2

./test/testngc test failure

  1. Make sure all configuration files and environment settings are correct.

  2. Kill testngc process which didn't finish correctly

    ​​​​killall -9 testngc

  3. Remove test subscriber left by previous failed test (NextEPC issue #57)

    ​​​​$ mongo
​​​​> use free5gc
​​​​> db.subscribers.find()  ### (Check the test subscriber)
​​​​> db.subscribers.drop()  ### Remove all subscriber
​​​​> db.subscribers.find()  ### (Check that all subscribers are empty)

./free5gc-ngcd errors

  1. ERRR: - The certificate is expired (NextEPC issue #94)

    ​​​​cd support/freeDiameter
​​​​./make_certs.sh .
​​​​cd ../..
​​​​make install

  2. Address already in use

    ​​​​$ killall -9 testngc
​​​​or
​​​​$ killall -9 free5gc-ngcd

Rebuild failure

  1. config.status: error: cannot find input file: `Makefile.in' (NextEPC issue #68) 
    ​​​​autoheader \
​​​​    && aclocal \
​​​​    && libtoolize --ltdl --copy --force \
​​​​    && automake --add-missing --copy \
​​​​    && autoconf \
​​​​    && ./configure

Appendix A: Program the SIM Card

Install packages:

sudo apt-get install pcscd pcsc-tools libccid python-dev swig python-setuptools python-pip libpcsclite-dev
sudo pip install pycrypto

Download PySIM

git clone git://git.osmocom.org/pysim.git

Change to pyscard folder and install

cd <pyscard-path>
sudo /usr/bin/python setup.py build_ext install

Verify your reader is ready

sudo pcsc_scan

Check whether your reader can read the SIM card

cd <pysim-path>
./pySim-read.py –p 0

Program your SIM card information

./pySim-prog.py -p 0 -x 208 -y 93 -t sysmoUSIM-SJS1 -i 208930000000003 --op=8e27b6af0e692e750f32667a3b14605d -k 8baf473f2f8fd09487cccbd7097c6862 -s 8988211000000088313 -a 23605945
Last changed by 
 
Chi Chang
0
1
3432

Read more

Proxmox 6.2 GPU Passthrough Tutorial

Hardware MB: ASUS TUF GAMING B460-PLUS CPU: Intel i7-10700 GPU: NVIDIA GTX-1060 BIOS Config Your hardware needs to support IOMMU (I/O Memory Management Unit) interrupt remapping, this includes the CPU and the mainboard. A. Enable VT-x In the Asus UEFI BIOS, this feature is in &quot;Advanced -&gt; CPU configuration&quot; and is named &quot;Intel Virtualization Technology&quot;.

May 3, 2023
UPF PFCP References

Nov 9, 2019
NextEPC Installation on KVM

Apr 23, 2019
Read more from Chi Chang
Published on HackMD