Skip to content. | Skip to navigation

Personal tools


You are here: Home / Wiki / PhantomNet / OEPC-Protected / OpenEPC Tutorial - using the classic PhantomNet portal

OpenEPC Tutorial - using the classic PhantomNet portal

Gain a working knowledge of OpenEPC in PhantomNet by following through this tutorial.

Foreword and Prerequisites

We now have two ways for experimenters to interact with PhantomNet. The Classic PhantomNet interface uses the original Emulab interface and makes use of NS files to specify the experiments. The (new) PhantomNet interface makes use of profiles, developed for the Apt testbed, to specify experiments. Under-the-hood both interfaces provide access to the same resources. Note, however, that over time new features will be developed primarily for the new profile driven interface. 

This version of the tutorial shows how to interact with PhantomNet via the Classic PhantomNet interface. A version of this tutorial using the profile-based interface is available here.

PhantomNet sits atop Emulab, and relies on the latter for a much of its core testbed functionality. We reuse much of the Emulab terminology as well (such as "experiment", "swap-in" and "swap-out"). PhantomNet diverges as it gets into the particulars of mobile components and functionality, which is the primary focus of this document (as it relates to OpenEPC).

For the classic PhantomNet interface we also use the Emulab experiment configuration specification language. Via this interface PhantomNet experiments utilize much of the same specification syntax and semantics as Emulab. If you run into unfamiliar terms in this tutorial, please look through the Emulab tutorial for explanations and definitions.  

You might also want to familiarize yourself with OpenEPC by reading through the OpenEPC documentation.

Basic OpenEPC Setup

This guide will walk you through the detailed steps necessary to create a basic 3GPP LTE/EPC network.  Such a setup consists of user equipment (UE), an EnodeB, Serving Gateway (SGW), Packet Gateway (PGW), Home Subscriber Server (HSS), Mobility Management Entity (MME), and some other supporting services. The goal of this portion of the tutorial is to have the UE connect to the Internet via the PhantomNet-provisioned LTE/EPC network.





Figure 1.LTE/EPC experiment topology


Figure 1 shows the topology of our basic LTE/EPC experiment. There are five EPC nodes whose names are under rectangle boxes and depicted by blue words. EPC nodes are Emulab physical or virtual machines connected to each other using LANs. For example, enodeb node and sgw-mme node are connected by the “net d“ LAN. Each Emulab node can host one or multiple EPC logical instances. For example, the first Emulab node hosts only the UE, while the third node hosts the SGW and MME logical instances (and other mobility elements we will not cover in this tutorial). An EPC logical instance is a process running on a physical or virtual Emulab machine.

Experiment Specification (NS file):

Below is the NS fi le that declares the topology in Figure 1. Essentially, the file creates nodes, connects them as desired, and updates/configures necessary EPC software on the nodes to make them become EPC nodes.  There is a lot going on in this file, and you don't necessarily need to understand it all to get a basic experiment going.  In fact, you probably will want to use it as is initially,  perhaps tuning some of the parameters near the top to suit your needs.
# Basic OpenEPC NS specification file.
source tb_compat.tcl

set ns [new Simulator]

# OS to use on the nodes. This image must be one that has been prepared the way OpenEPC expects! 
set OEPC_OS "PhantomNet/UBUNTU12-64-BINOEPC"

# Were to log the output of the startup command on each node 
set OEPC_LOGFILE "/var/tmp/openepc_start.log"

# Location of OpenEPC-in-Emulab startup script 
set OEPC_SCRIPT "/usr/bin/sudo /opt/OpenEPC/bin/"

# Number of clients to allocate (currently, value can be 1 or 2)
set num_clients 1

# Code to generate OpenEPC topology and set it up follows.

# Some top-level lists - don't change these directly unless you know what you are doing.
set nodelist ""
set clientlist "alice bob"

# List of lans that nodes may be added to below.
set lanlist "mgmt net_a net_b net_d an_lte"

