Documentation 

  • Introduction
  • Hints
  • Installation
  • Usage
  • Examples
  • Future plans

  • Introduction
    IPP2P is a netfilter extension to identify P2P filesharing traffic. The main goal for developing IPP2P was giving the adminstrator a dynamic tool to filter the traffic in an intelligent way. So it doesn't aim at prohibiting all P2P traffic but make it possible to shape this traffic to a given rate. For this purpose IPP2P searchs the payload of TCP packets for signaling patterns of P2P networks. As these patterns are not beeing present in all P2P packets we had to use some other netfilter extensions in order to get the whole IPP2P package working as already described. IPP2P works togeter with connection tracking and connection marking - in that way you can catch the bigger part of all P2P packets and limit the bandwidth rate.
    The name IPP2P comes on the one side from IP (internet protocol) and on the other from P2P (short for peer-to-peer). Writing both shortcuts in big letter in german I entitled IPP2P also in big letters. As new matches for netfilter are labeled in small letters the IPP2P-files and netfilter options are in small letters too. I know this is a little bit confusing :-)
    Go to the top of this page

    Hints
    IPP2P was developed and tested using SuSE Linux but it should work together with other distributions as well. Importent is the usage of a recent linux kernel (2.4.xx series) and iptables version. Even though IPP2P was running very stable and reliable during all tests done but this is no guaranty that it runs smoothly with every setup. Use it at your own risk the author is not responsible for any downtimes of servers or damaged soft- or hardware. Feel free to contact the author with any kind of feedback.

    kernel
    It is always a good idea to use the latest stable kernel because of recent bugfixes and improved stability. During it's development IPP2P was successful used with the following kernel versions:
    2.4.18, 2.4.19, 2.4.20, 2.4.21, 2.4.22, 2.4.23, 2.4.26
    2.6.3, 2.6.4, 2.6.6
    This does NOT mean that IPP2P may not run together with other kernel versions but it was not tested yet. If someone finds out that IPP2P also is running stable with other kernel versions feel free to inform the author (contact). A very important source for updates of the netfilter code is the patch-o-matic next generation system (POM-ng) available at the netfilter homepage. It contains the latest bugfixes and netfilter extensions (like CLASSIFY, CONNMARK, ...). The daily snapshots may be a good choice to get the very latest kernel updates. IPP2P is also included in POM-ng. If you don't want to use the source tarball grep latest POM-ng snapshot and run "./runme ipp2p" to install IPP2P only or "./runme extra" for IPP2P and some other updates. You'll need to enable IPP2P support in kernel config and recompile kernel and iptables.

    iptables
    As said with kernel try to use a recent version of iptables as well. We used the following versions of iptables without any problems:
    1.2.7a, 1.2.8, 1.2.9rc1, 1.2.9, 1.2.11
    It is also possible (and likely) that IPP2P runs together with older versions as well but we're lacking of experiences on this issue. New versions of iptables are released in unsteady intervals at the netfilter homepage.
    Go to the top of this page

    Installation
    preparation
    If you want to use IPP2P you have to use a linux box running a recent kernel. It has to be compiled with netfilter support enabled. Running the system as an ethernet bridge you have to enable this option in the kernel setup as well. Using netfilter on a bridge requires a kernel patch available at the ebtables homepage (see links). For a nat-ing router you do not need this patch as netfilter works well on routers.
    Traffic shaping on this box requires QoS support and at least a scheduler enabled in kernel config. We used HTB as it is easy to configure, fast and reliable. Although beeing included in standard kernel you should check the HTB website (see links) for latest patches. You will find there also an adapted version of the "tc" (traffic control) tool for configuring HTB qdiscs, classes and filters.
    The last step for preparation is the already mentioned patch-o-matic-ng. Install the patches you may need for your setup but don't forget about CONNMARK as you may need it for traffic shaping with IPP2P. Also CLASSIFY may be a good choice if you don't want to work with tc filter and we found it very reliable during our tests. If the patches are installed and all necessary kernel options are enabled compile the kernel and modules and install them.

    installation of IPP2P
    You should have a gzip-compressed tar archive of IPP2P (if not grab it at downloads). After decompression (tar -xzf) you get a new directory containing some files (source code, Makefile, README, Gnu GPL). As you install IPP2P by compiling the source code you may need to adapt the Makefile to fit your setup. Open it in an editor and search for the following line:
    IPTABLES_SRC = /usr/src/iptables
    
    IPTABLES_SRC is the path to iptables source files wich we try to autodetect. We also try to determine kernel version and location of the include directory and netfilter version but if you want to change this modify KERNEL_SRC and IPTABLES_VERSION to fit your needs.
    If the Makefile is adapted compile IPP2P by typing "make" in your console. The process should be finished without any warnings or errors otherwise recheck the setting in Makefile. If everything went right you'll get two important files: the kernel module ipt_ipp2p.o (kernel 2.4.x) or ipt_ipp2p.ko (kernel 2.6.x) and libipt_ipp2p.so (shared object file). To install IPP2P you have to copy libipt_ipp2p.so to your iptables library directory (usually located at /usr/lib/iptables/ but may depend on your distribution). Now test if iptables knows that IPP2P exists by entering "iptables -m ipp2p --help". If you get an error message check if you copied the file to the right destination. If iptables finds the new file you should see the help screen of IPP2P.
    Finally you have to load the kernel module to be able to create a firewall rule using IPP2P. Use "insmod ipt_ipp2p.o" (kernel 2.4.x) ord "insmod ipt_ipp2p.ko" (kernel 2.6.x) to load the module. If you get any warnings or error messages while insmoding please make sure that we've detected the correct path to the kernel files in the Makefile and if necessary recompile. Forcing to load a wrong module could crash your kernel! Kernel and POM-ng patches are available (downloads) as well for simplified installation.
    Go to the top of this page

    Usage
    If you successfully finished the installation of IPP2P you can start to create filter rules. First determine the aims you're pointing at and maybe investigate the peer-to-peer usage at your link (look at example 3). Also find out if there are time-critical applications wich may be easilly influenced by increased latency of a firewall. If this is the case make sure to use few but efficient rules. During early days of IPP2P I though it may be a good idea to give different filters for one P2P network - one that is fast and imprecise (--ipp2p-data) and another that is slower but offers less mismatches. Well, we measured IPP2P using high precise equipment (DAG measurement cards) but could not find any influence on latency. So I think the -data filters are obsolete and may be removed with next code cleanup. Please keep this in mind if you create your firewall rules!

    filter rules using IPP2P
    Basically netfilter allows to control custom matching modules by using the switch "-m". That's the way to configure IPP2P with the following syntax:
    iptables -A FORWARD -m modulename --moduleoption1 --moduleoption2 ... -j JUMPTARGET
    To use IPP2P select "ipp2p" as modulename and one or more of the available options. Maybe the most important one is "--ipp2p" as sum of all exact and well tested match options. At the moment the following matches are equal:
    -m ipp2p --ipp2p
    -m ipp2p --edk --kazaa --gnu --dc
    Thus a complete and simple filterrule using IPP2P would look like this:
    iptables -A FORWARD -m ipp2p --ipp2p -j DROP
    The following table shows a lineup of all module options currently available for IPP2P. Make sure not to use --ipp2p together with any other option already included in --ipp2p !

    option P2P network protocol quality
    --edk eDonkey, eMule, Kademlia TCP and UDP very good
    --kazaa KaZaA, FastTrack TCP and UDP good
    --gnu Gnutella TCP and UDP good
    --dc Direct Connect TCP only good
    --bit BitTorrent, extended BT TCP and UDP good
    --apple AppleJuice TCP only (need feedback)
    --winmx WinMX TCP only (need feedback)
    --soul SoulSeek TCP only good (need feedback)
    --ares Ares, AresLite TCP only moderate (DROP only)
    table 1: overview of IPP2P options

    Note that some options are not much tested yet. Please don't hesitate contacting me with any feedback about them. If you find one is producing mismatches use --debug (included in 0.7 and later) to locate the wrong filter. See section "debug" below for more details.

    TCP traffic
    As already mentioned IPP2P was intended for TCP packets only. In older versions (before 0.7) you had to specify the tcp protocol match ("-p tcp") for every rule using IPP2P. Due to increasing usage of UDP I extended IPP2P to cover both protocols where P2P networks actually use them. It's not necessary to specify "-p tcp" anymore because IPP2P checks the protocol itself. But you still can use it if you want to match TCP traffic. A complete filter rule for IPP2P would look like this:
    iptables -A PREROUTING -p tcp -m ipp2p --ipp2p -j MARK --set-mark 1
    This is a working rule where a matched packet gets marked with "1" (or 0x1). This mark is just for internal purposes and the packet itself is NOT altered in any way. It keeps this mark as long as it traverses through the firewall. You can refer at every position to this mark and even the tool tc is able to do filtering based on this mark.

    UDP traffic
    IPP2P 0.7 introduced support for UDP traffic to detect as much current P2P network traffic as possible. You can either look at table 1 wich UDP filters are currently available or use "iptables -m ipp2p --help" to find out wich UDP filters your version of IPP2P supports. Using -p udp tells IPP2P to analyze UDP traffic. Here is an example howto drop any identified UDP KaZaA packet (TCP is not analyzed with this rule):
    iptables -A FORWARD -p udp -m ipp2p --kazaa -j DROP
    To decrease the number of firewall rules you can use TCP and UDP together in one rule. If you want to drop all (TCP & UDP) KaZaA packets use a rule like this:
    iptables -A FORWARD -m ipp2p --kazaa -j DROP
    During my tests the whole UDP part worked fine - no mismatches occured at all. This does not mean that there can't be any false matches. Please contact me with any comments, experiences or suggestions about UDP handling of IPP2P.

    Connection Tracking
    So far we considered single packets only. From a firewalls view it's not enough to match a single p2p packet but we'll need to consider whole connections to be able to classify as much p2p traffic as possible. We have a single marked packet but what is missing at the moment is a way to assign it to a whole connection so we can handle upcoming packets in the same way like the first match. Therefore we use connection tracking and its extension connection marking. Using CONNMARK let you put a mark on every connection found in the conntrack table by command "--save-mark". Restoring this mark is very easy as well "--restore-mark". For usage have a look at example two and three in the next chapter.

    debug
    You think that IPP2P produces false matches in your setup? Read on. IPP2P has always been intended to match P2P packets and no other traffic. Sometimes we just have a few characteristics to rely on. This increases the chance of false matches. So what can we do to detect false matches? The ideal case for me would be a traffic dump together with the debug output of IPP2P. In version 0.7 --debug was introduced that prints a statement about every single match into the kernel logfile. An entry would look like this:
    Dec 20 14:23:10 box kernel: IPP2P.debug:UDP-match: 201 from: 192.168.0.1:4693 to: 192.168.0.2:2004 Length: 26
    You can see what protocol was matched (UDP in this case), wich hosts were involved and the IP payload length of the packet (26 bytes). For me the most important thing for debugging is the match identifier (201) wich consists of two parts. First part represents the network (2 is --edk - compare with ipt_ipp2p.h) and the last two digits stand for the actual characteristic that identified the packet.
    Try to reproduce the behavior and if you could provide me a network traffic dump where a false match occured it would help me a lot to improve the applied characteristics. Send an email with all collected information. Thank you for your help!
    One final note: --debug will produce many log entries (depending on P2P usage) so make sure to use it for debugging only and not with your permanent ruleset!
    Go to the top of this page

    Examples
    example one:
    01# iptables -A FORWARD -m ipp2p --ipp2p --bit --apple --winmx --soul --ares -j DROP
    
    The first example is a very simple one where IPP2P is used to drop all forwarded P2P packets. It seems to be the only reasonable scenario where CONNMARK is not needed. Using this rule restricts P2P networks usage more or less depending on the know search patterns. eDonkey is well matched by IPP2P and should not work anymore at all (no searches, no connects, no downloads). But it depends on the p2p network what is still working. Downloads are prohibited for every P2P network supported by IPP2P.
    example two:
    01# iptables -t mangle -A PREROUTING -p tcp -j CONNMARK --restore-mark
    02# iptables -t mangle -A PREROUTING -p tcp -m mark ! --mark 0 -j ACCEPT
    03# iptables -t mangle -A PREROUTING -p tcp -m ipp2p --ipp2p -j MARK --set-mark 1
    04# iptables -t mangle -A PREROUTING -p tcp -m mark --mark 1 -j CONNMARK --save-mark
    
    05# iptables -t mangle -A POSTROUTING -o eth0 -m mark --mark 1 -j CLASSIFY --set-class 1:12
    06# iptables -t mangle -A POSTROUTING -o eth1 -m mark --mark 1 -j CLASSIFY --set-class 2:12
    
    This example seems to be the most common way to use IPP2P with TCP. It matches single packets of P2P network traffic (03) and marks them. Afterwards a mark is put on the whole connection (04) by CONNMARK. Rule 01 restores a mark for each incoming packet and the second rule makes sure that an already marked packet won't get marked again (02). All marked packets get sorted into QoS classes depending on their output device (05&06) by the netfilter extension CLASSIFY. Thats the way P2P traffic shaping with IPP2P works. One could easily adapt this example to mark UDP as well.

    Hint:
    With kernel series 2.6. we need to change this setup because -o eth0 does not work anymore if eth0 belongs to a bridge device. This is an adapted example where 01 - 04 are unchanged:
    05# iptables -t mangle -N MARKED
    
    06# iptables -t mangle -A POSTROUTING  -m mark --mark 1 -j MARKED
    
    07# iptables -t mangle -A MARKED -m physdev --physdev-out eth0 -j CLASSIFY --set-class 1:12
    08# iptables -t mangle -A MARKED -m physdev --physdev-out eth1 -j CLASSIFY --set-class 2:12
    
    
    05 creates a new chain MARKED for marked packets and 06 puts every packet marked with 1 into this chain. Rules 07 and 08 sort these packets into QoS classes depending on their physical output interface.
    example three:
    01# iptables -t mangle -A PREROUTING -j CONNMARK --restore-mark
    02# iptables -t mangle -A PREROUTING -m mark ! --mark 0 -j ACCEPT
    03# iptables -t mangle -A PREROUTING -m ipp2p --edk -j MARK --set-mark 1
    04# iptables -t mangle -A PREROUTING -m ipp2p --dc -j MARK --set-mark 2
    05# iptables -t mangle -A PREROUTING -m ipp2p --gnu -j MARK --set-mark 3
    06# iptables -t mangle -A PREROUTING -m ipp2p --kazaa -j MARK --set-mark 4
    07# iptables -t mangle -A PREROUTING -m ipp2p --bit -j MARK --set-mark 5
    08# iptables -t mangle -A PREROUTING -j CONNMARK --save-mark
    
    09# iptables -t mangle -A POSTROUTING -m mark --mark 1 -j ACCEPT
    10# iptables -t mangle -A POSTROUTING -m mark --mark 2 -j ACCEPT
    11# iptables -t mangle -A POSTROUTING -m mark --mark 3 -j ACCEPT
    12# iptables -t mangle -A POSTROUTING -m mark --mark 4 -j ACCEPT
    13# iptables -t mangle -A POSTROUTING -m mark --mark 5 -j ACCEPT
    
    Finally an example where IPP2P is used for statistical purposes. Packets of different P2P networks get different marks (03-07). Like in example two CONNMARK is used to save (08) and restore (01&02) marks but then we add rules to the POSTROUTING chain (09-13) and use the iptables byte and packet counters to sum up P2P usage. Use "iptables -t mangle -L -n -v -x" then to print out the counters for all rules and get an overview of P2P traffic at your link. You could add other supported P2P networks as well - I think through this example you understand how! ;-)
    Go to the top of this page

    Future plans
    The future development of IPP2P is influenced by a number of factors. The main focus lays on integration of further P2P networks (OpenNap and Science2Science for example) to provide a wide spectrum of coverage on P2P filesharing networks. Furthermore intense testing could help to improve and optimize IPP2P. Maintainance and installation improvements (better Makefile, more POM-ng testing) are also on my todo list.
    Since UDP support is introduced to IPP2P it needs a lot of testing as well. I hope to get some feedback from IPP2P users and hopefully we'll be able to do some performance tests in a lab environment using the DAG measurement cards again. The results will be published here.
    If you have any suggestion wich further P2P network to support or what feature to improve feel free to contact me with your feedback.

    "The peer-to-peer sites are impossible to fight. In any given network, peer-to-peer traffic is between 30 and 60 percent of total traffic. We technically cannot control such traffic."

    This is a quote of Mario Mariani, senior vice president of media and access at Tiscali,Europe's third largest IDP. It decribes well the situation we're in at the moment. It's not possible to control all p2p traffic but every step we make to relieve commited networks (company networks, campus networks etc.) helps other network applications by giving them more available bandwidth and lower latency. This may impoves efficiency of application/users and reduces network costs. It's worthwhile to develop and improve filters and cover more P2P networks.
    Go to the top of this page