OpenRoads (n-casting) clients

From OpenFlow Wiki

Contents 1 Background 2 Requirements 2.1 Hardware 2.2 Software 3 Setting up 3.1 Get code 3.2 Custom Kernel 3.2.1 Install packages with apt-get 3.2.2 Extract kernel source code 3.2.3 Configure the source code 3.2.4 Compile custom kernel 3.2.5 Install custom kernel 3.3 Client programs 3.3.1 Madwifi driver 3.3.2 Hoolock 3.3.3 n-casting 4 Running the client 5 References

Background

Hoolock and n-casting showcase how different experiments can be performed on the OpenRoads platform. This page contains instructions on how to set up a Ubuntu 8.10 client to support these two handover techniques.

Requirements

Hardware

At least two wireless adapters are needed. Hoolock has been tested only between two adapters, but the code is written to be generalizable to many adapters. Important: Look for adapters that obey MAC-rewrite commands from the Linux kernel. Some chips (e.g., Atheros chips) will use its burned-in MAC address in control packets even if the kernel specifies another MAC address for the interface. Intel chipsets seem to be safe in this regard. In any case, you can have at most one adapter that does not do MAC rewrite, and use this adapter's address for all other interfaces. More details below in the section about bonding driver.

The machines used were Dell Latitude E5400's with an internal Intel wireless chipset and a D-Link card (WNA-2330) with an Atheros chip.

Software

The software has been tested under kernel 2.6.27 with Ubuntu 8.10. We have not tested all the code for every possible minor revision of 2.6. Ubuntu 8.10 is strongly recommended for the provided code. "sudo" rights are required for kernel recompilation.

Setting up

Installing all the client-side code is separated into three main parts

1. Get files from the (open) code repository - a simple operation of svn (will be moved to git soon)
2. Recompile kernel - Move some files, recompile kernel, install kernel
3. Install client programs - Run a makefile with sudo

Get code

First, install some tools for obtaining the source code.

sudo apt-get install git-core # for accessing the OpenRoads repository
sudo apt-get install subversion # for accessing madwifi source

Second, get client code:

git clone git://gitosis.stanford.edu/multiinterfaceclient.git <target directory>

Finally, retrieve the MadWifi driver source code for the Atheros chip:

svn checkout http://svn.madwifi-project.org/madwifi/trunk <target directory>

Custom Kernel

Hoolock code makes some changes to the kernel source in addition to modifying the bonding driver code. As a result, a custom kernel is required.

Install packages with apt-get

sudo apt-get install build-essential fakeroot makedumpfile libncurses5 libncurses5-dev
sudo apt-get build-dep linux
sudo apt-get install kernel-package
sudo apt-get install linux-source

Extract kernel source code

mkdir ~/src
cd ~/src
tar xjf /usr/src/linux-source-<version #>.tar.bz2

Configure the source code

cd linux-source-<version #>
cp /boot/config-`uname -r` .config
sudo make menuconfig

Make sure the following are done: (If Ubuntu 8.10 is used, all of these should already be done by default, except for the bonding driver setting.)

1. Network support -> Wireless -> Device drivers -> Network device support -> Wireless LAN : Intel Wireless Wifi 4965AGN, 5000AGN and 3945 AGB/BG should be all checked. Intel Pro/Wireless 3945ABG/BG Network Connection is a module (M) by default - this is correct
2. Device drivers -> Network device support : Bonding driver should be checked as a module (M)
3. Review Madwifi driver requirements. For the impatient, here are the affected parameters and their correct values:

CONFIG_WLAN_80211=y
CONFIG_SYSCTL=y
CONFIG_CRYPTO=y
CONFIG_CRYPTO_AES=m

Next, several files have to be replaced by the custom versions from the git repository. You may apply the kernel patch that comes along with the client code, but a note of CAUTION: Since the Linux kernel keeps evolving, it is impossible to have a fixed patch for all versions (for now). If in doubt about replacing source files, make a copy of those files and diff the stock and custom versions to find any potential conflicts.

The list below shows where files should be moved/merged into. All directory paths are relative to the linux source directory. Assuming the commands above were followed, that directory would be ~/src/linux-source-<version #>.

• Directory include/linux
  • sockios.h : The custom version adds some SIOCBONDHOOLOCK<XXXX> macros, where <XXXX> is one of MAKE, BREAK, GETACTIVE, GETPASSIVE and TEST
  • if_bonding.h : The custom version adds a single line for the macro definition BOND_MODE_HOOLOCK
• Directory include/asm-generic
  • errno.h : The custom version adds a macro definition EHOOLOCKBUFF. Note: There is another errno.h in include/linux. Do NOT touch this file!
