cool Simu5G logo

5G New Radio User Plane Simulation Model for INET & OMNeT++

Download this project as a .zip file Download this project as a tar.gz file

Running Simu5G as a network emulator

Running Simu5G as a network emulator means that the simulation must run in real time and must be able to communicate with the real world, i.e. capturing/injecting packets from/to real networks. This is especially useful for integrating Simu5G with external real-world applications and frameworks. For example, it allows one to make Simu5G interoperable with the Intel OpenNESS framework.

OpenNESS is an open source framework that allows to run application on a real Mobile Edge Computing environment. More information on the OpenNESS website.

Check out our PIMRC 2020 paper on this topic:

  • G. Nardini, G. Stea, A. Virdis, D. Sabella, P. Thakkar, "Using Simu5G as a Realtime Network Emulator to Test MEC Apps in an End-To-End 5G Testbed", PiMRC 2020, London, UK, 1-3 September 2020

An emulation demo

With reference to the video below, the "sender" PC on the left sends 2.5kB packets to the "receiver" laptop on the right every 100ms, and the PC in the middle runs Simu5G as an emulator, transporting packets between the two endpoints. On receipt of a packet, the receiver sends back an ACK. TCP is used as a transport protocol. The scenario emulated in Simu5G is displayed on the middle screen, and it contains one UE (the red dot) that moves away from its serving gNB (the triangle in the central hexagon) and back again. Neighboring gNBs interfere on the downlink spectrum. The deployment bandwdith is kept artificially low, to saturate the radio frame. Within Simu5G, the sender is connected to a remote server (not shown in the picture) and the receiver is connected to the moving UE. The sender screen displays a moving-window average of the round-trip time (RTT) of the communication, measured at the application layer. The RTT climbs up as the UE moves away from the gNB, because its CQI goes down, hence more radio resources are used for the same transmission, and then it climbs down again as the UE moves back towards the gNB. Local delay spikes can be observed, corresponding to H-ARQ retransmissions.



Running an emulation example with Simu5G

Emulation support will be included in the next stable release of Simu5G. In the meantime, you can run a network emulation with Simu5G by downloading the code directly from the GitHub repository. Please note that such version requires OMNeT++ 6.0.pre10 and INET 4.3.2. As per INET instructions, emulation is only available on Linux OS.

The Simu5G repository comes with two (single-machine) emulation examples, which you can use as a basis to develop your own emulation testbed:

  • The "emulation/extserver" folder includes one emulated network composed of two UEs connected to one gNB, one UPF, one router and one external (real) server. The external server sends 10MB to ue1 using TCP (in the downlink), whereas ue2 sends 10MB to the external server using TCP (in the uplink);
  • The "emulation/extserver" folder includes one emulated network composed of one UE connected to one gNB, one UPF, one NAT router, one router, one external (real) server and one external (real) client. The external client application (i.e. associated to the UE in the emulation) sends 10MB using TCP to the external server application, traversing the emulated 5G network.

Detailed instructions can be found in the README files included in the above folders.

How to setup an emulation with OpenNESS

Install and configure OpenNESS

Please refer to the official OpenNESS documentation.

We refer to a simple video streaming Edge App (implementing one server instance of the well-known VLC software), although it can be replaced with any other Edge App.
Two scenarios can be deployed:
  • Client application, e.g. the app on the UE, running on the same host where Simu5G runs (if the hardware allows it).
  • Client application, e.g. the app on the UE, running on a different host from where Simu5G runs.

NOTE: Both the guides refer to the configuration files present in the emulation/extclientserver folder.

Client application on the same host of Simu5G

In the following, we refer to the architecture depicted in the figure:

The main components of the above architecture are:

  • Host A, which acts as a client and requests a service from the OpenNESS server and which also emulates the 5G network by running an instance of Simu5G in real-time mode;
  • Host B, which runs an instance of OpenNESS and acts as the video-streaming application server.

Host B runs a containeraized Edge App reachable at 10.16.0.104:8080 and the hosts interfaces and IP addresses are configured as shown in the figure.

Regarding the emulated network scenario, we refer to the "EmulatedNetwork" example, shown in the figure below.

