@node Emulation

@chapter Emulation

ns-3 has been designed for integration into testbed and virtual machine

environments.  We have addressed this need by providing two kinds of 

net devices.  The first kind, which we call an @code{Emu} @code{NetDevice}

allows ns-3 simulations to send data on a ``real'' network.  The second kind,

called a @code{Tap} @code{NetDevice} allows a ``real'' host to participate 

in an ns-3 simulation as if it were one of the simulated nodes.  An ns-3 

simulation may be constructed with any combination of simulated, @code{Emu}, 

or @code{Tap} devices.

One of the use-cases we want to support is that of a testbed.  A concrete 

example of an environment of this kind is the ORBIT testbed.  ORBIT is a 

laboratory emulator/field trial network arranged as a two dimensional grid of

400 802.11 radio nodes.  We integrate with ORBIT by using their ``imaging'' 

process to load and run ns-3 simulations on the ORBIT array.  We use our

@code{Emu} @code{NetDevice}s to drive the hardware in the testbed and we can

accumulate results either using the ns-3 tracing and logging functions, or the 

native ORBIT data gathering techniques.  See @uref{http://www.orbit-lab.org/} 

for details on the ORBIT testbed.

A simulation of this kind is shown in the following figure:

@float Figure,fig:testbed

@center @caption{Example Implementation of Testbed Emulation.}

@center @image{figures/testbed, 5in}

@end float

You can see that there are separate hosts, each running a subset of a ``global''

simulation.  Instead of an ns-3 channel connecting the hosts, we use real

hardware provided by the testbed.  This allows ns-3 applications and protocol

stacks attached to a simulation node to communicate over real hardware.

We expect the primary use for this configuration will be to generate repeatable

experimental results in a real-world network environment that includes all of 

the ns-3 tracing, logging, visualization and statistics gathering tools.

In what can be viewed as essentially an inverse configuration, we allow ``real'' 

machines running native applications and protocol stacks to integrate with

an ns-3 simulation.  This allows for the simulation of large networks connected

to a real mahince, and also enables virtualization.  A simulation of this kind

is shown in the following figure:

@float Figure,fig:emulated-channel

@caption{Implementation overview of emulated channel.}

@image{figures/emulated-channel, 5in}

@end float

Here, you will see that there is a single host with a number of virtual machines 

running on it.  An ns-3 simulation is shown running in the virtual machine shown

in the center of the figure.  This simulation has a number of nodes with associated 

ns-3 applications and protocol stacks that are talking to an ns-3 channel through 

native simulated ns-3 net devices.

There are also two virtual machines shown at the far left and far right of the 

figure.  These VMs are running native (Linux) applications and protocol stacks.

The VM is connected into the simulation by a Linux Tap net device.  The user-mode

handler for the Tap device is instantiated in the simulation and attached to a 

proxy node that represents the native VM in the simulation.  These handlers allow

the Tap devices on the native VMs to behave as if they were ns-3 net devices in 

the simulation VM.  This, in turn, allows the native software and protocol suites

in the native VMs to believe that they are connected to the simulated ns-3

channel.

We expect the typical use case for this environment will be to analyze the 

behavior of native applications and protocol suites in the presence of large 

simulated ns-3 networks.