Skip to content
This repository has been archived by the owner on Nov 15, 2023. It is now read-only.

Home

Jump to bottom
Steven Galgano edited this page Mar 30, 2018 · 26 revisions

The emane-tutorial is a guided walk through deploying a series of emulation configurations and scenarios using the EMANE emulator. Each demonstration in this tutorial is designed to highlight specific capabilities of the emulator. The tutorial provides a simple test flow using LXC Containers to create a set of test nodes that run emulator instances along with other applications and services typically used in the MANET world.

In order to run the demonstration examples you will need the following applications installed:

Looking for an easy way to get started? Try the Tutorial VM.

The EMANE tutorial has been tested on Fedora 26, Fedora 27, CentOS 7, and Ubuntu 14.04 LTS. See the Install page for installation instructions.

Contents

Demonstrations

Within this tutorial, each demonstration example is contained in its own numeric directory. There are a total of 8 demonstrations. Follow the numeric demonstration links for a detailed guide to each one.

Demo Containers Models Transport Description
0 2 Bypass Virtual Introduction to emulator subsystems and applications
1 10 RF Pipe Virtual Introduction to event generation, the EMANE Shell and general physical layer concepts
2 7 RF Pipe Virtual Introduction to the RF Pipe radio model
3 10 IEEE 802.11abg Virtual Introduction to the IEEE 802.11abg radio model
5 4 IEEE 802.11abg, RF Pipe Virtual Understanding emulator spectrum monitoring and noise processing
6 4 RF Pipe Virtual How to use physical layer antenna profiles
7 10 Comm Effect Raw Introduction to the Comm Effect utility model and black-box testing
8 10 TDMA Virtual Introduction to the TDMA Event Scheduler radio model

Tutorial Test Flow

Makefiles are used to generate portions of the configuration for each demonstration from a series of template files. Using information in these files as well as variables defined in the Makefiles themselves, a demo-start and demo-stop script is created that simply calls the scripts/democtl-host script with the appropriate demonstration parameters.

The democtl-host script will launch a number of LXC containers using lxc-execute to invoke the scripts/demo-init script for each container. Each demo-init script instance is aware of its associated NODEID and looks for specific files in the demonstration directory in order to determine which applications and services to run.

File Action If Present
platform<NODEID>.xml Run emane and use as the configuration input file.
transportdaemon<NODEID>.xml Run emanetransportd and use as the configuration input file.
eventdaemon<NODEID>.xml Run emaneventd and use as the configuration input file.
iperf Run iperf and use as the configuration input file.
iperf<NODEID> Run iperf and use as the configuration input file. Ignore iperf input file, if present.
mgen Run mgen and use as the configuration input file.
mgen<NODEID> Run mgen and use as the configuration input file. Ignore mgen input file, if present.
routing.conf Run olsrd and use as the configuration input file.
routing<NODEID>.conf Run olsrd and use as the configuration input file. Ignore routing.conf file, if present.
node-prestart Run this script prior to starting any other applications.
node-prestart<NODEID> Run this script prior to starting any other applications. Ignore node-prestart, if present.
node-preapplication Run this script after starting all EMANE components but before starting any other applications.
node-preapplication<NODEID> Run this script after starting all EMANE components but before starting any other applications. Ignore node-preapplication, if present.
node-poststart Run this script after starting everything.
node-poststart<NODEID> Run this script after starting everything. Ignore node-poststart, if present.
otestpointd<NODEID>.xml Run otestpointd and use as the configuration input file.
otestpoint-recorder<NODEID>.xml Run otestpoint-recorder and use as the configuration input file.

Each LXC container test node will write all log, pid and uuid files to persist/<NODEID>/var/{log,run}.

Similarly the demctl-host script uses the presence of some files to take additional actions.

File Action If Present
platform.xml Run emane and use as the configuration input file.
transportdaemon.xml Run emanetransportd and use as the configuration input file.
eventservice.xml Run emaneeventservice and use as the configuration input file.
host-poststart Run this script after starting everything.
host-prestop Run this script before stopping anything.
otestpoint-broker.xml Run otestpoint-broker and use as the configuration input file.

