shorewall_code/docs/IPP2P.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<article>
  <!--$Id$-->

  <articleinfo>
    <title>Shorewall and ipp2p</title>

    <authorgroup>
      <author>
        <firstname>Tom</firstname>

        <surname>Eastep</surname>
      </author>
    </authorgroup>

    <pubdate><?dbtimestamp format="Y/m/d"?></pubdate>

    <copyright>
      <year>2004</year>

      <year>2005</year>

      <year>2006</year>

      <year>2009</year>

      <holder>Thomas M. Eastep</holder>
    </copyright>

    <legalnotice>
      <para>Permission is granted to copy, distribute and/or modify this
      document under the terms of the GNU Free Documentation License, Version
      1.2 or any later version published by the Free Software Foundation; with
      no Invariant Sections, with no Front-Cover, and with no Back-Cover
      Texts. A copy of the license is included in the section entitled
      <quote><ulink url="GnuCopyright.htm">GNU Free Documentation
      License</ulink></quote>.</para>
    </legalnotice>
  </articleinfo>

  <caution>
    <para><emphasis role="bold">This article applies to Shorewall 3.0 and
    later. If you are running a version of Shorewall earlier than Shorewall
    3.0.0 then please see the documentation for that
    release.</emphasis></para>

    <para><emphasis role="bold">If you are running the xtables-addons version
    of IPP2P, you are strongly advised to use Shorewall-perl 4.2.5 or
    later.</emphasis></para>
  </caution>

  <section id="Intro">
    <title>Introduction</title>

    <para>Shorewall versions 2.2.0 and later include support for the ipp2p
    match facility. This is a departure from my usual policy in that the ipp2p
    match facility is included in xtables-addons and is unlikely to ever be
    included in the kernel.org source tree. Questions about how to install
    xtables-addons or how to build your kernel and/or iptables should not be
    posted on the Shorewall mailing lists but should rather be referred to the
    Netfilter Mailing List.</para>
  </section>

  <section id="Scope">
    <title>Scope</title>

    <para>In the following files, the "PROTO" or "PROTOCOL" column may contain
    "ipp2p":</para>

    <simplelist>
      <member><ulink
      url="traffic_shaping.htm">/etc/shorewall/tcrules</ulink></member>

      <member><ulink
      url="Accounting.html">/etc/shorewall/accounting</ulink></member>

      <member><ulink
      url="Shorewall_and_Routing.html">/etc/shorewall/rules</ulink> (Note
      Recommend. But if you insist, then you should place the rules in the
      ESTABLISHED section of that file).</member>
    </simplelist>

    <para>When the PROTO or PROTOCOL column contains "ipp2p" then the DEST
    PORT(S) or PORT(S) column may contain a recognized ipp2p option
    (Shorewall-perl 4.2.5 and later accepts a comma-separated list of
    options); for a list of the options and their meaning, at a root prompt
    type:</para>

    <programlisting><command>iptables -m ipp2p --help</command></programlisting>

    <para>You must not include the leading "--" on the option(s); Shorewall
    will supply those characters for you. If you do not include an option
    then:</para>

    <itemizedlist>
      <listitem>
        <para>Shorewall-shell and Shorewall-perl up through 4.2.4 will assume
        "ipp2p". Note that the xtables-addons version of IPP2P no longer
        supports that option.</para>
      </listitem>

      <listitem>
        <para>Shorewall-perl 4.2.5 and later will assume "ipp2p" if that
        option is supported by the installed iptables/Netfilter. Otherwise,
        Shorewall-perl will assume "edk,kazaa,gnu,dc"</para>
      </listitem>
    </itemizedlist>

    <para>If 'ipp2p' is specified, Shorewall-perl 4.2.5 and later will
    substitute "edk,kazaa,gnu,dc".</para>
  </section>

  <section id="Example">
    <title>Example:</title>

    <para>Example 2 in the ipp2p documentation recommends the following
    iptables rules:</para>

    <programlisting>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</programlisting>

    <para>Let's examine the above rules more carefully.</para>

    <para>The individual packets of a P2P data stream do not all carry
    tell-tale signs that are identifiable as being a particular P2P
    application. So simply asking the ipp2p match code to mark each individual
    packet isn't enough because only those packets that carry these tell-tale
    signs will be marked. Fortunately, Netfilter provides a different type of
    mark -- the <firstterm>Connection Mark</firstterm> which is associated
    with the entry in the conntrack table rather that with the individual
    packet. You can see connection mark values with the <command>shorewall
    show connections</command> command:</para>

    <programlisting>gateway:/etc/test# shorewall show connections
