Kickass Endpoint - V. 1.0
Marcel Flores - marcel-flores@u.northwestern.edu

About
=====
Kickass is a congestion control mechanism by Marcel Flores and Aleksandar
Kuzmanovic at the Northwestern Networks Group.

These files contain the implementation of the kickass endpoint for Linux.
Kickass has been placed directly into the Linux Kernel. While it violates
a number of Kernel programming guidelines, it offers a real-life version of
kickass that can be run on real machines.

Requirements
============

0) Custom kernel installation instructions for your distribution
1) Any dependencies for building a regular kernel (e.g. bc, etc.)
2) ethtool - to turn off offloading

Building and patching
=====================

1) Obtain a copy of the Linux Kernel version 3.12.3:

    wget http://kernel.org/pub/linux/kernel/v3.x/linux-3.12.3.tar.xz

2) Unpack the kernel

    tar xvf linux-3.12.3.tar.xz

3) Apply the patch

    patch -p0 < kickass_kernel.patch

4) Configure the kernel according to your distribution. The patch was largely
   written and tested on Arch Linux (highly recommended).

5) Enable kickass (and set it as the default if you so desire) in:

    -> Networking Support
        ->Networking Options
            ->TCP/IP Networking
                ->TCP: Advanced Congestion Control
                    ->TCP Kickass

    And

                    ->TCP Default Congestion Control: Kickass

6) Build and install the kernel and modules according to your distribution,
   likely something like:

   make
   make install [Or similar...]

Running
=======

1) Be sure to disable path MTU discovery, as this labels all packets as Do Not
   Fragment:

        echo 1 >> /proc/sys/net/ipv4/ip_no_pmtu_disc

2) Disable offloading using the included script:

    ./turn_off_offloading.sh <net_device>

3) Use the network!

    Kickass works by fragmenting packets to indicate explicit rates. In
    particular, routers run an algorithm similar to that of RCP (kickass_qdisc),
    and determine an explicit rate. As packets pass through the router, it
    fragments them, encoding the rate in the size of the leading fragment. The
    receiver notes these sizes, decodes the corresponding rates, and sends them
    back to the sender in the corresponding ack messages. The sender then
    changes its congestion window and pacing rate to conform to the instructions
    from the router:
    
    |Sender| ->  [ data ] -> /Router/ -> [da] [ta] -> |Receiver|
                                                            
                                                   <- [Ack, Rate]

    The encoding uses the length of only the leading fragment to allow
    subsequent routers to further adjust the rate and will ultimately indicate
    the lowest permitted rate on the network.

    If there are no Kickass routers on the path, the endpoints will behave as
    TCP Reno.

Known Issues:
===========
1) Sometimes the first packet in the first flow after boot is incorrectly
   thought to contain a rate when it does not. Therefore the sender will record
   a very high nonsense rate. This is usually corrected immediately when it
   receives a valid rate. Likely lurking in net/ipv4/tcp_ipv4.c somewhere.

2) In general, kickass code is placed directly where it needs to be, and rarely
   is it wrapped in ifdefs, or other traditional compile-time controls. Where
   necessary it checks for a sysctl, but in general it is hard to "turn off"
   kickass without just using a different kernel.

3) Current code to detect tampering with options or fragmented packets is
   incomplete. There are two cases which are not currently implemented:
    
    a) Packets with kickass negotiation options are dropped. In this case, the
       system should retry with no KA negotiation option. In reality what
       happens much more often is something strips the option, but the packets
       still go through. This is fine, it just does normal TCP.

    b) If fragmented packets are dropped. Ie, after k RTO, before the connection
       is dropped, it should try sending with the IP_DF flags set.

Acknowledgements
================
Kickass development team acknowledgements can be found on the project website.

The packet pacing code was lifted from the Multi-TCP implementation by
Daniele Lacamera, and ported to the appropriate kernel version.

http://sourceforge.net/projects/multitcp/

The RCP code also provided guidance, thanks to Nandita Dukkipati and all
involved in its development.

http://yuba.stanford.edu/rcp/

Contact
=======
Questions and comments should be directed to Marcel Flores at
marcel-flores@u.northwestern.edu