free5GC

free5GC Installation on KVM

Minimum Requirement

Hardware Tested

eNB

UE

Preparation

KVM Environment Setup

Collect eNodeB and USIM Information

Installation

Please follow the instructions from Part A ~ Part C.

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-stage-1.git
cd free5gc-stage-1
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

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)

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

You can get your SIM card from sysmocom. You also need a card reader to write your SIM card. You can get a card reader from here or equivalent device will do.