Tun Setup on UEsim

The purpose of this tutorial is to show how to setup tun interface for each UE created by UEsim.  In case of MT data traffic (e.g, the data is generated by Callbox(i.e, eNB or gNB) and is sent to UE), you would not need any specific tun interface on UEsim. But if you want to do MO data traffic, you need to setup tun interface for each PDN of each UE simulated by UEsim.

Since there can be multiple UEs simulated in a single UEsim box, these tun interfaces should be created independently for each UE which operate independantly from each other. In other words, those tun interface for each UE should run in a separate container. These container is called a namespace. So the underlying mechanism for tun interface setup is to create a separate network namespace for each UE.

Table of Contents

• Tun Setup on UEsim
• Introduction
• Summary of the Tutorial
• Test Setup
• Key Configuration Parameters
• Test 1 : Basic Tun Setup
• Configuration
• Perform the test

Introduction

In modern mobile network testing and simulation environments, accurately emulating user equipment (UE) behavior is critical for validating network performance, service continuity, and protocol compliance. UEsim is a sophisticated simulation tool designed to mimic the behavior of real UEs by generating and handling both Mobile Originated (MO) and Mobile Terminated (MT) data traffic within a controlled lab setting. One essential aspect of realistic simulation is the ability to route IP traffic for each simulated UE through a dedicated virtual network interface, commonly implemented using Linux TUN (network TUNnel) interfaces. A TUN interface acts as a virtual network device operating at layer 3 (IP layer), allowing the simulated UE instance to send and receive IP packets as if it were a physical device. To ensure complete isolation and accurate emulation of real-world scenarios—where each UE operates independently on the network—these TUN interfaces are instantiated inside separate Linux network namespaces. Each namespace provides a distinct, isolated networking stack for every UE, preventing cross-interference and accurately simulating the behavior of multiple UEs on a single UEsim platform. This tutorial provides a comprehensive guide to setting up individual TUN interfaces and namespaces for each UE simulated by UEsim, outlining the underlying architecture, the significance of this approach for MO traffic testing, and the practical steps required to achieve a scalable, containerized simulation environment. By leveraging these virtualization techniques, testers and developers can create robust, repeatable, and isolated testbeds for end-to-end data path validation and advanced troubleshooting within LTE and 5G network environments.

• Context and Background
  • UEsim provides a flexible environment for simulating multiple UEs, supporting both MO (Mobile Originated) and MT (Mobile Terminated) data traffic scenarios.
  • MT data traffic flows from the network to the UE and typically does not require a dedicated TUN interface on the simulator.
  • MO data traffic, where the simulated UE initiates data transmission, necessitates a TUN interface for each PDN (Packet Data Network) session to accurately route and track individual IP flows.
  • Linux network namespaces are used to isolate the network stack of each UE, ensuring that each simulated device operates independently within the same physical or virtual UEsim instance.
• Relevance and Importance
  • Setting up TUN interfaces within isolated namespaces is essential for emulating realistic multi-UE environments, especially for MO data testing, protocol validation, and functional regression.
  • This approach ensures that each UE simulation instance mirrors the behavior of an actual device, providing accurate insights into network performance, scalability, and troubleshooting.
  • Network isolation via namespaces prevents configuration conflicts and allows for parallel testing of multiple, independent UEs.
• Learning Outcomes
  • Understand the architecture and purpose of TUN interfaces and network namespaces in the context of UE simulation.
  • Gain practical experience in configuring and managing multiple TUN interfaces for simulated UEs within a single UEsim environment.
  • Learn best practices for creating isolated, scalable, and reproducible simulation testbeds that reflect real-world deployment scenarios.
• Prerequisite Knowledge
  • Familiarity with basic Linux networking concepts and virtual network interfaces (e.g., TUN/TAP).
  • Understanding of mobile network architecture, especially concepts related to UEs, PDN connectivity, and data traffic flows.
  • Basic experience with containerization or Linux namespaces is helpful but not mandatory.
  • Some command-line proficiency for executing configuration steps and validating the setup.

