Document change to accounting rule structure with bridges

git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@6692 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb

Shorewall-common/releasenotes.txt

@@ -211,6 +211,28 @@ Migration Considerations:
 
 	lan	eth1:192.168.2.0/24	...
 
+       The structure of the accounting rules changes slightly when
+       there are bridges defined in the Shorewall
+       configuration. Because of the restrictions imposed by Netfilter
+       in kernel 2.6.21 and later, output accounting rules must be
+       segregated from forwarding and input rules.
+
+       To accomplish this separation, Shorewall-perl creates two
+       accounting chains:
+
+       - accounting - for input and forwarded traffic.
+       - accountout - for output traffic.
+
+       If the CHAIN column contains '-', then:
+
+       - If the SOURCE column in a rule includes the name of the
+         firewall zone (e.g., $FW), then the default chain to insert
+         the rule into is accountout only.
+
+       - Otherwise, if the DEST in the rule is any or all or 0.0.0.0/0,
+	 then the rule is added to both accounting and accountout.
+
+       - Otherwise, the rule is added to accounting only.	
 
     d) The BROADCAST column in the interfaces file is essentially unused;
        if you enter anything in this column but '-' or 'detect', you will

docs/Accounting.xml

@@ -41,9 +41,12 @@
     release</emphasis>.</para>
   </caution>
 
+  <section id="Basics">
+    <title>Accounting Basics</title>
+
     <para>Shorewall accounting rules are described in the file
-  /etc/shorewall/accounting. By default, the accounting rules are placed in a
+    /etc/shorewall/accounting. By default, the accounting rules are placed in
-  chain called <quote>accounting</quote> and can thus be displayed using
+    a chain called <quote>accounting</quote> and can thus be displayed using
     <quote>shorewall[-lite] show accounting</quote>. All traffic passing into,
     out of, or through the firewall traverses the accounting chain including
     traffic that will later be rejected by interface options such as
@@ -56,30 +59,31 @@
 
     <itemizedlist>
       <listitem>
-      <para><emphasis role="bold">ACTION </emphasis>- What to do when a match
+        <para><emphasis role="bold">ACTION </emphasis>- What to do when a
-      is found. Possible values are:</para>
+        match is found. Possible values are:</para>
 
         <itemizedlist>
           <listitem>
-          <para>COUNT- Simply count the match and continue trying to match the
+            <para>COUNT- Simply count the match and continue trying to match
-          packet with the following accounting rules</para>
+            the packet with the following accounting rules</para>
           </listitem>
 
           <listitem>
-          <para>DONE- Count the match and don't attempt to match any following
+            <para>DONE- Count the match and don't attempt to match any
-          accounting rules.</para>
+            following accounting rules.</para>
           </listitem>
 
           <listitem>
             <para><emphasis>&lt;chain&gt;</emphasis> - The name of a chain to
-          jump to. Shorewall will create the chain automatically. If the name
+            jump to. Shorewall will create the chain automatically. If the
-          of the chain is followed by <quote>:COUNT</quote> then a COUNT rule
+            name of the chain is followed by <quote>:COUNT</quote> then a
-          matching this rule will automatically be added to &lt;chain&gt;.
+            COUNT rule matching this rule will automatically be added to
-          Chain names must start with a letter, must be composed of letters
+            &lt;chain&gt;. Chain names must start with a letter, must be
-          and digits, and may contain underscores (<quote>_</quote>) and
+            composed of letters and digits, and may contain underscores
-          periods (<quote>.</quote>). Beginning with Shorewall version 1.4.8,
+            (<quote>_</quote>) and periods (<quote>.</quote>). Beginning with
-          chain names may also contain embedded dashes (<quote>-</quote>) and
+            Shorewall version 1.4.8, chain names may also contain embedded
-          are not required to start with a letter.</para>
+            dashes (<quote>-</quote>) and are not required to start with a
+            letter.</para>
           </listitem>
         </itemizedlist>
       </listitem>
@@ -87,25 +91,26 @@
       <listitem>
         <para><emphasis role="bold">CHAIN</emphasis> - The name of the chain
         where the accounting rule is to be added. If empty or <quote>-</quote>
-      then the <quote>accounting</quote> chain is assumed.</para>
+        then the <quote>accounting</quote> chain is assumed (see <link
+        linkend="Bridge">below</link> for exceptions).</para>
       </listitem>
 
       <listitem>
-      <para><emphasis role="bold">SOURCE</emphasis> - Packet Source. The name
+        <para><emphasis role="bold">SOURCE</emphasis> - Packet Source. The
-      of an interface, an address (host or net), or an interface name followed
+        name of an interface, an address (host or net), or an interface name
-      by <quote>:</quote> and a host or net address.</para>
+        followed by <quote>:</quote> and a host or net address.</para>
       </listitem>
 
       <listitem>
-      <para><emphasis role="bold">DESTINATION</emphasis> - Packet Destination
+        <para><emphasis role="bold">DESTINATION</emphasis> - Packet
-      Format the same as the SOURCE column.</para>
+        Destination Format the same as the SOURCE column.</para>
       </listitem>
 
       <listitem>
-      <para><emphasis role="bold">PROTOCOL</emphasis> - A protocol name (from
+        <para><emphasis role="bold">PROTOCOL</emphasis> - A protocol name
-      <filename>/etc/protocols</filename>), a protocol number or "ipp2p". For
+        (from <filename>/etc/protocols</filename>), a protocol number or
-      "ipp2p", your kernel and iptables must have ipp2p match support from
+        "ipp2p". For "ipp2p", your kernel and iptables must have ipp2p match
-      <ulink url="http://www.netfilter.org">Netfilter
+        support from <ulink url="http://www.netfilter.org">Netfilter
         Patch_o_matic_ng</ulink>.</para>
       </listitem>
 
