GENILTE/LTEDeploymentRutgers: main.tex

\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage{hyperref}
\usepackage{graphicx}
\usepackage{alltt}
\renewcommand{\ttdefault}{txtt}
\title{GENI LTE EPC DOCUMENTATION}
\author{Raytheon BBN + Rutgers Winlab Orbit}
\date{July 18, 2017}

\begin{document}

\maketitle

\section{Introduction}
The purpose of this document is to outline the procedure needed to configure the GENI Test LTE EPC located at Rutgers Orbit Winlab. The main goal that was accomplished from this procedure was to create a central Evolved Packet Core (EPC) that all GENI sites may connect to using their own base stations (eNBs) and user equipment (UEs) without having to configure individual EPCs.

\section{System Requirements}
\subsection{Hardware}
The machine chosen to run as the EPC should have at least 4 GB of RAM, 120 GB or more of disk storage, have a 64-bit Intel processor, and also have a 1G Ethernet interface. As an example, at the Winlab Orbit Facility, the system is currently configured on a server with two 160 GB hard drives. Two VLANS are configured, one for the LTE Multipoint and the other for the WiMAX multipoint. 
\subsection{Software}
This EPC uses the Amarisoft LTE 100 software package, specifically their EPC solution(Version 2017-06-02). More details about this can be found at \url{https://www.amarisoft.com/software-enb-epc-ue-simulator/}. The software can run on any 64-bit Linux OS, and has been tested with Fedora versions 17-25 and Ubuntu releases 12.x-16.x. The GENI LTE EPC is configured with an Ubuntu Server 16.04 LTS install, running on Linux Kernel 4.4. 
\section{Installation Procedure}
Before installation:
\begin{itemize}
    \item Make sure the system is up-to-date: \begin{verbatim}
      sudo apt update && sudo apt upgrade  
    \end{verbatim}
    \item Acquire the tarball of the licensed Amarisoft software package.
    \item If a /opt/ directory is not already present, create one
\end{itemize}
Once these preliminary steps are complete, the following procedure can be followed to make a clean installation:
\begin{itemize}
    \item Unzip the tarball in the /opt/ directory: \begin{verbatim}tar -C /opt -xf amarisfot-2017-06-02.tar.gz \end{verbatim}
    \item To automatically install all components of the Amarisoft software, simply run the install script:\begin{verbatim}
    cd /opt/amarisoft-2017-06-02
    sudo ./install.sh \end{verbatim}
    \item Install SCTP tools if they are not present already on the system: \begin{verbatim} sudo apt install lkstcp-tools\end{verbatim}
    \item Next, run the script that sets the NAT forwarding rules. This will enable IP forwarding (where interface-name is the name of the Ethernet interface): \begin{verbatim}
sudo ./lte_init interface-name
    \end{verbatim}
\end{itemize}
\section{Configuration}
The GENI LTE EPC runs on the following IP: \textbf{10.3.0.250}, ensure that this is set as the static IP for the EPC. Configuration of the Amarisoft LTE software is rather simple, and takes place all in one file, the "mme.cfg" file. First, make a backup of \textbf{mme.cfg} in some convenient location. Then, edit the \textbf{mme.cfg} file in /opt/ in the following manner:
\begin{itemize}
    \item Change \textbf{GTP address} to the current outbound address, which is the IP of the EPC
    
    Before: \begin{verbatim}
        gtp_addr: "127.0.1.100",
    \end{verbatim}
    
    After: \begin{verbatim}
        gtp_addr: "10.3.0.250",
    \end{verbatim}
    \item Right below this change, add the following to set the gtp payload mtu:
    \begin{verbatim}
        gtp_payload_mtu: 1500, 
    \end{verbatim}
    \item Next, give the MME a name to be identified by and also a "short" name 
    
    Before: \begin{verbatim}
        network_name: "Amarisoft Network",
        network_short_name: "Amarisoft",
    \end{verbatim}
    
    After: \begin{verbatim}
        network_name: "GENI LTE Network",
        network_short_name: "GENI",
    \end{verbatim}
    \item The "pdn-list" structure needs to be modified. These modifications include the access point name, the IP start-end ranges for both IPV4 and the UE specific fields, and the addition of a mtu-ipv4 field that is not present in the default configuration file. Please refer to the bold text, they show the necessary adjustments.
    
    "pdn-list" before:
    \begin{alltt}
pdn_list: [
    {
      pdn_type: "ipv4",
      access_point_name: "test123",
      first_ip_addr: "192.168.3.2",
      last_ip_addr: "192.168.3.254",
      ip_addr_shift: 2, /* difference between allocated IP addresses is 4 */
      dns_addr: "8.8.8.8", /* Google DNS address */

      /* IPv6 sample config
      pdn_type: "ipv4v6",
      first_ipv6_prefix: "2001:468:3000:1::",
      last_ipv6_prefix: "2001:468:3000:ffff::",
      dns_addr: ["8.8.8.8", "2001:4860:4860::8888"], // Google IPv6 DNS address
      */

      erabs: [
        {
          qci: 9,
          priority_level: 15,
          pre_emption_capability: "shall_not_trigger_pre_emption",
          pre_emption_vulnerability: "not_pre_emptable",
        },
      ],
    },
    {
      /* Some UE requires a specific PDN for data access */
      pdn_type: "ipv4",
      access_point_name: "internet",
      first_ip_addr: "192.168.4.2",
      last_ip_addr: "192.168.4.254",
      ip_addr_shift: 2,
      dns_addr: "8.8.8.8", /* Google DNS address */
      erabs: [
        {
          qci: 9,
          priority_level: 15,
          pre_emption_capability: "shall_not_trigger_pre_emption",
          pre_emption_vulnerability: "not_pre_emptable",
        },
      ],
    },
  ],
\end{alltt}

"pdn-list" \textbf{after}:
\begin{alltt}
pdn_list: [
    {
      pdn_type: "ipv4",
      \textbf{access_point_name: "orbitA",
      first_ip_addr: "192.168.3.20",
      last_ip_addr: "192.168.3.200",}
      ip_addr_shift: 2, /* difference between allocated IP addresses is 4 */
      dns_addr: "8.8.8.8", /* Google DNS address */
      \textbf{mtu_ipv4: 1436,}

      /* IPv6 sample config
      pdn_type: "ipv4v6",
      first_ipv6_prefix: "2001:468:3000:1::",
      last_ipv6_prefix: "2001:468:3000:ffff::",
      dns_addr: ["8.8.8.8", "2001:4860:4860::8888"], // Google IPv6 DNS address
      */

      erabs: [
        {
          qci: 9,
          priority_level: 15,
          pre_emption_capability: "shall_not_trigger_pre_emption",
          pre_emption_vulnerability: "not_pre_emptable",
        },
      ],
    },
    {
      /* Some UE requires a specific PDN for data access */
      pdn_type: "ipv4",
      access_point_name: "internet",
      \textbf{first_ip_addr: "192.168.4.20",
      last_ip_addr: "192.168.4.200",}
      ip_addr_shift: 2,
      dns_addr: "8.8.8.8", /* Google DNS address */
      \textbf{mtu_ipv4: 1436,}
      erabs: [
        {
          qci: 9,
          priority_level: 15,
          pre_emption_capability: "shall_not_trigger_pre_emption",
          pre_emption_vulnerability: "not_pre_emptable",
        },
      ],
    },
  ],
\end{alltt}
\end{itemize}
Next, the UE "database" needs to be configured. Amarisoft allows users to either set up a persistent database, or simply use a dictionary like-structure within \textbf{mme.cfg} to specify allowable UEs. The GENI LTE EPC will use the standard structure, wherein a UE entry contains the following fields, all located in the mme.cfg file:
\begin{verbatim}
    {
    sim_algo: XXX,
    imsi: XXX,
    amf: XXX,
    sqn: XXX,
    k: XXX,
    opc: XXX
    }
\end{verbatim}

The default configuration file will obviously have no UEs configured in this structure. Any time a new SIM card is created, or a new UE needs to be added it must be appended to this list:

Before (default config file):
\begin{verbatim}
/* user data base */
  ue_db: [
    { 
      sim_algo: "xor", /* USIM authentication algorithm: xor, milenage or tuak */
      imsi: "001010123456789", /* Anritsu Test USIM */
//      imsi: "001012345678901", /* Agilent or R&S Test USIM */
      amf: 0x9001, /* Authentication Management Field */
      sqn: "000000000000", /* Sequence Number */
      K: "00112233445566778899aabbccddeeff", /* Anritsu Test USIM */
//      K: "4147494C454E5420544543484E4F0000", /* Agilent Test USIM */
//      K: "000102030405060708090A0B0C0D0E0F", /* R&S Test USIM */
      /* if true, allow several UEs to have the same IMSI (useful
         with test SIM cards). They are distinguished with their
         IMEI. default = false. */
      multi_sim: true,
    },
    /* Add new entries for each IMSI/K */
  ],
\end{verbatim}

An example of an addition to the UE list:
\begin{verbatim}
    ue_db: [
    { 
      sim_algo: "xor", /* USIM authentication algorithm: xor, milenage or tuak */
      imsi: "001010123456789", /* Anritsu Test USIM */
//      imsi: "001012345678901", /* Agilent or R&S Test USIM */
      amf: 0x9001, /* Authentication Management Field */
      sqn: "000000000000", /* Sequence Number */
      K: "00112233445566778899aabbccddeeff", /* Anritsu Test USIM */
//      K: "4147494C454E5420544543484E4F0000", /* Agilent Test USIM */
//      K: "000102030405060708090A0B0C0D0E0F", /* R&S Test USIM */
      /* if true, allow several UEs to have the same IMSI (useful
         with test SIM cards). They are distinguished with their
         IMEI. default = false. */
      multi_sim: true,
    },
    { 
      sim_algo: "milenage", /* OAI uses milenage */
      imsi: "0000000000000", /* OAI card 1 */
      amf: 0x000, /* Authentication Management Field */
      sqn: "000000000000", /* Sequence Number */
      K: "h3iu24kj34bkj234k34", /* OAI K key */
      opc: "2b4kh2b42hb34jh234", /* OAI opc */
    },
\end{verbatim}
\textbf{Important note:} Since UEs need to be added to the \textbf{mme.cfg} file that runs on the EPC at Rutgers, GENI sites that wish to tap into this EPC will need to request a SIM card to be sent out from Rutgers Winlab. Test SIM cards from Anritsu will work without further configuration and multiple clients can use identical SIMs. For a documentation on how to configure "factory-new" SIM cards, please refer to Orbit's wiki page on how to do so: \url{http://www.orbit-lab.org/wiki/Documentation/gWide/bLTESIM}

The last change that needs to be made is uncommenting the "persistent user database" field at the very end of mme.cfg:

Before: \begin{verbatim}
    /* persistent user database */
  //ue_db_filename: "lte_ue.db",
}
\end{verbatim}

After: \begin{verbatim}
    /* persistent user database */
  ue_db_filename: "lte_ue.db",
}
\end{verbatim}
\section{Licensing the EPC}
In order to license the Amarisoft EPC, one must use the provided USB-key. It must be plugged in directly to the GENI LTE EPC. First, mount the USB drive. Then, copy over the key files to the home folder of the root user. For convenience, it is worthwhile to edit \textbf{/etc/fstab} to have this drive auto mount in case it is ever unplugged: 
\begin{verbatim}
    UUID="device_block_id"  /opt/license    ext4    ro  0   0
