Skip to content. | Skip to navigation

Personal tools


You are here: Home / Wiki / PhantomNet / OEPC-Protected / UE shadow nodes

UE shadow nodes

How to set up nodes that sit behind your UEs, where you can install software and have root access.

Root Access Denied?

Arbitrary root access is disallowed on nodes containing OpenEPC code.  We do this in order to fulfill our obligation to protect the OpenEPC binaries, mandated by our license agreement with Fraunhofer / Core Network Dynamics. Although a good deal of latitude is afforded with regular user permissions (augmented with select sudo privileges), some experimenters find that this is not enough for their needs.  In particular, installing complex software with many dependencies can be difficult without root access.

An Alternative

One way to work around the lack of root access on OpenEPC-enabled nodes is to add extra nodes to your topology that run unrestricted images (do not contain OpenEPC code). These nodes can be added at strategic points in your topology.  For example, a node added to the "net_a" subnet is nicely positioned to interact with UE traffic as it exits the GTP bearers at the PGW. But what about the UE side?  This document describes how to add "shadow" nodes that communicate through your UEs.  Since the OS environment on the shadow nodes is unrestricted, you can install whatever software you wish, etc.

How it works

The idea is simple enough: Just add a secondary node for each UE node in your topoogy. The trick is proper network configuration.  The UE needs to be able to forward traffic for the shadow node, and the shadow node needs to be setup to forward traffic through the UE.  Because a UE only has a single IP address associated with its active data bearer, we will setup NAT on the UE to channel traffic to and from the attached shadow node.  Thus, traffic from the shadow node will appear to anything upstream of the UE to be coming from the UE itself. On the shadow node, we will manipulate the routing table to send the desired traffic on to the UE instead of through the default Emulab control network gateway.

Setting it up

Add shadow nodes to your topology

The following NS file has been modified to add shadow nodes to each UE:

Inside this NS file you will find a couple of items of interest.  First, there are a few new configuration variables:

Variable Possible values Description
alloc_shadow_nodes 1 or 0 When set to 1, add shadow nodes to your topology.

Set to any OS you find suitable. See "Experimentation > List ImageIDs" from the PhantomNet Web UI for a list.

SHADOW_SUBNET_BASE Integer between 0 and 254. Defaults to 100 The base subnet address to use for links between shadow nodes and UEs.  Each link must use a unique subnet. Do not use a base under 10 as you are likely to clash with existing OpenEPC subnets. Shadow node links will use class C subnets starting from 192.168.SHADOW_SUBNET_BASE and up.


Shadow node link and address mechanics: If you look further down in the NS file and find the loop that requests the UE client nodes, you will see the additional code for adding the shadow nodes and the link between them to their partner UE.  Note that the UE node's address on the shadow node link is set to ".1" in the assigned subnet, and the shadow node is at host address ".2".

Shadow node names: Shadow nodes created via this NS file will be named after their partner UE. The naming template is: <UE_name>-sn.  For example, if the UE's name is "alice", then the shadow node's hostname will be "alice-sn".  You are of course free to change this, or anything else in the NS file to suit your needs.

Enable NAT on the UE

The reference NS file above has been modified to pass along a parameter to the PhantomNet startup script ( that requests NAT to be setup for all traffic forwarded through the UE and out its data bearer interface.  This is the forth parameter to the modified "epcnode" function in this NS file.  The startup script will do the following:

  1. Locate the interface used for the RAN (between emulated UE and eNodeB)
  2. Set up NAT using the iptables "masquerade" extension.

If you need or wish to do the NAT setup by hand, first attach the UE as described in the basic OpenEPC tutorial.  Then execute "ip route" from the command line and note the device referenced in the default route (e.g., eth2).  Next, set up iptables to NAT traffic that egresses through this interface by issuing the following command:

sudo iptables -t nat -A POSTROUTING -o ethX -j MASQUERADE

Substitute "ethX" with the RAN interface you identified via the default route.

Change routes on your shadow node

As per usual for a testbed node, the shadow node's default route will be set to the Emulab/PhantomNet control network gateway (  To make specific destinations flow through the UE and its data bearer, add routes as desired, specifying the UE's address on the shadow node link as the next hop. For example, to have traffic to/from flow through the UE's data bearer, execute:

sudo ip route add via

(Check the subnet used on the link between the shadow node and UE, and substitute as necessary in the above command.)

Note: Your UE must be attached to the EPC before traffic will flow.

To make all traffic aside from that going to/from PhantomNet control servers flow through the UE, you can add a couple of routes for the control network traffic, and then change the default route on the shadow node to point to the UE's address:

sudo ip route add via
sudo ip route add via
sudo ip route change default via

Note: If you perform the last command in the above sequence while directly logged in to the shadow node via SSH, your SSH session will freeze.  To avoid this, log in to the shadow node by hopping through the "" server. First SSH to, then SSH to your shadow node from there.  The routes added above will prevent the shadow node from losing contact with the PhantomNet control servers.


This document has walked you through adding UE shadow nodes to your topology and configurating the networking on the UE and shadow nodes to accommodate. You can install software and manipulate your shadow nodes any way you wish, with full root access.  Shadow node traffic flows through and is NATed by its partner UE node.