# Initialize lan membership lists
array set lans {}
foreach lan $lanlist {
  set lans($lan) ""

proc addtolan {lan node} {
  global lans
  lappend lans($lan) $node

proc epcnode {node {role ""} {clname ""}} {
  global nodelist

  uplevel "set $node \[\$ns node]"
  lappend nodelist $node
  tb-set-node-os $node $OEPC_OS
  tb-set-node-failure-action $node "nonfatal"
  addtolan mgmt $node
  if {$role != {}} {
    if {$clname != {}} {
      set startcmd "$OEPC_SCRIPT -r $role -h $clname >& $OEPC_LOGFILE"
    } else {
      set startcmd "$OEPC_SCRIPT -r $role >& $OEPC_LOGFILE"
    tb-set-node-startcmd $node $startcmd

# Quick sanity check.
if {$num_clients < 1 || $num_clients > [llength $clientlist]} {
  perror "num_clients must be between 1 and [llength $clientlist] (inclusive)!"
  exit 1

# Create $num_clients client nodes
for {set i 0} {$i < $num_clients} {incr i} {
  set clnode [lindex $clientlist $i]
  epcnode $clnode "epc-client" $clnode
  addtolan an_lte $clnode

# Create the epc-enablers node (Mandatory)
epcnode epc "epc-enablers"
addtolan net_a $epc

# Create the pgw node (Mandatory)
epcnode pgw "pgw"
addtolan net_a $pgw
addtolan net_b $pgw

# Create the sgw-mme-sgsn node (Mandatory)
epcnode sgw "sgw-mme-sgsn"
addtolan net_b $sgw
addtolan net_d $sgw

# Create eNodeB (Mandatory)
epcnode enb "enodeb"
addtolan an_lte $enb
addtolan net_d $enb

# Create all lans that have at least two members
foreach lan $lanlist {
  # Since DNS doesn't officially allow underscores, we have to convert
  # them to dashes in the names of the lans before instantiation.
  set nslan [regsub -all -- "_" $lan "-"]
  if {[llength $lans($lan)] > 1} {
    set $nslan [ns make-lan $lans($lan) * 0ms]

# Go!
$ns run
Some notes on this NS file:
  • The procedure "epcnode" is used to declare an EPC node instead of a normal node.
A node declared with "epcnode" will have EPC software corresponding to the OpenEPC role configured. For example, the stanza "epcnode pgw pgw" fi rst creates a normal Emulab node and then sets it up to be configured as a PGW in an EPC network.
  • The procedure "addtolan" is syntactic sugar for adding a node to a particular EPC LAN.
After creating EPC nodes, the NS script assigns the nodes to the necessary LANs to connect them as in the topology pictured above. For example, the enodeb node and the sgw-mme node are connected via the net_d LAN.
  • Even a basic an LTE/EPC experiment needs at least five nodes: UE, eNodeB, SGW, PGW, and EPC-enabler.
Other access technologies and networks such as WLAN, WiMAX, UMTS, GPRS will be enabled in the future (and may require additional physical nodes).

Instantiating and Validating

Create a new PhantomNet experiment by logging in to the Classic PhantomNet web UI and browsing as follows: Experimentation -> Begin an Experiment.  Fill in the required fields.  In the "Your NS file", specify your own copy of the OpenEPC NS file presented above.  Submit your experiment for swap-in, and monitor its progress (PhantomNet will show you a live activity log).  You will receive email once your experiment is up and running (note that email from PhantomNet may arrive tagged as being from Emulab.Net).
Note: You may see what appear to be errors from the NS parser soon after submitting the experiment for swap-in.  This is just noise from the independent validation parser and can safely be ignored (fixing this up is on our TODO list).

To make sure the NS script does its job correctly, we'll need to check the connectivities among nodes using ping. eNodeB, SGW, PGW, and EPC-enablers should be able to ping each other. Note that the UE so far is not connected to the network and the Internet as it has not attached to the EPC network. After an attaching procedure (described below), the UE will connect to the eNodeB and be able to ping the others and the Internet. Note that because of the network setup between the OpenEPC nodes you cannot directly access the UE (node alice) or the PGW (node pgw) via the PhantomNet/Emulab control network. To reach these to nodes first ssh to the PhantomNet "users" control node ( and then ssh to the alice/pgw nodes.

Only making sure the connectivity among nodes is not enough; EPC software has to be running on nodes to make the whole thing work. To make sure the correct EPC software is running on the corresponding node, you can log into the node and check for any wharf/ser services:


Running the above command on the each Emulab node should return something like what is shown in Table 1.

Emulab node EPC logical instances
alice mm
enodeb enodeb
sgw-mme hnbgw, mme, sgsn, sgw
pgw pgw

aaa, andsf, bf, cdf ,cgf, hss, icscf,

pcrf, pcscf, pcscf.pcc, scscf, squid rx client

Table 1. OpenEPC instances in each Emulab node

OpenEPC instances can be started and stopped by running the appropriate start, stop or kill scripts.

To start an instance run:

sudo /opt/OpenEPC/bin/[element_name]

E.g., to start the PGW on the pgw node run:

sudo /opt/OpenEPC/bin/
To gracefully stop an instance run:
sudo /opt/OpenEPC/bin/[element_name]
E.g., to stop the PGW on the pgw node run:
sudo /opt/OpenEPC/bin/
To (ungracefully) stop an instance run:
sudo /opt/OpenEPC/bin/[element_name]
E.g., to kill the PGW on the pgw node run:
sudo /opt/OpenEPC/bin/
Attaching the UE
Now as all the EPC nodes are set, we'll try to attach the UE to the network and then access a website in the Internet using the UE. Note that currently there is an "emulated Radio Access Network (RAN)" between the UE and the eNodeB that mimics a RAN. Real RAN between UE and eNodeB is in development.  You can invoke an attachment procedure of the UE by either using terminal commands or a GUI.  You'll need an X session up and running on your local machine if you want to use the GUI attachment method below.
To attach the "alice" UE to the EPC, you'll first need to connect to the physical node hosting this UE logical instance. To do this, first SSH to the PhantomNet "users" control node ( and then ssh to your "alice" UE node:
yourhost> ssh -Y
... MOTD ...
you@users> ssh -Y alice.<your_experiment>.<your_project>
See the notes below for the reasons behind this indirect access.  The "-Y" flag is necessary to forward along the connection to your X session.  Another way to ensure X is forwarded along from the host to the UE is to add the following lines to  your ~/.ssh/config file on (just create the file if it isn't there):
ForwardAgent yes
ForwardX11 yes
ForwardX11Trusted yes
StrictHostKeyChecking no
Protocol 2
(Strictly speaking, only the "X11" entries are needed for X session forwarding, but the others are good to have as well.)
To attach the UE to the network using command line:
You can attach to the Mobility Manager (mm) OpenEPC component running on the UE by issuing the following command:
This will attach you to the mm component's console.  After connecting, you can list the available networks with:
So far, only "LTE" is in the list and the return information should show that the UE is currently "layer-2 connected". It will show "layer-3 connected" status when an UE is connected to the Internet. Let's try to attach ("layer-3 connecting") the UE to the LTE/EPC network:
mm.connect_l3 LTE
To disconnect network, you can use below command.
mm.disconnect_l3 LTE
You can see more options by typing “help“.

Attaching the UE to the network using the GUI (alternative to the text-based console):

Once logged into "alice", start up the OpenEPC mobility manager GUI by running "/opt/OpenEPC/mm_gui/".  This will bring up a window that looks like this:


Click on the "LTE" button with the red icon in the left hand column.  You should see status messages go by on the text console, and the red icon should turn green.  The line at the top should now read "mm-state-attached":



  • if you click the LTE button again, it should disconnect the alice client (and the icon should turn red once more). You can either close the mobility manager GUI client, or minimize it.  Closing the GUI will not disconnect the UE from the EPC.
  • Sometimes the GUI does not properly show the MM's state after clicking on the toggle button (e.g., it still shows red (detached)).  There is a refresh button in the lower left-hand corner of the GUI window that you can click to update the display.
Test Internet Access:

From your shell into the "alice" client, try pinging out to a host on the Internet, use wget to fetch something, and use internet browser after downloading browser, etc.  Traceroute will show you that the connection jumps through some internal connections in the EPC network.  When the "alice" client is connected, you should be able to see the associated session from the OpenEPC web interface by navigating as follows:

"E-UTRAN" top tab -> "EnodeB" sub-tab -> "Sessions" left-hand menu item -> Click "Search" button on form (no params) -> click the only listed session's IMSI (should be "001011234567890").

Miscellaneous Notes

  • OpenEPC logical instance (service) consoles

You can have a look at the individual OpenEPC component consoles by going to the respective node hosting the component of interest (e.g., the MME), and typing "/opt/OpenEPC/bin/<component>".

E.g., to connect to the console/CLI of the PGW element on the pgw node run:
To disconnect from a console/CLI session:
Ctl-a d

Use the command shown above on this page to see the list of active EPC services. These consoles are particularly useful for debugging.

OpenEPC console - mme

  • Useful console/CLI commands
In any console session type "help" to see the CLI options. Type "help [command]" to see more information about a particular command.
The CLI of most elements has a "bindings.print" type command which is useful to see the current state in a network element.
E.g., in the pgw console/CLI type:
to see current GTP tunnel information. (After a successful UE connect/attach this command should show details of the GTP tunnel terminating on the PGW. A subsequent disconnect/detach should result in the tunnel information being removed.)
  • OpenEPC setup hooks in PhantomNet

The PhantomNet harness that configures and starts the appropriate OpenEPC services based on node role (see above), is tied into the end of the boot process.  So, rebooting any node should ultimately trigger OpenEPC service startup.  Note that OpenEPC components are quite tolerant of service restarts and temporary outages (reconnecting when possible).

  • Indirect connectivity to mobile clients and the P-GW
You have to "hop" through the "users" PhantomNet infrastructure host to get to some of the OpenEPC nodes (all mobile client nodes and the "pgw").  This is because these nodes do not have a default route out to the Internet.  However, once clients are connected to the OpenEPC instance (via an eNodeB gateway), they should be able to get out via the EPC egress proxy (the "epc" node).  The PGW will remain directly inaccessible, as required for it to function and route traffic between the rest of the EPC Core network and the Internet gateway.
  • OpenEPC configuration
You can view and modify much of the EPC configuration in OpenEPC by pointing a web browser at your "epc" node, which should be named something like: epc.<your_experiment>.<your_project>

(Use username: "admin" and password: "epc").

Each OpenEPC logical instance (service) also has its own XML configuration file, which is located under /opt/OpenEPC/etc.  We hope to have heavily annotated versions of these XML files in the not-too-distant future.

  • Network configuration
Because of the network setup required by the OpenEPC components, the Emulab LAN subnet and interface assignments are replaced by the PhantomNet control software when nodes are configured according to their EPC roles. As such, the network assignments shown on the PhantomNet portal (under the Experiment -> Details tab) are not accurate.