359 lines
15 KiB
ReStructuredText
359 lines
15 KiB
ReStructuredText
.. This file is part of the CORE Manual
|
|
(c)2012 the Boeing Company
|
|
|
|
.. _EMANE:
|
|
|
|
*****
|
|
EMANE
|
|
*****
|
|
|
|
.. index:: EMANE
|
|
|
|
This chapter describes running CORE with the EMANE emulator.
|
|
|
|
.. _What_is_EMANE?:
|
|
|
|
What is EMANE?
|
|
==============
|
|
|
|
.. index:: EMANE; introduction to
|
|
|
|
The Extendable Mobile Ad-hoc Network Emulator (EMANE) allows heterogeneous
|
|
network emulation using a pluggable MAC and PHY layer architecture. The EMANE
|
|
framework provides an implementation architecture for modeling different radio
|
|
interface types in the form of *Network Emulation Modules* (NEMs) and
|
|
incorporating these modules into a real-time emulation running in a distributed
|
|
environment.
|
|
|
|
EMANE is developed by U.S. Naval Research Labs (NRL) Code 5522 and Adjacent
|
|
Link LLC,
|
|
who maintain these websites:
|
|
|
|
* `<http://www.nrl.navy.mil/itd/ncs/products/emane>`_
|
|
* `<http://www.adjacentlink.com/>`_
|
|
|
|
Instead of building Linux Ethernet bridging networks with CORE, higher-fidelity
|
|
wireless networks can be emulated using EMANE bound to virtual devices. CORE
|
|
emulates layers 3 and above (network, session, application) with its virtual
|
|
network stacks and process space for protocols and applications, while EMANE
|
|
emulates layers 1 and 2 (physical and data link) using its pluggable PHY and
|
|
MAC models.
|
|
|
|
The interface between CORE and EMANE is a TAP device. CORE builds the virtual
|
|
node using Linux network namespaces, installs the TAP device into the
|
|
namespace and instantiates one EMANE process in the namespace.
|
|
The EMANE process binds a user space socket to the TAP device for
|
|
sending and receiving data from CORE.
|
|
|
|
|
|
.. NOTE::
|
|
When the installed EMANE version is older than 0.9.2, EMANE runs on the host
|
|
and binds a userspace socket to the TAP device, before it is pushed into the
|
|
namespace, for sending and receiving data. The *Virtual Transport* was
|
|
the EMANE component responsible for connecting with the TAP device.
|
|
|
|
An EMANE instance sends and receives OTA traffic to and from other
|
|
EMANE instances via a control port (e.g. ``ctrl0``, ``ctrl1``).
|
|
It also sends and receives Events to and from the Event Service using
|
|
the same or a different control port.
|
|
EMANE models are configured through CORE's WLAN configuration dialog. A
|
|
corresponding EmaneModel Python class is sub-classed for each supported EMANE
|
|
model, to provide configuration items and their mapping to XML files. This way
|
|
new models can be easily supported. When CORE starts the emulation, it
|
|
generates the appropriate XML files that specify the EMANE NEM configuration,
|
|
and launches the EMANE daemons.
|
|
|
|
Some EMANE models support location information to determine when packets should
|
|
be dropped. EMANE has an event system where location events are broadcast to
|
|
all NEMs. CORE can generate these location events when nodes are moved on the
|
|
canvas. The canvas size and scale dialog has controls for mapping the X,Y
|
|
coordinate system to a latitude, longitude geographic system that EMANE uses.
|
|
When specified in the :file:`core.conf` configuration file, CORE can also
|
|
subscribe to EMANE location events and move the nodes on the canvas as they are
|
|
moved in the EMANE emulation. This would occur when an Emulation Script
|
|
Generator, for example, is running a mobility script.
|
|
|
|
.. index:: EMANE; Configuration
|
|
|
|
.. index:: EMANE; Installation
|
|
|
|
.. _EMANE_Configuration:
|
|
|
|
EMANE Configuration
|
|
===================
|
|
|
|
|
|
CORE and EMANE currently work together only on the Linux network namespaces
|
|
platform. The normal CORE installation instructions should be followed from
|
|
:ref:`Installation`.
|
|
|
|
The CORE configuration file :file:`/etc/core/core.conf` has options specific to
|
|
EMANE. Namely, the `emane_models` line contains a comma-separated list of EMANE
|
|
models that will be available. Each model has a corresponding Python file
|
|
containing the *EmaneModel* subclass. A portion of the default
|
|
:file:`core.conf` file is shown below:
|
|
|
|
::
|
|
|
|
# EMANE configuration
|
|
emane_platform_port = 8101
|
|
emane_transform_port = 8201
|
|
emane_event_monitor = False
|
|
emane_models = RfPipe, Ieee80211abg
|
|
|
|
|
|
EMANE can be installed from deb or RPM packages or from source. See the
|
|
`EMANE website <http://www.nrl.navy.mil/itd/ncs/products/emane>`_ for
|
|
full details.
|
|
|
|
Here are quick instructions for installing all EMANE packages:
|
|
|
|
::
|
|
|
|
# install dependencies
|
|
sudo apt-get install libssl-dev libxml-lixbml-perl libxml-simple-perl
|
|
# download and install EMANE 0.8.1
|
|
export URL=http://downloads.pf.itd.nrl.navy.mil/emane/0.8.1-r2
|
|
wget $URL/emane-0.8.1-release-2.ubuntu-12_04.amd64.tgz
|
|
tar xzf emane-0.8.1-release-2.ubuntu-12_04.amd64.tgz
|
|
sudo dpkg -i emane-0.8.1-release-2/deb/ubuntu-12_04/amd64/*.deb
|
|
|
|
|
|
If you have an EMANE event generator (e.g. mobility or pathloss scripts) and
|
|
want to have CORE subscribe to EMANE location events, set the following line in
|
|
the :file:`/etc/core/core.conf` configuration file:
|
|
::
|
|
|
|
emane_event_monitor = True
|
|
|
|
Do not set the above option to True if you want to manually drag nodes around
|
|
on the canvas to update their location in EMANE.
|
|
|
|
Another common issue is if installing EMANE from source, the default configure
|
|
prefix will place the DTD files in :file:`/usr/local/share/emane/dtd` while
|
|
CORE expects them in :file:`/usr/share/emane/dtd`. A symbolic link will fix
|
|
this:
|
|
::
|
|
|
|
sudo ln -s /usr/local/share/emane /usr/share/emane
|
|
|
|
|
|
.. _Single_PC_with_EMANE:
|
|
|
|
Single PC with EMANE
|
|
====================
|
|
|
|
This section describes running CORE and EMANE on a single machine. This is the
|
|
default mode of operation when building an EMANE network with CORE. The OTA
|
|
manager and Event service interface are set to use ``ctrl0`` and the virtual nodes
|
|
use the primary control channel for communicating with one another. The primary
|
|
control channel is automatically activated when a scenario involves EMANE.
|
|
Using the primary control channel prevents your emulation session from sending
|
|
multicast traffic on your local network and interfering with other EMANE users.
|
|
|
|
.. NOTE::
|
|
When the installed EMANE version is earlier than 0.9.2, the OTA manager and
|
|
Event service interfaces are set to use the loopback device.
|
|
|
|
|
|
EMANE is configured through a WLAN node, because it is all about emulating
|
|
wireless radio networks. Once a node is linked to a WLAN cloud configured with
|
|
an EMANE model, the radio interface on that node may also be configured
|
|
separately (apart from the cloud.)
|
|
|
|
Double-click on a WLAN node to invoke the WLAN configuration dialog. Click the
|
|
*EMANE* tab; when EMANE has
|
|
been properly installed, EMANE wireless modules should be listed in the
|
|
*EMANE Models* list. (You may need to restart the CORE daemon if
|
|
it was running prior to installing the EMANE Python bindings.)
|
|
Click on a model name to enable it.
|
|
|
|
When an EMANE model is selected in the *EMANE Models* list, clicking on
|
|
the *model options* button causes the GUI to query the CORE daemon for
|
|
configuration items. Each model will have different parameters, refer to the
|
|
EMANE documentation for an explanation of each item. The defaults values are
|
|
presented in the dialog. Clicking *Apply* and *Apply* again will store
|
|
the EMANE model selections.
|
|
|
|
The *EMANE options* button
|
|
allows specifying some global parameters for EMANE, some of
|
|
which are necessary for distributed operation, see :ref:`Distributed_EMANE`.
|
|
|
|
.. index:: RF-PIPE model
|
|
|
|
.. index:: 802.11 model
|
|
|
|
.. index:: ieee80211abg model
|
|
|
|
.. index:: geographic location
|
|
|
|
.. index:: Universal PHY
|
|
|
|
The RF-PIPE and IEEE 802.11abg models use a Universal PHY that supports
|
|
geographic location information for determining pathloss between nodes. A
|
|
default latitude and longitude location is provided by CORE and this
|
|
location-based pathloss is enabled by default; this is the *pathloss mode*
|
|
setting for the Universal PHY. Moving a node on the canvas while the emulation
|
|
is running generates location events for EMANE. To view or change the
|
|
geographic location or scale of the canvas use the *Canvas Size and Scale*
|
|
dialog available from the *Canvas* menu.
|
|
|
|
.. index:: UTM zones
|
|
|
|
.. index:: UTM projection
|
|
|
|
Note that conversion between geographic and Cartesian
|
|
coordinate systems is done using UTM
|
|
(Universal Transverse Mercator) projection, where
|
|
different zones of 6 degree longitude bands are defined.
|
|
The location events generated by
|
|
CORE may become inaccurate near the zone boundaries for very large scenarios
|
|
that span multiple UTM zones. It is recommended that EMANE location scripts
|
|
be used to achieve geo-location accuracy in this situation.
|
|
|
|
Clicking the green *Start* button launches the emulation and causes TAP
|
|
devices to be created in the virtual nodes that are linked to the EMANE WLAN.
|
|
These devices appear with interface names such as eth0, eth1, etc. The EMANE
|
|
processes should now be running in each namespace. For a four node scenario:
|
|
|
|
::
|
|
|
|
> ps -aef | grep emane
|
|
root 1063 969 0 11:46 ? 00:00:00 emane -d --logl 3 -r -f /tmp/pycore.59992/emane4.log /tmp/pycore.59992/platform4.xml
|
|
root 1117 959 0 11:46 ? 00:00:00 emane -d --logl 3 -r -f /tmp/pycore.59992/emane2.log /tmp/pycore.59992/platform2.xml
|
|
root 1179 942 0 11:46 ? 00:00:00 emane -d --logl 3 -r -f /tmp/pycore.59992/emane1.log /tmp/pycore.59992/platform1.xml
|
|
root 1239 979 0 11:46 ? 00:00:00 emane -d --logl 3 -r -f /tmp/pycore.59992/emane5.log /tmp/pycore.59992/platform5.xml
|
|
|
|
The example above shows the EMANE processes started by CORE. To view the configuration generated by CORE, look in the
|
|
:file:`/tmp/pycore.nnnnn/` session directory for a :file:`platform.xml` file
|
|
and other XML files. One easy way to view this information is by
|
|
double-clicking one of the virtual nodes, and typing *cd ..* in the shell to go
|
|
up to the session directory.
|
|
|
|
|
|
.. _single_pc_emane_figure:
|
|
|
|
.. figure:: figures/single-pc-emane.*
|
|
:alt: Single PC Emane
|
|
:align: center
|
|
:scale: 75%
|
|
|
|
Single PC with EMANE
|
|
|
|
|
|
|
|
.. index:: Distributed_EMANE
|
|
.. _Distributed_EMANE:
|
|
|
|
Distributed EMANE
|
|
=================
|
|
|
|
|
|
Running CORE and EMANE distributed among two or more emulation servers is
|
|
similar to running on a single machine. There are a few key configuration items
|
|
that need to be set in order to be successful, and those are outlined here.
|
|
|
|
It is a good idea to maintain separate networks for data (OTA) and control. The control
|
|
network may be a shared laboratory network, for example, and you do not want
|
|
multicast traffic on the data network to interfere with other EMANE users. Furthermore,
|
|
control traffic could interfere with the OTA latency and thoughput and might affect
|
|
emulation fidelity. The examples described here will use *eth0* as a control interface
|
|
and *eth1* as a data interface, although using separate interfaces
|
|
is not strictly required. Note that these interface names refer to interfaces
|
|
present on the host machine, not virtual interfaces within a node.
|
|
|
|
.. IMPORTANT::
|
|
If an auxiliary control network is used, an interface on the host has to be assigned to that network.
|
|
See :ref:`Distributed_Control_Network`
|
|
|
|
Each machine that will act as an emulation server needs to have CORE and EMANE
|
|
installed. Refer to the :ref:`Distributed_Emulation` section for configuring
|
|
CORE.
|
|
|
|
The IP addresses of the available servers are configured from the
|
|
CORE emulation servers dialog box (choose *Session* then
|
|
*Emulation servers...*) described in :ref:`Distributed_Emulation`.
|
|
This list of servers is stored in a :file:`~/.core/servers.conf` file.
|
|
The dialog shows available servers, some or all of which may be
|
|
assigned to nodes on the canvas.
|
|
|
|
Nodes need to be assigned to emulation servers as described in
|
|
:ref:`Distributed_Emulation`. Select several nodes, right-click them, and
|
|
choose *Assign to* and the name of the desired server. When a node is not
|
|
assigned to any emulation server, it will be emulated locally. The local
|
|
machine that the GUI connects with is considered the "master" machine, which in
|
|
turn connects to the other emulation server "slaves". Public key SSH should
|
|
be configured from the master to the slaves as mentioned in the
|
|
:ref:`Distributed_Emulation` section.
|
|
|
|
|
|
Under the *EMANE* tab of the EMANE WLAN, click on the *EMANE options* button.
|
|
This brings
|
|
up the emane configuration dialog. The *enable OTA Manager channel* should
|
|
be set to *on*. The *OTA Manager device* and *Event Service device* should
|
|
be set to a control network device. For example, if you have
|
|
a primary and auxiliary control network (i.e. controlnet and controlnet1), and you want
|
|
the OTA traffic to have its dedicated network, set the OTA Manager device to ``ctrl1``
|
|
and the Event Service device to ``ctrl0``.
|
|
The EMANE models can be configured as described in :ref:`Single_PC_with_EMANE`.
|
|
Click *Apply* to save these settings.
|
|
|
|
|
|
|
|
.. _distributed_emane_figure:
|
|
|
|
.. figure:: figures/distributed-emane-configuration.*
|
|
:alt: Distribute EMANE
|
|
:align: center
|
|
:scale: 75%
|
|
|
|
Distributed EMANE Configuration
|
|
|
|
|
|
|
|
|
|
.. NOTE::
|
|
When the installed EMANE version is earlier than 0.9.2, EMANE access to the host machine's
|
|
interfaces and OTA manager and Event service devices an be set to physical interfaces.
|
|
|
|
.. HINT::
|
|
Here is a quick checklist for distributed emulation with EMANE.
|
|
|
|
1. Follow the steps outlined for normal CORE :ref:`Distributed_Emulation`.
|
|
2. Under the *EMANE* tab of the EMANE WLAN, click on *EMANE options*.
|
|
3. Turn on the *OTA Manager channel* and set the *OTA Manager device*.
|
|
Also set the *Event Service device*.
|
|
4. Select groups of nodes, right-click them, and assign them to servers
|
|
using the *Assign to* menu.
|
|
5. Synchronize your machine's clocks prior to starting the emulation,
|
|
using ``ntp`` or ``ptp``. Some EMANE models are sensitive to timing.
|
|
6. Press the *Start* button to launch the distributed emulation.
|
|
|
|
|
|
Now when the Start button is used to instantiate the emulation,
|
|
the local CORE Python
|
|
daemon will connect to other emulation servers that have been assigned to nodes.
|
|
Each server will have its own session directory where the :file:`platform.xml`
|
|
file and other EMANE XML files are generated. The NEM IDs are automatically
|
|
coordinated across servers so there is no overlap. Each server also gets its
|
|
own Platform ID.
|
|
|
|
An Ethernet device is used for disseminating multicast EMANE events, as specified in the
|
|
*configure emane* dialog. EMANE's Event Service can be run with mobility or pathloss scripts
|
|
as described in :ref:`Single_PC_with_EMANE`. If CORE is not subscribed to location events, it
|
|
will generate them as nodes are moved on the canvas.
|
|
|
|
Double-clicking on a node during runtime will cause the GUI to attempt to SSH
|
|
to the emulation server for that node and run an interactive shell. The public
|
|
key SSH configuration should be tested with all emulation servers prior to
|
|
starting the emulation.
|
|
|
|
|
|
.. _distributed_emane_network_diagram:
|
|
|
|
.. figure:: figures/distributed-emane-network.*
|
|
:alt: Distribute EMANE
|
|
:align: center
|
|
:scale: 75%
|
|
|
|
Notional Distributed EMANE Network Diagram
|