51 * +---------------------------+ |
49 * +---------------------------+ |
52 *\endverbatim |
50 *\endverbatim |
53 * |
51 * |
54 * In this case, the ns-3 net device in the ghost node appears as if it were |
52 * In this case, the ns-3 net device in the ghost node appears as if it were |
55 * actually replacing the TAP device in the Linux host. The ns-3 process |
53 * actually replacing the TAP device in the Linux host. The ns-3 process |
56 * configures the IP address and MAC address of the TAP device to match the |
54 * creates the TAP device configures the IP address and MAC address of the |
57 * values assigned to the ns-3 net device. The IPC link is via the network |
55 * TAP device to match the values assigned to the ns-3 net device. The IPC |
58 * tap mechanism in the underlying OS and acts as a bridge; but a bridge |
56 * link is via the network tap mechanism in the underlying OS and acts as a |
59 * between devices that happen to have the same shared MAC address. |
57 * conventional bridge; but a bridge between devices that happen to have the |
|
58 * same shared MAC address. |
60 * |
59 * |
61 * The LocalDevice mode is the default operating mode of the Tap Bridge. |
60 * The LocalDevice mode is the default operating mode of the Tap Bridge. |
62 * |
61 * |
63 * The second mode, BridgedDevice mode, is more oriented toward allowing existing |
62 * The second mode, BridgedDevice mode, is more oriented toward allowing existing |
64 * host configurations. This allows the Tap Bridge to be "further bridged" to |
63 * host configurations. This allows ns-3 net devices to appear as part of a host |
65 * other existing devices via an existing TAP device. This mode is especially |
64 * operating system bridge (in Linux, we make the ns-3 device part of a "brctl" |
66 * useful in the case of virtualization where the configuration of the virtual |
65 * bridge. This mode is especially useful in the case of virtualization where |
67 * hosts may be dictated by an existing system and not easily changed. For |
66 * the configuration of the virtual hosts may be dictated by another system and |
68 * example, a particular VM scheme may create virtual "vethx" or "vmnetx" |
67 * not be changable to suit ns-3. For example, a particular VM scheme may create |
69 * devices that appear local to virtual hosts. In order to connect to such |
68 * virtual "vethx" or "vmnetx" devices that appear local to virtual hosts. In |
70 * systems, we need to manually create TAP devices on the host system and brigde |
69 * order to connect to such systems, one would need to manually create TAP devices |
71 * these TAP devices to the existing virtual devices. We then need to have a Tap |
70 * on the host system and brigde these TAP devices to the existing (VM) virtual |
72 * Bridge corresponding created to talk to each of these TAP devices. |
71 * devices. The job of the Tap Bridge in this case is to extend the bridge to |
|
72 * join the ns-3 net device. |
73 * |
73 * |
74 * This is illustrated below: |
74 * This is illustrated below: |
75 * |
75 * |
76 * \verbatim |
76 * \verbatim |
77 * +---------+ |
77 * +---------+ |
96 * +---------------------------+ |
96 * +---------------------------+ |
97 *\endverbatim |
97 *\endverbatim |
98 * |
98 * |
99 * In this case, a collection of virtual machines with associated Virtual |
99 * In this case, a collection of virtual machines with associated Virtual |
100 * Devices is created in the virtualization environment (for exampe, OpenVZ |
100 * Devices is created in the virtualization environment (for exampe, OpenVZ |
101 * or VMware). A TAP device is then created for each Virtual Device that is |
101 * or VMware). A TAP device (with a specific name) is then manually created |
102 * desired to be bridged into the ns-3 simulation. The created TAP devices are |
102 * for each Virtual Device that will be bridged into the ns-3 simulation. |
103 * then bridged together with the Virtual Devices using a native OS bridge |
103 * These created TAP devices are then bridged together with the Virtual Devices |
104 * mechanism shown as "OS (brctl) Bridge" in the illustration above.. |
104 * using a native OS bridge mechanism shown as "OS (brctl) Bridge" in the |
105 * |
105 * illustration above. |
106 * In the ns-3 simulation a Tap Bridge is created for each TAP Device. The |
106 * |
107 * name of the TAP Device is assigned to the Tap Bridge using the "DeviceName" |
107 * In the ns-3 simulation, a Tap Bridge is created to match each TAP Device. |
108 * attribute. The Tap Bridge then opens a network tap to the TAP Device and |
108 * The name of the TAP Device is assigned to the Tap Bridge using the |
109 * extends the bridge to encompass the ns-3 net device. This makes it appear |
109 * "DeviceName" attribute. The Tap Bridge then opens a network tap to the TAP |
110 * as if an ns-3 simulated net device is a member of the "OS (brctl) Bridge" |
110 * Device and logically extends the bridge to encompass the ns-3 net device. |
111 * and allows the Virtual Machines to communicate with the ns-3 simulation.. |
111 * This makes it appear as if an ns-3 simulated net device is a member of the |
|
112 * "OS (brctl) Bridge" and allows the Virtual Machines to communicate with the |
|
113 * ns-3 simulation.. |
112 * |
114 * |
113 * \subsection TapBridgeLocalDeviceMode TapBridge LocalDevice Mode |
115 * \subsection TapBridgeLocalDeviceMode TapBridge LocalDevice Mode |
114 * |
116 * |
115 * In LocalDevice mode, the TapBridge and therefore its associated ns-3 net |
117 * In LocalDevice mode, the TapBridge and therefore its associated ns-3 net |
116 * device appears to the Linux host computer as a network device just like any |
118 * device appears to the Linux host computer as a network device just like any |
117 * arbitrary "eth0" or "ath0" might appear. The creation and configuration |
119 * arbitrary "eth0" or "ath0" might appear. The creation and configuration |
118 * of the TAP device is done by the ns-3 simulation and no manual configuration |
120 * of the TAP device is done by the ns-3 simulation and no manual configuration |
119 * is required. The IP addresses, MAC addresses, gateways, etc., for created |
121 * is required by the user. The IP addresses, MAC addresses, gateways, etc., |
120 * TAP devices are extracted from the simulation itself by querying the |
122 * for created TAP devices are extracted from the simulation itself by querying |
121 * configuration of the ns-3 device and the TapBridge Attributes. |
123 * the configuration of the ns-3 device and the TapBridge Attributes. |
122 * |
124 * |
123 * The TapBridge appears to an ns-3 simulation as a channel-less net device. |
125 * The TapBridge appears to an ns-3 simulation as a channel-less net device. |
124 * This device must not have an IP address associated with it, but the bridged |
126 * This device must not have an IP address associated with it, but the bridged |
125 * (ns-3) net device must have an IP adress. Be aware that this is the inverse |
127 * (ns-3) net device must have an IP adress. Be aware that this is the inverse |
126 * of an ns-3 BridgeNetDevice which demands that its bridge ports not have IP |
128 * of an ns-3 BridgeNetDevice (or a conventional bridge in general) which |
127 * addresses, but allows the bridge device itself to have an IP address. |
129 * demands that its bridge ports not have IP addresses, but allows the bridge |
|
130 * device itself to have an IP address. |
128 * |
131 * |
129 * The host computer will appear in a simulation as a "ghost" node that contains |
132 * The host computer will appear in a simulation as a "ghost" node that contains |
130 * one TapBridge for each NetDevice that is being bridged. From the perspective |
133 * one TapBridge for each NetDevice that is being bridged. From the perspective |
131 * of a simulation, the only difference between a ghost node and any other node |
134 * of a simulation, the only difference between a ghost node and any other node |
132 * will be the presence of the TapBridge devices. Note however, that the |
135 * will be the presence of the TapBridge devices. Note however, that the |
149 * |
152 * |
150 * \subsection TapBridgeLocalDeviceModeOperation TapBridge LocalDevice Mode Operation |
153 * \subsection TapBridgeLocalDeviceModeOperation TapBridge LocalDevice Mode Operation |
151 * |
154 * |
152 * The Tap Bridge lives in a kind of a gray world somewhere between a Linux host |
155 * The Tap Bridge lives in a kind of a gray world somewhere between a Linux host |
153 * and an ns-3 bridge device. From the Linux perspective, this code appears as |
156 * and an ns-3 bridge device. From the Linux perspective, this code appears as |
154 * the user mode handler for a TAP net device. In LocalDevice mode, this TAP is |
157 * the user mode handler for a TAP net device. In LocalDevice mode, this TAP |
155 * automatically created by the ns-3 simulation. When the Linux host writes |
158 * device is automatically created by the ns-3 simulation. When the Linux host |
156 * to one of these /dev/tap devices, the write is redirected into the TapBridge |
159 * writes to one of these automatically created /dev/tap devices, the write is |
157 * that lives in the ns-3 world; and from this perspective, the packet write on |
160 * redirected into the TapBridge that lives in the ns-3 world; and from this |
158 * linux becomes a packet read. In other words, a Linux process writes a packet |
161 * perspective, the packet write on Linux becomes a packet read in the Tap Bridge. |
159 * to a tap device and this packet is redirected by the network tap mechanism to |
162 * In other words, a Linux process writes a packet to a tap device and this packet |
160 * an ns-3 process where it is received by the TapBridge as a result of a read |
163 * is redirected by the network tap mechanism toan ns-3 process where it is |
161 * operation there. The TapBridge then forwards the packet to the ns-3 net |
164 * received by the TapBridge as a result of a read operation there. The TapBridge |
162 * device to which it is bridged; and therefore it appears as if the Linux host |
165 * then writes the packet to the ns-3 net device to which it is bridged; and |
163 * sent a packet directly over an ns-3 net device. |
166 * therefore it appears as if the Linux host sent a packet directly through an |
164 * |
167 * ns-3 net device onto an ns-3 network. |
165 * In the other direction, a packet received by an ns-3 net device is bridged |
168 * |
166 * (in the ns-3 sense) to the TapBridge. A packet sent to the ns-3 device then |
169 * In the other direction, a packet received by the ns-3 net device connected to |
167 * appears via a callback in the TapBridge. The TapBridge then takes that |
170 * the Tap Bridge is sent via promiscuous callback to the TapBridge. The |
168 * packet and writes it back to the host using the network tap mechanism. This |
171 * TapBridge then takes that packet and writes it back to the host using the |
169 * write to the device will appear to the Linux host as if a packet has arrived |
172 * network tap mechanism. This write to the device will appear to the Linux |
170 * on its device; and therefore as if a packet received by the ns-3 net device |
173 * host as if a packet has arrived on its device; and therefore as if a packet |
171 * has appeared on the Linux net device. |
174 * received by the ns-3 net device has appeared on a Linux net device. |
172 * |
175 * |
173 * The upshot is that the Tap Bridge appears to bridge a tap device on a |
176 * The upshot is that the Tap Bridge appears to bridge a tap device on a |
174 * Linux host in the "real world" to an ns-3 net device in the simulation |
177 * Linux host in the "real world" to an ns-3 net device in the simulation. |
175 * and make is appear that a ns-3 net device is actually installed in the |
178 * Because the TAP device and the bridged ns-3 net device have the same MAC |
176 * Linux host. The network tap used as IPC acts as a network bridge between |
179 * address and the network tap IPC link is not exernalized, this particular |
177 * two devices that happen to have the same MAC address. This is okay since |
180 * kind of bridge makes ti appear that a ns-3 net device is actually installed |
178 * the two fact that there are two devices with the same address is not known |
181 * in the Linux host. |
179 * outside of the pair. |
|
180 * |
182 * |
181 * In order to implement this on the ns-3 side, we need a "ghost node" in the |
183 * In order to implement this on the ns-3 side, we need a "ghost node" in the |
182 * simulation to hold the bridged ns-3 net device and the TapBridge. This node |
184 * simulation to hold the bridged ns-3 net device and the TapBridge. This node |
183 * should not actually do anything else in the simulation since its job is |
185 * should not actually do anything else in the simulation since its job is |
184 * simply to make the net device appear in Linux. This is not just arbitrary |
186 * simply to make the net device appear in Linux. This is not just arbitrary |
211 * itself, though. |
213 * itself, though. |
212 * |
214 * |
213 * \subsection TapBridgeBridgedDeviceMode TapBridge BridgedDevice Mode |
215 * \subsection TapBridgeBridgedDeviceMode TapBridge BridgedDevice Mode |
214 * |
216 * |
215 * In BridgedDevice mode, the TapBridge and its associated ns-3 net device are |
217 * In BridgedDevice mode, the TapBridge and its associated ns-3 net device are |
216 * arranged in a fundamentally similar was as in LocalDevice mode. The bridging |
218 * arranged in a fundamentally similar was as in LocalDevice mode. The TAP |
217 * functionality is also accomplished in a fundamentally similar way. The |
219 * device is bridged to the ns-3 net device in the same way. The description |
218 * previous description applies except as noted below. |
220 * of LocalDevice mode applies except as noted below. |
219 * |
221 * |
220 * The most user-visible difference in modes is how the creation and |
222 * The most user-visible difference in modes is how the creation and |
221 * configuration of the underlying TAP device is done. In LocalDevice mode, |
223 * configuration of the underlying TAP device is done. In LocalDevice mode, |
222 * both creation and configuration of the underlying TAP device are handled |
224 * both creation and configuration of the underlying TAP device are handled |
223 * completely by ns-3. In BridgedDevice mode, creation and configuration is |
225 * completely by ns-3. In BridgedDevice mode, creation and configuration is |
224 * delegated (due to requirements) to the user. No configuration is done in |
226 * delegated (due to requirements) to the user. No configuration is done in |
225 * ns-3 other than settting the operating mode of the TapBridge to |
227 * ns-3 other than settting the operating mode of the TapBridge to |
226 * "BridgedDevice" and specifying the name of the pre-configured TAP device, |
228 * "BridgedDevice" and specifying the name of a pre-configured TAP device |
227 * both via ns-3 Attributes of the TapBridge. |
229 * using ns-3 Attributes of the TapBridge. |
228 * |
230 * |
229 * The primary difference between modes is due to the fact that in BridgedDevice |
231 * The primary conceptual difference between modes is due to the fact that in |
230 * mode the MAC addresses of the TAPs will be pre-configured and will therefore |
232 * BridgedDevice mode the MAC addresses of the user-created TAPs will be pre- |
231 * be different than those in the bridged device. As in LocalDevice mode, the |
233 * configured and will therefore be different than those in the bridged device. |
232 * Tap Bridge functions as IPC bridge between the TAP device and the ns-3 net |
234 * As in LocalDevice mode, the Tap Bridge functions as IPC bridge between the |
233 * device, but in BridgedDevice configurations the two devices will have |
235 * TAP device and the ns-3 net device, but in BridgedDevice configurations the |
234 * different MAC addresses. |
236 * two devices will have different MAC addresses and the bridging functionality |
|
237 * will be fundamentally the same as in any bridge. Since this implies MAC |
|
238 * address spoofing, the only ns-3 devices which may paritcipate in a bridge |
|
239 * in BridgedDevice mode must support SendFrom (i.e., a call to the method |
|
240 * SupportsSendFrom in the bridged net device must return true). |
235 * |
241 * |
236 * \subsection TapBridgeBridgedDeviceModeOperation TapBridge BridgedDevice Mode Operation |
242 * \subsection TapBridgeBridgedDeviceModeOperation TapBridge BridgedDevice Mode Operation |
237 * |
243 * |
238 * As described in the LocalDevice mode section, when the Linux host writes to |
244 * As described in the LocalDevice mode section, when the Linux host writes to |
239 * one of the /dev/tap devices, the write is redirected into the TapBridge |
245 * one of the /dev/tap devices, the write is redirected into the TapBridge |
240 * that lives in the ns-3 world; and from this perspective, the packet write on |
246 * that lives in the ns-3 world. In the case of the BridgedDevice mode, these |
241 * linux becomes a packet read. The packet at this point will contain a MAC |
247 * packets will need to be sent out on the ns-3 network as if they were sent on |
242 * source address corresponding to the address of the TAP device. Before this |
248 * the Linux network. This means calling the SendFrom method on the bridged |
243 * packet is sent to the bridged ns-3 net device, the MAC headers are stripped |
249 * device and providing the source and destination MAC addresses found in the |
244 * off. When the bridged net device actually executes the send, it will replace |
250 * packet. |
245 * the MAC headers with its own. |
251 * |
246 * |
252 * In the other direction, a packet received by an ns-3 net device is hooked |
247 * In the other direction, a packet received by an ns-3 net device is bridged |
253 * via callback to the TapBridge. This must be done in promiscuous mode since |
248 * (in the ns-3 sense) to the TapBridge. A packet sent to the ns-3 device then |
254 * the goal is to bridge the ns-3 net device onto the OS (brctl) bridge of |
249 * appears via a callback in the TapBridge. At this point, there is no MAC |
255 * which the TAP device is a part. |
250 * addressing information on the packet. In LocalDevice mode, the TapBridge |
|
251 * adds back the MAC address that it found in the ns-3 bridged net device |
|
252 * configuration. In the BridgedDevice mode, it needs to add back the MAC |
|
253 * address of the TAP device. |
|
254 * |
256 * |
255 * There is no functional difference between modes at this level, even though |
257 * There is no functional difference between modes at this level, even though |
256 * the configuration and conceptual models regarding what is going on are quite |
258 * the configuration and conceptual models regarding what is going on are quite |
257 * different -- the Tap Bridge is just a bridge. In the LocalDevice model, the |
259 * different -- the Tap Bridge is just acting like a bridge. In the LocalDevice |
258 * bridge is between devices having the same MAC address and in the |
260 * mode, the bridge is between devices having the same MAC address and in the |
259 * BridgedDevice model the bridge is between devices having different MAC |
261 * BridgedDevice model the bridge is between devices having different MAC |
260 * addresses. |
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. |
261 * |
283 * |
262 * \section TapBridgeChannelModel Tap Bridge Channel Model |
284 * \section TapBridgeChannelModel Tap Bridge Channel Model |
263 * |
285 * |
264 * There is no channel model associated with the Tap Bridge. In fact, the |
286 * There is no channel model associated with the Tap Bridge. In fact, the |
265 * intention is make it appear that the real internet host is connected to |
287 * intention is make it appear that the real internet host is connected to |