The router and the UE are endowed with an ExtLowerEthernetInterface module, which is capable to receive real packets received by a network interface card attached to it. The latter is virtual and is created as a veth device. This way, data packets coming to the veth attached to Simu5G are injected into the "ue" element of the running instance of it. From there, data are forwarded through the emulated NR network towards the router. When data packets reach the router, they are sent out to Edge App via a veth attached to it. Vice versa, packets coming from the Edge App are injected into the "router" element of the running instance of Simu5G and forwarded to the "ue", which sends them out to the Client application.
The natRouter is used in order to run an emulation in which both the endpoints of a connection are real applications, so the client application needs to use the IP address of the NAT router within the simulation as destination address. Such NAT router element will perform Network Address Translation (NAT), according to the rules specified with the corresponding parameter in the INI file.

Setting the environment

In order to setup the above scenario, the following steps are required to configure the OS on Host A (the one running Simu5G).

NOTE: The following instructions refer to a host equipped with Linux Ubuntu 18.04 OS.

Configure the network

We need to configure the Host A's OS so that it can reroute packets from the veth interface connected to Simu5G to the Host B

  1. Enable IP forwarding on Host A, by running "sudo gedit /etc/sysctl.conf" from the terminal. Look for the ip_forward parameter and edit it as follows:
    net.ipv4.ip_forward=1
  2. It could be possible that Host B machine cannot be accessed by the user, so the routing table cannot be modified in order to add the route for the natRouter (in Simu5G). For this reason, Host A performs NAT by changing the natRouter source address with the Host A interface address connected to Host B.
    sudo iptables -t nat -A POSTROUTING -d 10.16.0.104 -o eth0 -j MASQUERADE
    sudo iptables-save
    sudo iptables -L 
  3. Add IP route for packets destined to the container running the Edge App on Host B:
    sudo route add -net 10.16.0.0/24 via 192.168.1.1 dev eth1

NOTE: routes to inject packet into Simu5G, i.e the veth interfaces management, are automatically added by the run_wSocket.sh script present in the emulation/clientserver folder.

Configure the simulation

