KUTE - Kernel-based Traffic Engine

KUTE has been developed to have a maximum performance traffic
generator and receiver mainly for use with Gigabit Ethernet. Standard 
userland tools do not have much performance in terms of packet/s as 
compared to hardware testers (e.g. Smartbits).  

The main reason for this is that user space tools suffer from context 
switching and the packets must traverse the complete network stack.
Another advantage of kernel-based tools is that they can send with
more accurately inter packet gaps and more accurately measure packet
inter-arrival times.

kute_snd is a UDP packet sender. It is a Linux kernel module which
sends packets as fast as possible directly to the hardware driver
bypassing the stack. It can generate very high packet rates for
a software solution and can be used to test hardware+driver performance
performance of receiving stack, routers/switches, middleboxes etc.

kute_rcv is a UDP packet receiver. It is a Linux kernel module
which can either hook in at the UDP protocol hook or directly
at the receiving routine getting packets from the hardware driver
(using a patch supplied in this distribution). The tool
will count received packets and measure the packet inter-arrival
times. It can accurately measure high packet rates and can be
used together with kute_snd for various performance testing.

DOWNLOAD

http://caia.swin.edu.au/genius/tools/kute-1.4.tar.gz

INSTALLATION

The tools work only with Linux version 2.6. An older version exists
for Linux 2.4 but it is no longer supported.

1. Unpack the source distribution
   cd <dir>
   tar -xvzf kute-1.4.tar.gz 

2. Patch the kernel if the kute receiver shall be used with either the
   kute-hook-patch or the kute-udphandler-patch (ONLY newer kernels) 
   cd /usr/src/linux
   a. fast mode
      patch -p1 < <dir>/kute-1.4/linux-2.6.4-52-kute-hook-patch
      enable -DGRAB_EARLY in Makefile
   b. normal mode
      patch -p1 < <dir>/kute-1.4/linux-2.6.16-13-kute-udphandler-patch
      (this patch is NOT needed for early 2.6 kernels e.g. 2.6.4)

3. Compile the modules
   cd kute-1.4 
   make

4. Optionally install modules 
   make install

KERNEL PATCHES

The kernel patches are only needed for the kute receiver. There are two 
patches:
- linux-XXX-kute-hook-patch
- linux-XXX-kute-udphandler-patch

The kute-hook-patch inserts a hook into the kernel to grab packets very
early after they leave the device driver. The kute-udphandler-path grabs
packets fairly late (this patch was not necessary in early version of Linux
2.6).

There are only patches for some kernel versions in the package. However, 
the kernel code is in constant flux and it seems every version breaks the 
patches.

If the patch does not work please check if you can apply the patch manually.
This should be fairly simple at least for the kute-udphandler-patch, which
contains only one line of code.

USAGE

These tools have been made for test purposes. Do not use these tools on 
production machines or machines which important data as they may crash the 
machine. The good news is that the tools run quite stable on all machines 
where i have tested them :).

The tools can only be executed with root privileges. The following is the
usage of the two shell scripts which act as wrappers around the kernel
modules. The kernel modules can also be used directly without the .sh scripts 
and they support _more_ configuration options.

Usage kute_snd.sh: -d <destination ip> [-p <port number] [-t <duration in s>] 
[-l <overall packet length>] [-r <packets per second>]

<destination ip> specifies the target host (name or IP address)
<port> defines source and destination UDP port numbers
<duration> defines the duration of sending in seconds
<overall packet length> is the length of the packets generated including
IP and UDP header but _excluding_ link layer header
<packets per second> defines how many packets are generated per second

Usage kute_rcv.sh: -a <ip address> [-p <port number] [-t <duration in s>] 
[-w <usec per bin>] [-c <bin count>]

<ip address> specifies the destination IP adress to filter on
<port number> specifies source and destination port number to filter on
<duration> defines the duration in seconds. Using 'inf' will cause the script
not to remove the kernel module after a specific duration. It must be
removed manually with rmmod. 
<usec per bin> defines the length of the bins which are 'filled' according
to packet interarrival times
<bin count> defines the number of bins

The usage of the kernel modules is documented in the source code.

EXAMPLES

Sending a UDP data stream for 10s with a packet rate of 100 pkt/s and each
packet has an overall length of 64 bytes (including IP and UDP header). The
stream is send from hostA to hostB. 

su root
./kute_snd.sh -d hostB -t 10 -r 100 -l 64

Receiving a UDP stream for 10s and generating packet interarrival time 
statistics. In this example the interarrival time is measured and the
distribution is stored in a set of 50 bins with each bin 0.1 ms long.

su root
./kute_rcv.sh -a hostA -t 10 -w 100 -c 50 

ACKNOWLEDGEMENTS

The kernel modules were initially based on basic Linux 2.2 kernel modules
developed in the click project (http://www.pdos.lcs.mit.edu/click/).
However, i have introduced substantial improvements in the sender and 
receiver routines, ported the code to Linux 2.6 and added a couple of 
additional features. 

LIMITATIONS

KUTE has only been tested on Intel PCs and Ethernet network cards.
The current version works only with Linux 2.6. 

CONTACT

Sebastian Zander (sebastian.zander@gmx.de)