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

Demonstration 0

Jump to bottom
Steven Galgano edited this page Mar 24, 2014 · 12 revisions

Purpose

The purpose of this demonstration is to provide an introduction to the three major EMANE subsystems and the applications and tools which make up the EMANE emulator.

Background

The EMANE emulator consists of three major subsystems:

Demonstration

This demonstration consists of a series of activities used to introduce core EMANE concepts.

Activity 1 - Let's have a look around

Lets start up our first demonstration, Demonstration 0.

  1. Change directory into the Demonstration 0 directory
[me@host emane-tutorial]$ cd 0
  1. Take a look at the contents of the demonstration directory
[me@host 0]$ ls
bypassmac.xml     gpsdlocationagent1.xml     platform1.xml
bypassnem.xml     gpsdlocationagent2.xml     platform2.xml
bypassphy.xml     Makefile                   routing1.conf
demo-start        NO-host-emaneeventservice  routing2.conf
demo-stop         NO-node-emane              transportdaemon1.xml
eelgenerator.xml  NO-node-emaneeventd        transportdaemon2.xml
eventdaemon1.xml  NO-node-emanetransportd    transvirtual.xml
eventdaemon2.xml  NO-node-gpsd
eventservice.xml  NO-node-routing

The first thing that you probably notice is all the NO-node-* files and the NO-host-emaneeventservice file. The presence of these empty files prevents the experiment work flow from starting certain applications.

File Prevented Action If Present
NO-node-emane Do not run emane even if an appropriate configuration input file is present.
NO-node-emane<NODEID> Do not run emane even if an appropriate configuration input file is present. Ignore NO-node-emane, if present.
NO-node-emanetransportd Do not run emanetransportd even if an appropriate configuration input file is present.
NO-node-emanetransportd<NODEID> Do not run emanetransportd even if an appropriate configuration input file is present. Ignore NO-node-emanetransportd, if present.
NO-node-emaneeventd Do not run emaneeventd even if an appropriate configuration input file is present.
NO-node-emaneeventd<NODEID> Do not run emaneeventd even if an appropriate configuration input file is present. Ignore NO-node-emaneeventd, if present.
NO-node-routing Do not run the routing application even if an appropriate configuration input file is present.
NO-node-routing<NODEID> Do not run the routing application even if an appropriate configuration input file is present. Ignore NO-node-routing, if present.
NO-node-iperf Do not run iperf even if an appropriate configuration input file is present.
NO-node-iperf<NODEID> Do not run iperf even if an appropriate configuration input file is present. Ignore NO-node-iperf, if present.
NO-node-mgen Do not run mgen even if an appropriate configuration input file is present.
NO-node-mgen<NODEID> Do not run mgen even if an appropriate configuration input file is present. Ignore NO-node-mgen, if present.

Similarly, the presence of certain NO-host-* files will prevent certain host actions.

File Prevented Action If Present
NO-host-emane Do not run emane even if an appropriate configuration input file is present.
NO-host-emanetransportd Do not run emanetransportd even if an appropriate configuration input file is present.
NO-node-emaneeventservice Do not run emaneeventservice even if an appropriate configuration input file is present.

We will be deleting some of these files shortly, but first lets identify the configuration input files for the EMANE emulator applications.

  1. Identify the emulation processing related configuration

platform1.xml and platform2.xml are the input configuration files for the emulator instances (emane application) that will run on node-1 and node-2, respectively.

Let's take a look at platform1.xml.

[me@host 0]$ cat platform1.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE platform SYSTEM "file:///usr/share/emane/dtd/platform.dtd">
<platform>
<param name="otamanagerchannelenable" value="on"/>
<param name="otamanagerdevice" value="eth1"/>
<param name="otamanagergroup" value="224.1.2.8:45702"/>
<param name="eventservicegroup" value="224.1.2.8:45703"/>
<param name="eventservicedevice" value="eth1"/>
<param name="controlportendpoint" value="0.0.0.0:47000"/>

