Click Modular Router Laboratory Guide

Andrea Bianco, Nanfang Li, Fikru Getachew, Robert Birke October 30, 2013

Introduction

This report is a guide for the laboratory on the Click modular router for the Network Management and QoS Provisioning class. The goal of the lab exercises is to develop some Click congurations (i.e., a chain of Click elements that perform specic packet processing task saved ina conguration le) and to implement some of the QoS algorithms presented in the class, with particular attention to trac generators, trac policers (conformance verication), trac shapers (regulators), and packet schedulers. Conguration les should be saved and will be discussed during the oral examination. Please send the conguration les at the end of the class or prior of taking the exam to Prof. Andrea Bianco via e-mail.

Click Basics

Click Modular Router is implemented as an extension of the Linux kernel. Since the laboratory PCs are installed with Windows OS, we need to run a Linux machine in a virtual environment. Virtualization refers to the creation of a Linux virtual (rather than actual) machine that acts like Linux PC. A virtualization software that emulates the whole physical computer machine must be run. In this laboratory we use one virtualization software package called VirtualBox which is already installed on all the laboratory computers. To install a virtual machine, start VirtualBox and use one of the following two methods: add the image D:\ClickUbuntu10.04\ClickUbuntu10.04.vbox to virtualBox or install D:\ClickUbuntu10.04\ClickUbuntu10.04.vmdk with your own VM congurations. Recommended conguration for installation are: - VM name: ClickUbuntu10.04 - Memory: 1024MB - Virtual Hard Disk: use existing hard disk

Once you nish adding or installing the image, use the following credential to access the VM user name: click password: router Note that the VM installation procedure is run only once at the begining of your laboratory execersis. To install Click in VM, open terminal and cd to click-2.0.1 source directory on Desktop. Congure the source with the options enable-linuxmodule enablelocal ./configure --enable-linuxmodule --enable-local Now you can compile and install Click with sudo privilege: make make install Test the installation click Click src/conf/test.click Output should be ve times ok: 40 | 45000028 00000000 401177c3 01000001 02000002 13691369 The Click source code can be downloaded from http://www.read.cs.ucla.edu/click/click-2.0.1.tar.gz You might need to congure your browser proxy to access the Internet everytime you start the VM or add the following line to /etc/apt/apt.conf le: Acquire::http::Proxy "http://proxy.polito.it:8080";

Clicky GUI for Click congurations

A GUI based interface, named clicky is available. It permits to graphically look at conguration les, and/or to analyze a running Click conguration les. Change your directory to Click src/apps/clicky to install clicky. Issue the following commands in sequence: ./configure make install Test clicky installation clicky -r Click src/conf/test-clicky.click & You can also open a conguration le from inside clicky. Click on open file from the file menu and select a conguration le. The GUI interface is best suited to begin with when starting to use Click. When dealing with more complex congurations, it will be easier to directly operate on the proper les using a text editor.

Click conguration le
To develop a Click conguration, you must write a conguration le that describes a chain of elements. Elements can be either newly developed or taken and modied starting from the available elements in the Click library. Elements in the library are organized in packages, according to their functionalities. For a documentation on available elements, see 2

http://read.cs.ucla.edu/click/elements Click conguration language is described in detail here: http://www.read.cs.ucla.edu/click/docs/language Note that Click elements are described using the C++ language. A basic knowledge of C++ is assumed and should be considered as a class pre-requisite.

3
3.1

Getting Started
First example: test.click

Open via the GUI the test.click congurations, found in Click src/conf/ directory, to learn how it works. 1. Which is the task executed by each element? 2. Find each element description in the available documentation. 3. Have a look at the C++ code describing each element. Most important ones are in the folder Click src/elements/standard. At this stage you dont need to go in depth to explore the code. 4. Try to run the conguration le to see the outcome. 5. Replace Print with IPPrint element. What is the dierence in the print output? 6. What is test.click doing? Open via the GUI the test-clicky.click congurations. Change the interval parameter in TimedSource@2 (TimedSource connected to counter C1). Observe how the queue length is aected. Play with other parameters to understand the interaction among the elements.

