-
Notifications
You must be signed in to change notification settings - Fork 15
Home
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:
- gpsd, gpsd-clients
- olsrd
- iperf
- mgen
- pynodestatviz
- [Demonstration Examples](#Demonstration Examples)
- [Tutorial Test Flow](#Tutorial Test Flow)
- [Running a Demonstration](#Running a Demonstration)
- [LXC Test Node Topology](#LXC Test Node Topology)
- [Common Misconceptions](#Common Misconceptions)
Within this tutorial, each demonstration example is contained in its own numeric directory. There are a total of 9 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 the RF Pipe Radio Model and Emulator Physical Layer |
2 | 10 | RF Pipe | Raw | How to setup black-box emulation |
3 | 7 | RF Pipe | Virtual | How to use the RF Pipe Radio Model as a surrogate for other radio models |
4 | 10 | IEEE 802.11abg | Virtual | Introduction to the IEEE 802.11abg Radio Model |
5 | 4 | IEEE 802.11abg | Virtual | How to use flow control between the emulator and application domains |
6 | 4 | IEEE 802.11abg, RF Pipe | Virtual | Understanding emulator spectrum monitoring and noise processing |
7 | 4 | RF Pipe | Virtual | How to using physical layer Antenna Profiles |
8 | 10 | Comm Effect | Virtual | Introduction to the Comm Effect Utility Model |
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 lxs-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. |
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. |
All log, pid and uuid files generated by these applications are written to persist/host/var/{log,run}.
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
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 2, will create a virtual interface (vif) within the containers named emane0, for use as the Radio Interface. Demonstration 2 will configure eth1 as the Radio Interface.
To make things a little easier you should add the following to your /etc/hosts file
10.99.0.1 node-1
10.99.0.2 node-2
10.99.0.3 node-3
10.99.0.4 node-4
10.99.0.5 node-5
10.99.0.6 node-6
10.99.0.7 node-7
10.99.0.8 node-8
10.99.0.9 node-9
10.99.0.10 node-10
10.99.0.100 node-server
10.100.0.1 radio-1
10.100.0.2 radio-2
10.100.0.3 radio-3
10.100.0.4 radio-4
10.100.0.5 radio-5
10.100.0.6 radio-6
10.100.0.7 radio-7
10.100.0.8 radio-8
10.100.0.9 radio-9
10.100.0.10 radio-10
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.
The following are common misconceptions new EMANE users often have.
-
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. -
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. -
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. In short, EMANE scales by adding more CPUs to your emulation, not by adding more emulation to your CPUs.
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.