<nem id="1" definition="bypassnem.xml">
  <param name="platformendpoint" value="127.0.0.1:8201"/>
  <param name="transportendpoint" value="127.0.0.1:8301"/>
  <transport definition="transvirtual.xml">
    <param name="address" value="10.100.0.1"/>
    <param name="mask" value="255.255.255.0"/>
  </transport>
  </nem>
</platform>

The first six parameters are used to configure the emulator:

1. [otamanagerchannelenable](https://github.com/adjacentlink/emane/wiki/Configuring-the-Emulator#otamanagerchannelenable)
2. [otamanagerdevice](https://github.com/adjacentlink/emane/wiki/Configuring-the-Emulator#otamanagerdevice)
3. [otamanagergroup](https://github.com/adjacentlink/emane/wiki/Configuring-the-Emulator#otamanagergroup)
4. [eventservicegroup](https://github.com/adjacentlink/emane/wiki/Configuring-the-Emulator#eventservicegroup)
5. [eventservicedevice](https://github.com/adjacentlink/emane/wiki/Configuring-the-Emulator#eventservicedevice)
6. [controlportendpoint](https://github.com/adjacentlink/emane/wiki/Configuring-the-Emulator#controlportendpoint)

The <nem> element is used to tell the emulator which NEMs to create, how to configure them, and how to connect them to their respective transport boundary.

In this example, this instance of the emulator will instantiate NEM 1 and will transmit messages destined for it's respective transport boundary to 127.0.0.1:8301. Likewise, it will listen on an endpoint bound to 127.0.0.1:8201 for messages sent by it's respective transport boundary. These transport messages are sent via UDP datagrams.

In order to determine which NEM plugins to instantiate to build NEM 1, the emulator will look at the XML file referenced by the definition attribute: bypassnem.xml.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE nem SYSTEM "file:///usr/share/emane/dtd/nem.dtd">
<nem>
<mac definition="bypassmac.xml"/>
<phy definition="bypassphy.xml"/>
<transport definition="transvirtual.xml"/>
</nem>

The Bypass Radio Model is the EMANE equivalent of Hello World!. It serves no other purpose than to allow us to demonstrate NEM composition and emulator application roles without getting bogged down with the particulars of radio waveforms.

Looking at the this file we can see that this NEM instance will be composed of a <mac> and <phy> , also referenced by XML file. When you see the element <mac> in these XML files think of it as the lowest layer of a radio waveform model, i.e. the parts concerned with channel access schemes, retries, segmentation, fragmentation, etc.

Looking closer at bypassmac.xml we find the end of the indirection amusement ride.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mac SYSTEM "file:///usr/share/emane/dtd/mac.dtd">
<mac library="bypassmaclayer"/>

Here the library attribute tells the emulator to load the libbypassmaclayer.so plugin in order instantiate this NEM's MAC layer.

At any point where you use an XML element with a definition attribute you can specify configuration for the element that will override any configuration parameters found in the referenced XML file. We'll see examples of this later.

If you were to compare platform1.xml with platform2.xml you would find they are virtually identical.

[me@host 0]$ diff platform1.xml platform2.xml 

11c11
<   <nem id="1" definition="bypassnem.xml">
---
>   <nem id="2" definition="bypassnem.xml">
15c15
<       <param name="address" value="10.100.0.1"/>
---
>       <param name="address" value="10.100.0.2"/>

The obvious difference is the NEM id attribute. All NEMs must have a unique id. The id functions as an emulation transceiver MAC address. The all 1's NEM id 65535 is the NEM broadcast address and NEM id 0 is invalid.

The other difference has to do with the Transport Boundary address parameter. We'll cover that next.

  1. Identify the application/emulation transport boundary processing related configuration

transportdaemon1.xml and transportdaemon2.xml are the input configuration files for the transport boundary instances (emanetransportd application) that will run on node-1 and node-2, respectively.

Before looking at one of these files, let's first revisit platform1.xml and take a look at the <transport> element used when defining NEM 1.

  <transport definition="transvirtual.xml">
    <param name="address" value="10.100.0.1"/>
    <param name="mask" value="255.255.255.0"/>
  </transport>

NEM 1 is using the Virtual Transport. The Virtual Transport will create a vif for use as the emulation entry/exit mechanism. All packets routed by the kernel to the vif will be processed by the emulator and all packets determined to have been received by the emulator will be written back to the vif for delivery to application space by the kernel.

In the same way NEM layers are indirectly defined, so too are transport boundaries. Here we are overriding configuration for the transport instance:

1. [address](https://github.com/adjacentlink/emane/wiki/Virtual-Transport#address)
2. [mask](https://github.com/adjacentlink/emane/wiki/Virtual-Transport#mask)

These parameter values would override any found in bypassnem.xml.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE nem SYSTEM "file:///usr/share/emane/dtd/nem.dtd">
<nem name="BYPASS NEM">
<mac definition="bypassmac.xml"/>
<phy definition="bypassphy.xml"/>
<transport definition="transvirtual.xml"/>
</nem>

And they would override any found in transvirtual.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE transport SYSTEM "file:///usr/share/emane/dtd/transport.dtd">
<transport library="transvirtual"/>

From the library element in transvirtual.xml we see that an instance the libtransvirtual.so plugin will be used for this NEM.

Now that we have a better understanding about what will be instantiated, let's take a look at transportdaemon1.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE transportdaemon SYSTEM "file:///usr/share/emane/dtd/transportdaemon.dtd">
<transportdaemon>
<instance nemid="1">
  <param name="platformendpoint" value="127.0.0.1:8201"/>
  <param name="transportendpoint" value="127.0.0.1:8301"/>
  <transport definition="transvirtual.xml">
    <param name="address" value="10.100.0.1"/>
    <param name="mask" value="255.255.255.0"/>
  </transport>
</instance>
</transportdaemon>

You might be thinking: Wow, that is pretty redundant. It is all the same information. If so, you are correct. No worries, 99.9% of the time you will not have to hand edit emanetransportd configuration. You can use the emanegentransportxml script to generate the required input files from platform XML.

[me@chaos 0]$ chmod u+w transportdaemon?.xml && emanegentransportxml platform*.xml
--> Platform XML file: platform1.xml
--> Platform XML file: platform2.xml
--> Generated file will be placed in:
--> DTDs for validation are from: file:///usr/share/emane/dtd/
--> Name of DTD to validate generated file: transportdaemon.dtd
--> Generated file will be placed in:
--> DTDs for validation are from: file:///usr/share/emane/dtd/
--> Name of DTD to validate generated file: transportdaemon.dtd
Done.

The chmod u+w transportdaemon?.xml portion of the command was only required if you would like to try now for yourself. The tutorial test flow generates these files for you and makes them read-only as a reminder that you don't need to edit them.

  1. Identify the event processing related configuration

eventdaemon1.xml and eventdaemon2.xml are the input configuration files for the event daemon instances (emaneeventd application) that will run on node-1 and node-2, respectively.

eventservice.xml is the input configuration files for the event service instance ([emaneeventservice](https://github.com/adjacentlink/emane/wiki/Man-Page-emaneeventservice application) that will run on the host.

We'll start with the configuration for emaneeventd. Let's take a look at eventdaemon1.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE eventdaemon SYSTEM "file:///usr/share/emane/dtd/eventdaemon.dtd">
<eventdaemon nemid="1">
<param name="eventservicegroup" value="224.1.2.8:45703"/>
<param name="eventservicedevice" value="eth1"/>
<agent definition="gpsdlocationagent1.xml"/>
</eventdaemon>

By now you should be recognize the EMANE application configuration pattern. The top level configuration parameters are for the application - in this case emaneeventd.

1. [eventservicegroup](https://github.com/adjacentlink/emane/wiki/Configuring-the-Event-Daemon#eventservicegroup)
2. [eeventservicedevice](https://github.com/adjacentlink/emane/wiki/Configuring-the-Event-Daemon#eventservicedevice)

And the remaining elements specify the plugins to load and how they should be configured.

<agent definition="gpsdlocationagent1.xml"/>

Taking a look at gpsdlocationagent1.xml we see that the Event Daemon will create an instance of the GPSD Location Agent from the plugin: libgpsdlocationagent.so. The GPSD Location Agent creates a pseudo terminal on the test node (pseudo serial port), translates received EMANE Location events into NMEA strings and writes them out the pseudo terminal for processing by applications such as gpsd.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE eventagent SYSTEM "file:///usr/share/emane/dtd/eventagent.dtd">
<eventagent library="gpsdlocationagent">
<param name="gpsdconnectionenabled" value="no"/>
<param name="pseudoterminalfile"
       value="persist/1/var/run/gps.pty"/>
</eventagent>

But where do EMANE events come from? They can come from a variety of sources. In this demonstrations events are generated by the Event Service. The Event Service is run on the host system and sends events over the Event multicast channel to all the test nodes.

Looking at eventservice.xml we see configuration pattern emerge again.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE eventservice SYSTEM "file:///usr/share/emane/dtd/eventservice.dtd">
<eventservice>
<param name="eventservicegroup" value="224.1.2.8:45703"/>
<param name="eventservicedevice" value="emanenode0"/>
<generator definition="eelgenerator.xml"/>
</eventservice>

The two application parameters are the same as we saw for the event daemon, almost.

1. [eventservicegroup](https://github.com/adjacentlink/emane/wiki/Configuring-the-Event-Service#eventservicegroup)
2. [eeventservicedevice](https://github.com/adjacentlink/emane/wiki/Configuring-the-Event-Service#eventservicedevice)

The <generator> element references the definition of the EEL Event Generator.

Looking at eelgenerator.xml we see the name of the plugin to load: libeelgenerator.so and the configuration to pass to the plugin instance.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE eventgenerator SYSTEM "file:///usr/share/emane/dtd/eventgenerator.dtd">
<eventgenerator library="eelgenerator">
  <param name="inputfile" value="../scenario/scenario.eel" />
  <paramlist name="loader">
    <item value="commeffect:eelloadercommeffect:delta"/>
    <item value="location,velocity,orientation:eelloaderlocation:delta"/>
    <item value="pathloss:eelloaderpathloss:delta"/>
    <item value="antennaprofile:eelloaderantennaprofile:delta"/>
  </paramlist>
</eventgenerator>

You may have noticed the the Event Daemon multicast device is different than the Event Service multicast device. This is because the Event Daemon instances run in test node containers and the Event Service instance runs on the host. Remember, the host emanenode0 interface is the bridge that connects together all the container eth1 interfaces.

  1. The two remaining configuration input files: routing1.conf and routing2.conf are olsrd configuration files. EMANE is an emulator not a MANET routing protocol. In this tutorial we will use the olsr.org implementation of the Optimized Link State Routing Protocol.

Don't worry if you are not familiar with OLSR, familiarity is not necessary for this tutorial. It is enough to know that this routing protocol is used to create/manage routes across a MANET.

Activity 2 - Let's run something

This activity could alternatively be titled Let's develop an appreciation for not having to run things by hand. You'll see.

  1. The first thing we need to do is to start the demonstration. This will launch the two containers that are part of this demonstration but won't do much more since we have the following files present in the demonstration directory:
[me@host 0]$ ls -1 NO-* 
NO-host-emaneeventservice
NO-node-emane
NO-node-emaneeventd
NO-node-emanetransportd
NO-node-gpsd
NO-node-routing

To start the demonstration use the demo-start script.

[me@host 0]$ sudo ./demo-start
Creating bridge: emanenode0
kernel.sched_rt_runtime_us = -1
Starting lxc instance: node-1
Starting lxc instance: node-2
  1. Open up a terminal window and ssh into node-1. Then change to the /var/lib/emanenode directory.
[me@host ~]$ ssh node-1
[me@node-1 ~]$ cd /var/lib/emanenode
[me@node-1 emanenode]$

The /var/lib/emanenode directory is a bind mount of whatever is the current running demonstration directory. Check it out by listing the directory contents.

  1. Open another terminal window and do the same for node-2.
[me@host ~]$ ssh node-2
[me@node-2 ~]$ cd /var/lib/emanenode
[me@node-2 emanenode]$
  1. Pick a test node and take a look at the existing network interfaces and routes.
[me@node-1 emanenode]$ ifconfig
eth1: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
      inet 10.99.0.1  netmask 255.255.255.0  broadcast 10.99.0.255
      inet6 fe80::1ff:fe01:1  prefixlen 64  scopeid 0x20<link>
      ether 02:00:01:01:00:01  txqueuelen 1000  (Ethernet)
      RX packets 212  bytes 24088 (23.5 KiB)
      RX errors 0  dropped 2  overruns 0  frame 0
      TX packets 61  bytes 8403 (8.2 KiB)
      TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0
lo: flags=73<UP,LOOPBACK,RUNNING>  mtu 65536
      inet 127.0.0.1  netmask 255.0.0.0
      inet6 ::1  prefixlen 128  scopeid 0x10<host>
      loop  txqueuelen 0  (Local Loopback)
      RX packets 0  bytes 0 (0.0 B)
      RX errors 0  dropped 0  overruns 0  frame 0
      TX packets 0  bytes 0 (0.0 B)
      TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

[me@node-1 emanenode]$ route -n
Kernel IP routing table
Destination     Gateway         Genmask         Flags Metric Ref    Use Iface
10.99.0.0       0.0.0.0         255.255.255.0   U     0      0        0 eth1
  1. Now let's start up the transport boundary

On node-1 start emanetransportd

[me@node-1 emanenode]$ sudo emanetransportd transportdaemon1.xml -r -d -l 3 -f persist/1/var/log/transportdaemon.log

On node-2 start emanetransportd

[me@node-2 emanenode]$ sudo emanetransportd transportdaemon2.xml -r -d -l 3 -f persist/2/var/log/transportdaemon.log
  1. Now take a look at the current interfaces.
[me@node-2 emanenode]# ifconfig 
emane0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
      inet 10.100.0.2  netmask 255.255.255.0  broadcast 10.100.0.255
      inet6 fe80::2:ff:fe00:2  prefixlen 64  scopeid 0x20<link>
      ether 02:02:00:00:00:02  txqueuelen 500  (Ethernet)
      RX packets 0  bytes 0 (0.0 B)
      RX errors 0  dropped 0  overruns 0  frame 0
      TX packets 8  bytes 648 (648.0 B)
      TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0
eth1: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
      inet 10.99.0.2  netmask 255.255.255.0  broadcast 10.99.0.255
      inet6 fe80::2ff:fe01:1  prefixlen 64  scopeid 0x20<link>
      ether 02:00:02:01:00:01  txqueuelen 1000  (Ethernet)
      RX packets 547  bytes 48852 (47.7 KiB)
      RX errors 0  dropped 0  overruns 0  frame 0
      TX packets 202  bytes 27201 (26.5 KiB)
      TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0
lo: flags=73<UP,LOOPBACK,RUNNING>  mtu 65536
      inet 127.0.0.1  netmask 255.0.0.0
      inet6 ::1  prefixlen 128  scopeid 0x10<host>
      loop  txqueuelen 0  (Local Loopback)
      RX packets 29  bytes 3869 (3.7 KiB)
      RX errors 0  dropped 0  overruns 0  frame 0
      TX packets 29  bytes 3869 (3.7 KiB)
      TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

Notice anything new?

  1. Let's start the emulator

On node-1 start emane

[me@node-1 emanenode]$ sudo emane platform1.xml -r -d -l 3 -f persist/1/var/log/emane.log

On node-2 start emane

[me@node-2 emanenode]$ sudo emane platform2.xml -r -d -l 3 -f persist/2/var/log/emane.log
  1. Now you are able to ping across the emulation.

On node-1 ping radio-2

[me@node-1 emanenode]$ ping radio-2

On node-2 ping radio-1

[me@node-2 emanenode]$ ping radio-1

We are not quite done yet though. There is more to start.

  1. Next lets start the routing protocol.

On node-1 start olsrd

[me@node-1 emanenode]$ sudo olsrd -f routing1.conf

On node-2 start olsrd

[me@node-2 emanenode]$ sudo olsrd -f routing2.conf
  1. Back in your host shell window, start up the simple OLSR topology viewer
[me@host 0]$ ../scripts/olsrlinkview.py &

This viewer provides a very simple view of the wireless network. It displays one hop neighbors and GPS location information (if available) for each test node.

You'll notice there is no position information for nodes 1 and 2. This is because we have not finished starting all the applications and services.

  1. Now we need to start up emaneeventd and gpsd on both test nodes.

On node-1 start emaneventd

[me@node-1 emanenode]$ sudo emaneeventd eventdaemon1.xml -r -d -l 3 -f persist/1/var/log/emaneeventd.log

On node-2 start emaneeventd

[me@node-2 emanenode]$ sudo emaneeventd eventdaemon2.xml -r -d -l 3 -f persist/2/var/log/emaneeventd.log

On node-1 start gpsd

[me@node-1 emanenode]$ sudo gpsd -G -n -b $(cat persist/1/var/run/gps.pty)

On node-2 start gpsd

[me@node-2 emanenode]$ sudo gpsd -G -n -b $(cat persist/2/var/run/gps.pty)

You still will not see position information on the topology viewer. We need to generate some location events.

  1. Start up the Event Service on the host
[me@host 0]$ emaneeventservice eventservice.xml -l 3

Now you should see position information on the viewer. The viewer does not position nodes based on geolocation but you are free to drag the nodes about the canvas.

Type Ctrl-c to stop emaneeventservice. If you started emaneeventservice in the background you can use kill or killall to stop it.

[me@host 0]$ killall -QUIT emaneeventservice
  1. Once you have had your fill of fun, stop the demonstration with demo-stop.
[me@host 0]$ sudo ./demo-stop

Activity 3 - Let's do it again using the tutorial test flow

Let's try the same things again but this time we'll let the tutorial test flow do the heavy lifting.

  1. Remove all the N0- prefixed files from the demonstration directory.
[me@host 0]$ rm NO-* -f
  1. Start the demonstration with demo-start.
[me@host 0]$ sudo ./demo-start
  1. Take a look at the processes running on one of the test nodes.
[me@host 0]$ ssh node-1
[me@node-1 ~]$ ps ax
PID TTY      STAT   TIME COMMAND
  1 ?        S+     0:00 /usr/libexec/lxc/lxc-init -- ../scripts/demo-init -s Tue
 12 ?        Ss     0:00 /usr/sbin/sshd -o PidFile=persist/1/var/run/ssh.pid
 14 ?        Ssl    0:00 emanetransportd -r -d transportdaemon1.xml -l 3 -f persi
 26 ?        Ssl    0:00 emane platform1.xml -r -d -l 3 -f persist/1/var/log/eman
 37 pts/0    Ssl+   0:00 emaneeventd -r -d eventdaemon1.xml -l 3 -f persist/1/var
 46 ?        S<s    0:00 gpsd -P persist/1/var/run/gpsd.pid -G -n -b /dev/pts/0
 52 ?        Ss     0:00 olsrd -f routing1.conf
 53 ?        Ss     0:00 sshd: me [priv]
 56 ?        R      0:00 sshd: me@pts/1
 57 pts/1    Ss     0:00 -bash
 87 pts/1    R+     0:00 ps ax

That was much easier. If you still have the topology viewer running you should see a two node network and positions displayed for both nodes. The tutorial test flow waits 30 seconds before starting the emaneeventservice, mgen, and/or iperf. So in this case you won't see positions for 30 seconds.

  1. Once you are finished, stop the demonstration with demo-stop.
[me@host 0]$ sudo ./demo-stop

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