OpenRoads Client Operation

From OpenFlow Wiki

Background

This article is about how to run the OpenRoads Client components - the bonding driver, the netfilter n-cast module and accessory client programs.

You should have set up the client already. If not, please set it up first. The OpenRoads Client Setup article is a guide. For the remainder of this article, we assume that the client code (from git) is placed in

/home/<your username>/client-code/

so all paths will be relative to this path unless otherwise stated.

Bonding driver

The bonding driver must be loaded for either n-casting or Hoolock to work properly. To load it, execute

modprobe bonding mode=7

where mode 7 is called "Hoolock mode", basically a bonding mode that either does Hoolock or allows all packets from all enslaved interfaces to pass through. If this command fails, you may want to use insmod on the module file directly. For example:

insmod <linux source tree>/drivers/net/bonding/bonding.ko mode=7

To unload the bonding driver, in case you forgot to specify the mode, use

modprobe -r bonding

If modprobe complains again, try

rmmod <linux source tree>/drivers/net/bonding/bonding.ko

Once you have loaded the bonding driver module, a new bonding interface, normally called bond0, is created. Enable it by

ifconfig bond0 up

The bonding interface aggregates multiple physical interfaces into a virtual interface. Every packet that goes through these physical interfaces go through the bonding interface. In bonding driver terminology, the physical interfaces are "enslaved" by the bonding interface. To enslave these interfaces, use the ifenslave command:

ifenslave bond0 <physical interface>

To detach physical interfaces from the bonding interface:

ifconfig <physical interface> down
ifenslave -d bond0 <physical interface>

Note: We noticed sometimes detaching a physical interface causes a kernel freeze-up. We have not figured out the reason, but the problem seems to manifest when we try to detach interfaces when they are still enabled. So it is safer to first disable the physical interface before detaching it, as illustrated above.

The bonding interface's MAC address is that of the first physical interface being enslaved. Depending on the wireless chipset used, this MAC address may or may not be the one used by the physical interfaces. The normal behavior is that physical interfaces transmit using the bonding interface's MAC address as the source MAC address. However, there are wireless chipsets which uses their original (burned-in) MAC addresses as source MAC address. For instance, the Atheros association with access points. For instance, the Atheros AR5212 chipset in the D-Link WNA-2330 card we used uses only the burned-in MAC address for association packets. Therefore, we ended up having to use that burned-in address as the bonding driver's MAC address so that addresses reported by SNMP during AP association is uniform for all physical interfaces. To change the MAC address of the bonding interface:

ifconfig bond0 down
ifconfig bond0 hw ether <new mac address>
ifconfig bond0 up

A packet sent by the bonding interface is transmitted by the current active slave. To change the current active slave, you may either use

ifenslave -c bond0 <new active slave>

or use the change-active-slave program provided in the netfilter client code. With ifenslave, you need to ensure that the new active slave is already associated with an access point, otherwise the operation fails. The program we provide bypasses this association check for greater timing flexibility.

Netfilter n-cast module

In the nf-bicast directory, after running make all, a kernel module called nf_mobility.ko that performs duplicate removal. In n-casting, packets from multiple enslaved physical interfaces are all passed by the bonding interface to IP, which performs complex tasks like defragmentation. The Netfilter module intercepts the packet when it leaves the IP layer, performs duplicate removal, and, if the packet is not a duplicate, passes it to the transport layer. Duplicate packets are dropped. Obviously, the module cannot keep account of all previously received packets, so there's a time-based sliding window for storing packet information (e.g. sequence numbers of received TCP segments). Information that falls outside the window is discarded. The default size of the window is 4 jiffies, which may range from 4ms to 16ms using default jiffy settings in 2.6 kernels.

To load the Netfilter module:

insmod nf-bicast/nf_mobility.ko

Simply loading the module does not start the duplicate removal - the default behavior of the module is simply to pass on intercepted packets to the transport layer. To actually start the duplicate removal:

nf-bicast/nf-start-bicast

The various programs in the nf-bicast directory are for configuring the Netfilter module and bonding-driver-related programs to facilitate n-casting. In particular, nf-control allows you to start and stop duplicate removal, and adjust the size of the time-based sliding window. nf-control communicates with the kernel module through a device file, which can be created by

sudo mknod nfm_dev c 240 0

The run-bicast.sh and run-bicast-manual-switch.sh show how the various client programs are used. In particular, they use change-active-slave for flexible timing of access point associations.