[Ns-developers] Request for Design Review -- Tap Bridge Net Device

[craigdo@ee.washington.edu]

Dear All,

As many of you know, I have been working on features for integrating real-time simulation and emulation into ns-3.  I have
previously integrated a real-time simulator and a net device that allows a simulation to send packets over real networks -- the emu
device feature.  The final piece to this puzzle is the inverse -- the ability for real hosts to send packets over simulated
networks.  This is called the tap bridge.

The Tap Bridge is now ready for review.  I am requesting that this new feature be added to ns-3.4.  Even though the new feature
deadline has passed, Raj has agreed to accept this feature for review and inclusion in ns-3.4 if it doesn't cause too many problems.

The code may be found in http://code.nsnam.org/craigdo/ns-3-tap.

This feature allows you to connect an ns-3 net device to a "real" Linux host, and have the host treat the ns-3 device and associated
network as if it were real.  In the following illustration, you will see that a tap device is created on a host computer (in this
case it is called /dev/blah, but the name is programmable via Attribute).  This device causes the ns-3 device on node n0 to appear
as a network device on the host.  The simulated CSMA network then appears as if were a real network connected to the host.

  +----------+
  |   Real   |
  | Internet |
  |   Host   |
  |          |
  |/dev/blah |
  +----------+
       |           n0             n3
       |       +--------+     +--------+
       +-------|  tap   |     |  tap   |
               | bridge | ... | bridge |
               +--------+     +--------+
               |  CSMA  |     |  CSMA  |
               +--------+     +--------+
                   |              |
                   |              |
                   |    n1  n2    |
                   |     |   |    |
                   ================

You can, for example, run "ping" on your host computer and directly ping one of the nodes on the CSMA network.  For more detail and
an example using internet routing, Wifi and CSMA, see the example file examples/tap-wifi-dumbbell.cc and the "activities" listed in
the topology section of the file under "Some simple things to do."

There are no regression tests provided with this feature since everything is passive, waiting for an external internet host to drive
the bridge and the associated networks.  The provided example program runs for one minute waiting for packets from the internet
host.

Caveats:

ns-3 internetwork routing is not completely integrated, as the routing table code is currently in flux.  Routes must currently be
manually added in the host.  Future work may include automatically managing routes on the host as routes in the ghost node (n0 in
the illustration above) change.

There is no attempt to "address" Ipv6 in this version.  As the ns-3 v6 story settles out, this can be easily added.

There is no attempt to deal with MTU across the system boundaries as the ns-3 MTU story is not yet fully cooked.

---------- Added files ----------

- examples/csma-tap-wifi-dumbbelle.cc is an example file showing how to create a dumbbell network with one side implemented using a
CSMA network and the other side using a wifi network.  There is background CBR traffic flowing over the point-to-point of the
dumbbell.  The tap device on the linux host is bridged to the wifi access point on the wifi network.  There are "activities" listed
in the file showing how one would use ping on the Linux host to ping wifi nodes in the simulation and CSMA nodes across the
simulated point-to-point link using ns-3 global routing.

- src/devices/tap-bridge/tap.h is a description of the net device implementing the bridge.

- src/devices/tap-bridge/tap-bridge.h is the header file for the tap bridge, which is implemented as an ns-3 net device.

- src/devices/tap-bridge/tap-bridge.cc is the implementation of the tap bridge net device.

- src/devices/tap-bridge/tap-creator.cc is a program that runs as root and is responsible for creating and setting up the tap
device.

- src/devices/tap-bridge/tap-encode-decode.h is a header file describing a mechanism to pass binary data between the tap-creator and
the tap-bridge.

- src/devices/tap-bridge/tap-encode-decode.cc is the implementation of this mechanism.

- src/helper/tap-bridge-helper.cc is the helper used in scripts to make life easy for people using the tap bridge.

- src/helper/tap-bridge-helper.h is the header file for the helper.

---------- Changed files ----------

- various wscript files to enable building all of the pieces of the bridge and also to treat the --enable-sudo option in waf to be a
configure-time option.

- src/devices/csma/csma-net-device.cc is changed to allow a given net device to receive DIX or LLC/SNAP packets independent of the
choice of framing.  This is required since other devices in the "real world" won't be observing an ns-3 internal configuration item.

- src/internet-stack/arp-header.cc was changed to read all of the size items in an ARP packet and return an error if the sizes are
unexpected.

- src/internet-stack/arp-l3-protocol.cc was changed to check for errors from the ARP header deserialize.

Regards,

-- Craig