(obsolete) OpenAir, single machine Ubuntu 17.04, after major EPC update

(updated: 2017, July 10th)

Modifs since version on July 6th:

  • Latest commit
  • Fix lacking file in the tarball
    (non modified ones since the June version were missing)
  • improved code pieces formating in HTML, added automatic git patch
  • Full re-test, from disk install of Ubuntu 17.04 to UE throughput measurement

This document explains how to install and configure OAI EPC+eNB on one single Ubuntu 17.04 64 bits machine connected with a regular UE (a Huawei E3272), routing the UE traffic to internet.

We use EPC after a major contribution in May 2017: a lot of code has been modified, all directories names were changes, configuration parameters names/values changed.

The description uses a USRP B210 board, a Lime SDR page is provided separately.

We also explain how to simplify, fix existing issues, to make a single computer as a full LTE network: EPC+eNB.

Known limitations fixed in the hereafter description

  • OAI EPC require kernel >= 4.7, so we have to use Ubuntu 17.04
    • We already pushed some enhancements in OAI, nevertheless some more are required
  • GTP UDP ports are in conflict for eNB and SGW
  • Useless link between OAI and the Ubuntu/Linux hostname removed
  • Several simplifications and precisions to make easier and reliable installations

Install Ubuntu

  • Prepare a machine: a 4 actual cores, no hyper-threading.
    All other configuration in OAI Wiki (C1 states, …) describes is about useless.
  • Download Ubuntu 17.04 64 bits version iso file
  • create a usb key to boot on it
  • install Ubuntu: choose to install Third party SW, and to upgrade all packages while installing
  • do: apt update; apt upgrade until the machine is up-to-date
  • install git and configure your identification in git:
     sudo apt install git 
     git config --global user.name "Laurent"
     git config --global user.email "laurent.thomas@open-cells.com"
  • Add the OAI repository as authorized remote system
    echo -n | openssl s_client -showcerts -connect gitlab.eurecom.fr:443 2>/dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' | sudo tee -a /etc/ssl/certs/ca-certificates.crt
  • if you are upset with sudo password, add this line in /etc/sudoers
    • xxxxxx ALL=(ALL) NOPASSWD: ALL (xxxxxx is your login name)
    • sudo will not ask anymore for a password

Install USRP drivers

Ettus has not yet released their driver for Ubuntu 17.04, we take it from source:

sudo apt-get install libboost-all-dev libusb-1.0-0-dev python-mako doxygen python-docutils python-requests cmake build-essential
git clone git://github.com/EttusResearch/uhd.git
cd uhd; mkdir host/build; cd host/build
cmake -DCMAKE_INSTALL_PREFIX=/usr ..
make -j4
sudo make install
sudo ldconfig
sudo /usr/lib/uhd/utils/uhd_images_downloader.py

Download our modifications

download: patches   extract the data:

tar xf opencells-mods-20170710.tgz

Download & Compile the eNB on 17.04

git clone https://gitlab.eurecom.fr/oai/openairinterface5g.git
cd openairinterface5g
git checkout develop
  • We tested with commit 08b8b3142df16831396a5283a015564ff56bf91c

We already merged in develop most of updates for Ubuntu 17.04, so we need only to add in build_helper file the Ubuntu 17.04 support

git apply opencells-mods/eNB.patch
  • Now, you should be able to build as usual the eNB
source oaienv  
./cmake_targets/build_oai -I       # install SW packages from internet
./cmake_targets/build_oai  -w USRP --eNB --UE # compile eNB

Download and patch EPC

Clone OAI EPC:

git clone https://gitlab.eurecom.fr/oai/openair-cn.git
cd openair-cn
git checkout develop

(we used: commit 5353b606662a6ae7eaadf6bc39cbf6452d298b0e)

Apply the patch:

git apply opencells-mods/EPC.patch

The new version of the source files are also in the tar, if you want to merge with another version of OpenAir EPC

What is in the patch file:

  • Add Ubuntu 17.04 for compilation and fix some bugs
    • build/tools/build_helper
    • src/common/common_defs.h
    • src/oai_hss/utils/hss_config.c
  • Remove link between Linux host name and LTE diameter protocol configuration
    • src/s6a/s6a_peer.c
  • Add usage of the input address for the SGW input socket
    • src/gtpv1-u/gtp_mod_kernel.c
    • src/gtpv1-u/gtp_mod_kernel.h
    • src/gtpv1-u/gtpv1u_task.c