Shorewall-2.5.6 Connections at gateway - Tue Oct  4 15:45:11 PDT 2005

tcp      6 269712 ESTABLISHED src=192.168.3.8 dst=206.124.146.177 sport=50584 dport=993 packets=4899
         bytes=302282 src=206.124.146.177 dst=192.168.3.8 sport=993 dport=50584 packets=7760 bytes=10032928 [ASSURED] <emphasis
        role="bold">mark=0</emphasis> use=1
...</programlisting>

    <para>Connection marks are persistent -- that is, once a connection mark
    is set it retains its value until the connection is terminated.</para>

    <para>Netfilter provides features to:</para>

    <orderedlist>
      <listitem>
        <para>Mark individual packets with a numeric value.</para>
      </listitem>

      <listitem>
        <para>Save the current packet mark value in the connection
        mark.</para>
      </listitem>

      <listitem>
        <para>Restore the value in the connection mark to the current
        packet.</para>
      </listitem>
    </orderedlist>

    <para>The strategy employed in the above rules is to mark the connection
    of each P2P session with a mark value of 1. That way, each packet that is
    part of the session can be marked using the 'Restore' function and can be
    classified accordingly.</para>

    <orderedlist>
      <listitem>
        <para>Rule 01# restores the connection mark into the current
        packet.</para>
      </listitem>

      <listitem>
        <para>Rule 02# tests that restored mark and if it is not equal to
        zero, the packet is ACCEPTed (no further processing).</para>
      </listitem>

      <listitem>
        <para>Rule 03# asks the ipp2p match module to examine the packet and
        if it is identifiable as part of a P2P session, mark the packet with
        value 1.</para>
      </listitem>

      <listitem>
        <para>Rule 04# saves the current packet mark in the conntrack table if
        the current mark value is 1 (in other words, if it was marked by rule
        03#).</para>
      </listitem>

      <listitem>
        <para>Rule 05# classifies the packet to traffic shaping class 1:12 if
        it is going out of eth0 and has mark value 1.</para>
      </listitem>

      <listitem>
        <para>Rule 06# classifies the packet to traffic shaping class 2:12 if
        it is going out of eth1 and has mark value 1.</para>
      </listitem>
    </orderedlist>

    <para>These are implemented in the /etc/shorewall/tcrules file as
    follows:</para>

    <programlisting>#MARK                SOURCE        DEST        PROTO        PORT(S)        CLIENT     USER    TEST
#                                                                          PORT(S)
RESTORE:P            -             -           tcp
CONTINUE:P           -             -           tcp          -              -          -       !0
1:P                  -             -           ipp2p        ipp2p
SAVE:P               -             -           tcp          -              -          -       1
1:12                 -             eth0        -            -              -          -       1
2:12                 -             eth1        -            -              -          -       1    </programlisting>

    <para>These rules do exactly the same thing as their counterparts
    described above.</para>

    <para>One change that I recommend --do your marking in the FORWARD chain
    rather than in the PREROUTING chain:</para>

    <programlisting>#MARK                SOURCE        DEST        PROTO        PORT(S)        CLIENT     USER    TEST
#                                                                          PORT(S)
RESTORE:F            -             -           tcp
CONTINUE:F           -             -           tcp          -              -          -       !0
1:F                  -             -           ipp2p        ipp2p
SAVE:F               -             -           tcp          -              -          -       1
1:12                 -             eth0        -            -              -          -       1
2:12                 -             eth1        -            -              -          -       1    </programlisting>

    <para>It will work the same and will work with a <ulink
    url="MultiISP.html">Multi-ISP setup</ulink>.</para>
  </section>
</article>