3.2

Second example: print-pings.click

To perform the exercises in this section and section 3.3, you need two VMs running on your PC. To create the second VM, right click on the existing VM and clone it with the following options: - give a new name to the newly cloned VM - reinitialize all MAC addresses - make a full clone Now you need to connect the VMs through a bridge network. To setup a bridge network, turn o both VMs. Click on one of the VM and select Setting from Machine menu. From the left side list, click on Network. Choose Bridged Adapter from the Attached to drop down menu. Select virbr0 as a name. Repeat the same for the second VM. After network setup, you need to congure the IP address of the VMs network interface in the 10.0.2.0/24 range. Start the VMs and note the available 3

Ethernet interface on both machines. Open terminal and use the following command: ifconfig For each VM congure the Ethernet interface IP address as follows: sudo ifconfig eth<x> 10.0.2.5/24 on the original VM and sudo ifconfig eth<y> 10.0.2.6/24 on the cloned VM where eth<x> and eth<y> are the interface you noted earlier. Now you can ping one VM from the other to test the network connectivity. For example, ping 10.0.2.5 from the cloned VM. If ping succeeds, continue to work out the following exercises. 1. Send ICMP request from on VM terminal and capture the packets in the other VM with the print-pings.click script. 2. Which is the task executed by each element in the script? 3. Find each element description in the available documentation. 4. Have a look at the C++ code describing each element. Most important ones are in the folder Click src/elements/standard. Again at this stage you dont need to go in depth to explore the code. 5. Try to run the conguration le to see the outcome. 6. Change the IPFilter parameter to see requests and replies. 7. What is the print-pings.click script doing? You could use ICMP type names or ICMP type numbers as IPFilter parameters. Refer to: http://www.iana.org/assignments/icmp-parameters/icmp-parameters.xml for full list of ICMP parameters.

3.3

Use Click to send echo request

Use the following elements to write Click script used to generate echo request: ICMPPingSource, EtherEncap, and ToDevice. Capture the ping packets using print-ping.click both in the receiver and sender side. What is the dierence in the capture? Answer questions 2 through 7 in section 3.2. Note: After nishing this exersise you need to disable the bridge network to access the Internet.

3.4

Trac generator

Modify the test.click conguration le to create a trac generator named Counter test.click.

1. Generate 100 identical IP packets, with the source IP address set to 192.168.1.245. Hints: Try to modify the Infinitesource element DATA to set the source IP address. Run the script and discuss the outcome. Try to use a proper element in the library to add a proper IP header checksum. You may need to check the Packet class and see how to operate on it. Hint: besides setting the IP checksum, you need to set the IP header annotation as well. Look for the right element to set it. Another possible solution is to exploit a library element available in the IP package to build an IP packet. Finally, you could write (but maybe its too early) your own element. See also below the random generator. 2. Use the Counter and the Print elements after the generator to check generator correctness. To test the counter behavior, name the counter in your conguration le and use the following commands: click [your conf file] -h element name.handler i.e. click ./Counter test -h counter myname.count You may also use clicky to see the counter values through handler interaction. However, you need to either continuously run the conguration le in user mode or to load the conguration le in kernel mode. 3. Modify the scripts to generate 200 packets, 100 with IP address 192.168.1.245, 100 with IP address 192.168.2.235. Classify the packets to check if they have the proper IP address. Repeat step 2 to check the outcome. Hints: a) Use Queue and RoundRobinSched element to merge two generators into one ow b) Use the IPClassier or CheckIPHeader element to separate packets. 4. Add 3 counters, 1 before classifying and 2 after classifying. The two counters after the classier should check the packets number with IP address 192.168.1.245 and 192.168.2.235 respectively. Check if packets are properly classied. e.g., use the following commands: click ./Counter test -h counter before IPcheck.count click ./Counter test -h counter after IPcheck flow1.count click ./Counter test -h counter after IPcheck flow2.count 5. Try to add/test some other new elements as you wish from the standard element library to your scripts.

4
4.1

Customize element
Introduction