\end{verbatim}

\textbf{Important Note:} This will work for the current configuration, however, if the Amarisoft system ever gets re-licensed it will simply be a key file, with no USB drive. The same procedure (copying over to root's home folder) will still apply.
\section{GENI-site Base Station Configuration}
The following steps are needed in order to point a GENI base station to the GENI LTE EPC. It is important to note that all GENI sites should use the same network profile to connect to the EPC, unless if they need a local VLAN configured a new profile will need to be configured. This newly configured profile should be almost identical other than the newly updated VLAN tags. Within Netspan:
\begin{itemize}
    \item Make a profile named \textbf{AmarisoftMME1000} if one is not already there
    \item Set the following parameters:
    \begin{verbatim}
        MCC: 001
        MNC: 01
        MME IP: 10.3.0.250
        SCTP Port: 36412
    \end{verbatim}
    \item Once the necessary changes have been made, restart your base station using the \textbf{forced reset node} option
\end{itemize}
For convenience, the following image is included to help show how Netspan should be configured:

\begin{figure}[htp]
\centering
\includegraphics[width=14cm]{netspan_config_profile}
\caption{Netspan Profile Configuration Page}
\label{fig:lion}
\end{figure}

\section{Running the EPC}
Once all of the configuration is complete, the EPC can be started by running the following command. Please note it must be done from the root user, as it relies on the root user's environment variables. 
\begin{verbatim}
    ./ltemme .config/mme.cfg
\end{verbatim}
Upon server reboots, the MME system will automatically start via Orbit's internal \textbf{bscontrol} service module. To insure it is running, simply run the following:
\begin{verbatim}
    ps aux | grep mme
\end{verbatim}
The Amarisfot MME system has several logging levels. By default, it will capture all connect and disconnect messages, as well as any eNodeB heartbeats. If desired, one can turn on verbose logging which will capture much more data, such as any and all GTP packets coming/going, as well as the standard messages. Be cautious when using verbose logging, as it generates log files that are quite large in size, and can easily fill up the rotating log files very quickly. Syslog will be set up to allow users who are not currently logged into the physical EPC to view/parse log files themselves.


Amarisoft places log files into \begin{verbatim}
    /var/log/mme.log
\end{verbatim}
\end{document}