Since we are, in essence, connecting the inputs and outputs of an ns-3 net device to the inputs and outputs of a Linux Tap net device, we call this arrangement a Tap Bridge.
There are two basic operating modes of this device available to users. Basic functionality is essentially identical, but the two modes are different in details regarding how the arrangement is configured. In the first mode, the configuration is ns-3 configuration-centric. Configuration information is taken from the ns-3 simulation and a tap device matching the ns-3 attributes is created for you. In this mode, which we call LocalDevice mode, an ns-3 net device is made to appear to be directly connected to a real host.
This is illustrated below
* +--------+ * | Linux | * | host | +----------+ * | ------ | | ghost | * | apps | | node | * | ------ | | -------- | * | stack | | IP | +----------+ * | ------ | | stack | | node | * | TAP | |==========| | -------- | * | device | <-- IPC Bridge --> | tap | | IP | * +--------+ | bridge | | stack | * | -------- | | -------- | * | ns-3 | | ns-3 | * | net | | net | * | device | | device | * +----------+ +----------+ * || || * +---------------------------+ * | ns-3 channel | * +---------------------------+ *
In this case, the ns-3 net device in the ghost node appears as if it were actually replacing the TAP device in the Linux host. The ns-3 process creates the TAP device configures the IP address and MAC address of the TAP device to match the values assigned to the ns-3 net device. The IPC link is via the network tap mechanism in the underlying OS and acts as a conventional bridge; but a bridge between devices that happen to have the same shared MAC address.
The LocalDevice mode is the default operating mode of the Tap Bridge.
The second mode, BridgedDevice mode, is more oriented toward allowing existing host configurations. This allows ns-3 net devices to appear as part of a host operating system bridge (in Linux, we make the ns-3 device part of a "brctl" bridge. This mode is especially useful in the case of virtualization where the configuration of the virtual hosts may be dictated by another system and not be changable to suit ns-3. For example, a particular VM scheme may create virtual "vethx" or "vmnetx" devices that appear local to virtual hosts. In order to connect to such systems, one would need to manually create TAP devices on the host system and brigde these TAP devices to the existing (VM) virtual devices. The job of the Tap Bridge in this case is to extend the bridge to join the ns-3 net device.
This is illustrated below:
* +---------+ * | Linux | * | VM | +----------+ * | ------- | | ghost | * | apps | | node | * | ------- | | -------- | * | stack | | IP | +----------+ * | ------- | +--------+ | stack | | node | * | Virtual | | TAP | |==========| | -------- | * | Device | | Device | <-- IPC Bridge-> | tap | | IP | * +---------+ +--------+ | bridge | | stack | * || || | -------- | | -------- | * +--------------------+ | ns-3 | | ns-3 | * | OS (brctl) Bridge | | net | | net | * +--------------------+ | device | | device | * +----------+ +----------+ * || || * +---------------------------+ * | ns-3 channel | * +---------------------------+ *
In this case, a collection of virtual machines with associated Virtual Devices is created in the virtualization environment (for exampe, OpenVZ or VMware). A TAP device (with a specific name) is then manually created for each Virtual Device that will be bridged into the ns-3 simulation. These created TAP devices are then bridged together with the Virtual Devices using a native OS bridge mechanism shown as "OS (brctl) Bridge" in the illustration above.
In the ns-3 simulation, a Tap Bridge is created to match each TAP Device. The name of the TAP Device is assigned to the Tap Bridge using the "DeviceName" attribute. The Tap Bridge then opens a network tap to the TAP Device and logically extends the bridge to encompass the ns-3 net device. This makes it appear as if an ns-3 simulated net device is a member of the "OS (brctl) Bridge" and allows the Virtual Machines to communicate with the ns-3 simulation..
The TapBridge appears to an ns-3 simulation as a channel-less net device. This device must not have an IP address associated with it, but the bridged (ns-3) net device must have an IP adress. Be aware that this is the inverse of an ns-3 BridgeNetDevice (or a conventional bridge in general) which demands that its bridge ports not have IP addresses, but allows the bridge device itself to have an IP address.
The host computer will appear in a simulation as a "ghost" node that contains one TapBridge for each NetDevice that is being bridged. From the perspective of a simulation, the only difference between a ghost node and any other node will be the presence of the TapBridge devices. Note however, that the presence of the TapBridge does affect the connectivity of the net device to the IP stack of the ghost node.
Configuration of address information and the ns-3 devices is not changed in any way if a TapBridge is present. A TapBridge will pick up the addressing information from the ns-3 net device to which it is connected (its "bridged" net device) and use that information to create and configure the TAP device on the real host.
The end result of this is a situation where one can, for example, use the standard ping utility on a real host to ping a simulated ns-3 node. If correct routes are added to the internet host (this is expected to be done automatically in future ns-3 releases), the routing systems in ns-3 will enable correct routing of the packets across simulated ns-3 networks. For an example of this, see the example program, tap-wifi-dumbbell.cc in the ns-3 distribution.
In the other direction, a packet received by the ns-3 net device connected to the Tap Bridge is sent via promiscuous callback to the TapBridge. The TapBridge then takes that packet and writes it back to the host using the network tap mechanism. This write to the device will appear to the Linux host as if a packet has arrived on its device; and therefore as if a packet received by the ns-3 net device has appeared on a Linux net device.
The upshot is that the Tap Bridge appears to bridge a tap device on a Linux host in the "real world" to an ns-3 net device in the simulation. Because the TAP device and the bridged ns-3 net device have the same MAC address and the network tap IPC link is not exernalized, this particular kind of bridge makes ti appear that a ns-3 net device is actually installed in the Linux host.
In order to implement this on the ns-3 side, we need a "ghost node" in the simulation to hold the bridged ns-3 net device and the TapBridge. This node should not actually do anything else in the simulation since its job is simply to make the net device appear in Linux. This is not just arbitrary policy, it is because:
Of course, if you understand all of the issues you can take control of your own destiny and do whatever you want -- we do not actively prevent you from using the ghost node for anything you decide. You will be able to perform typical ns-3 operations on the ghost node if you so desire. The internet stack, for example, must be there and functional on that node in order to participate in IP address assignment and global routing. However, as mentioned above, interfaces talking any Tap Bridge or associated bridged net devices will not work completely. If you understand exactly what you are doing, you can set up other interfaces and devices on the ghost node and use them; or take advantage of the operational send side of the bridged devices to create traffic generators. We generally recommend that you treat this node as a ghost of the Linux host and leave it to itself, though.
The most user-visible difference in modes is how the creation and configuration of the underlying TAP device is done. In LocalDevice mode, both creation and configuration of the underlying TAP device are handled completely by ns-3. In BridgedDevice mode, creation and configuration is delegated (due to requirements) to the user. No configuration is done in ns-3 other than settting the operating mode of the TapBridge to "BridgedDevice" and specifying the name of a pre-configured TAP device using ns-3 Attributes of the TapBridge.
The primary conceptual difference between modes is due to the fact that in BridgedDevice mode the MAC addresses of the user-created TAPs will be pre- configured and will therefore be different than those in the bridged device. As in LocalDevice mode, the Tap Bridge functions as IPC bridge between the TAP device and the ns-3 net device, but in BridgedDevice configurations the two devices will have different MAC addresses and the bridging functionality will be fundamentally the same as in any bridge. Since this implies MAC address spoofing, the only ns-3 devices which may paritcipate in a bridge in BridgedDevice mode must support SendFrom (i.e., a call to the method SupportsSendFrom in the bridged net device must return true).
In the other direction, a packet received by an ns-3 net device is hooked via callback to the TapBridge. This must be done in promiscuous mode since the goal is to bridge the ns-3 net device onto the OS (brctl) bridge of which the TAP device is a part.
There is no functional difference between modes at this level, even though the configuration and conceptual models regarding what is going on are quite different -- the Tap Bridge is just acting like a bridge. In the LocalDevice mode, the bridge is between devices having the same MAC address and in the BridgedDevice model the bridge is between devices having different MAC addresses.
We do, however, have a specific requirement to be able to bridge Virtual Machines onto wireless STA nodes. Unfortunately, the 802.11 spec doesn't provide a good way to implement SendFrom. So we have to work around this.
To this end, we provice the SingleSource mode of the Tap Bridge. This mode allows you to create a bridge as described in BridgedDevice mode, but only allows one source of packets on the Linux side of the bridge. The address on the Linux side is remembered in the Tap Bridge, and all packets coming from the Linux side are repeated out the ns-3 side using the ns-3 device MAC source address. All packets coming in from the ns-3 side are repeated out the Linux side using the remembered MAC address. This allows us to use SendFrom on the ns-3 device side which is available on all ns-3 net devices.