--- a/src/devices/tap-bridge/tap.h Tue Jan 05 12:27:50 2010 -0800
+++ b/src/devices/tap-bridge/tap.h Tue Jan 05 18:06:05 2010 -0800
@@ -9,22 +9,91 @@
* goal is to make it appear to a "real" host node in that it has an ns-3 net
* device as a local device. The concept of a "real host" is a bit slippery
* since the "real host" may actually be virtualized using readily avialable
- * technologies such as VMware or OpenVZ.
+ * technologies such as VMware, VirtualBox or OpenVZ.
*
* 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.
+ * There are three basic operating modes of this device available to users.
+ * Basic functionality is essentially identical, but the modes are different
+ * in details regarding how the arrangement is created and configured;
+ * and what devices can live on which side of the bridge.
+ *
+ * We call these three modes the ConfigureLocal, UseLocal and UseBridge modes.
+ * The first "word" in the camel case mode identifier indicates who has the
+ * responsibility for creating and configuring the taps. For example,
+ * the "Configure" in ConfigureLocal mode indicates that it is the TapBridge
+ * that has responsibility for configuring the tap. In UseLocal mode and
+ * UseBridge modes, the "Use" prefix indicates that the TapBridge is asked to
+ * "Use" an existing configuration.
+ *
+ * In other words, in ConfigureLocal mode, the TapBridge has the responsibility
+ * for creating and configuring the TAP devices. In UseBridge or UseLocal
+ * modes, the user provides a configuration and the TapBridge adapts to that
+ * configuration.
+ *
+ * \subsection TapBridgeConfigureLocalMode TapBridge ConfigureLocal Mode
+ *
+ * In the ConfigureLocal mode, the configuration of the tap device is ns-3
+ * configuration-centric. Configuration information is taken from a device
+ * in the ns-3 simulation and a tap device matching the ns-3 attributes is
+ * automatically created. In this case, a Linux computer is made to appear as
+ * if it was directly connected to a simulated ns-3 network.
*
- * This is illustrated below
+ * This is illustrated below:
+ *
+ * \verbatim
+ * +--------+
+ * | Linux |
+ * | host | +----------+
+ * | ------ | | ghost |
+ * | apps | | node |
+ * | ------ | | -------- |
+ * | stack | | IP | +----------+
+ * | ------ | | stack | | node |
+ * | TAP | |==========| | -------- |
+ * | device | <----- IPC ------> | tap | | IP |
+ * +--------+ | bridge | | stack |
+ * | -------- | | -------- |
+ * | ns-3 | | ns-3 |
+ * | net | | net |
+ * | device | | device |
+ * +----------+ +----------+
+ * || ||
+ * +---------------------------+
+ * | ns-3 channel |
+ * +---------------------------+
+ * \endverbatim
+ *
+ * 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
+ * simulation creates the TAP device on the underlying Linux OS and configures
+ * the IP and MAC addresses of the TAP device to match the values assigned to
+ * the simulated ns-3 net device. The "IPC" link shown above is the network
+ * tap mechanism in the underlying OS. The whole arrangement acts as a
+ * conventional bridge; but a bridge between devices that happen to have the
+ * same shared MAC and IP addresses.
+ *
+ * Here, the user is not required to provide any configuration information
+ * specific to the tap. A tap device will be created and configured by ns-3
+ * according to its defaults, and the tap device will have its name assigned
+ * by the underlying operating system according to its defaults.
+ *
+ * If the user has a requirement to access the created tap device, he or she
+ * may optionally provide a "DeviceName" attribute. In this case, the created
+ * OS tap device will be named accordingly.
+ *
+ * The ConfigureLocal mode is the default operating mode of the Tap Bridge.
+ *
+ * \subsection TapBridgeUseLocalMode TapBridge UseLocal Mode
+ *
+ * The UseLocal mode is quite similar to the ConfigureLocal mode. The
+ * significant difference is, as the mode name implies, the TapBridge is
+ * going to "Use" an existing tap device previously created and configured
+ * by the user. This mode is particularly useful when a virtualization
+ * scheme automatically creates tap devices and ns-3 is used to provide
+ * simulated networks for those devices.
*
* \verbatim
* +--------+
@@ -36,12 +105,13 @@
* | stack | | IP | +----------+
* | ------ | | stack | | node |
* | TAP | |==========| | -------- |
- * | device | <-- IPC Bridge --> | tap | | IP |
- * +--------+ | bridge | | stack |
- * | -------- | | -------- |
+ * | device | <----- IPC ------> | tap | | IP |
+ * | MAC X | | bridge | | stack |
+ * +--------+ | -------- | | -------- |
* | ns-3 | | ns-3 |
* | net | | net |
* | device | | device |
+ * | MAC Y | | MAC Z |
* +----------+ +----------+
* || ||
* +---------------------------+
@@ -49,41 +119,59 @@
* +---------------------------+
*\endverbatim
*
- * 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.
+ * In this case, the pre-configured MAC address of the "Tap device" (MAC X)
+ * will not be the same as that of the bridged "ns-3 net device" (MAC Y) shown
+ * in the illustration above. In order to bridge to ns-3 net devices which do
+ * not support SendFrom() (especially wireless STA nodes) we impose a requirement
+ * that only one Linux device (with one unique MAC address -- here X) generates
+ * traffic that flows across the IPC link. This is because the MAC addresses of
+ * traffic across the IPC link will be "spoofed" or changed to make it appear to
+ * Linux and ns-3 that they have the same address. That is, traffic moving from
+ * the Linux host to the ns-3 ghost node will have its MAC address changed from
+ * X to Y and traffic from the ghost node to the Linux host will have its MAC
+ * address changed from Y to X. Since there is a one-to-one correspondence
+ * between devices, there may only be one MAC source flowing from the Linux side.
+ * This means that Linux bridges with more than one net device added are
+ * incompatible with UseLocal mode.
*
- * The LocalDevice mode is the default operating mode of the Tap Bridge.
+ * In UseLocal mode, the user is expected to create and configure a tap device
+ * completely outside the scope of the ns-3 simulation using something like:
*
- * 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.
+ * \verbatim
+ * sudo tunctl -t tap0
+ * sudo ifconfig tap0 hw ether 08:00:2e:00:00:01
+ * sudo ifconfig tap0 10.1.1.1 netmask 255.255.255.0 up
+ * \endverbatim
+ *
+ * To tell the TapBridge what is going on, the user will set either directly
+ * into the TapBridge or via the TapBridgeHelper, the "DeviceName" attribute.
+ * In the case of the configuration above, the "DeviceName" attribute would be
+ * set to "tap0" and the "Mode" attribute would be set to "UseLocal".
+ *
+ * One particular use case for this mode is in the OpenVZ environment. There it
+ * is possible to create a Tap device on the "Hardware Node" and move it into a
+ * Virtual Private Server. If the TapBrige is able to use an existing tap device
+ * it is then possible to avoid the overhead of an OS bridge in that environment.
+ *
+ * \subsection TapBridgeUseBridgeMode TapBridge UseBridge Mode
+ *
+ * The simplest mode for those familiar with Linux networking is the UseBridge
+ * mode. Again, the "Use" prefix indicates that the TapBridge is going to Use
+ * an existing configuration. In this case, the TapBridge is going to logically
+ * extend a Linux bridge into ns-3.
*
* This is illustrated below:
*
* \verbatim
* +---------+
- * | Linux |
- * | VM | +----------+
+ * | Linux | +----------+
* | ------- | | ghost |
* | apps | | node |
* | ------- | | -------- |
* | stack | | IP | +----------+
* | ------- | +--------+ | stack | | node |
* | Virtual | | TAP | |==========| | -------- |
- * | Device | | Device | <-- IPC Bridge-> | tap | | IP |
+ * | Device | | Device | <---- IPC -----> | tap | | IP |
* +---------+ +--------+ | bridge | | stack |
* || || | -------- | | -------- |
* +--------------------+ | ns-3 | | ns-3 |
@@ -94,27 +182,55 @@
* +---------------------------+
* | ns-3 channel |
* +---------------------------+
- *\endverbatim
+ * \endverbatim
+ *
+ * In this case, a computer running Linux applications, protocols, etc., is
+ * connected to a ns-3 simulated network in such a way as to make it appear
+ * to the Linux host that the TAP device is a real network device participating
+ * in the Linux bridge.
*
- * 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 TapBridge is created to match each TAP Device.
+ * The name of the TAP Device is assigned to the Tap Bridge using the
+ * "DeviceName" attribute. The TapBridge then logically extends the OS bridge
+ * to encompass the ns-3 net device.
+ *
+ * Since this mode logically extends an OS bridge, there may be many Linux net
+ * devices on the non-ns-3 side of the bridge. Therefore, like a net device on
+ * any bridge, the ns-3 net device must deal with the possibly of many source
+ * addresses. Thus, ns-3 devices must support SendFrom()
+ * (NetDevice::SupportsSendFrom() must return true) in order to be configured
+ * for use in UseBridge mode.
+ *
+ * It is expected that the user will do something like the following to
+ * configure the bridge and tap completely outside ns-3:
*
- * 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..
+ * \verbatim
+ * sudo brctl addbr mybridge
+ * sudo tunctl -t mytap
+ * sudo ifconfig mytap hw ether 00:00:00:00:00:01
+ * sudo ifconfig mytap 0.0.0.0 up
+ * sudo brctl addif mybridge mytap
+ * sudo brctl addif mybridge ...
+ * sudo ifconfig mybridge 10.1.1.1 netmask 255.255.255.0 up
+ * \endverbatim
*
- * \subsection TapBridgeLocalDeviceMode TapBridge LocalDevice Mode
+ * To tell the TapBridge what is going on, the user will set either directly
+ * into the TapBridge or via the TapBridgeHelper, the "DeviceName" attribute.
+ * In the case of the configuration above, the "DeviceName" attribute would be
+ * set to "mytap" and the "Mode" attribute would be set to "UseBridge".
+ *
+ * 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 a ns-3 net device.
+ *
+ * \subsection TapBridgeConfigureLocalOperation TapBridge ConfigureLocal Operation
*
- * In LocalDevice mode, the TapBridge and therefore its associated ns-3 net
+ * In ConfigureLocal mode, the TapBridge and therefore its associated ns-3 net
* 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
@@ -122,6 +238,12 @@
* for created TAP devices are extracted from the simulation itself by querying
* the configuration of the ns-3 device and the TapBridge Attributes.
*
+ * Since the MAC addresses are identical on the Linux side and the ns-3 side,
+ * we can use Send() on the ns-3 device which is available on all ns-3 net devices.
+ * Since the MAC addresses are identical there is no requirement to hook the
+ * promiscuous callback on the receive side. Therefore there are no restrictions
+ * on the kinds of net device that are usable in ConfigureLocal mode.
+
* 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
@@ -150,11 +272,9 @@
* For an example of this, see the example program, tap-wifi-dumbbell.cc in
* the ns-3 distribution.
*
- * \subsection TapBridgeLocalDeviceModeOperation TapBridge LocalDevice Mode Operation
- *
* 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
+ * the user mode handler for a TAP net device. In ConfigureLocal 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
@@ -167,17 +287,18 @@
* ns-3 net device onto an ns-3 network.
*
* 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
+ * the Tap Bridge is sent via a receive 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.
+ * host as if a packet has arrived on a net device; and therefore as if a packet
+ * received by the ns-3 net device during a simulation has appeared on a real
+ * 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
+ * kind of bridge makes it 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
@@ -186,10 +307,10 @@
* simply to make the net device appear in Linux. This is not just arbitrary
* policy, it is because:
*
- * - Bits sent to the Tap Bridge from higher layers in the ghost node (using
- * the TapBridge Send method) are completely ignored. The Tap Bridge is
+ * - Bits sent to the TapBridge from higher layers in the ghost node (using
+ * the TapBridge Send method) are completely ignored. The TapBridge is
* not, itself, connected to any network, neither in Linux nor in ns-3. You
- * can never send nor receive data over a Tap Bridge from the ghost node.
+ * can never send nor receive data over a TapBridge from the ghost node.
*
* - The bridged ns-3 net device has its receive callback disconnected
* from the ns-3 node and reconnected to the Tap Bridge. All data received
@@ -204,7 +325,7 @@
* 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
+ * interfaces talking to any TapBridge 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
@@ -212,75 +333,58 @@
* that you treat this node as a ghost of the Linux host and leave it to
* itself, though.
*
- * \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 TAP
- * device is bridged to the ns-3 net device in the same way. The description
- * of LocalDevice mode applies except as noted below.
+ * \subsection TapBridgeUseLocalOperation TapBridge UseLocal Mode Operation
*
- * 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.
+ * As described in above, the TapBridge acts like a bridge from the "real" world
+ * into the simulated ns-3 world. In the case of the ConfigureLocal mode,
+ * life is easy since the IP address of the Tap device matches the IP address of
+ * the ns-3 device and the MAC address of the Tap device matches the MAC address
+ * of the ns-3 device; and there is a one-to-one relationship between the
+ * devices.
+ *
+ * Things are slightly complicated when a Tap device is externally configured
+ * with a different MAC address than the ns-3 net device. The conventional way
+ * to deal with this kind of difference is to use promiscuous mode in the
+ * bridged device to receive packets destined for the different MAC address and
+ * forward them off to Linux. In order to move packets the other way, the
+ * conventional solution is SendFrom() which allows a caller to "spoof" or change
+ * the source MAC address to match the different Linux MAC address.
*
- * 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).
+ * We do have a specific requirement to be able to bridge Linux 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 that problem.
+ *
+ * To this end, we provided the UseLocal mode of the Tap Bridge. This mode allows
+ * you approach the problem as if you were creating a bridge with a single net
+ * device. A single allowed address on the Linux side is remembered in the
+ * TapBridge, 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 Send() on the ns-3 device side which is
+ * available on all ns-3 net devices.
+ *
+ * UseLocal mode is identical to the ConfigureLocal mode except for the creation
+ * and configuration of the tap device and the MAC address spoofing.
+ *
+ * \subsection TapBridgeUseBridgeOperation TapBridge UseBridge Operation
*
- * \subsection TapBridgeBridgedDeviceModeOperation TapBridge BridgedDevice Mode Operation
- *
- * As described in the LocalDevice mode section, when the Linux host writes to
+ * As described in the ConfigureLocal 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. In the case of the BridgedDevice mode, these
+ * that lives in the ns-3 world. In the case of the UseBridge 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.
+ * a device participating in the Linux bridge. This means calling the
+ * SendFrom() method on the bridged device and providing the source MAC address
+ * found in the packet.
*
* 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.
- *
- * \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.
+ * For these reasons, only ns-3 net devices that support SendFrom() and have a
+ * hookable promiscuous receive callback are allowed to participate in UseBridge
+ * mode TapBridge configurations.
*
- * 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
*
* There is no channel model associated with the Tap Bridge. In fact, the
@@ -294,10 +398,9 @@
* one function call away from the bridged device. We expect that the trace
* hooks in the bridged device will be sufficient for most users,
*
- * \section TapBridgeUsage Using the Tap Bridge
+ * \section TapBridgeUsage Using the TapBridge
*
* We expect that most users will interact with the TapBridge device through
* the TapBridgeHelper. Users of other helper classes, such as CSMA or Wifi,
- * should be comfortable with the idioms used.
+ * should be comfortable with the idioms used there.
*/
-