Document per-IP accounting

Shorewall/changelog.txt

@@ -6,6 +6,8 @@ Changes in Shorewall 4.4.17 Beta 3
 
 3)  Correct two defects in compiler module loading.
 
+4)  Implement per-IP module loading.
+
 Changes in Shorewall 4.4.17 Beta 2
 
 1)  Handle line containing only INCLUDE.

Shorewall/releasenotes.txt

@@ -16,11 +16,14 @@ VI.   PROBLEMS CORRECTED AND NEW FEATURES IN PRIOR RELEASES
 
 Beta 3
 
-1)  If the SOURCE column in /etc/shorewall6/rules contained [<address>],
+1)  If the SOURCE column in /etc/shorewall6/rules contained an IPv6
-    a spurious error was generated:
+    address enclosed in [...], a spurious error was generated:
 
       ERROR: Invalid VLSM (0]) : /etc/shorewall6/rules (line 20)
 
+    The error did not occur if <...> was used to enclose the IPv6
+    address.
+
 2)  Two compiler defects in module loading have been corrected:
 
     a) Previously, the kernel/net/ipv6/netfilter/ directory was not
@@ -69,6 +72,58 @@ Beta 1
       I I I.  N E W   F E A T U R E S   I N   T H I S  R E L E A S E
 ----------------------------------------------------------------------------
 
+Beta 3
+
+1)  This release adds support for per-IP accounting using the ACCOUNT
+    target. That target is only available when xtables-addons is
+    installed. This support has been successfully tested with
+    xtables-addons 1.32 on:
+
+    - Fedora 14
+    - Debian Squeeze
+
+    Versions of xtables-addons supporting the ACCOUNT target do not
+    install successfully on Debian Lenny.
+
+    Information about xtables-addons installation may be found at
+    http://www.shorewall.net/Dynamic.html#xtables-addons
+
+    This feature required addition of the "ACCOUNT Target" capability
+    so if you use a capabilities file, you will want to refresh it
+    after installing this release.
+
+    Per-IP accounting is configured in /etc/shorewall/accounting (it is
+    not currently supported in IPv6). In the ACTION column, enter:
+
+       ACCOUNT(<table>,<network>)
+
+    where:
+
+       <table> is the name of an accounting table (you choose the
+       	       name). Rules specifying the same table will have their
+       	       per-IP counters accumulated in that table.
+
+       <network> is an IPv4 in CIDR format. May be as large as a /8.
+
+    Example: Suppose your WAN interface is eth0 and your LAN interface
+    	     is eth1 with network 172.20.1.0/24. To account for all
+    	     traffic between the WAN and LAN interfaces:
+
+	#ACTION                        TABLE     SOURCE        DEST ...
+	ACCOUNT(net-loc,172.20.1.0/24) -         eth0          eth1
+	ACCOUNT(net-loc,172.20.1.0/24) -         eth0          eth1
+
+    This will create a net-loc table for counting packets and
+    bytes for traffic between the two interfaces. The table is dumped
+    using the iptaccount utility:
+
+    	iptaccount [-f] -l net-loc
+
+    For each local IP address with non-zero counters, the packet and
+    byte count for both incoming traffic (IP is DST) and outgoing
+    traffic (IP is SRC) are listed. The -f option causes the table to
+    be flushed (reset all counters to zero). 
+
 Beta 2
 
 1)  Traditionally, the -lite products have used the modules (or

docs/Accounting.xml

@@ -243,4 +243,71 @@
     traffic activity. The article may be found at <ulink
     url="http://collectd.org/wiki/index.php/Plugin:IPTables">http://collectd.org/wiki/index.php/Plugin:IPTables</ulink>.</para>
   </section>
+
+  <section id="perIP">
+    <title>Per-IP Accounting</title>
+
+    <para>Shorewall 4.4.17 added support for per-IP accounting using the
+    ACCOUNT target. That target is only available when xtables-addons is
+    installed. This support has been successfully tested with xtables-addons
+    1.32 on:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>Fedora 14</para>
+      </listitem>
+
+      <listitem>
+        <para>Debian Squeeze</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Versions of xtables-addons supporting the ACCOUNT target do not
+    install successfully on Debian Lenny.</para>
+
+    <para>Information about xtables-addons installation may be found at <ulink
+    url="Dynamic.html#xtables-addons">here</ulink>.</para>
+
+    <para>Per-IP accounting is configured in <ulink
+    url="manpages/shorewall-accounting.html">shorewall-accounting</ulink> (5)
+    (it is currently not supported in IPv6). In the ACTION column,
+    enter:</para>
+
+    <simplelist>
+      <member><emphasis
+      role="bold">ACCOUNT(</emphasis><replaceable>table</replaceable>,<replaceable>network</replaceable><emphasis
+      role="bold">)</emphasis></member>
+    </simplelist>
+
+    <para>where</para>
+
+    <simplelist>
+      <member><replaceable>table</replaceable> is the name of an accounting
+      table (you choose the name). All rules specifying the same table will
+      have their per-IP counters accumulated in that table.</member>
+
+      <member><replaceable>network</replaceable> is an IPv4 network in CIDR
+      notation. The network can be as large as a /8 (class A).</member>
+    </simplelist>
+
+    <para>Example: Suppose your WAN interface is eth0 and your LAN interface
+    is eth1 with network 172.20.1.0/24. To account for all traffic between the
+    WAN and LAN interfaces:</para>
+
+    <programlisting>#ACTION                         CHAIN        SOURCE              DEST          ...
+ACCOUNT(net-loc,172.20.1.0/24)  -            eth0                eth1
+ACCOUNT(net-loc,172.20.1.0/24)  -            eth1                eth0</programlisting>
+
+    <para>This will create a <emphasis role="bold">net-loc</emphasis> table
+    for counting packets and bytes for traffic between the two interfaces. The
+    table is dumped using the <command>iptaccount</command> utility (part of
+    xtables-addons):</para>
+
+    <programlisting><command>iptaccount [-f] -l net-loc</command></programlisting>
+
+    <para>For each local IP address with non-zero counters, the packet and
+    byte count for both incoming traffic (IP is DST) and outgoing traffic (IP
+    is SRC) are listed. The -f option causes the table to be flushed (reset
+    all counters to zero) after printing. </para>
+  </section>
 </article>

manpages/shorewall-accounting.xml

@@ -35,7 +35,7 @@
         <term><emphasis role="bold">ACTION</emphasis> - {<emphasis
         role="bold">COUNT</emphasis>|<emphasis
         role="bold">DONE</emphasis>|<emphasis>chain</emphasis>[:<emphasis
-        role="bold">{COUNT</emphasis>:JUMP}]|COUNT
+        role="bold">{COUNT</emphasis>:JUMP}]|ACCOUNT(<replaceable>table</replaceable>,<replaceable>network</replaceable>)|COUNT
         <emphasis>comment</emphasis>}</term>
 
         <listitem>
