ModelNet Installation and Configuration

ModelNet is a network emulation environment that enables experimentation with distributed systems on arbitrary network topologies with realistic propagation delays, bandwidths, drop rates, and queuing. In contrast to other network emulation platforms such as EmuLab or DETER, ModelNet runs entirely on low-cost commodity hardware and operating systems, which allows an investigator to setup their very own ModelNet environment within their research lab. In addition, ModelNet can easily scale to run applications on thousands of virtual end-hosts, which is beyond what is currently possible with Emulab or DETER.

Briefly, ModelNet's system architecture consists of Emulator machines that are responsible for emulating a specified network topology and virtual nodes that run applications on end-hosts within the emulated topology. An emulator runs as a FreeBSD kernel module. Virtual nodes run on Linux machines. More details about ModelNet's design and implementation can be found in Scalability and Accuracy in a Large-Scale Network Emulator published at OSDI '02.

The remainder of this page offers a step-by-step guide to ModelNet installation and configuration. For a high-level introduction to ModelNet, please see the primary ModelNet documentation.

Emulator Setup

Network emulation is handled by a FreeBSD kernel module running on at least one FreeBSD machine. For the purposes of easy explanation, we describe the installation and configuration process for one emulator machine, but the procedure generalizes to arbitrarily many emulator machines.

To install and setup a FreeBSD ModelNet emulator, follow these steps:

FreeBSD 6.3 Install and Kernel Compilation

1. Download the FreeBSD 6.3 ISO images and install on a target machine (cached). Important: Be sure to install FreeBSD 6.3, as ModelNet may not work correctly with other OS versions.
2. Select the Kern-Developer package when prompted to select optional packages to install.
3. When the OS installation is finished, reboot and login as root.
4. The ModelNet developers recommend a minor modification to the FreeBSD kernel to boost the emulator's performance. First, run: sysinstall and select "Configure" --> "Distributions" --> "src" --> "sys." This will install the kernel source code. When finished, exit sysinstall.

   Next, run: cd /sys/i386/conf/

   Add options HZ=10000 to the "GENERIC" file. Save the file and run: config GENERIC

   Run: cd ../compile/GENERIC

   Run: make ; make install

   When the compilation and installation finish, reboot the machine.

   You can check that kern.clockrate is now 10000 HZ by running sysctl kern.clockrate

Download and Install Dependencies

1. Before building the ModelNet kernel module, we need to install its dependencies using FreeBSD's pkg_add package manager. First, point pkg_add to the FreeBSD 6.3 software packages by running:
2. Next, fetch and install the dependencies using:
3. Fetch the Heap and Graph perl libraries using:

Cached dependencies are available here.

Emulator Kernel Module Installation

1. Download the kernel module source code and run tar zxf modelnet-0.99-freebsd-module.tar.gz
2. Run ./configure ; make
3. Once the module is built, you can load it by running: cd module ; kldload ./modelnet.ko

Note: If you are installing and configuring your machine remotely (over SSH or similar), the above kldload command will cause your network connection to break. To remedy this situation, please skip to the next section ("Configure the Emulator's Firewall and Routing Table) and follow the instructions to configure the firewall and routing table. After that, run the kldload command.

You can verify that the emulator module (modelnet.ko) is loaded by running kldstat.

Configure the Emulator's Firewall and Routing Table

ModelNet virtual nodes use the 10.0.0.0/8 address space, so it's necessary to configure the emulator machine to route packets on the 10.0.0.0/8 network to the ModelNet virtual node host(s).

The first step is to configure the firewall.

1. Configure the firewall kernel module (ipfw.ko) to load at boot time. Add the following lines to /etc/rc.conf:
2. Add the following to /usr/local/etc/ipfw.rules:
3. Reboot. Run ipfw list and verify that the firewall rules consist of:

   00100 pipe 1 ip from any to 10.0.0.0/8 in

   00200 pipe 1 udp from any to me dst-port 5347

   00300 allow ip from any to any

   65535 deny ip from any to any

The next step is to setup a static route to the virtual node machine. Note that one could setup arbitrarily many virtual node machines, each with a distinct static route for a portion of the 10.0.0.0/8 network. For the sake of simplicity, we assume a ModelNet deployment with just a single virtual node machine.

1. Run /sbin/route add 10.0.0.0/8 virtual_node_host

You can verify that the static route is configured by running netstat -rn.

Loading a topology

You'll need to create topology files (the .model and .route files) for whatever virtual network you want to emulate. To load them into the ModelNet kernel module, execute:

modelload foo.model foo.route

(Replace foo with the name of your topology in both places, of course.)

Virtual Node Setup

ModelNet virtual nodes are simply end-hosts scattered throughout the virtual topology. These end-hosts may physically run on one (or more) Linux machine(s). Applications run at virtual nodes simply by specifying the desired end-host by its IP address using the LD_PRELOAD environment variable. For example, if you wish to run wget on the virtual host 10.0.0.1, simply run:

LD_PRELOAD=/usr/local/lib/libipaddr.so SRCIP=10.0.0.1 wget URL.

Download and Install Dependencies

The first step to configure the virtual node machine(s) is to install the dependencies.

As root, run apt-get install libboost-graph-dev libxml-simple-perl libxerces-c2-dev libssl-dev

Also, follow the instructions above to install the perl Heap and Graph libraries.

Download and Install ModelNet

Download the patched ModelNet source code. Run ./configure ; cd src ; make ; make install.

Testing the Deployment

The best way to test the deployment is to run applications on a small topology. See the ModelNet documentation to instructions on setting up a small topology.

Other ModelNet Resources

For additional ModelNet setup documentation, see:

• Primary ModelNet documentation
• An excellent ModelNet guide