• Directory net/core
  • dev.c : Caution advised in replacing/merging this file, since it tends to change between minor versions of the kernel. Diff-ing the two versions is a useful start.
• Directory drivers/net/bonding
  • bonding.h : The custom version should only add Hoolock-specific lines to the stock version
  • bond_main.c : Same as bonding.h, but there may be some differences in debugging functions used, e.g. printk vs. dprintk. Use the stock version in these cases.

Compile custom kernel

The source is now ready for compilation. If the machine has multiple cores, set the CONCURRENCY_LEVEL to number of cores plus 1 for faster compilation. For example, on a dual core machine,

export CONCURRENCY_LEVEL=3

To actually compile the source,

cd ~/src/linux-source-<version #>
sudo make-kpkg clean
sudo fakeroot make-kpkg --initrd --append-to-version=<unique kernel id string> kernel-image kernel-headers

where <unique kernel id string> helps distinguish this custom kernel from the stock kernel in the bootloader. A suitable id string might be "-mobility".

The kernel compilation should take anywhere from minutes to hours depending on how fast the machine is. After the kernel image and headers are compiled, compile the modules by

sudo make modules

This should compile the bonding driver module as well. The module is a file named bonding.ko in drivers/net/bonding.

Install custom kernel

The final step is to install the newly compiled kernel image and headers.

cd ~/src
sudo dpkg -i linux-image<unique kernel id string>.deb
sudo dpkg -i linux-headers<unique kernel id string>.deb

where <unique kernel id string> is the id string used during compilation. The kernel should be installed as /boot/vmlinuz-<version #>-<unique id string>. /boot should also have config, System.map and initrd.img files for the custom kernel. To ensure that the kernel is accessible during boot time, check the boot loader for its entry. If grub is used, a section similar to the following should be present in /boot/grub/menu.lst:

title       Ubuntu 8.10, kernel 2.6.27.18-mobility
uuid        61232b84-a515-47df-a846-d55ae16df655
kernel      /boot/vmlinuz-2.6.27.18-mobility root=UUID=61232b84-a515-47df-a846-d55ae16df655 ro quiet splash  crashkernel=384M-2G:64M@16M,2G-:128M@16M
initrd      /boot/initrd.img-2.6.27.18-mobility
quiet

title       Ubuntu 8.10, kernel 2.6.27.18-mobility (recovery mode)
uuid        61232b84-a515-47df-a846-d55ae16df655
kernel      /boot/vmlinuz-2.6.27.18-mobility root=UUID=61232b84-a515-47df-a846-d55ae16df655 ro  crashkernel=384M-2G:64M@16M,2G-:128M@16M single
initrd      /boot/initrd.img-2.6.27.18-mobility

Client programs

The following assumes that the custom kernel is used. This can be verified using 'uname, such as:

> uname -a
Linux OpenRoadsPC 2.6.27.18-mobility #1 SMP Wed Sep 2 22:34:36 i686 GNU/Linux

Two packages are needed for client program installation:

sudo apt-get install build-essential perl

Madwifi driver

Madwifi is a driver for Atheros chips used in the experiments. To install the driver:

• Add ath_pci to DISABLED_MODULES in /etc/default/linux-restricted-modules-common
• Get code from Madwifi's svn:

svn checkout http://svn.madwifi-project.org/madwifi/trunk madwifi-src

• Compile the source (more info in INSTALL file of the checked out directory)

cd madwifi-src
make KERNELPATH=~/src/linux-source-<version #>   # KERNELPATH should be set to kernel source used to compile the custom kernel above
make install KMODPATH=/lib/modules/`uname -r`
depmod -a

• If the make install command complains about an unfound directory, e.g. /lib/modules/linux-2.6.28, a workaround is to simply create the directory. This will require sudo rights.
• After installation, the driver may be loaded manually via

modprobe ath_pci

It should also be loaded automatically after a reboot and upon plugging in the wireless card.

Hoolock

The bonding driver has already been compiled during kernel compilation. To load it, use the modprobe command:

modprobe bonding mode=7 # mode 7 corresponds to Hoolock

n-casting

The Makefile included in the ncast directory produces two sets of outputs:

• A Netfilter kernel module named nf_mobility.ko that can be loaded via insmod nf_mobilility.ko
• A set of client programs that help run test scripts

To make them all in a batch,

make all # sudo may be required depending on your environment

To produce only the netfilter module,

make ncast-nf-module

To produce only the client programs,

make client-progs

To clean up, issue make clean as usual.

Running the client

See OpenRoads Client Operation on how to run the client

References

Madwifi-project.org

Linux module development guide