@@ -86,6 +86,40 @@
               </listitem>
             </varlistentry>
 
+            <varlistentry>
+              <term><emphasis
+              role="bold">ACCOUNT(</emphasis><replaceable>table</replaceable>,<replaceable>network</replaceable><emphasis
+              role="bold">)</emphasis></term>
+
+              <listitem>
+                <para>This action implements per-IP accounting and was added
+                in Shoreall 4.4.17. Requires the <emphasis>ACCOUNT
+                Target</emphasis> capability in your iptables and kernel (see
+                the output of <command>shorewall show
+                capabilities</command>).</para>
+
+                <simplelist>
+                  <member><replaceable>table</replaceable> is the name of an
+                  accounting table (you choose the name). All rules specifying
+                  the same table will have their per-IP counters accumulated
+                  in that table.</member>
+
+                  <member><replaceable>network</replaceable> is an IPv4
+                  network in CIDR notation. The network can be as large as a
+                  /8 (class A).</member>
+                </simplelist>
+
+                <para>The counters in a <replaceable>table</replaceable> are
+                printed using the <command>iptaccount</command> utility. As of
+                February 2011, the ACCOUNT Target capability and the
+                iptaccount utility are only available when <ulink
+                url="http://xtables-addons.sourceforge.net/">xtables-addons</ulink>
+                is installed. See <ulink
+                url="http://www.shorewall.net/Accounting.html#perIP">http://www.shorewall.net/Accounting.html#perIP</ulink>
+                for additional information.</para>
+              </listitem>
+            </varlistentry>
+
             <varlistentry>
               <term>COMMENT</term>