The emulation/extclientserver folder includes an exemplary omnetpp.ini file. You can use it as a starting point for your own configuration.

  1. In the omnetpp.ini file, set the UE's 'extHostAddress' parameter to the IP address of the veth2 interface
    *.ue.extHostAddress = "192.168.3.2"
  2. Configure the routing tables of all the network devices in the simulated network. To do so, edit the .mrt files included in the folder 'routing'. Edit them so as to enable a path from the router to the UE. In the omnetpp.ini file, set the 'routingTable.routingFiles' parameters to the path of the .mrt files.
  3. In the omnetpp.ini file, set the 'device' parameters for both the router and the UE. It is the name of the virtual interfaces which you want to capture the packets
    *.ue.eth[0].device = "veth2"
    *.router.eth[0].device = "veth0"
  4. Configure NAT rules:
    • The destination address known by the client application is 10.0.2.1, while the real Edge App address is 10.16.0.104.
    • The destination address known by the Edge App is 10.0.3.2, while the real client application address is 192.168.3.2 (i.e. the address of the veth2 interface).
    *.router.ipv4.natTable.config = xml("
         <config> 
             <entry type='prerouting' 
                 packetDataFilter='*Ipv4Header and destAddress=~10.0.2.1' 
                 srcAddress='10.0.3.2' destAddress='10.16.0.104'> 
             <entry type='prerouting' 
                 packetDataFilter='*Ipv4Header and destAddress=~10.0.3.2' 
                 srcAddress='10.0.2.1' destAddress='192.168.3.2'> 
         </config>
         ") 
Run the scenario
NOTE: the INET framework must be compiled with the Network Emulation Support feature enabled! To enable it (if not): open the OMNeT++ IDE > select the inet projet > Projet tab > select Project Features > Network Emulation Support
  1. In your terminal, navigate to the "simulations/emulation" folder
  2. Run the simulation with root privileges, by typing:
    sudo ./run_wSocket.sh
    This is needed for running the simulation in real time mode. As already mentioned, such script also contains the creation and the management of the veth interfaces.
  3. Open VLC client > Ctrl-N > enter the network URL as: http://10.0.2.1:8080
  4. Enjoy the movie coming from a 5G mobile network!

Client application on a different host from where Simu5G runs

In the following, we refer to the architecture depicted in the figure:

The main components of the above architecture are:

  • Host A, which acts as a client and requests a service from the OpenNESS server
  • Host B, which emulates the 5G network by running an instance of Simu5G in real-time mode
  • Host C, which runs an instance of OpenNESS and acts as the video-streaming application server

Host C runs a containeraized Edge App reachable at 10.16.0.104:8080 and the hosts interfaces and IP addresses are configured as shown in the figure.

Regarding the emulated network scenario, we refer to the "EmulatedNetwork" example, shown in the figure below.

The router and the UE are endowed with an ExtLowerInterface module, which is capable to receive real packets received by a network interface card attached to it. The latter is virtual and is created as a veth device. This way, data packets coming to the veth attached to Simu5G are injected into the "ue" element of the running instance of. From there, data are forwarded through the emulated NR network towards the router. When data packets reach the router, they are sent out to Edge App via a veth attached to it. Vice versa, packets coming from the Edge App are injected into the "router" element of the running instance of Simu5G and forwarded to the "ue", which sends them out to the Client application.
The natRouter is used in order to run an emulation in which both the endpoints of a connection are real applications, so the client application needs to use the IP address of the NAT router within the simulation as destination address. Such NAT router element will perform Network Address Translation (NAT), according to the rules specified with the corresponding parameter in the INI file.

Setting the environment

In order to setup the above scenario, the following steps are required to configure the OS on Host B (the one running Simu5G).

NOTE: The following instructions refer to a host equipped with Linux Ubuntu 18.04 OS.

Configure the network

We need to configure the Host B OS so that it can reroute packets from the veth interfaces connected to Simu5G to Host A and Host C.

  1. Enable IP forwarding on Host B, by running "sudo gedit /etc/sysctl.conf" from the terminal. Look for the ip_forward parameter and edit it as follows:
    net.ipv4.ip_forward=1
  2. It could be possible that Host C machine cannot be accessed by the user, so the routing table cannot be modified in order to add the route for the natRouter (in Simu5G). For this reason, Host B performs NAT by changing the natRouter source address with the Host B interface address connected to Host C.
    sudo iptables -t nat -A POSTROUTING -d 10.16.0.104 -o eth1 -j MASQUERADE
    sudo iptables-save
    sudo iptables -L
              
  3. Add IP route for packets destined to the container running the Edge App on Host C:
    sudo route add -net 10.16.0.0/24 via 192.168.1.1 dev eth1

On Host A

  1. Add IP route for packets destined to the natRouter running in Simu5G:
    sudo route add -net 10.0.2.0/24 via 192.168.1.3 dev eth0

NOTE: routes to inject packet into Simu5G, i.e the veth interfaces management, are automatically added by the run_wSocket.sh script present in the emulation/clientserver folder.

Configure the simulation

The emulation/extclientserver folder includes an exemplary omnetpp.ini file. You can use it as a starting point for your own configuration.

  1. In the omnetpp.ini file, set the UE's 'extHostAddress' parameter to the IP address of the Hosta A eth0 interface
    *.ue.extHostAddress = "192.168.1.10"
  2. Configure the routing tables of all the network devices in the simulated network. To do so, edit the .mrt files included in the folder 'routing'. Edit them so as to enable a path from the router to the UE. In the omnetpp.ini file, set the 'routingTable.routingFiles' parameters to the path of the .mrt files.
  3. In the omnetpp.ini file, set the 'device' parameters for both the router and the UE. It is the name of the veth interfaces which you want to capture the packets
    *.ue.eth[0].device = "veth2"
    *.router.eth[0].device = "veth0"
  4. Configure NAT rules:
    • The destination address known by the client application is 10.0.2.1, while the real Edge App address is 10.16.0.104.
    • The destination address known by the Edge App is 10.0.3.2, while the real client application address is 192.168.1.10.
     *.router.ipv4.natTable.config = xml("
            <config> 
               <entry type='prerouting' 
                   packetDataFilter='*Ipv4Header and destAddress=~10.0.2.1' 
                   srcAddress='10.0.3.2' destAddress='10.16.0.104'> 
               <entry type='prerouting' 
                   packetDataFilter='*Ipv4Header and destAddress=~10.0.3.2' 
                   srcAddress='10.0.2.1' destAddress='192.168.1.10'> 
            </config>
        ") 
Run the scenario
NOTE: the INET framework must be compiled with the Network Emulation Support feature enabled! To enable it (if not): open the OMNeT++ IDE > select the inet projet > Projet tab > select Project Features > Network Emulation Support > recompile the inet project
  1. In your terminal, navigate to the "simulations/emulation" folder
  2. Run the simulation with root privileges, by typing:
    sudo ./run_wSocket.sh
    This is needed for running the simulation in real time mode. As already mentioned, such script also contains the creation and the management of the veth interfaces.
  3. Open VLC client on Host A > Ctrl-N > enter the network URL as: http://10.0.2.1:8080
  4. Enjoy the movie coming from a 5G mobile network!

Back to Guides