DCBT README.TXT FILE --------------------------------- Students: Jon Yurek jyurek@alumn.wpi.edu Charles McAuley chuck@alum.wpi.edu Brian Conway bconway@alum.wpi.edu Advising Professor: Mark Claypool claypool@cs.wpi.edu ---------------------------------- CONTENTS: - ./: this README.TXT - ./src: source code files for CBT, RED, DCBT, DCBT with ChIPS - ./config: Linux config file, picture of our network testbed, Makefile - ./scripts: scripts for installation ---------------------------------- Q: What is DCBT? CBT? ChIPS? A: CBT is short for Class Based Thresholds. It determines the amount of bandwidth allowable for a type of traffic (UDP / TCP / other) by how much you set the thresholds at for them. DCBT is short of Dynamic Class Based Thresholds It's a lot like CBT, except that its thresholds change depending on what types of traffic are using the router by using a flow counter (ours hashes together source IP, destination IP, and type of traffic). ChIPS is short for Cut-In Packet Scheduling It's an alternative to using FIFO to queue a packet. Specifically, it requeues "multimedia" packets to guarantee a ceiling on the amount of jitter experienced by the client. For more information, see: Brian Conway, Charles McAuley and Jonathan Yurek. Evaluation of DCBT. MQP-MLC-LR01, Spring 2002. (Advisor Mark Claypool) http://www.cs.wpi.edu/~claypool/mqp/dcbt-eval/ Jae Chung and Mark Claypool. "Dynamic-CBT and ChIPS - Router Support for Improved Multimedia Performance on the Internet", In Proceedings of ACM Multimedia, Los Angeles, CA, USA, November 2000. http://www.cs.wpi.edu/~claypool/papers/dcbt-chips/ M. Parris, K. Jeffay, and F.D. Smith. "Lightweight Active Router-Queue Management for Multimedia Networking", In Proceedings of Multimedia Computing and Networking, San Jose, CA, Jan 1999. http://www.cs.unc.edu/Research/dirt/abstracts/MMCN-99-abs.html Sally Floyd and Van Jacobson. "Random Early Detection Gateways for Congestion Avoidance", IEEE/ACM Transactions on Networking, 1993. Q: WHERE IS THE CODE, AND WHAT DO I DO WITH IT? A: look for the files sch_dcbt.c, sch_cbt.c, and sch_chips.c They should be in the same directory as this README Hopefully the code itself is pretty explanatory but a few things need to be noted: 1) Linux's take on routing schemes tend to be isolated. It provides an interface of entry functions that you specify, and it calls them when necessary. this is explained in detail in the file: /usr/src/linux/net/sched/sch_api.c 2) The queue is managed using a double linked list, with a very fleshed out API, called a sk_buf. This also contains a structure telling you all about the packet you are looking at. You can find descriptions of how to play around with your own queue at: /usr/src/linux/include/linux/skbuff.h 3) Need more information on your packet? /usr/src/linux/include/linux/ip.h 4) Lets not forget about where all the queue management schemes are located: /usr/src/linux/net/sched/ Q: WHAT VERSION OF THE LINUX KERNEL DOES THE CODE AND SCRIPTS WORK WITH? A: We developed the code with Linux v. 2.4.13, but it should be compatible with most 2.4.xx kernels. Specifically, the file "config-2.4" is the .config file used for our router. You will need to modify the scripts to suit your specific kernel version. The network topology that our code works is depicted in the file "our_network.png". Q: HOW DO I RUN DCBT, CBT, ChIPS, ETC? A: There are a variety of scripts used to accomplish this, all stored in /usr/sbin and to be run as root. Note that you will need to modify the scripts to suit your specific kernel version and network setup. The first script is 'builddcbt'. This builds all scheduling modules from the kernel source. Another script run by 'qdisc_stats' prints all the qdisc stats from tc for reporting purposes. The next set of scripts all consist of 'loadNAME' where NAME is the queuing mechanism, such as loaddcbt, loadcbt, loadred, or loadchips. These scripts load the modules, but do not initialize them. The next set of scripts are of the form 'addNAME'. These scripts use tc to set the queuing mechanism parameters and put them into action. The final set of scripts are of the form 'delNAME'. These scripts use tc to remove the queuing mechanism parameters and then unload the modules. Q: HOW WAS YOUR CODE INCORPORATED INTO THE KERNEL SOURCE? A: All code was written and stored in /usr/src/dcbt. Source code files were then symlinked in /usr/src/linux/net/sched/ as follows: lrwxrwxrwx 1 root root 25 Dec 2 15:51 sch_chips.c -> /usr/src/dcbt/sch_chips.c lrwxrwxrwx 1 root root 23 Nov 27 14:57 sch_cbt.c -> /usr/src/dcbt/sch_cbt.c lrwxrwxrwx 1 root root 24 Nov 12 17:07 sch_dcbt.c -> /usr/src/dcbt/sch_dcbt.c The Makefile was adjusted in that directory to add our source files to the RED configuration option, and are built when 'builddcbt' is run. A copy of this Makefile is stored in this directory for reference, as is a copy of the kernel configuration file we used (which did not need to be rebuilt regularly, only the modules). Q: HOW DO I ASSEMBLE THE NETWORK TEST BED? A: The gateway should be connected to the WPI network with a standard cable to the upper network card. The lower network card should be connected to the upper of the two horizontal network cards in the router with a cross- over cable (not the onboard ethernet port). Each of the two client machines should be connected to the remaining ethernet cards on the router with cross-over cables according to the labels on the front of the machines to match up the subnets. This is detailed in the our_network.png imagine included in this directory. IMPORTANT: The internal network card on the gateway does not auto-reconnect correctly if the connection is lost. If the router loses power, the gateway must be powercycled after bringing the router back up. Note that simply rebooting the router without losing power does not cause a problem. Q: WHAT TRIPPED YOU GUYS UP THE MOST? HOW CAN I AVOID DOING IT? A: There are a number of things, here's a few that really hung us up for a while: 1) in the RED code (sch_red.c) qave is a FIXED POINT number. that means you have to shift it to the right if you want to compare it to an ordinary integer of some kind (look at the ChIPS code if you want an example). 2) IP addresses are stored backwards. Well, backwards as far as you would be concerned. 3) The way RED handles qave, q_min, and q_max on Linux is not through number of packets, but instead through packet size. Hence, one really really big packet has the same affect as many small ones. 4) This can't be stressed enough: DON'T BE LAZY WITH YOUR POINTERS AND MEMORY ALLOCATION. This is a kernel. It doesn't "segfault" it crashes. And it will crash badly if you don't keep track of them. This doesn't mean that mistakes don't happen. Just be sure to catch them if you come across them.