--- a/src/devices/tap-bridge/tap.h Sat Mar 14 00:54:18 2009 -0700
+++ b/src/devices/tap-bridge/tap.h Tue Mar 17 16:00:46 2009 -0700
@@ -22,9 +22,7 @@
* 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. In LocalDevice mode, configuration of the TAP
- * device is almost completely handled by ns-3. This is useful if you want
- * to use real processes in your host to talk over simulated networks.
+ * connected to a real host.
*
* This is illustrated below
*
@@ -53,23 +51,25 @@
*
* 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
- * 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 bridge; but a bridge
- * between devices that happen to have the same shared MAC address.
+ * 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 the Tap Bridge to be "further bridged" to
- * other existing devices via an existing TAP device. This mode is especially
- * useful in the case of virtualization where the configuration of the virtual
- * hosts may be dictated by an existing system and not easily changed. 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, we need to manually create TAP devices on the host system and brigde
- * these TAP devices to the existing virtual devices. We then need to have a Tap
- * Bridge corresponding created to talk to each of these TAP devices.
+ * 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:
*
@@ -98,17 +98,19 @@
*
* 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 is then created for each Virtual Device that is
- * desired to be bridged into the ns-3 simulation. The 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..
+ * 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 for 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
- * 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..
+ * 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..
*
* \subsection TapBridgeLocalDeviceMode TapBridge LocalDevice Mode
*
@@ -116,15 +118,16 @@
* device appears to the Linux host computer as a network device just like any
* arbitrary "eth0" or "ath0" might appear. The creation and configuration
* of the TAP device is done by the ns-3 simulation and no manual configuration
- * is required. The IP addresses, MAC addresses, gateways, etc., for created
- * TAP devices are extracted from the simulation itself by querying the
- * configuration of the ns-3 device and the TapBridge Attributes.
+ * is required by the user. The IP addresses, MAC addresses, gateways, etc.,
+ * for created TAP devices are extracted from the simulation itself by querying
+ * the configuration of the ns-3 device and the TapBridge Attributes.
*
* 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 which demands that its bridge ports not have IP
- * addresses, but allows the bridge device itself to have an IP address.
+ * 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
@@ -151,32 +154,31 @@
*
* The Tap Bridge lives in a kind of a gray world somewhere between a Linux host
* and an ns-3 bridge device. From the Linux perspective, this code appears as
- * the user mode handler for a TAP net device. In LocalDevice mode, this TAP is
- * automatically created by the ns-3 simulation. When the Linux host writes
- * to one of these /dev/tap devices, the write is redirected into the TapBridge
- * that lives in the ns-3 world; and from this perspective, the packet write on
- * linux becomes a packet read. In other words, a Linux process writes a packet
- * to a tap device and this packet is redirected by the network tap mechanism to
- * an ns-3 process where it is received by the TapBridge as a result of a read
- * operation there. The TapBridge then forwards the packet to the ns-3 net
- * device to which it is bridged; and therefore it appears as if the Linux host
- * sent a packet directly over an ns-3 net device.
+ * the user mode handler for a TAP net device. In LocalDevice mode, this TAP
+ * device is automatically created by the ns-3 simulation. When the Linux host
+ * writes to one of these automatically created /dev/tap devices, the write is
+ * redirected into the TapBridge that lives in the ns-3 world; and from this
+ * perspective, the packet write on Linux becomes a packet read in the Tap Bridge.
+ * In other words, a Linux process writes a packet to a tap device and this packet
+ * is redirected by the network tap mechanism toan ns-3 process where it is
+ * received by the TapBridge as a result of a read operation there. The TapBridge
+ * then writes the packet to the ns-3 net device to which it is bridged; and
+ * therefore it appears as if the Linux host sent a packet directly through an
+ * ns-3 net device onto an ns-3 network.
*
- * In the other direction, a packet received by an ns-3 net device is bridged
- * (in the ns-3 sense) to the TapBridge. A packet sent to the ns-3 device then
- * appears via a callback in 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 the Linux net device.
+ * 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
- * and make is appear that a ns-3 net device is actually installed in the
- * Linux host. The network tap used as IPC acts as a network bridge between
- * two devices that happen to have the same MAC address. This is okay since
- * the two fact that there are two devices with the same address is not known
- * outside of the pair.
+ * 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
@@ -213,9 +215,9 @@
* \subsection TapBridgeBridgedDeviceMode TapBridge BridgedDevice Mode
*
* In BridgedDevice mode, the TapBridge and its associated ns-3 net device are
- * arranged in a fundamentally similar was as in LocalDevice mode. The bridging
- * functionality is also accomplished in a fundamentally similar way. The
- * previous description applies except as noted below.
+ * arranged in a fundamentally similar was as in LocalDevice mode. The TAP
+ * device is bridged to the ns-3 net device in the same way. The description
+ * of LocalDevice mode applies except as noted below.
*
* The most user-visible difference in modes is how the creation and
* configuration of the underlying TAP device is done. In LocalDevice mode,
@@ -223,41 +225,61 @@
* 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 the pre-configured TAP device,
- * both via ns-3 Attributes of the TapBridge.
+ * "BridgedDevice" and specifying the name of a pre-configured TAP device
+ * using ns-3 Attributes of the TapBridge.
*
- * The primary difference between modes is due to the fact that in BridgedDevice
- * mode the MAC addresses of the 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.
+ * 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).
*
* \subsection TapBridgeBridgedDeviceModeOperation TapBridge BridgedDevice Mode Operation
*
* As described in the LocalDevice mode section, when the Linux host writes to
* one of the /dev/tap devices, the write is redirected into the TapBridge
- * that lives in the ns-3 world; and from this perspective, the packet write on
- * linux becomes a packet read. The packet at this point will contain a MAC
- * source address corresponding to the address of the TAP device. Before this
- * packet is sent to the bridged ns-3 net device, the MAC headers are stripped
- * off. When the bridged net device actually executes the send, it will replace
- * the MAC headers with its own.
+ * that lives in the ns-3 world. In the case of the BridgedDevice mode, these
+ * packets will need to be sent out on the ns-3 network as if they were sent on
+ * the Linux network. This means calling the SendFrom method on the bridged
+ * device and providing the source and destination MAC addresses found in the
+ * packet.
*
- * In the other direction, a packet received by an ns-3 net device is bridged
- * (in the ns-3 sense) to the TapBridge. A packet sent to the ns-3 device then
- * appears via a callback in the TapBridge. At this point, there is no MAC
- * addressing information on the packet. In LocalDevice mode, the TapBridge
- * adds back the MAC address that it found in the ns-3 bridged net device
- * configuration. In the BridgedDevice mode, it needs to add back the MAC
- * address of the TAP device.
+ * 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 a bridge. In the LocalDevice model, the
- * bridge is between devices having the same MAC address and in the
+ * 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.
+ *
+ * \subsection TapBridgeSingleSourceModeOperation TapBridge SingleSource Mode Operation
+ *
+ * As described in above, the Tap Bridge acts like a bridge. Just like every
+ * other bridge, there is a requirement that participating devices must have
+ * the ability to receive promiscuously and to spoof the source MAC addresses
+ * of packets.
+ *
+ * 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.
*
* \section TapBridgeChannelModel Tap Bridge Channel Model
*