All log, pid and uuid files generated by these applications are written to persist/host/var/{log,run}.

Running a Demonstration

To run a demonstration run the demo-start script from the appropriate demonstration directory.

[me@host emane-tutorial]$ cd 2
[me@host 2]$ sudo ./demo-start

To stop a demonstration run the demo-stop script from the appropriate demonstration directory.

[me@host 2]$ sudo ./demo-stop

LXC Test Node Topology

Each LXC container instance has two interfaces: eth1 and eth2. The eth1 interface is used as the back-channel control interface as well as the Over-The-Air and Event Channel interface.

Test Node Back Channel Address Radio Interface Address
1 10.99.0.1 10.100.0.1
2 10.99.0.2 10.100.0.2
3 10.99.0.3 10.100.0.3
4 10.99.0.4 10.100.0.4
5 10.99.0.5 10.100.0.5
6 10.99.0.6 10.100.0.6
7 10.99.0.7 10.100.0.7
8 10.99.0.8 10.100.0.8
9 10.99.0.9 10.100.0.9
10 10.99.0.10 10.100.0.10

All demonstrations, with the exception of demonstration 7, will create a virtual interface (vif) within the containers named emane0, for use as the Radio Interface. Demonstration 7 will configure eth1 as the Radio Interface.

From your host machine you can ssh into a container using the 10.99.0.0/24 network (node-<NODEID> host names). From within each container you can route traffic through the emulation using the 10.100.0.0/24 network (radio- host names).

When the demonstration starts the democtl-host script will create a bridge named emanenode0. All container vifs that correspond to the container eth1 interfaces will be added to this bridge.

[me@host 2]$ ifconfig emanenode0
emanenode0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
        inet 10.99.0.100  netmask 255.255.255.0  broadcast 0.0.0.0
        inet6 fe80::fc7b:68ff:fe40:1f3a  prefixlen 64  scopeid 0x20<link>
        ether fe:07:f5:6c:f1:f9  txqueuelen 0  (Ethernet)
        RX packets 135828  bytes 46012434 (43.8 MiB)
        RX errors 0  dropped 0  overruns 0  frame 0
        TX packets 96515  bytes 9342380 (8.9 MiB)
        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

[me@host 2]$ brctl show emanenode0
bridge name   bridge id         STP enabled   interfaces
emanenode0    8000.fe07f56cf1f9 no            veth1.1
                                              veth10.1
                                              veth2.1
                                              veth3.1
                                              veth4.1
                                              veth5.1
                                              veth6.1
                                              veth7.1
                                              veth8.1
                                              veth9.1

When the demonstration is stopped using ./demo-stop, all the containers are destroyed along with their associated vifs and the emanenode0 bridge.

Common Misconceptions

The following are common misconceptions new EMANE users often have.

  1. Do we need to use the emane-tutorial test flow?
    No. The test flow used in this tutorial serves as a simple mechanism to allow individuals to get introduced to EMANE. We use a variety of testbed control systems, some open source and some proprietary, when deploying EMANE for large scale distributed emulations. In addition to being overkill for this project, they tend to add a level of complexity that quickly distracts from this project's goal: Demonstrate how EMANE works.
  2. EMANE requires LXC Containers.
    No. In fact EMANE does not require any form of virtualization. See the EMANE FAQ for more information on this topic.
  3. I should be able to run any number of emulator instances on a given piece of hardware, whether it be natively, using LXC containers or using virtualization.
    No. This simple tutorial test flow does not attempt to tune the host system to better support distributed emulation or measure host system capabilities. You will need to determine the capabilities of your testbed hardware in terms of CPU, memory, network bandwidth and latency and then analyze your test scenario to determine if enough resources are available to support what you are trying to do.

Copyright (c) 2014-2018 - Adjacent Link LLC, Bridgewater, New Jersey
Except where otherwise noted, content on this site is licensed under a Creative Commons Attribution 4.0 International License.

Clone this wiki locally