12  * technologies such as VMware or OpenVZ.

    12  * technologies such as VMware, VirtualBox or OpenVZ.

    18  * There are two basic operating modes of this device available to users.  

    18  * There are three basic operating modes of this device available to users.  

    19  * Basic functionality is essentially identical, but the two modes are 

    19  * Basic functionality is essentially identical, but the modes are different

    20  * different in details regarding how the arrangement is configured.  In the

    20  * in details regarding how the arrangement is created and configured;

    21  * first mode, the configuration is ns-3 configuration-centric.  Configuration

    21  * and what devices can live on which side of the bridge.

    22  * information is taken from the ns-3 simulation and a tap device matching

    22  *

    23  * the ns-3 attributes is created for you.  In this mode, which we call 

    23  * We call these three modes the ConfigureLocal, UseLocal and UseBridge modes.

    24  * LocalDevice mode, an ns-3 net device is made to appear to be directly 

    24  * The first "word" in the camel case mode identifier indicates who has the 

    25  * connected to a real host.  

    25  * responsibility for creating and configuring the taps.  For example,

    26  * 

    26  * the "Configure" in ConfigureLocal mode indicates that it is the TapBridge 

    27  * This is illustrated below

    27  * that has responsibility for configuring the tap.  In UseLocal mode and 

    28  * UseBridge modes, the "Use" prefix indicates that the TapBridge is asked to 

    29  * "Use" an existing configuration.

    30  *

    31  * In other words, in ConfigureLocal mode, the TapBridge has the responsibility

    32  * for creating and configuring the TAP devices.  In UseBridge or UseLocal 

    33  * modes, the user provides a configuration and the TapBridge adapts to that 

    34  * configuration.

    35  *

    36  * \subsection TapBridgeConfigureLocalMode TapBridge ConfigureLocal Mode

    37  *

    38  * In the ConfigureLocal mode, the configuration of the tap device is ns-3 

    39  * configuration-centric.  Configuration information is taken from a device

    40  * in the ns-3 simulation and a tap device matching the ns-3 attributes is 

    41  * automatically created.  In this case, a Linux computer is made to appear as

    42  * if it was directly connected to a simulated ns-3 network.

    43  * 

    44  * This is illustrated below:

    39  *     | device | <-- IPC Bridge --> |   tap    |     |    IP    |

    56  *     | device | <----- IPC ------> |   tap    |     |    IP    |

    52  * In this case, the ns-3 net device in the ghost node appears as if it were 

   122  * In this case, the pre-configured MAC address of the "Tap device" (MAC X)

    53  * actually replacing the TAP device in the Linux host.  The ns-3 process 

   123  * will not be the same as that of the bridged "ns-3 net device" (MAC Y) shown

    54  * creates the TAP device configures the IP address and MAC address of the 

   124  * in the illustration above.  In order to bridge to ns-3 net devices which do

    55  * TAP device to match the values assigned to the ns-3 net device.  The IPC 

   125  * not support SendFrom() (especially wireless STA nodes) we impose a requirement

    56  * link is via the network tap mechanism in the underlying OS and acts as a 

   126  * that only one Linux device (with one unique MAC address -- here X) generates 

    57  * conventional bridge; but a bridge between devices that happen to have the 

   127  * traffic that flows across the IPC link.  This is because the MAC addresses of

    58  * same shared MAC address.

   128  * traffic across the IPC link will be "spoofed" or changed to make it appear to

    59  *

   129  * Linux and ns-3 that they have the same address.  That is, traffic moving from

    60  * The LocalDevice mode is the default operating mode of the Tap Bridge.

   130  * the Linux host to the ns-3 ghost node will have its MAC address changed from 

    61  *

   131  * X to Y and traffic from the ghost node to the Linux host will have its MAC 

    62  * The second mode, BridgedDevice mode, is more oriented toward allowing existing

   132  * address changed from Y to X.  Since there is a one-to-one correspondence 

    63  * host configurations.  This allows ns-3 net devices to appear as part of a host

   133  * between devices, there may only be one MAC source flowing from the Linux side.

    64  * operating system bridge (in Linux, we make the ns-3 device part of a "brctl"

   134  * This means that Linux bridges with more than one net device added are 

    65  * bridge.  This mode is especially  useful in the case of virtualization where 

   135  * incompatible with UseLocal mode.

    66  * the configuration of the virtual hosts may be dictated by another system and 

   136  *

    67  * not be changable to suit ns-3.  For example, a particular VM scheme may create

   137  * In UseLocal mode, the user is expected to create and configure a tap device

    68  * virtual "vethx" or "vmnetx" devices that appear local to virtual hosts.  In 

   138  * completely outside the scope of the ns-3 simulation using something like:

    69  * order to connect to such systems, one would need to manually create TAP devices

   139  *

    70  * on the host system and brigde these TAP devices to the existing (VM) virtual 

   140  * \verbatim

    71  * devices.  The job of the Tap Bridge in this case is to extend the bridge to

   141  *   sudo tunctl -t tap0

    72  * join the ns-3 net device.

   142  *   sudo ifconfig tap0 hw ether 08:00:2e:00:00:01

   143  *   sudo ifconfig tap0 10.1.1.1 netmask 255.255.255.0 up

   144  * \endverbatim

   145  *

   146  * To tell the TapBridge what is going on, the user will set either directly

   147  * into the TapBridge or via the TapBridgeHelper, the "DeviceName" attribute.

   148  * In the case of the configuration above, the "DeviceName" attribute would be 

   149  * set to "tap0" and the "Mode" attribute would be set to "UseLocal".

   150  *

   151  * One particular use case for this mode is in the OpenVZ environment.  There it

   152  * is possible to create a Tap device on the "Hardware Node" and move it into a

   153  * Virtual Private Server.  If the TapBrige is able to use an existing tap device

   154  * it is then possible to avoid the overhead of an OS bridge in that environment.

   155  *

   156  * \subsection TapBridgeUseBridgeMode TapBridge UseBridge Mode

   157  *

   158  * The simplest mode for those familiar with Linux networking is the UseBridge 

   159  * mode.  Again, the "Use" prefix indicates that the TapBridge is going to Use 

   160  * an existing configuration.  In this case, the TapBridge is going to logically

   161  * extend a Linux bridge into ns-3.  

    78  *     |  Linux  |

   167  *     |  Linux  |                             +----------+

    79  *     |   VM    |                             +----------+

    86  *     | Device  | | Device | <-- IPC Bridge-> |   tap    |     |    IP    |

   174  *     | Device  | | Device | <---- IPC -----> |   tap    |     |    IP    |

    97  *\endverbatim

   185  * \endverbatim

    98  *

   186  *

    99  * In this case, a collection of virtual machines with associated Virtual

   187  * In this case, a computer running Linux applications, protocols, etc., is

   100  * Devices is created in the virtualization environment (for exampe, OpenVZ

   188  * connected to a ns-3 simulated network in such a way as to make it appear

   101  * or VMware).  A TAP device (with a specific name) is then manually created 

   189  * to the Linux host that the TAP device is a real network device participating

   102  * for each Virtual Device that will be bridged into the ns-3 simulation.

   190  * in the Linux bridge.

   103  * These created TAP devices are then bridged together with the Virtual Devices

   191  *

   104  * using a native OS bridge mechanism shown as "OS (brctl) Bridge" in the 

   192  * In the ns-3 simulation, a TapBridge is created to match each TAP Device.

   105  * illustration above.

   106  *

   107  * In the ns-3 simulation, a Tap Bridge is created to match each TAP Device.

   109  * "DeviceName" attribute.  The Tap Bridge then opens a network tap to the TAP 

   194  * "DeviceName" attribute.  The TapBridge then logically extends the OS bridge

   110  * Device and logically extends the bridge to encompass the ns-3 net device.  

   195  * to encompass the ns-3 net device.  

   111  * This makes it appear as if an ns-3 simulated net device is a member of the 

   196  *

   112  * "OS (brctl) Bridge" and allows the Virtual Machines to communicate with the 

   197  * Since this mode logically extends an OS bridge, there may be many Linux net 

   113  * ns-3 simulation..

   198  * devices on the non-ns-3 side of the bridge.  Therefore, like a net device on 

   114  *

   199  * any bridge, the ns-3 net device must deal with the possibly of many source 

   115  * \subsection TapBridgeLocalDeviceMode TapBridge LocalDevice Mode

   200  * addresses.  Thus, ns-3 devices must support SendFrom() 

   116  * 

   201  * (NetDevice::SupportsSendFrom() must return true) in order to be configured 

   117  * In LocalDevice mode, the TapBridge and therefore its associated ns-3 net

   202  * for use in UseBridge mode.

   203  *

   204  * It is expected that the user will do something like the following to

   205  * configure the bridge and tap completely outside ns-3:

   206  *

   207  * \verbatim

   208  *   sudo brctl addbr mybridge

   209  *   sudo tunctl -t mytap

   210  *   sudo ifconfig mytap hw ether 00:00:00:00:00:01

   211  *   sudo ifconfig mytap 0.0.0.0 up

   212  *   sudo brctl addif mybridge mytap

   213  *   sudo brctl addif mybridge ...

   214  *   sudo ifconfig mybridge 10.1.1.1 netmask 255.255.255.0 up

   215  * \endverbatim

   216  *

   217  * To tell the TapBridge what is going on, the user will set either directly

   218  * into the TapBridge or via the TapBridgeHelper, the "DeviceName" attribute.

   219  * In the case of the configuration above, the "DeviceName" attribute would be 

   220  * set to "mytap" and the "Mode" attribute would be set to "UseBridge".

   221  *

   222  * This mode is especially  useful in the case of virtualization where the 

   223  * configuration of the virtual hosts may be dictated by another system and 

   224  * not be changable to suit ns-3.  For example, a particular VM scheme may create

   225  * virtual "vethx" or "vmnetx" devices that appear local to virtual hosts.  In 

   226  * order to connect to such systems, one would need to manually create TAP devices

   227  * on the host system and brigde these TAP devices to the existing (VM) virtual 

   228  * devices.  The job of the Tap Bridge in this case is to extend the bridge to

   229  * join a ns-3 net device.

   230  *

   231  * \subsection TapBridgeConfigureLocalOperation TapBridge ConfigureLocal Operation

   232  * 

   233  * In ConfigureLocal mode, the TapBridge and therefore its associated ns-3 net

   157  * the user mode handler for a TAP net device.  In LocalDevice mode, this TAP 

   277  * the user mode handler for a TAP net device.  In ConfigureLocal mode, this Tap 

   170  * the Tap Bridge is sent via promiscuous callback to the TapBridge.  The 

   290  * the Tap Bridge is sent via a receive callback to the TapBridge.  The 

   173  * host as if a packet has arrived on its device; and therefore as if a packet

   293  * host as if a packet has arrived on a net device; and therefore as if a packet

   174  * received by the ns-3 net device has appeared on a Linux net device.

   294  * received by the ns-3 net device during a simulation has appeared on a real 

   295  * Linux net device.

   180  * kind of bridge makes ti appear that a ns-3 net device is actually installed

   301  * kind of bridge makes it appear that a ns-3 net device is actually installed

   189  * - Bits sent to the Tap Bridge from higher layers in the ghost node (using

   310  * - Bits sent to the TapBridge from higher layers in the ghost node (using

   190  *   the TapBridge Send method) are completely ignored.  The Tap Bridge is 

   311  *   the TapBridge Send method) are completely ignored.  The TapBridge is 

   192  *   can never send nor receive data over a Tap Bridge from the ghost node.

   313  *   can never send nor receive data over a TapBridge from the ghost node.

   207  * interfaces talking any Tap Bridge or associated bridged net devices

   328  * interfaces talking to any TapBridge or associated bridged net devices

   215  * \subsection TapBridgeBridgedDeviceMode TapBridge BridgedDevice Mode

   336  * \subsection TapBridgeUseLocalOperation TapBridge UseLocal Mode Operation

   216  * 

   337  *

   217  * In BridgedDevice mode, the TapBridge and its associated ns-3 net device are

   338  * As described in above, the TapBridge acts like a bridge from the "real" world

   218  * arranged in a fundamentally similar was as in LocalDevice mode.  The TAP

   339  * into the simulated ns-3 world.  In the case of the ConfigureLocal mode, 

   219  * device is bridged to the ns-3 net device in the same way.  The description

   340  * life is easy since the IP address of the Tap device matches the IP address of

   220  * of LocalDevice mode applies except as noted below.

   341  * the ns-3 device and the MAC address of the Tap device matches the MAC address

   221  *

   342  * of the ns-3 device; and there is a one-to-one relationship between the 

   222  * The most user-visible difference in modes is how the creation and 

   343  * devices.

   223  * configuration of the underlying TAP device is done.  In LocalDevice mode,

   344  *

   224  * both creation and configuration of the underlying TAP device are handled 

   345  * Things are slightly complicated when a Tap device is externally configured 

   225  * completely by ns-3.  In BridgedDevice mode, creation and configuration is

   346  * with a  different MAC address than the ns-3 net device.  The conventional way

   226  * delegated (due to requirements) to the user.  No configuration is done in

   347  * to deal with this kind of difference is to use promiscuous mode in the 

   227  * ns-3 other than settting the operating mode of the TapBridge to 

   348  * bridged device to receive packets destined for the different MAC address and 

   228  * "BridgedDevice" and specifying the name of a pre-configured TAP device

   349  * forward them off to Linux.  In order to move packets the other way, the 

   229  * using ns-3 Attributes of the TapBridge.

   350  * conventional solution is SendFrom() which allows a caller to "spoof" or change

   230  *

   351  * the source MAC address to match the different Linux MAC address.

   231  * The primary conceptual difference between modes is due to the fact that in 

   352  *

   232  * BridgedDevice mode the MAC addresses of the user-created TAPs will be pre-

   353  * We do have a specific requirement to be able to bridge Linux Virtual Machines

   233  * configured and will therefore be different than those in the bridged device.

   354  * onto wireless STA nodes.  Unfortunately, the 802.11 spec doesn't provide a 

   234  * As in LocalDevice mode, the Tap Bridge functions as IPC bridge between the

   355  * good way to implement SendFrom(), so we have to work around that problem.

   235  * TAP device and the ns-3 net device, but in BridgedDevice configurations the

   356  * 

   236  * two devices will have different MAC addresses and the bridging functionality

   357  * To this end, we provided the UseLocal mode of the Tap Bridge.  This mode allows 

   237  * will be fundamentally the same as in any bridge.  Since this implies MAC

   358  * you approach the problem as if you were creating a bridge with a single net

   238  * address spoofing, the only ns-3 devices which may paritcipate in a bridge

   359  * device.  A single allowed address on the Linux side is remembered in the 

   239  * in BridgedDevice mode must support SendFrom (i.e., a call to the method

   360  * TapBridge, and all packets coming from the Linux side are repeated out the 

   240  * SupportsSendFrom in the bridged net device must return true).

   361  * ns-3 side using the ns-3 device MAC source address.  All packets coming in 

   241  *

   362  * from the ns-3 side are repeated out the Linux side using the remembered MAC 

   242  * \subsection TapBridgeBridgedDeviceModeOperation TapBridge BridgedDevice Mode Operation

   363  * address.  This allows us to use Send() on the ns-3 device side which is 

   243  *

   364  * available on all ns-3 net devices.

   244  * As described in the LocalDevice mode section, when the Linux host writes to 

   365  * 

   366  * UseLocal mode is identical to the ConfigureLocal mode except for the creation

   367  * and configuration of the tap device and the MAC address spoofing.

   368  * 

   369  * \subsection TapBridgeUseBridgeOperation TapBridge UseBridge Operation

   370  *

   371  * As described in the ConfigureLocal mode section, when the Linux host writes to 

   246  * that lives in the ns-3 world.  In the case of the BridgedDevice mode, these

   373  * that lives in the ns-3 world.  In the case of the UseBridge mode, these

   248  * the Linux network.  This means calling the SendFrom method on the bridged

   375  * a device participating in the Linux bridge.  This means calling the 

   249  * device and providing the source and destination MAC addresses found in the

   376  * SendFrom() method on the bridged device and providing the source MAC address

   250  * packet.

   377  * found in the packet.

   257  * There is no functional difference between modes at this level, even though

   384  * For these reasons, only ns-3 net devices that support SendFrom() and have a

   258  * the configuration and conceptual models regarding what is going on are quite

   385  * hookable promiscuous receive callback are allowed to participate in UseBridge

   259  * different -- the Tap Bridge is just acting like a bridge.  In the LocalDevice

   386  * mode TapBridge configurations.

   260  * mode, the bridge is between devices having the same MAC address and in the 

   387  *

   261  * BridgedDevice model the bridge is between devices having different MAC 

   262  * addresses.

   263  *

   264  * \subsection TapBridgeSingleSourceModeOperation TapBridge SingleSource Mode Operation

   265  *

   266  * As described in above, the Tap Bridge acts like a bridge.  Just like every

   267  * other bridge, there is a requirement that participating devices must have

   268  * the ability to receive promiscuously and to spoof the source MAC addresses

   269  * of packets.

   270  *

   271  * We do, however, have a specific requirement to be able to bridge Virtual 

   272  * Machines onto wireless STA nodes.  Unfortunately, the 802.11 spec doesn't

   273  * provide a good way to implement SendFrom.  So we have to work around this.

   274  * 

   275  * To this end, we provice the SingleSource mode of the Tap Bridge.  This

   276  * mode allows you to create a bridge as described in BridgedDevice mode, but

   277  * only allows one source of packets on the Linux side of the bridge.  The

   278  * address on the Linux side is remembered in the Tap Bridge, and all packets

   279  * coming from the Linux side are repeated out the ns-3 side using the ns-3 device

   280  * MAC source address.  All packets coming in from the ns-3 side are repeated

   281  * out the Linux side using the remembered MAC address.  This allows us to use

   282  * SendFrom on the ns-3 device side which is available on all ns-3 net devices.

   283  * 

   297  * \section TapBridgeUsage Using the Tap Bridge

   401  * \section TapBridgeUsage Using the TapBridge

   301  * should be comfortable with the idioms used.

   405  * should be comfortable with the idioms used there.