No kernel module patch is required anymore: generic Ubuntu kernel 17.04 works fine with OAI

Install third party SW for EPC

cd openair-cn; source oaienv; cd scripts
./build_hss -i
  • Do you want to install freeDiameter 1.2.0 ?: yes
  • set your MySQL password and remember it!
  • Answer yes to install: freeDiameter 1.2.0
  • phpmyadmin:
    • choose light or apache as you prefer
    • Configure database for phpmyadmin with dbconfig-common: yes
    • password: same as MySQL for simplicity
    • We don’t use phpmyadmin later in this procedure, nevertheless we tested successfully also with it
  • Install 3PP SW for mme and spgw
./build_mme -i
  • Do you want to install freeDiameter 1.2.0: no
  • Do you want to install asn1c rev 1516 patched? <y/N>: no
  • Do you want to install libgtpnl ? <y/N>: yes
  • wireshark permissions: as you prefer
 ./build_spgw -i
  • Do you want to install libgtpnl ? <y/N>: no

Compile the EPC nodes

No difficulty found in this phase.

cd openair-cn; source oaienv; cd scripts
./build_hss
./build_mme
./build_spgw

Our Network setup description

I’ve made a simple configuration for this all-in-one setup.

Each node is on a separate IP address, this address is used for all it’s interfaces. In our case of all-in-one, we take addresses on the loopback: this will be fine on all your machines.

  • HSS is on localhost: 127.0.0.1
  • eNB is on 127.0.0.10
  • MME is on 127.0.0.20
  • SPGW is on 127.0.0.30

The LTE diameter configuration is now isolated from Linux hostname.

realm for our EPC: “OpenAir5G.Alliance”, so, full distinguish names (FQDN) are: hss.OpenAir5G.Alliance, mme.OpenAir5G.Alliance

Install this configuration for eNB

In your eNB configuration file, the network is now fixed, as lo interface always exists and our computer internal addresses also:

////////// MME parameters:
 mme_ip_address = ( { ipv4 = "127.0.0.20";
 ipv6 = "192:168:30::17";
 active = "yes";
 preference = "ipv4";
 }
 );

NETWORK_INTERFACES : 
 {
 ENB_INTERFACE_NAME_FOR_S1_MME = "lo";
 ENB_IPV4_ADDRESS_FOR_S1_MME = "127.0.0.10/8";

 ENB_INTERFACE_NAME_FOR_S1U = "lo";
 ENB_IPV4_ADDRESS_FOR_S1U = "127.0.0.10/8";
 ENB_PORT_FOR_S1U = 2152; # Spec 2152
 };

In the eNB config file, you need also to set the MCC and MNC as per your SIM card:

tracking_area_code = “1”;
mobile_country_code = “208”;
mobile_network_code = “92”;

And obviously, your radio parameters.

Wwe tested with USRP B210 and two parameter files: 10MHz band, 20MHz band, Huawei E3272 UE, a cavity duplexer a simple antenna, about 1 meter distance UE/eNB antenna.

  • openairinterface5g/targets/PROJECTS/GENERIC-LTE-EPC/CONF/enb.band7.tm1.50PRB.usrpb210.conf
  • openairinterface5g/targets/PROJECTS/GENERIC-LTE-EPC/CONF/enb.band7.tm1.100PRB.usrpb210.conf

Install this configuration for EPC

For the EPC, we install in OAI default directory: /usr/local/etc/oai

