From 3eff196614e82bf3ab303b7f95bf063643d45943 Mon Sep 17 00:00:00 2001 From: Craig Dowell Date: Tue, 17 Mar 2009 16:00:46 -0700 Subject: [PATCH] a little more dox --- src/devices/tap-bridge/tap.h | 182 ++++++++++++++++++++--------------- 1 file changed, 102 insertions(+), 80 deletions(-) diff --git a/src/devices/tap-bridge/tap.h b/src/devices/tap-bridge/tap.h index f3abef4ce..d819061d0 100644 --- a/src/devices/tap-bridge/tap.h +++ b/src/devices/tap-bridge/tap.h @@ -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 *