You are going to write our own elements in the following sections. Please read again carefully the slides about how to implement new elements rst. Remember, the easiest way to write your own element is to copy a standard element which shares similar functions, give it a new element name and modify the source code according to your needs. All standard elements are found in Click src/elements/ directory. Your should save new elements in Click src/elements/local directory. Put both the .hh and .cc les in this directory. To compile and install new elements issue the following commands: ./configure --enable-local make elemlist make install Check if the compilation is successful. If not, solve any compilation errors and compile again. Note that every time you make changes to a source code of an element, you must do a make install with a sudo privilege! Once the compilation is successful, you can check your elements in click elements list using the following command: cat Click src/userlevel/elements.conf Do you see your element in the list? If yes, you can start using it.

4.2

Random source

Create a Random IP generator trac generator which generates packets with source IP addresses in the form 192.168.1.x, where x is a randomly generated number between 0 and 255. Hints: Use click random to generate a random number. No single library element can be directly used to generate packet with random content. One possible solution is to modify the InnitSource.cc le in the standard package. Remember to set the packet length parameter, and check how the element deals with initialization strings whose length is shorter than the packet length parameter. Are packet annotations correctly set up? Another solution is to create a packet content (data only), and exploit the library elements IP Encap and Ether Encap to build the packet. 1. Test the Random IP generator trac generator using the previously developed counter example, generating 1000 packets. Print the content eld to show random behaviors. 2. Add one FIFO queue (standard element) to examine the generator behavior in terms of packet time generation. Print packet timestamp at the input and at the output of the queue. Hints: Use the SetTimeStamp and StoreTimestamp element to study whether re-ordering happens when queueing the packets. Another solution is to use the Print element to directly show the generation time added by Click itself. 6

3. Use one LIFO instead of FIFO queue (standard element) to examine the generator behavior in terms of packet time generation. Print packet timestamp at the output of the queue. Does queue occupancy increase? If not, try to modify the generators to have a queue build up.

4.3

Random queue

Dene and create a new element behave as random queue. 1. Use one RANDOM queue element (instead of FIFO or LIFO) to substitute the previous developed script and print packet times tamp at the input and output of the queue. Hints: RANDOM behavior can be obtained by either inserting packets in random order (and serving the queue in FIFO) or by inserting packets in FIFO order and serving the queue in random order. 2. Add a CRC check. Hints: append a CRC code to the packet by using SetCRC32() for each packet. Check carefully the printing process, because the packet has an increased length. 3. Simulate an error free link via a queue element and check the CRC (via CheckCRC32) after the packet has crossed the error free link. Then, add some errors to the simulated link by using RandomBitErrors with parameter 0.1, 0.001, 0.0005. Check via counters that the proper packet error rate is created.

QoS Test

In this section we are going to test some QoS concepts learned from lectures. To be precise, we will develop a simple trac generator rstly, then connect it with regulators to change the ow behavior(CBR, VBR etc), nally we will use/develop some schedulers to further cascade with the regulated source and to demonstrate multiple ows fairness properties.

5.1

TCP/UDP Trac Generation

Create a UDP TCP trac generator able to generate a given percentage of UDP/TCP trac according to a proper parameter setting. Suggested Inputs: Percentage of UDP and TCP, aggregate trac speed in Mb/s(Kb/s etc) packet size for TCP and UDP respectively. Output: 1 interface with the mixed tcp/udp ows. 1. Dene the trac generator. Hints: at least three approaches (maybe more) can be pursued. Two timed generators generating into two separate queues and a FIFO (or Random or Round Robin scheduler). 7

 Two generators generating respectively TCP and UDP packets, sent to two separate queues. Use a simple Weighted Round Robin scheduler (not available) to extract the packets from the proper queue. One generator in which it is possible to control the percentage of TCP with respect to UDP packets, need to modify the source code and write your own element. Discuss the dierences among the three approaches. 2. Count and/or print the packet types to check that the trac generator works properly 3. Dene the generator as a compound element when choose the rst two approaches.

5.2

Shapers/Policers