Summary of the Tutorial

This tutorial describes the procedure for configuring and verifying the basic TUN (network tunnel) interface setup on UEsim instances and conducting fundamental connectivity tests such as ping and curl. The summary below outlines the key setup steps, configuration parameters, and test procedures.

• Test 1: Basic Tun Setup
  • Configuration Steps:
    • Enable TUN interface for each UE by setting the tun_setup_script parameter to reference the appropriate shell script (commonly ue-ifup) in the UEsim configuration.
    • The ue-ifup script is typically included in the default installation package. In many sample configurations, this parameter is present but commented out; simply uncomment it to activate.
    • Additional relevant parameters include tun_setup_param and tun_ifname, which may be referenced as needed for further customization.
  • Test Procedure:
    • Ensure that the UE is in a connected state with the eNB or gNB before beginning tests.
    • Note that TUN interfaces are not visible at the global IP configuration level (e.g., using ifconfig alone will not show per-UE TUN interfaces).
    • To interact with UE-specific TUN interfaces:
      • Use the ip netns command to work with network namespaces.
      • Check existing UE namespaces by executing ip netns list. If UEs with TUN setup are present, their namespaces will be listed; otherwise, the command returns nothing.
      • To inspect the network interfaces within a given UE namespace, use ip netns exec <UE id> ifconfig.
    • Basic Data Connectivity Tests:
      • To generate data traffic, execute ip netns exec <UE id> ping <destination ip> to test IP connectivity from the UE namespace.
      • For HTTP access, run ip netns exec <UE id> curl <url> to download content from HTTP servers using the UE's network namespace.

The methodology focuses on the use of Linux network namespaces to manage and test individual UE network interfaces, ensuring isolation and accurate simulation of per-UE connectivity. The tutorial emphasizes practical command-line operations for both setup verification and basic traffic testing, following a logical sequence from configuration through to connectivity validation.

Test Setup

Test setup for this tutorial is as shown below.

Key Configuration Parameters

Followings are important configuration parameters for this tutorial. You may click on the items for the descriptions from Amarisoft documents.

• UEsim
• tun_setup_script
• tun_setup_param
• tun_ifname

Test 1 : Basic Tun Setup

In this test, we will look into how to enable tun setup on UEsim and perform very basic test (e.g, ping, curl)

Configuration

In terms of configuration, it is super simple to enable tun setup for each UE. You just configure the parameter tun_setup_script to the specific shell script (ue-ifup) which is provided with default installation package. (NOTE : most of sample configurations provided by the installation package would have this configured but commented out. Just uncomment the configuration)

If you are interested in further details, you can find the script (ue-ifup) in /root/ue/config directory and look into the contents of the file in any text editor.

Perform the test

First make it sure that UE is in connected mode with eNB or gNB.

This is optional but good to check to learn that UEsim does not setup tun at global ip setup. If you just do ifconfig, you wouldn't see any difference and wouldn't see any specific ip interface for a specific UE.

The tun interface for UEs is created as individual namespaces. So you need to use special command to check or manipulate the namespace. The command for this purpose is 'ip netns'.

Before you do anything especially you are not familiar with what can be done or how it can be done with ip netns, it is always handy to ask for help (ip netns help)

The first meaningful checkup is to see if there is any namespaces created for any UE in communication state. You can check it up by running the command 'ip netns list'. If there is any UE with tun setup, you will see the list as shown in this example. If there is no UEs with the namespace, the command will not return anything.

If you have any items returned by 'ip netns list', you can find the details about the interfaces associated with the UE by running the command 'ip netns exec <UE id> ifconfig'.  

Now you can try with some data traffic like ping by running the command 'ip netns exec <UE id> ping <destination ip>'.

Or you can get access even to http server and download the contents by running 'ip netns exec ue1 curl <url>'.