Network Simulator ns-3

As the successor of the well-known Network Simulator 2, ns-3 is a discrete-event communication simulator for Internet systems, wireless networks and more. In connection with Eclipse MOSAIC, especially the IEEE 802.11(p) capabilities are employed for Ad-hoc communication.

Installation

ns-3 is primarily developed on and for GNU/Linux platforms.

On other platforms like Windows you should consider

• the Windows Subsystem for Linux
• the installation in Docker environment
• the installation of Linux in a virtual machine environment, such as VMware or VirtualBox.

For more information on how to set up ns-3 with Eclipse MOSAIC, please just refer to the following section. We prepared an installation script, which manages most of the required work.

Prerequisites

For GNU/Linux platforms, the minimal requirements to run basic simulations are a gcc or clang compiler and a Python interpreter. At least you need the following packages to be installed:

Minimum requirement:

gcc
g++
cmake
python3
python3-dev

For a complete list of required packages for different distributions, please refer to the ns-3 installation guide: https://www.nsnam.org/wiki/Installation

Please make also sure the following libraries are installed before running the installation script:

• libxml2
• libsqlite3
• libprotobuf 3.3.0

Run the installation script

To ease the installation of ns-3 for Eclipse MOSAIC, the installation process has been delegated to an installation script, called ns3_installer.sh that can be found in the associated ns-3 federate folder.

└─ mosaic/bin/fed/
   └─ ns3
      ├─ Dockerfile.sh ................... Dockerfile for ns-3 federate
      └─ ns3_installer.sh ................ Installation script for ns-3

The ns-3 installation script accomplishes the following tasks:

1. Download ns-3 tarball from the official sources
2. Download the ns-3 federate for Eclipse MOSAIC.
3. Apply a patch to ns-3 in order to make it work with Eclipse MOSAIC.
4. Add the ns-3 federate to the waf build system.
5. Configure and build the patched ns-3 with the ns-3 federate.

In order to start the simulation, the following steps need to be performed:

1. Set up the ns3_federate_config.xml-file in the scenario folder (see section Configuration). An example ns3_federate_config.xml - file is shipped with the Tiergarten scenario.
2. At last ns-3 has to be activated in the mosaic_config.xml and the simulation can be started.

Installation in Docker environment

This guide gives instructions to execute the ns-3 federate inside a docker container. If you already installed ns-3 on your machine following the steps before, you can skip this section.

Docker is a new approach to execute software. More precisely, it “wraps software in a complete filesystem that contains everything it needs to run: code, runtime, system tools, and system libraries”. As a result, the software is executed within a container and its execution does not rely on the environment the container is running in.

In context of Eclipse MOSAIC, this approach allows to execute ns-3 within a docker container. The user does not need to manually install ns-3 and can even run ns-3 on Windows hosts.

1. Install Docker ≥ 1.13 on your machine.
2. To get everything to work, please make sure to execute the following steps depending on your operating system:
   • Windows - In the settings, share the drive where Eclipse MOSAIC is installed on. You may need to restart docker in the reset tab.
   • Linux - Make sure your user account belongs to the unix-group docker. You may need to restart your machine.
3. Switch to the location of the Dockerfile in <mosaic>/bin/fed/ns3
4. Execute the following command on command line:
   docker build -t ns3-federate . This could take a while to finish.
5. Enter the name of the docker image etc/runtime.json in the ns3-section into the property dockerImage:

"federates": [
   ...
   {
      "id": "ns3",
      "dockerImage": "ns3-federate",
      ...
   },
   ...
]

You can test the installation of your docker image with the Tiergarten scenario, by activating ns3 in the scenario_config.json.

Configuration

The whole ns-3 specific configuration is done via the files ns3_config.json and ns3_federate_config.xml in the scenario folder.

└─ <scenario_name>
   └─ ns3
      ├─ ns3_config.json ................. Ambassador configuration file.
      └─ ns3_federate_config.xml ......... Federate configuration file.

The ns3_config.json mainly allows the configuration of a filter for different message routing options employed in the ambassador. The current integration of ns-3 does not support all combinations (e.g. no TCP is possible for ad-hoc communication). Accordingly, changes in this config would require adaptions in the ns-3 integration as well and are therefore only recommended developers not for users.

The ns3_federate_config.xml allows the configuration of all modules in the IEEE 802.11(p) communication stack of ns-3. The ns-3 propagation module defines two generic interfaces, namely PropagationLossModel and PropagationDelayModel, for the modelling of propagation loss respectively propagation delay.

In the default ns3_federate_config.xml, the Wi-Fi device uses the ns-3 standard propagation delay model ns3::ConstantSpeedPropagationDelayModel and the ns-3 standard propagation loss model ns3::FriisPropagationLossModel. Radio propagation models in ns-3 can easily be exchanged with the ns-3 class registration system (see the ns-3 documentation for details). The Wi-Fi configuration includes additional parameters, like sending power and antenna gain.