free5GC Stage 2 Installation Guide

Minimum Requirement

Note: Please use Ubuntu 18.04 or later versions and go 1.12.9 linux/amd64

You can use go version to check your current Go version.

Hardware Tested

There are no gNB and UE for standalone 5GC available in the market yet.


A. Install Control Plane Entities

  1. Install the required packages

    sudo apt -y update
    sudo apt -y install mongodb wget git
    sudo systemctl start mongodb
  2. Go installation a. If another version of Go is installed

    • Please remove the previous Go version
      sudo rm -rf /usr/local/go
    • Install Go 1.12.9
      sudo tar -C /usr/local -zxvf go1.12.9.linux-amd64.tar.gz

    b. Clean installation

    • Install Go 1.12.9
      sudo tar -C /usr/local -zxvf go1.12.9.linux-amd64.tar.gz
      mkdir -p ~/go/{bin,pkg,src}
      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=off' >> ~/.bashrc
      source ~/.bashrc
  3. Clone free5GC project in $GOPATH/src

    cd $GOPATH/src
    git clone free5gc
  4. Run the script to install dependent packages

    cd $GOPATH/src/free5gc
    chmod +x ./
     Please ignore error messages during the package dependencies installation process.

  1. Extract the free5gc_libs.tar.gz to setup the environment for compiling
    cd $GOPATH/src/free5gc
    tar -C $GOPATH -zxvf free5gc_libs.tar.gz
  2. Compile network function services in $GOPATH/src/free5gc, e.g. AMF:
    cd $GOPATH/src/free5gc
    go build -o bin/amf -x src/amf/amf.go
  3. Run network function services, e.g. AMF:
    cd $GOPATH/src/free5gc
     In step 3, the folder name should remain free5gc. Please do not modify it or the compilation would fail.

B. Install User Plane Entity (UPF)

  1. Install the required packages
    sudo apt -y update
    sudo apt -y install git gcc cmake autoconf libtool pkg-config libmnl-dev libyaml-dev
    go get -u
  2. Enter the UPF directory
    cd $GOPATH/src/free5gc/src/upf
  3. Build from sources
    mkdir build
    cd build
    cmake ..
    make -j `nproc`
  4. Run UPF library test
    (In directory: $GOPATH/src/free5gc/src/upf/build)
    sudo ./bin/testgtpv1
  5. Config is located at $GOPATH/src/free5gc/src/upf/build/config/upfcfg.yaml

C. Run Procedure Tests

Start Wireshark to capture any interface with pfcp||icmp||gtp filter and run the tests below to simulate the procedures:

cd $GOPATH/src/free5gc
chmod +x ./

a. TestRegistration

# (In directory: $GOPATH/src/free5gc)
./ TestRegistration

b. TestServiceRequest

./ TestServiceRequest

c. TestXnHandover

./ TestXnHandover

d. TestDeregistration

./ TestDeregistration

e. TestPDUSessionReleaseRequest

./ TestPDUSessionReleaseRequest

f. TestPaging

./ TestPaging

g. TestN2Handover

./ TestN2Handover

Appendix A: Web Console

Subscriber information can be managed using the web console.

  1. Run the web console server
cd webconsole
go run server.go
  1. Access the web console by
URL: http://localhost:5000
Username: admin
Password: free5gc

Appendix B: System Environment Cleaning

The below commands may be helpful for development purposes.

  1. Remove POSIX message queues
    ls /dev/mqueue/
    rm /dev/mqueue/*
  2. Remove gtp tunnels (using tools in libgtpnl)
    cd ./src/upf/lib/libgtpnl-1.2.1/tools
    ./gtp-tunnel list
  3. Remove gtp devices (using tools in libgtpnl)
    cd ./src/upf/lib/libgtpnl-1.2.1/tools
    sudo ./gtp-link del {Dev-Name}

Appendix C: 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 use other similar devices.