Juggler virtual link layer for Linux, version 0.99 12 April 2008 Anthony J. Nicholson , University of Michigan Project webpage: http://www.eecs.umich.edu/~tonynich/juggler/ -------------------------------------------------------------------- Please visit the project webpage for the latest documentation, information on supported wireless cards, et cetera. This release supports wireless cards based on the Realtek rtl8185/7 chipset. Juggler has also been ported to the Broadcom chipset by researchers at Duke University as part of the COPSE project (http://copse.cs.duke.edu/). Juggler consists of four parts: (1) Kernel patch to the 2.6.22.14 kernel (2) Modified Realtek WiFi device driver (3) Connection Manager kernel module (the main Juggler code) (4) Configuration scripts and helper application ------------------- (1) Kernel patch ------------------------------------- The kernel patch is connmgr/patch.connmgr. After obtaining a fresh 2.6.22.14 Linux kernel, apply the patch, configure and compile. The patch should apply with minimal hand-tuning to more recent Linux kernel versions, but your mileage may vary. ------------------- (2) WiFi device driver ------------------------------- After rebooting into the patched kernel, first compile the wireless device driver. Run "make" in the rtl-wifi/ directory, then load the driver's modules by running the "module_install" script. Note that the Realtek driver relies on the ieee80211 software MAC layer. If you have any other wireless drivers active on your computer that are using that layer, you *MUST* first rmmod all those modules or the install will fail due to namespace clashes. After the Realtek driver is loaded, verify it is working by doing ifup, iwlist scan, et cetera, on the new interface. Note the device name (e.g. wlan0, eth2) that the driver allocated, as that will be important later. ------------------- (3) Connection Manager ------------------------------- The bulk of Juggler's functionality lies in the "connection manager", found in the connmgr/ directory. In that directory, first make a link to the module version file from the Realtek driver: ln -s ../rtl-wifi/Module.symvers . This makes the build process smoother because the connmgr kernel module calls several device-driver specific functions in the Realtek driver that we added to the public rtl-wifi driver. Next, compile the kernel module by running the "build_module" script. This will generate connmgr.ko. Insmod this kernel module and you will notice a new network device named "connmgr". The connection manager exports a configuration file interface in /proc/connmgr. The helper scripts and application described below handle most interaction with these files, and this interface is described below. ------------------- (4) User-level configuration ------------------------- The directory connmgr/gui/ contains user-level configuration tools. First, compile the switcher tool: gcc -o switcher switcher.c This tool is used to add or delete access points, and to adjust the relative weight of each in the rotation. We have included several scripts (named set_*) as examples of how to use the switcher tool to accomplish various tasks. ADDING AN AP switcher add accesspoint The last four parameters are optional---if they are omitted, Juggler will associate with the AP and add it to the rotation, but no data will be assigned to it until an IP-level configuration is specified (by calling switcher again with the full parameters). ADDING AN AD HOC NETWORK switcher add adhocnetwork The concept of a DNS server may be meaningless in the context of an ad hoc network, but the parameter is still expected and required. ADDING A SCANSLOT A scanslot is simply a portion of the Juggler duty cycle where the radio is passively collecting beacons, rather than associated with a given AP. This is advantageous for many situations, particuarly supporting fast handoff as described in the Juggler technical report. The "set_scanslot" script illustrates how to do this. The SSID, MAC address and channel # fields are irrelevant and can be set to whatever you wish. The beacons collected during the scanslot can later be obtained by reading the file /proc/connmgr/beacons. First, however, one must once write the name of the "real" wireless device (e.g. wlan0, eth2), to the /proc/connmgr/beacons file. Our user-level python scripts use this rather than externally calling "iwlist scan" over and over again. DELETING AN AP, AD HOC NETWORK, OR SCANSLOT To delete a network, simply call switcher with the MAC address of the network: switcher del SWITCHING FREQUENCY The current frequency with with Juggler switches from one network to the next can be read by "cat /proc/connmgr/freq". The default is 100 milliseconds. To change the timeout to 50 ms, for example, "echo 50 > /proc/connmgr/freq". ADJUSTING RELATIVE WEIGHTS OF NETWORKS Juggler can allocate different portions of the radio duty cycle to different networks. First, add the desired networks as described above. Next, use switcher to adjust the weights as follows: switcher adj ... For example, if two networks were active, where the first network had a MAC address of 00:01:02:03:04:05 and the second 06:07:08:09:0a:0b, we could assign the first AP 75% of the radio time and the second AP 25% of the radio time by: switcher adj 2 00:01:02:03:04:05 3 06:07:08:09:0a:0b 1 This assigned the first network to have three times as much of the radio as the second network (because slice1=3, and slice2=1), therefore a 75%/25% split. The basic unit here is the switching frequency, so under this scenario if the switching frequency were 100 ms, then a 75%/25% split would mean AP1 active for 300 ms, then AP2 for 100 ms, then AP1 for 300 ms, et cetera. DEBUGGING MESSAGES To activate debugging, "echo "on" > /proc/connmgr/debug", "off" to turn it off. Messages appear in the kernel log. The current status is obtained by reading the file. ------------------------ Assigning user-level flows to a certain network ---------------- By default, when a socket is created Juggler assigns the socket to whatever virtual network is currently active. Applications can specific which network they want a flow assigned to, however, in order to stripe data across APs or accomplish other domain-specific goals. We added two new socket options in the Linux kernel, in order that applications may communicate their intentions to Juggler. After an application creates a socket, it can set this "override" option by specifying the MAC address of the AP or ad hoc group to which all packets generated by this socket should be assigned. Because MAC addresses are 6-byte values and socket options are each an integer (4 bytes), we added two new socket options. One handles the bottom four bytes, the other the top two bytes. The definition of these socket options (SO_CONNMGR_OVERRIDE_HI and SO_CONNMGR_OVERRIDE_LO) can be found in linux/include/asm/socket.h. Below is a snippet of Python code illustrating how to set these options: SO_CONNMGR_OVERRIDE_HI = 37 SO_CONNMGR_OVERRIDE_LO = 38 # to set the socket option, we need the MAC address of the # AP we want to use to be split into two integers def parse_apmac_addr_string(macstr): bytes = macstr.split(':') ints = [] for byte in bytes: ints.append(int(byte,16)) return ints # force this socket to be associated with the given AP def set_apoverride_option(sock, macaddr): ints = parse_apmac_addr_string(macaddr) upper_mac = struct.pack('BBBB',0,0,ints[0], ints[1]) lower_mac = struct.pack('BBBB',ints[2],ints[3],ints[4],ints[5]) sock.setsockopt(SOL_SOCKET, SO_CONNMGR_OVERRIDE_HI, upper_mac) sock.setsockopt(SOL_SOCKET, SO_CONNMGR_OVERRIDE_LO, lower_mac) return