sudo mkdir -p /usr/local/etc/oai
sudo cp -rp opencells-mods/config_epc/* /usr/local/etc/oai
cd openair-cn; source oaienv; cd scripts
./check_hss_s6a_certificate /usr/local/etc/oai/freeDiameter hss.OpenAir5G.Alliance
./check_mme_s6a_certificate /usr/local/etc/oai/freeDiameter mme.OpenAir5G.Alliance

Only the SGi output to internet need to be configured.
In /usr/local/etc/oai/spgw.conf,
your should set the Ethernet interface that is connected to Internet, and,
to tell to the PGW to implement NAPT for the UE traffic

 PGW_INTERFACE_NAME_FOR_SGI = "enp3s0"; 
 PGW_MASQUERADE_SGI = "yes";

For the SIM card, you’ll have more to do:

  • SIM MCC/MNC should be duplicated in a couple of files
    • eNB: See above in eNB configuration chapter
    • MME file: /usr/local/etc/oai/mme.conf to update
GUMMEI_LIST = ( MCC="208" ; MNC="92"; MME_GID="4" ; MME_CODE="1"; } );
TAI_LIST = ({MCC="208" ; MNC="92"; TAC = "1"; } );
    • HSS
      • Configure the password for MySQL
        • in /usr/local/etc/oai/hss.conf, set password as the password you created during MySQL installation
      • A HSS database in text is in: opencells-mods/opencells_db.sql
        • We don’t use phpmyadmin: we load the database from a ascii file
        • It is pre-configured with the
          • mme id
          • 10 users is network 208/92 (a French test network) are also created (don’t use 3GPP test network: 001/01: the mme fails when MCC starts by “0”)
        • Each time you import this db, it erases the entire database
          (example: you set mysql password to “linux”)
./hss_db_import 127.0.0.1 root linux oai_db opencells-mods/opencells_db.sql
        • We use to modify the db by updating this file with regular text editor,
          then we re-load the entire database,
          but, if you prefer, usage of http://localhost/phpmyadmin is fine
        • The important values to set are:
          • table pdn:
            • all IMSI are listed, with the APN: these values are in UE/USIM
          • table users:
            • all IMSI, key (Ki) and OPc must be the same in USIM card
            • Sqn increments automatically  when the UE authenticate in both USIM and HSS DB: it should be set as per USIM internal incrementation
      • SIM card update
        • Open cells UICC and card reader will  be supported

Final test and verification

open 4 terminal windows

  1. in each window
cd openair-cn; source oaienv; cd SCRIPTS; ./run_hss
cd openair-cn; source oaienv; cd SCRIPTS; ./run_mme
cd openair-cn; source oaienv; cd SCRIPTS; sudo -E ./run_spgw
sudo bash
cd openairinterface5g; source oaienv
./cmake_targets/lte_build_oai/build/lte-softmodem -O <your config file>

Connect the UE, it should attach to network and be able to reach internet through OAI network

We re-built this procedure from scratch and tested two machines: i5-4570 and i5-6600K.

On the i5-4570, at maximum traffic, the eNB is stable on 10MHz band at full user data speed.

On the i5-6600K, we obtain stable performance at maximum traffic over 20MHz, transmission mode 1 (SISO), one single UE over-the-air 1 meter distance:

Intel CPUs performance

Most people recommends to disable hyper-threading for tasks such as signal processing on Intel CPUs.

So,there will be no difference between two CPUs, if they have same core architecture and same number of actual cores.

Not only frequency matter: instructions set (AVX2 for example) and the core internal architecture are important.

Many people have issues related to thermal capacity of the box: brick like format may decrease CPU performance if it becomes too hot.

Taking 3 different CPUs, similar SSD, Ubuntu, let’s see how OAI performs with OAI PHY unitary tests

General purpose usage: let’s compile the OAI PHY simulators

N3160
Ubuntu 17.04
i5-4300M
Ubuntu 16.04
i5-6600K
Ubuntu 17.04
Total cpu cost cumulated all cores395 sec146 sec75 sec
Elapsed time216s sec80 sec40 sec

Now, we run OAI phy processing on one core

N3160i5-4300Mi5-6600K
Detected cpu_freq1.6 GHz
(turbo: 2.2GHz)
2.6 GHz
(Turbo 3.3GHz)
3.5 GHz
(overclock: 4.1GHz)
UE mode: Total PHY proc tx339.031893 us72.814188 us50.013725 us
UE mode: only
ULSCH multiplexing time
20.204291 us7.258590 us5.122038 us
eNB mode: total time483.742061 us 86.693388 us62.064970 us

Conclusion:

N3160, that is recent Atom core architecture (Braswell) is much slower than main stream core architecture.

On main stream CPUs, Intel improved but not that much between Haswell architecture and Skylake.

The difference between the two i5-xxxx is also small because both have AVX2 instructions.

Intel developed more the GPU part between gen 4 (Haswell) and gen 6 (Skylake).

If we take a older CPU like ix-3xxx or before, the difference will be larger for same frequency.

If some people perform similar tests with i7-xxxx or Xeon, they will find out the same values for the same core architecture, no matter the commercial denomination.

LimeSDR installation

Tutorial to install LimeSDR USB instead of USRP in the setup described in:

OpenAir, single machine Ubuntu 17.04, after major EPC update

Considering LimeSDR is under development we will install all from source

Add Ubuntu packages required by SoapySDR and LimSDR

sudo apt-get install cmake g++ libpython-dev python-numpy swig git libsqlite3-dev libi2c-dev libusb-1.0-0-dev libwxgtk3.0-dev freeglut3-dev

Install SoapySDR

git clone https://github.com/pothosware/SoapySDR.git
cd SoapySDR
git pull origin master
mkdir build && cd build
cmake ..
make -j4
sudo make install
sudo ldconfig

Install LimeSDR

git clone https://github.com/myriadrf/LimeSuite.git
cd LimeSuite
mkdir build && cd build
cmake ..
make -j4
sudo make install
sudo ldconfig
cd ../udev-rules/
sudo ./install.sh
# Download board firmware
sudo LimeUtil --update

Now, we can implement all the tuto made for USRP, changing a few parameters

Compile OpenAirInterface softmodem, as for USRP

./cmake_targets/build_oai -c -w LMSSDR --eNB --UE

To run, you need a config file specific for the LimeSDR board

./cmake_targets/lte_build_oai/build/lte-softmodem -d -O enb.conf --rf-config-file targets/ARCH/LMSSDR/LimeSDR_above_1p8GHz_1v4.ini

This config file is for 1v4 or 1v4s LimeSDR board revision (revision is written on the board).

The connector to use with this config file: RX1_H and TX1_2

I managed to attach a regular UE fdd band 7, but the throughput and stability is much poorer than my USRP.

I’ll try to make better radio configuration soon.

(obsolete) All-in-one OpenAirInterface eNB+EPC

(updated: 2017, May 8th)

This document explains how to install and configure OAI EPC+eNB on one single Ubuntu 17.04 64 bits machine connected with a regular UE (a Huawei E3272), routing the UE traffic to internet.

The description uses a USRP B210 board.

We also explain how to simplify, fix existing issues, to make a single computer as a full LTE network: EPC+eNB.

Known limitations fixed in the hereafter description

  • OAI EPC require kernel >= 4.7, so we have to use Ubuntu 17.04
  • GTP UDP ports are in conflict for eNB and SGW
  • Useless link between OAI and the Ubuntu/Linux hostname

Install Ubuntu

  • Prepare a machine: a 4 actual cores, no hyper-threading.
    All other configuration OAI Wiki (C1 states, …) describes is about useless.
  • Download Ubuntu 17.04n 64 bits version iso file
  • create a usb key to boot on it
  • install Ubuntu: choose to install Third party SW, and to upgrade all packages while installing
  • do: apt update; apt upgrade until the machine is up-to-date
  • install git and configure your identification in git:
    apt install git
    git config –global user.name “Laurent”
    git config –global user.email “laurent.thomas@open-cells.com”
  • Add the OAI repository as authorized remote system
    echo -n | openssl s_client -showcerts -connect gitlab.eurecom.fr:443 2>/dev/null | sed -ne ‘/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p’ | sudo tee -a /etc/ssl/certs/ca-certificates.crt
  • if you are upset with sudo password, add this line in /etc/sudoers
    • xxxxxxxxxxx ALL=(ALL) NOPASSWD: ALL
    • (xxxxxxxxxxx is your login name)
    • sudo will not ask anymore for a password

Install USRP drivers

Ettus has not yet released their driver for Ubuntu 17.04, we take it from source:

  • sudo apt-get install libboost-all-dev libusb-1.0-0-dev python-mako doxygen python-docutils python-requests cmake build-essential
  • git clone git://github.com/EttusResearch/uhd.git
  • cd uhd; mkdir host/build; cd host/build
  • cmake -DCMAKE_INSTALL_PREFIX=/usr ..
  • make -j4
  • sudo make install
  • sudo ldconfig
  • sudo /usr/lib/uhd/utils/uhd_images_downloader.py

Download & Compile the eNB on 17.04

  • git clone https://gitlab.eurecom.fr/oai/openairinterface5g.git
  • cd openairinterface5g
  • git checkout develop
  • As we already tested and merged in develop updates for Ubuntu 16.10
  • A few updates are required for Ubuntu 17.04
    replace the file cmake_targets/tools/build_helper by: build_helper
  • Now, you should be able to build as usual the eNB
    • source oaienv                                    # configure the shell
    • ./cmake_targets/build_oai -I       # install SW packages from internet
    • ./cmake_targets/build_oai -c -w USRP –eNB –UE # compile eNB

Download and patch EPC

First, clone OAI EPC:
git clone https://gitlab.eurecom.fr/oai/openair-cn.git

I detached the OAI code from any relation between the Linux host name, DNS and the Diameter protocol identifiers such as Realm and end point identifier for diameter protocol

For this, you need to replace with  openair-cn-fixes these files

  • SRC/GTPV1-U/gtp_mod_kernel.[ch] and SRC/GTPV1-U/gtpv1u_task.c
    To use the SPGW destination address parameter. This parameter is already in the config file (but not used in the present EPC code). This enhancement removes the conflict on the same port with the eNB, therefore we can run both SPGW and eNB in the same machine.
  • SRC/S6A/s6a_peer.c
    The modification is only to remove the code that reads Linux host name to overwrite the (correct, already read from the configuration file) diameter id.
  • build_helper: for Ubuntu 17.04 support

Install third party SW for EPC

  • cd openair-cn; source oaienv; cd SCRIPTS
  • ./build_hss -i
    • Answer yes to install: freeDiameter 1.2.0
    • for mysql and phpmyadmin, remember the password you set, it will be mandatory to configure the hss
  • Install 3PP SW for mme and spgw
  • ./build_mme -i ; ./build_spgw -i
    When questions pop-up

    • Don’t re-install ans1c (should have been installed correctly for eNB)
    • Don’t re-install what is already installed
  • Install the GTP kernel module
    • The kernel you have should be 4.10, it contains the Osmocom gtp module
    • This archive contains the module source, patched with the OAI improvements done for kernel 4.7: gtp
      • NO need to download the whole kernel in source to compile a module
        • tar xf gtp_mod.4.10.tgz; cd gtp_mod.4.10
        • make -C /lib/modules/`uname -r`/build M=$PWD
        • sudo cp gtp.ko /lib/modules/`uname -r`/kernel/drivers/net/gtp.ko
      • If you keep Ubuntu up-to-date automatically (default Ubuntu behavior), you’ll need to update the module after each Ubuntu kernel upgrades (each time “uname -r” changes)
      • If you want to use another kernel, you’ll have to merge the file gtp.c with your kernel version source code of gtp.c.
        To help, I’ve let origin 4.10 code in gtp.c.orig

Compile the EPC nodes

No difficulty found in this phase.

  • cd openair-cn; source oaienv; cd SCRIPTS
  • ./build_hss
  • ./build_mme
  • ./build_spgw

Our Network setup description

I’ve made a simple configuration for this all-in-one setup.

Each node is on a separate IP address, this address is used for all it’s interfaces. In our case of all-in-one, we take addresses on the loopback: this will be fine on all your machines.

  • HSS is on localhost: 127.0.0.1
  • eNB is on 127.0.0.10
  • MME is on 127.0.0.20
  • SPGW is on 127.0.0.30

Thanks to the above patch: the diameter configuration is now isolated from Linux hostname.

I’ve chosen: realm for the EPC: “OpenAir5G.Alliance”
So, full distinguish names are:

  • hss.OpenAir5G.Alliance
  • mme.OpenAir5G.Alliance

Install this configuration for eNB

In your eNB configuration file, the network is now fixed, as lo interface always exists and our computer internal addresses also:

////////// MME parameters:
 mme_ip_address = ( { ipv4 = "127.0.0.20";
 ipv6 = "192:168:30::17";
 active = "yes";
 preference = "ipv4";
 }
 );

NETWORK_INTERFACES : 
 {
 ENB_INTERFACE_NAME_FOR_S1_MME = "lo";
 ENB_IPV4_ADDRESS_FOR_S1_MME = "127.0.0.10/8";

ENB_INTERFACE_NAME_FOR_S1U = "lo";
 ENB_IPV4_ADDRESS_FOR_S1U = "127.0.0.10/8";
 ENB_PORT_FOR_S1U = 2152; # Spec 2152
 };

In the eNB config file, you need also to set the MCC and MNC as per your SIM card:

tracking_area_code = “1”;
mobile_country_code = “208”;
mobile_network_code = “92”;

And obviously, your radio parameters.

Install this configuration for EPC

For the EPC, we install in OAI default directory: /usr/local/etc/oai this tar file: oai.config

Then, you should generate the cyphering certificates:

  • cd openair-cn; source oaienv; cd SCRIPTS
  • ./check_hss_s6a_certificate /usr/local/etc/oai/freeDiameter hss.OpenAir5G.Alliance
  • ./check_mme_s6a_certificate /usr/local/etc/oai/freeDiameter mme.OpenAir5G.Alliance

Only the SGi output to internet need to be configured.
In /usr/local/etc/oai/spgw.conf,
your should set the Ethernet interface that is connected to Internet, and,
to tell to the PGW to implement NAPT for the UE traffic

 PGW_INTERFACE_NAME_FOR_SGI = "enp3s0"; 
 PGW_MASQUERADE_SGI = "yes";

For the SIM card, you’ll have more to do:

  • SIM MCC/MNC should be duplicated
    • eNB: See above in eNB configuration chapter
    • MME
      • file: /usr/local/etc/oai/mme.conf to update
        • GUMMEI_LIST = ( MCC=”208″ ; MNC=”92″; MME_GID=”4″ ; MME_CODE=”1″; } );
        • TAI_LIST = ({MCC=”208″ ; MNC=”92″; TAC = “1”; } );
        • S-GW_LIST_SELECTION = (
          {ID=”tac-lb01.tac-hb00.tac.epc.mnc092.mcc208.3gppnetwork.org” ; SGW_IPV4_ADDRESS_FOR_S11=”127.0.0.30/8″;}
          );
    • HSS
      • Configure the password for MySQL
        • in /usr/local/etc/oai/hss.conf, set user as root and password as the password you created during MySQL installation
      • A HSS database in text is in: /usr/local/etc/oai/opencells_db.sql
        • It is preconfigured with the mme id, the pgw id
        • A SIM user in network 001/01 (the test network defined by 3GGP) is already created.
        • 10 users is network 208/92 (a French test network) are also created
        • Each time you import this db, it erases the entire database
          (example: mysql user=root, password=linux)

          • ./hss_db_import 127.0.0.1 root linux oai_db /usr/local/etc/oai/opencells_db.sql
        • One can modify the db either with a text editor of this file, or ,
          by sql: http://localhost/phpmyadmin
        • The important values to set are:
          • table pdn:
            • all IMSI are listed, with the APN: these values are in UE/SIM
          • table users:
            • all IMSI are, key (Ki) and OPc must be the same in USIM card.
              Sqn increments when the UE authenticate,
              it should be set as per USIM internal incrementation
      • SIM card update
        • will be described later, for Open cells UICC and card reader

Final test and verification

open 4 terminal windows

  1. in first window
    • cd openair-cn; source oaienv; cd SCRIPTS; ./run_hss
  2. in second window
    • cd openair-cn; source oaienv; cd SCRIPTS; ./run_mme
  3. in third window
    • cd openair-cn; source oaienv; cd SCRIPTS; sudo -E ./run_spgw
  4. in last windows
    • sudo bash
    • cd openairinterface5g; source oaienv;
    • export LD_LIBRARY_PATH=/usr/local/lib/:./targets/bin;
    • ./cmake_targets/lte_build_oai/build/lte-softmodem -d -O <your config file>
  5. Connect the UE, it should attach to network and be able to reach internet through OAI network
  6. Enjoy