The goal is to dene trac regulators and show their behavior. 1. Generate an uncontrolled ow(Use the TCP/UDP generator with fast generation speed or implement a VBR source) and regulate it through a leaky bucket. Hints: one simple possible implementation is to use the LinkUnqueue or BandwidthShaper element. token bucket token bucket + leaky bucket 2. Regulator rates and queue size should be made available as parameters. 3. Create two versions, one to shape the trac, one to police the trac 4. Create an incoming trac pattern that highlights the eect of having a leaky bucket in cascade with the token bucket (in other words, show that an incoming trac pattern creates a dierent outgoing trac pattern in case a leaky bucket is cascaded after the token bucket. 5. Optional: Create a policer that admits a trac according to a negotiated CIR (Committed Information Rate), CBS (Committed Burst Size) and EBS (Excess Burst Size) values. In other words, a regulated source able to admit a two priority trac within a given ow. For all the above examples, elements that permit to quantify shapers/policers behavior should be introduced (e.g., count dropped packets, count regulated packets, count low and high priority packets, etc.).

5.3

Schedulers

The goal is to dene best-eort and QoS schedulers and to show their characteristics by dening a proper set of trac ows through the scheduler. Enable the scheduler to support at most up to 10 separate queues/ows and have running examples with at least 5 active ows. 1. Implement a FIFO scheduler. 2. Implement a RR (Round Robin) scheduler. 3. Show that a FIFO scheduler does not protect well behaved ows against a not regulated ow. (Add the scheduler into the conguration les from last section) 4. Show that the round robin scheduler does protect well behaved ows against a not regulated ow in the same scenario as above. 5. Test a RR scheduler with several ows to demonstrate that if the packet size is xed, RR is fair both in terms of packet/s and bit/s, whereas in case of variable packet size it is fair only in packet/s but not in bit/s. 6. Implement a DRR scheduler and test it for xed and variable packet size to show that it is fair also in terms of bit/s. 7. Implement a WRR (Weighted Round Robin) scheduler. Show that ows get a rate proportional to weights regardless of their incoming rate. 8. Optional: Extend the WRR scheduler to a Decit Weighted Round Robin.

FAQs about the lab guide:

Where can I nd the elements descriptions, i.e, parameter lists? Go to the web page http://read.cs.ucla.edu/click/elements and search for the target element. Remember on the top-left there is a table linked to dierent groups of elements sorted by their functions. Where do I nd the location of the example conguration les? Go to the folder located at Click src/conf/, or at /home/examples/, all the les with extension .click are conguration script. Where can I nd the source code for the element? Go to the folder located at Click src/elements/, all the element source codes are there, but the most useful ones are located in Click src/elements/standard/ and Click src/elements/ip. How do I know which package each element belongs to? Go to the web page http://read.cs.ucla.edu/click/elements, you can nd 4 elds

for each element as shown like Name, Function, Drivers and Package, read the Package column to see where the element is specically. How do I know if the target element is working on user level or kernel level or even specic environment like NS simulator? Go to the web page http://read.cs.ucla.edu/click/elements, you can nd 4 elds for each element as shown like Name, Function, Drivers and Package, read the Drivers column. All means it can be used in kernel, user-level and NS simulator. userlevel means it can only be used in userlevel etc. What does align element do exactly? It just move the packet to a better location to boost the cup processing time. When processor reads data from memory, it does not read bit by bit but more with 2k , if the packet is not placed in a good position, it might take the processor more time to fetch the data, just that. For instance, if the IP header is located at pointer value 0x8CCA03, its better to shift it into position 0x8CCA00 or 0x8CCA04, which is friendly to the CPU. How do I introduce customized elements into the main source tree? 2 steps, one is ./congure your click with the option enable-local (Only need to do ONCE and we have already enabled it for you in the live-CD). Then implement your own element and place the .cc and .hh les into Click src/elements/local/ folder. Compile the click again with make install in the top level of click folder, thats it! How do I know the functions for dierent class? Go to the web page http://read.cs.ucla.edu/click/doxygen/classes.html and nd the interesting class you want to know. How do I check my output results when running kernel level click Run dmesg in a shell to view the output.

10