Try   HackMD

NextEPC Installation on KVM

Use Wirelab NextEPC or Official NextEPC commit 2afb6b

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]

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

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

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

    ​​​​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)
    ​​​​autoheader \
    ​​​​    && aclocal \
    ​​​​    && libtoolize --ltdl --copy --force \
    ​​​​    && automake --add-missing --copy \
    ​​​​    && autoconf \
    ​​​​    && ./configure
    

References

[ 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