free5GC Installation on KVM

Minimum Requirement

Hardware Tested




KVM Environment Setup

Collect eNodeB and USIM Information


Please follow the instructions from Part A ~ Part C.

Part A. Compile Source Code


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
chmod +x installer_linux
source ~/.bash_profile
rm -f installer_linux

go get -u -v ""
go get -u -v ""
go get -u -v ""

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

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/

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

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


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
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
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
# Provides:          ngc-network-setup
# Required-Start:    networkd
# Required-Stop:     networkd
# Default-Start:     networkd
# Default-Stop:      networkd
# Short-Description:
# Description:

ifconfig ens4
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

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 AMFSMFUPFHSS, and PCRF. Thus, instead of running all 5 daemons, you can just run free5gc-ngcd in your development environment.


Run functions separately

We also provide 5GC functions running separately.


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 | 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)

        addr: <IP of GW NIC to eNB:>
  2. upf-gtpu address (line 162)

        addr: <IP of GW NIC to eNB:>
  3. AMF GUMMEI (line 91)

          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)

          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


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:

./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
    ./ .
    cd ../..
    make install
  2. Address already in use

    $ killall -9 testngc
    $ killall -9 free5gc-ngcd

Rebuild failure

  1. config.status: error: cannot find input file: `' (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://

Change to pyscard folder and install

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

Verify your reader is ready

sudo pcsc_scan

Check whether your reader can read the SIM card

cd <pysim-path>
./ –p 0

Program your SIM card information

./ -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.