GENILTE/LTEDeploymentRutgers: main.tex

File main.tex, 13.2 KB (added by lnevers@bbn.com, 6 years ago)
Line 
1\documentclass{article}
2\usepackage[utf8]{inputenc}
3\usepackage{hyperref}
4\usepackage{graphicx}
5\usepackage{alltt}
6\renewcommand{\ttdefault}{txtt}
7\title{GENI LTE EPC DOCUMENTATION}
8\author{Raytheon BBN + Rutgers Winlab Orbit}
9\date{July 18, 2017}
10
11\begin{document}
12
13\maketitle
14
15\section{Introduction}
16The 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.
17
18\section{System Requirements}
19\subsection{Hardware}
20The 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.
21\subsection{Software}
22This 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.
23\section{Installation Procedure}
24Before installation:
25\begin{itemize}
26    \item Make sure the system is up-to-date: \begin{verbatim}
27      sudo apt update && sudo apt upgrade 
28    \end{verbatim}
29    \item Acquire the tarball of the licensed Amarisoft software package.
30    \item If a /opt/ directory is not already present, create one
31\end{itemize}
32Once these preliminary steps are complete, the following procedure can be followed to make a clean installation:
33\begin{itemize}
34    \item Unzip the tarball in the /opt/ directory: \begin{verbatim}tar -C /opt -xf amarisfot-2017-06-02.tar.gz \end{verbatim}
35    \item To automatically install all components of the Amarisoft software, simply run the install script:\begin{verbatim}
36    cd /opt/amarisoft-2017-06-02
37    sudo ./install.sh \end{verbatim}
38    \item Install SCTP tools if they are not present already on the system: \begin{verbatim} sudo apt install lkstcp-tools\end{verbatim}
39    \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}
40sudo ./lte_init interface-name
41    \end{verbatim}
42\end{itemize}
43\section{Configuration}
44The 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:
45\begin{itemize}
46    \item Change \textbf{GTP address} to the current outbound address, which is the IP of the EPC
47   
48    Before: \begin{verbatim}
49        gtp_addr: "127.0.1.100",
50    \end{verbatim}
51   
52    After: \begin{verbatim}
53        gtp_addr: "10.3.0.250",
54    \end{verbatim}
55    \item Right below this change, add the following to set the gtp payload mtu:
56    \begin{verbatim}
57        gtp_payload_mtu: 1500,
58    \end{verbatim}
59    \item Next, give the MME a name to be identified by and also a "short" name
60   
61    Before: \begin{verbatim}
62        network_name: "Amarisoft Network",
63        network_short_name: "Amarisoft",
64    \end{verbatim}
65   
66    After: \begin{verbatim}
67        network_name: "GENI LTE Network",
68        network_short_name: "GENI",
69    \end{verbatim}
70    \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.
71   
72    "pdn-list" before:
73    \begin{alltt}
74pdn_list: [
75    {
76      pdn_type: "ipv4",
77      access_point_name: "test123",
78      first_ip_addr: "192.168.3.2",
79      last_ip_addr: "192.168.3.254",
80      ip_addr_shift: 2, /* difference between allocated IP addresses is 4 */
81      dns_addr: "8.8.8.8", /* Google DNS address */
82
83      /* IPv6 sample config
84      pdn_type: "ipv4v6",
85      first_ipv6_prefix: "2001:468:3000:1::",
86      last_ipv6_prefix: "2001:468:3000:ffff::",
87      dns_addr: ["8.8.8.8", "2001:4860:4860::8888"], // Google IPv6 DNS address
88      */
89
90      erabs: [
91        {
92          qci: 9,
93          priority_level: 15,
94          pre_emption_capability: "shall_not_trigger_pre_emption",
95          pre_emption_vulnerability: "not_pre_emptable",
96        },
97      ],
98    },
99    {
100      /* Some UE requires a specific PDN for data access */
101      pdn_type: "ipv4",
102      access_point_name: "internet",
103      first_ip_addr: "192.168.4.2",
104      last_ip_addr: "192.168.4.254",
105      ip_addr_shift: 2,
106      dns_addr: "8.8.8.8", /* Google DNS address */
107      erabs: [
108        {
109          qci: 9,
110          priority_level: 15,
111          pre_emption_capability: "shall_not_trigger_pre_emption",
112          pre_emption_vulnerability: "not_pre_emptable",
113        },
114      ],
115    },
116  ],
117\end{alltt}
118
119"pdn-list" \textbf{after}:
120\begin{alltt}
121pdn_list: [
122    {
123      pdn_type: "ipv4",
124      \textbf{access_point_name: "orbitA",
125      first_ip_addr: "192.168.3.20",
126      last_ip_addr: "192.168.3.200",}
127      ip_addr_shift: 2, /* difference between allocated IP addresses is 4 */
128      dns_addr: "8.8.8.8", /* Google DNS address */
129      \textbf{mtu_ipv4: 1436,}
130
131      /* IPv6 sample config
132      pdn_type: "ipv4v6",
133      first_ipv6_prefix: "2001:468:3000:1::",
134      last_ipv6_prefix: "2001:468:3000:ffff::",
135      dns_addr: ["8.8.8.8", "2001:4860:4860::8888"], // Google IPv6 DNS address
136      */
137
138      erabs: [
139        {
140          qci: 9,
141          priority_level: 15,
142          pre_emption_capability: "shall_not_trigger_pre_emption",
143          pre_emption_vulnerability: "not_pre_emptable",
144        },
145      ],
146    },
147    {
148      /* Some UE requires a specific PDN for data access */
149      pdn_type: "ipv4",
150      access_point_name: "internet",
151      \textbf{first_ip_addr: "192.168.4.20",
152      last_ip_addr: "192.168.4.200",}
153      ip_addr_shift: 2,
154      dns_addr: "8.8.8.8", /* Google DNS address */
155      \textbf{mtu_ipv4: 1436,}
156      erabs: [
157        {
158          qci: 9,
159          priority_level: 15,
160          pre_emption_capability: "shall_not_trigger_pre_emption",
161          pre_emption_vulnerability: "not_pre_emptable",
162        },
163      ],
164    },
165  ],
166\end{alltt}
167\end{itemize}
168Next, 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:
169\begin{verbatim}
170    {
171    sim_algo: XXX,
172    imsi: XXX,
173    amf: XXX,
174    sqn: XXX,
175    k: XXX,
176    opc: XXX
177    }
178\end{verbatim}
179
180The 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:
181
182Before (default config file):
183\begin{verbatim}
184/* user data base */
185  ue_db: [
186    {
187      sim_algo: "xor", /* USIM authentication algorithm: xor, milenage or tuak */
188      imsi: "001010123456789", /* Anritsu Test USIM */
189//      imsi: "001012345678901", /* Agilent or R&S Test USIM */
190      amf: 0x9001, /* Authentication Management Field */
191      sqn: "000000000000", /* Sequence Number */
192      K: "00112233445566778899aabbccddeeff", /* Anritsu Test USIM */
193//      K: "4147494C454E5420544543484E4F0000", /* Agilent Test USIM */
194//      K: "000102030405060708090A0B0C0D0E0F", /* R&S Test USIM */
195      /* if true, allow several UEs to have the same IMSI (useful
196         with test SIM cards). They are distinguished with their
197         IMEI. default = false. */
198      multi_sim: true,
199    },
200    /* Add new entries for each IMSI/K */
201  ],
202\end{verbatim}
203
204An example of an addition to the UE list:
205\begin{verbatim}
206    ue_db: [
207    {
208      sim_algo: "xor", /* USIM authentication algorithm: xor, milenage or tuak */
209      imsi: "001010123456789", /* Anritsu Test USIM */
210//      imsi: "001012345678901", /* Agilent or R&S Test USIM */
211      amf: 0x9001, /* Authentication Management Field */
212      sqn: "000000000000", /* Sequence Number */
213      K: "00112233445566778899aabbccddeeff", /* Anritsu Test USIM */
214//      K: "4147494C454E5420544543484E4F0000", /* Agilent Test USIM */
215//      K: "000102030405060708090A0B0C0D0E0F", /* R&S Test USIM */
216      /* if true, allow several UEs to have the same IMSI (useful
217         with test SIM cards). They are distinguished with their
218         IMEI. default = false. */
219      multi_sim: true,
220    },
221    {
222      sim_algo: "milenage", /* OAI uses milenage */
223      imsi: "0000000000000", /* OAI card 1 */
224      amf: 0x000, /* Authentication Management Field */
225      sqn: "000000000000", /* Sequence Number */
226      K: "h3iu24kj34bkj234k34", /* OAI K key */
227      opc: "2b4kh2b42hb34jh234", /* OAI opc */
228    },
229\end{verbatim}
230\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}
231
232The last change that needs to be made is uncommenting the "persistent user database" field at the very end of mme.cfg:
233
234Before: \begin{verbatim}
235    /* persistent user database */
236  //ue_db_filename: "lte_ue.db",
237}
238\end{verbatim}
239
240After: \begin{verbatim}
241    /* persistent user database */
242  ue_db_filename: "lte_ue.db",
243}
244\end{verbatim}
245\section{Licensing the EPC}
246In 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:
247\begin{verbatim}
248    UUID="device_block_id"  /opt/license    ext4    ro  0   0
249\end{verbatim}
250
251\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.
252\section{GENI-site Base Station Configuration}
253The 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:
254\begin{itemize}
255    \item Make a profile named \textbf{AmarisoftMME1000} if one is not already there
256    \item Set the following parameters:
257    \begin{verbatim}
258        MCC: 001
259        MNC: 01
260        MME IP: 10.3.0.250
261        SCTP Port: 36412
262    \end{verbatim}
263    \item Once the necessary changes have been made, restart your base station using the \textbf{forced reset node} option
264\end{itemize}
265For convenience, the following image is included to help show how Netspan should be configured:
266
267\begin{figure}[htp]
268\centering
269\includegraphics[width=14cm]{netspan_config_profile}
270\caption{Netspan Profile Configuration Page}
271\label{fig:lion}
272\end{figure}
273
274\section{Running the EPC}
275Once 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.
276\begin{verbatim}
277    ./ltemme .config/mme.cfg
278\end{verbatim}
279Upon 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:
280\begin{verbatim}
281    ps aux | grep mme
282\end{verbatim}
283The 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.
284
285
286Amarisoft places log files into \begin{verbatim}
287    /var/log/mme.log
288\end{verbatim}
289\end{document}
290