---
tags: 5GC
---

# NextEPC Installation on KVM

Use **Wirelab NextEPC** or [Official NextEPC commit `2afb6b`](https://github.com/acetcom/nextepc/commit/e2afb6b2fce6414ec086f516f7bce86e15fbccf6)

[ToC]

## Preparation

### KVM Environment Setup

* VM NIC Cards
1. For connecting Internet
* Netowrk source: `Virtual network - NAT`
* Interface name in VM: `ens3` (in this example)
2. NIC for connecting eNB:
* Netowrk 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
    PLMN:
      MCC: 208
      MNC: 93
    MME GID:  1
    MME Code: 1
    TAC: 1

* USIM Information (in this example)

    IMSI 208930000000003
    K    8baf473f2f8fd09487cccbd7097c6862
    OPc  8e27b6af0e692e750f32667a3b14605d

    IMSI 460990000072000
    K    0123456789ABCDEF0123456789ABCDEF
    OP   0123456789ABCDEF0123456789A46099

    IMSI 466680123457005
    K    000102030405060708090A0B0C0D0E0F
    OP   00112233445566778899AABBCCDDEEFF

## Installation

*You can either follow instructions from Part A ~ Part C or directly execute the shell on the bottom of this document.*

### Part A. Compile Source Code

#### Prerequisites

Install Mongo DB with Package Manager.

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

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

ls -al /dev/net/tun
crw-rw-rw- 1 root 28 10, 200 Feb 11 05:13 /dev/net/tun

Write the configuration file for the TUN deivce.

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

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

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

(if the output is 0 and IPv6 is enabled, skip the followings)
sudo sh -c "echo 'net.ipv6.conf.pgwtun.disable_ipv6=0' > /etc/sysctl.d/30-nextepc.conf"
sudo sysctl -p /etc/sysctl.d/30-nextepc.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-nextepc.network
[Match]
Name=pgwtun
[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 pgwtun
iface pgwtun inet static
	address 45.45.0.1
	netmask 255.255.0.0

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

Restart pgwtun interface

sudo ip a flush pgwtun
sudo systemctl restart networking

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

#### MME, SGW, PGW, 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://github.com/acetcom/nextepc
cd nextepc
autoreconf -iv
./configure --prefix=`pwd`/install
make -j `nproc`
make install

#### Self-test
We provide a program that checks whether the installation is correct.
After running the wireshark, select `loopback` interface, filter `s1ap || diameter || gtpv2 || gtp` and run `./test/testepc`. You can see the virtually created packets. [[testepc.pcapng]](http://nextepc.org/static/pcapng/testepc.pcapng)

./test/testepc

#### Run in all-in-one mode
The daemon `nextepc-epcd` includes both *MME*, *SGW*, *PGW*, *HSS*, and *PCRF*.
So, instead of running all 5 daemons, you can just run `nextepc-epcd` in your development environment.

./nextepc-epcd

* While running `nextepc-epcd`
* All logs for MME, SGW, PGW, PCRF, and HSS are written to `./install/var/log/nextepc/nextepc.log`.
* All settings are managed in one place for `./install/etc/nextepc/nextepc.conf`.
* You can find the log/conf path at the beginning of running screen.
* You can user ``-f`` argument to specify config file to be used.

### Part B. Web User Interface

Install [Node.js](https://nodejs.org/) and [NPM](https://www.npmjs.com/)

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

Running WebUI

cd webui
npm run dev

Now the web server is running on _http://localhost:3000_.

### Part C. Configuration

#### Modify NextEPC config file
Modify `./install/etc/nextepc/nextepc.conf`

1. mme-slap address (line 66)

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

2. sgw-gtpu address (line 212)

    sgw:
      gtpu:
        addr: <IP of GW NIC to eNB: 192.188.2.2>

3. MME GUMMEI (line 100)

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

4. MME TAI (line 139)

    mme:
      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
* Run the web server: `cd ./webui && npm run dev`
* Visit _http://localhost:3000_

      - 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 affects immediately NextEPC without restaring any daemon.

### 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 pgwtun -j ACCEPT

[Option 2] or configure as auto run on boot

sudo sh -c "cat << EOF > /etc/init.d/epc-network-setup
#!/bin/sh
### BEGIN INIT INFO 
# Provides:          epc-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 pgwtun -j ACCEPT
EOF"

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

sudo ln -s /etc/init.d/epc-network-setup /etc/rc3.d/S99epc-network-setup
sudo ln -s /etc/init.d/epc-network-setup /etc/rc4.d/S99epc-network-setup
sudo ln -s /etc/init.d/epc-network-setup /etc/rc5.d/S99epc-network-setup

## Rebuild Project
To completely rebuild after modifying source code

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

## Troubleshooting

### Notice for Modifying Config File
1. Use space for ident, **DO NOT use tab**
2. A white space must be added between the **colon** and **value** after the item nam. e.g. ``addr: 192.188.2.2``

### ./test/testepc Test Failed
1. Make sure all config file and environment settings are correct.

2. Kill testepc process which didn't finish correctly

    killall -9 testepc

3. Remove test subscriber left by previous failed test ([Issue #57](https://github.com/acetcom/nextepc/issues/57#issuecomment-386177165))

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

### ./nextepc-epcd Error Occurred
1. ``ERRR: - The certificate is expired`` ([Issue #94](https://github.com/acetcom/nextepc/issues/94))

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

2. ``Address already in use``

    $ killall -9 testepc
    or
    $ killall -9 nextepc-epcd

### Rebuild Error
1. ``config.status: error: cannot find input file: `Makefile.in'`` ([Issue #68](https://github.com/rscada/libmbus/issues/68))

    autoheader \
        && aclocal \
        && libtoolize --ltdl --copy --force \
        && automake --add-missing --copy \
        && autoconf \
        && ./configure

## References
* https://github.com/acetcom/nextepc
* http://nextepc.org/guides/2-build/
* http://nextepc.org/guides/3-configuration/
* https://github.com/acetcom/nextepc/issues/18

## \[ Shell Script \]

*Please make some modifications to the environment variables on the top of this script if needed according to the actual condition.*

Bash Script for Ubuntu 18.04 Minimal Installation

#!/bin/sh
set -o xtrace
set -e

##### [Env Variables] #####
GIT_REPO=https://gitlab.com/wirelab/nextepc.git

if [ $# != 8 ]
then
    NIC_INTERNET=ens3
    NIC_eNB=ens4
    NIC_eNB_IP=192.188.2.2

    PLMN_MCC=208
    PLMN_MNC=93
    MME_GID=1
    MME_CODE=1
    TAC=1
else
    NIC_INTERNET=$1
    NIC_eNB=$2
    NIC_eNB_IP=$3

    PLMN_MCC=$4
    PLMN_MNC=$5
    MME_GID=$6
    MME_CODE=$7
    TAC=$8
fi

##### Clone Git Repo #####
sudo apt-get -y install git
git clone $GIT_REPO


##### Install NextEPC #####
sudo apt-get -y update
sudo apt-get -y install mongodb net-tools
sudo systemctl start mongodb 

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

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

if [[ $(sysctl -n net.ipv6.conf.pgwtun.disable_ipv6) != 0 ]]; then
    sudo sh -c "echo 'net.ipv6.conf.pgwtun.disable_ipv6=0' > /etc/sysctl.d/30-nextepc.conf"
    sudo sysctl -p /etc/sysctl.d/30-nextepc.conf
fi

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

sudo systemctl restart systemd-networkd

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

cd nextepc
autoreconf -iv
./configure --prefix=`pwd`/install
make -j `nproc`
make install


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

cd webui
npm install
cd ..


##### Self-Test #####
# Running self test after modifying config may fail
sleep 10
./test/testepc


##### NextEPC Config #####
CONFIG_PATH=./install/etc/nextepc
CONFIG=$CONFIG_PATH/nextepc.conf

# Backup the original config
cp $CONFIG $CONFIG_PATH/nextepc.conf.original

sed -i "66s/.*/      addr: $NIC_eNB_IP\n/" $CONFIG
sed -i "213s/.*/      addr: $NIC_eNB_IP\n/" $CONFIG

sed -i "103s/.*/        mcc: $PLMN_MCC/" $CONFIG
sed -i "104s/.*/        mnc: $PLMN_MNC/" $CONFIG
sed -i "105s/.*/      mme_gid: $MME_GID/" $CONFIG
sed -i "106s/.*/      mme_code: $MME_CODE/" $CONFIG

sed -i "142s/.*/        mcc: $PLMN_MCC/" $CONFIG
sed -i "143s/.*/        mnc: $PLMN_MNC/" $CONFIG
sed -i "144s/.*/      tac: $TAC/" $CONFIG


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

ifconfig $NIC_eNB $NIC_eNB_IP
sh -c 'echo 1 > /proc/sys/net/ipv4/ip_forward'
iptables -t nat -A POSTROUTING -o $NIC_INTERNET -j MASQUERADE
iptables -I INPUT -i pgwtun -j ACCEPT
EOF"

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

sudo ln -s /etc/init.d/epc-network-setup /etc/rc3.d/S99epc-network-setup
sudo ln -s /etc/init.d/epc-network-setup /etc/rc4.d/S99epc-network-setup
sudo ln -s /etc/init.d/epc-network-setup /etc/rc5.d/S99epc-network-setup


##### Start the Standalone Deamon #####
./nextepc-epcd