@@ -113,21 +118,22 @@
         <para><emphasis role="bold">DEST PORT</emphasis> - Destination Port
         number. Service name from <filename>/etc/services</filename> or port
         number. May only be specified if the protocol is TCP or UDP (6 or 17).
-      If the PROTOCOL is "ipp2p", then this column is interpreted as an ipp2p
+        If the PROTOCOL is "ipp2p", then this column is interpreted as an
-      option without the leading "--" (default "ipp2p"). For a list of value
+        ipp2p option without the leading "--" (default "ipp2p"). For a list of
-      ipp2p options, as root type <command>iptables -m ipp2p
+        value ipp2p options, as root type <command>iptables -m ipp2p
         --help</command>.</para>
       </listitem>
 
       <listitem>
-      <para><emphasis role="bold">SOURCE PORT</emphasis>- Source Port number.
+        <para><emphasis role="bold">SOURCE PORT</emphasis>- Source Port
-      Service name from /etc/services or port number. May only be specified if
+        number. Service name from /etc/services or port number. May only be
-      the protocol is TCP or UDP (6 or 17).</para>
+        specified if the protocol is TCP or UDP (6 or 17).</para>
       </listitem>
 
       <listitem>
-      <para><emphasis role="bold">USER/GROUP</emphasis> - This column may only
+        <para><emphasis role="bold">USER/GROUP</emphasis> - This column may
-      be non-empty if the CHAIN is OUTPUT. The column may contain:</para>
+        only be non-empty if the CHAIN is OUTPUT. The column may
+        contain:</para>
 
         <programlisting> [!][&lt;user name or number&gt;][:&lt;group name or number&gt;][+&lt;program name&gt;]</programlisting>
 
@@ -159,14 +165,14 @@
 
     <para>The accounting rules are evaluated in the Netfilter
     <quote>filter</quote> table. This is the same environment where the
-  <quote>rules</quote> file rules are evaluated and in this environment, DNAT
+    <quote>rules</quote> file rules are evaluated and in this environment,
-  has already occurred in inbound packets and SNAT has not yet occurred on
+    DNAT has already occurred in inbound packets and SNAT has not yet occurred
-  outbound ones.</para>
+    on outbound ones.</para>
 
-  <para>Accounting rules are not stateful -- each rule only handles traffic in
+    <para>Accounting rules are not stateful -- each rule only handles traffic
-  one direction. For example, if eth0 is your internet interface, and you have
+    in one direction. For example, if eth0 is your internet interface, and you
-  a web server in your DMZ connected to eth1, then to count HTTP traffic in
+    have a web server in your DMZ connected to eth1, then to count HTTP
-  both directions requires two rules:</para>
+    traffic in both directions requires two rules:</para>
 
     <programlisting>        #ACTION CHAIN   SOURCE  DESTINATION     PROTOCOL        DEST            SOURCE
         #                                                       PORT            PORT
@@ -225,7 +231,9 @@
      Chain accounting (3 references)
          pkts bytes target     prot opt in     out     source               destination
          8767  727K web        tcp  --  eth0   eth1    0.0.0.0/0            0.0.0.0/0          tcp dpt:80
-            0     0 web        tcp  --  eth0   eth1    0.0.0.0/0            0.0.0.0/0          tcp dpt:443
+            0     0 web        tcp  --  eth0   eth1    0.0.0.0/0            0.0.0.0/0          tcp dpt:443</programlisting>
+
+    <programlisting>
         11506   13M web        tcp  --  eth1   eth0    0.0.0.0/0            0.0.0.0/0          tcp spt:80
             0     0 web        tcp  --  eth1   eth0    0.0.0.0/0            0.0.0.0/0          tcp spt:443
 
@@ -279,4 +287,51 @@
     <para>For an example of integrating Shorewall Accounting with MRTG, see
     <ulink
     url="http://www.nightbrawler.com/code/shorewall-stats/">http://www.nightbrawler.com/code/shorewall-stats/</ulink>.</para>
+  </section>
+
+  <section id="Bridge">
+    <title>Accounting with Bridges</title>
+
+    <para>The structure of the accounting rules changes slightly when there
+    are <ulink url="bridge-Shorewall-perl.html">bridges</ulink> defined in the
+    Shorewall configuration. Because of the restrictions imposed by Netfilter
+    in kernel 2.6.21 and later, output accounting rules must be segregated
+    from forwarding and input rules. To accomplish this separation,
+    Shorewall-perl creates two accounting chains:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para><emphasis role="bold">accounting</emphasis> - for input and
+        forwarded traffic.</para>
+      </listitem>
+
+      <listitem>
+        <para><emphasis role="bold">accountout</emphasis> - for output
+        traffic.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>If the CHAIN column contains '-', then:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>If the SOURCE column in a rule includes the name of the firewall
+        zone (e.g., $FW), then the default chain to insert the rule into is
+        <emphasis role="bold">accountout</emphasis> only.</para>
+      </listitem>
+
+      <listitem>
+        <para>Otherwise, if the DEST in the rule is <emphasis
+        role="bold">any</emphasis> or <emphasis role="bold">all</emphasis> or
+        0.0.0.0/0, then the rule is added to both <emphasis
+        role="bold">accounting</emphasis> and <emphasis
+        role="bold">accountout</emphasis>.</para>
+      </listitem>
+
+      <listitem>
+        <para>Otherwise, the rule is added to <emphasis
+        role="bold">accounting</emphasis> only.</para>
+      </listitem>
+    </itemizedlist>
+  </section>
 </article>