Documentation updates

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

Shorewall-docs2/Actions.xml

@@ -15,7 +15,7 @@
       </author>
     </authorgroup>
 
-    <pubdate>2005-01-19</pubdate>
+    <pubdate>2005-05-13</pubdate>
 
     <copyright>
       <year>2005</year>
@@ -151,7 +151,7 @@ Reject:REJECT   #Common Action for REJECT policy</programlisting>
   </section>
 
   <section>
-    <title> Defining your own Actions</title>
+    <title>Defining your own Actions</title>
 
     <para>To define a new action:</para>
 
@@ -477,6 +477,9 @@ acton:info:test  fw               net</programlisting>
         <para>$TAG="test"</para>
       </listitem>
     </itemizedlist>
+
+    <para>For an example of how to use these variables, see <ulink
+    url="PortKnocking.html">this article</ulink>.</para>
   </section>
 
   <section id="Extension">
@@ -499,5 +502,8 @@ acton:info:test  fw               net</programlisting>
 
       <para>/etc/shorewall/DropBcasts<programlisting>run_iptables -A DropBcasts -m pkttype --pkttype broadcast -j DROP</programlisting></para>
     </example>
+
+    <para>For a richer example, see <ulink url="PortKnocking.html">this
+    article</ulink>.</para>
   </section>
 </article>

Shorewall-docs2/Documentation_Index.xml

@@ -15,7 +15,7 @@
       </author>
     </authorgroup>
 
-    <pubdate>2005-05-09</pubdate>
+    <pubdate>2005-05-12</pubdate>
 
     <copyright>
       <year>2001-2005</year>
@@ -439,6 +439,10 @@
       </itemizedlist>
     </listitem>
 
+    <listitem>
+      <para><ulink url="PortKnocking.html">Port Knocking</ulink></para>
+    </listitem>
+
     <listitem>
       <para><ulink url="PPTP.htm">PPTP</ulink></para>
     </listitem>

Shorewall-docs2/FAQ.xml

@@ -17,7 +17,7 @@
       </author>
     </authorgroup>
 
-    <pubdate>2005-05-09</pubdate>
+    <pubdate>2005-05-10</pubdate>
 
     <copyright>
       <year>2001-2005</year>
@@ -77,7 +77,7 @@
       not modify those files.</para>
     </section>
 
-    <section>
+    <section id="faq44">
       <title>(FAQ 44) I can't install/upgrade the RPM — I keep getting the
       message "error: failed dependencies:iproute is needed..."</title>
 
@@ -320,6 +320,14 @@ DNAT    net     fw:192.168.1.1:22       tcp     4104</programlisting>
       url="http://ian.idallen.ca/dnat.txt">Paper about DNAT and
       Linux</ulink>.</para>
     </section>
+
+    <section id="faq48">
+      <title>(FAQ 48) How do I Set up Transparent Proxy with
+      Shorewall?</title>
+
+      <para>Answer: See <ulink
+      url="Shorewall_Squid_Usage.html">Shorewall_Squid_Usage.html</ulink>.</para>
+    </section>
   </section>
 
   <section>
@@ -554,10 +562,9 @@ really dumb and does not deserve to exist at all. It was an excellent tool
 to debug/develop the newnat interface.</programlisting></para>
       </blockquote>
 
-      <para>Look <ulink url="http://linux-igd.sourceforge.net">here</ulink>
+      <para>Look <ulink url="UPnP.html">here</ulink> for a solution for MSN IM
-      for a solution for MSN IM but be aware that there are significant
+      but be aware that there are significant security risks involved with
-      security risks involved with this solution. Also check the Netfilter
+      this solution. Also check the Netfilter mailing list archives at <ulink
-      mailing list archives at <ulink
       url="http://www.netfilter.org">http://www.netfilter.org</ulink>.</para>
     </section>
   </section>
@@ -757,6 +764,33 @@ SPT=33120 DPT=5000 LEN=22</programlisting>
 #                                               ZONE
 generic:udp:5000        net     69.145.71.133</programlisting>
     </section>
+
+    <section id="faq47">
+      <title>(FAQ 47) This Rule Doesn't Work as Documented</title>
+
+      <para>I want to allow access from the local zone to the net except for
+      two systems (192.168.100.101 and 192.168.100.115). I use the following
+      rule but find that 192.168.100.115 can still access the net. Is this a
+      bug?</para>
+
+      <programlisting>#ACTION        SOURCE                                 DEST          PROTO
+ACCEPT         loc:!192.168.100.101,192.168.100.115   net</programlisting>
+
+      <para><emphasis role="bold">Answer</emphasis>: Shorewall is currently
+      inconsistent as to where it correctly supports the "!" before a list of
+      addresses. In some places, it works as you would expect and in other
+      cases such as this one it does not. You will need to take a different
+      approach to accomplish what you want. I recommend that you change your
+      loc-&gt;net policy to ACCEPT and then use this rule:</para>
+
+      <programlisting>#ACTION        SOURCE                                 DEST          PROTO
+REJECT         loc:192.168.100.101,192.168.100.115    net</programlisting>
+
+      <para><emphasis role="bold">Author's Note</emphasis>: I have looked
+      several times at correcting this problem but it really isn't feasible
+      until I muster the energy to rewrite the Shorewall rules parser.
+      Sorry.</para>
+    </section>
   </section>
 
   <section>
@@ -2183,9 +2217,14 @@ REJECT    fw            net:216.239.39.99    all</programlisting>Given that
       <title>(FAQ 42) How can I tell which features my kernel and iptables
       support?</title>
 
-      <para>Answer: At a root prompt, enter the command <command>shorewall
+      <para>Answer: Users running Shorewall 2.2.4 or later can simply use the
-      check</command>. There is a section near the top of the resulting output
+      <command>shorewall show capabilities</command> command at a root
-      that gives you a synopsis of your kernel/iptables capabilities.</para>
+      prompt.</para>
+
+      <para>For those running older versions, at a root prompt, enter the
+      command <command>shorewall check</command>. There is a section near the
+      top of the resulting output that gives you a synopsis of your
+      kernel/iptables capabilities.</para>
 
       <programlisting>gateway:/etc/shorewall # shorewall check
 Loading /usr/share/shorewall/functions...

Shorewall-docs2/IPSEC-2.6.xml

@@ -15,7 +15,7 @@
       </author>
     </authorgroup>
 
-    <pubdate>2005-05-02</pubdate>
+    <pubdate>2005-05-11</pubdate>
 
     <copyright>
       <year>2004</year>
@@ -50,6 +50,48 @@
     <para>You must have <emphasis role="bold">BOTH</emphasis> the
     Netfilter+ipsec patches and the policy match patch. <emphasis
     role="bold">One without the other will not work</emphasis>.</para>
+
+    <para>Here's a combination of components that I know works:</para>
+
+    <orderedlist>
+      <listitem>
+        <para>Kernel 2.6.11 from kernel.org. Patched with:</para>
+
+        <itemizedlist>
+          <listitem>
+            <para>The five patches in <ulink
+            url="http://shorewall.net/pub/shorewall/contrib/IPSEC/2.6.11">http://shorewall.net/pub/shorewall/contrib/IPSEC/2.6.11</ulink></para>
+          </listitem>
+
+          <listitem>
+            <para>The "policy match" extension from the Patch-o-matic-ng CVS
+            snapshot from 2005-May-04 (be sure to NOT try to apply the
+            ipsec-NN patches from patch-o-matic-ng).</para>
+          </listitem>
+        </itemizedlist>
+      </listitem>
+
+      <listitem>
+        <para>iptables 1.3.1 patched with the "policy match" extension from
+        the Patch-o-matic-ng CVS snapshot from 2005-May-04.</para>
+      </listitem>
+
+      <listitem>
+        <para>ipsec-tools 0.5.2 compiled from source. I've also had success
+        with:</para>
+
+        <itemizedlist>
+          <listitem>
+            <para>ipsec-tools 0.5.2 and racoon 0.5.2 from Debian
+            Sarge/testing</para>
+          </listitem>
+
+          <listitem>
+            <para>The ipsec-tools 0.5 rpm from SuSE 9.3.</para>
+          </listitem>
+        </itemizedlist>
+      </listitem>
+    </orderedlist>
   </important>
 
   <warning>
@@ -194,6 +236,13 @@
     of) SA(s) used to encrypt and decrypt traffic to/from the zone and the
     security policies that select which traffic to encrypt/decrypt.</para>
 
+    <para>This article assumes the use of ipsec-tools (<ulink
+    url="http://ipsec-tools.sourceforge.net">http://ipsec-tools.sourceforge.net</ulink>).
+    As of this writing, I recommend that you run at least version 0.5.2.
+    Debian users, please note that there are separate Debian packages for
+    ipsec-tools and racoon although the ipsec-tools project releases them as a
+    single package.</para>
+
     <para>For more information on IPSEC, Kernel 2.6 and Shorewall see <ulink
     url="LinuxFest.pdf">my presentation on the subject given at LinuxFest NW
     2005</ulink>.</para>
@@ -773,7 +822,7 @@ all             all             REJECT          info
       url="http://www.ipsec-howto.org/">http://www.ipsec-howto.org/</ulink>.</para>
 
       <para>One piece of information that may not be so easy to find is "How
-      to I generate a PKCS#12 certificate to import into Windows?". Here's the
+      do I generate a PKCS#12 certificate to import into Windows?". Here's the
       openssl command that I used:</para>
 
       <programlisting><command>openssl pkcs12 -export -in eastepnc6000.pem -inkey eastepnc6000_key.pem -out eastepnc6000.pfx -name "IPSEC Cert for Home Wireless"</command> </programlisting>
@@ -785,18 +834,19 @@ all             all             REJECT          info
 
       <itemizedlist>
         <listitem>
-          <para>eastepnc6000.pem was the laptop's certificate in PEM
+          <para><filename>eastepnc6000.pem</filename> was the laptop's
-          format.</para>
+          certificate in PEM format.</para>
         </listitem>
 
         <listitem>
-          <para>eastepnc6000_key.pem was the laptop's private key (actually,
+          <para><filename>eastepnc6000_key.pem</filename> was the laptop's
-          it's the original signing request which includes the private
+          private key (actually, it's the original signing request which
-          key).</para>
+          includes the private key).</para>
         </listitem>
 
         <listitem>
-          <para>eastepnc6000.pfx is the PKCS#12 output file.</para>
+          <para><filename>eastepnc6000.pfx</filename> is the PKCS#12 output
+          file.</para>
         </listitem>
 
         <listitem>
@@ -813,4 +863,13 @@ all             all             REJECT          info
       different dialog boxes on Windows XP!!!</para>
     </warning>
   </section>
+
+  <section>
+    <title>Source of Additional Samples</title>
+
+    <para>Be sure to check out the <filename
+    class="directory">src/racoon/samples</filename> subdirectory in the
+    ipsec-tools source tree. It has a wide variety of sample racoon
+    configuration files.</para>
+  </section>
 </article>

Shorewall-docs2/Install.xml

@@ -185,10 +185,13 @@ INIT="rc.firewall"</programlisting>
 
       <listitem>
         <para>If you are running Slackware and are installing Shorewall 2.0.3
-        Beta 1 or later, then type:</para>
+        Beta 1 to Shorewall 2.2.3, then type:</para>
 
         <programlisting><emphasis role="bold">DEST=/etc/rc.d INIT=rc.firewall ./install.sh</emphasis></programlisting>
 
+	<para>If you are running Slackware and are installing Shorewall 2.2.4 or later, then type:</para>
+	<programlisting><command>./install.sh</command></programlisting>
+
         <para>Otherwise, type:</para>
 
         <programlisting><command>./install.sh</command></programlisting>

Shorewall-docs2/PortKnocking.xml

@@ -0,0 +1,129 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<article>
+  <!--$Id$-->
+
+  <articleinfo>
+    <title>Port Knocking</title>
+
+    <authorgroup>
+      <author>
+        <firstname>Tom</firstname>
+
+        <surname>Eastep</surname>
+      </author>
+    </authorgroup>
+
+    <pubdate>2005-05-13</pubdate>
+
+    <copyright>
+      <year>2005</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 SHby 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>
+
+  <section>
+    <title>What is Port Knocking?</title>
+
+    <para>Port knocking is a technique whereby attempting to connect to port A
+    enables access to port B from that same host. For the example on which
+    this article is based, see <ulink
+    url="http://www.soloport.com/iptables.html">http://www.soloport.com/iptables.html</ulink>
+    which should be considered to be part of this documentation.</para>
+  </section>
+
+  <section>
+    <title>Implementing Port Knocking in Shorewall</title>
+
+    <para>In order to implement this solution, your iptables and kernel must
+    support the 'recent match' extension (see <ulink url="FAQ.htm#faq42">FAQ
+    42</ulink>). These instructions also assume Shorewall version 2.2.0 or
+    later.</para>
+
+    <para>In this example:</para>
+
+    <orderedlist>
+      <listitem>
+        <para>Attempting to connect to port 1600 enables SSH access.</para>
+      </listitem>
+
+      <listitem>
+        <para>Attempting to connect to port 1601 disables SSH access (note
+        that in the article linked above, attempting to connect to port 1599
+        also disables access. This is an port scan defence as explained in the
+        article). </para>
+      </listitem>
+    </orderedlist>
+
+    <para>To implement that approach:</para>
+
+    <orderedlist>
+      <listitem>
+        <para>Add an action named SSHKnock (see the <ulink
+        url="Actions.html">Action documentation</ulink>). Leave the
+        <filename>action.SSHKnock</filename> file empty.</para>
+      </listitem>
+
+      <listitem>
+        <para>Create /etc/shorewall/SSHKnock with the following
+        contents:</para>
+
+        <programlisting>if [ -n "$LEVEL" ]; then
+    log_rule_limit $LEVEL $CHAIN SSHKnock ACCEPT "" "$TAG" -A -p tcp --dport 22   -m recent --rcheck --name SSH
+    log_rule_limit $LEVEL $CHAIN SSHKnock DROP   "" "$TAG" -A -p tcp --dport ! 22
+fi
+run_iptables -A $CHAIN -p tcp --dport 22   -m recent --rcheck --name SSH          -j ACCEPT
+run_iptables -A $CHAIN -p tcp --dport 1599 -m recent          --name SSH --remove -j DROP
+run_iptables -A $CHAIN -p tcp --dport 1600 -m recent          --name SSH --set    -j DROP
+run_iptables -A $CHAIN -p tcp --dport 1601 -m recent          --name SSH --remove -j DROP</programlisting>
+      </listitem>
+
+      <listitem>
+        <para>Now if you want to protect SSH access to the firewall from the
+        Internet, add this rule in
+        <filename>/etc/shorewall/rules</filename>:</para>
+
+        <programlisting>#ACTION          SOURCE            DEST           PROTO       DEST PORT(S)
+SSHKnock         net               fw             tcp         22,1599,1600,1601</programlisting>
+
+        <para>If you want to log the DROPs and ACCEPTs done by SSHKnock, you
+        can just add a log level as in:</para>
+
+        <programlisting>#ACTION          SOURCE            DEST           PROTO       DEST PORT(S)
+SSHKnock:info    net               fw             tcp         22,1599,1600,1601</programlisting>
+      </listitem>
+
+      <listitem>
+        <para>If you wish to use SSHKnock with a forwarded connection, you
+        must be using Shorewall 2.3.1 or later for fullest protection. Assume
+        that you forward port 22 from external IP address 206.124.146.178 to
+        internal system 192.168.1.5 In /etc/shorewall/rules:</para>
+
+        <programlisting>#ACTION          SOURCE            DEST            PROTO       DEST PORT(S)  SOURCE      ORIGINAL
+#                                                                            PORT(S)     DEST
+DNAT-            net               loc:192.168.1.5 tcp         22            -           206.124.146.178
+SSHKnock         net               fw              tcp         1599,1600,1601
+SSHKnock         net               loc:192.168.1.5 tcp         22            -           206.124.146.178</programlisting>
+
+        <note>
+          <para>You can use SSHKnock with DNAT on earlier releases provided
+          that you omit the ORIGINAL DEST entry on the second SSHKnock rule.
+          This rule will be quite secure provided that you specify 'norfc1918'
+          on your external interface.</para>
+        </note>
+      </listitem>
+    </orderedlist>
+  </section>
+</article>

Shorewall-docs2/shorewall_extension_scripts.xml

@@ -15,7 +15,7 @@
       </author>
     </authorgroup>
 
-    <pubdate>2005-04-06</pubdate>
+    <pubdate>2005-05-13</pubdate>
 
     <copyright>
       <year>2001-2005</year>
@@ -131,6 +131,53 @@
       <filename>/var/lib/shorewall/restore</filename> exists).</para>
     </listitem>
 
+    <listitem>
+      <para>If you wish to generate a log message, use <emphasis
+      role="bold">log_rule_limit</emphasis>. Parameters are:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>Log Level</para>
+        </listitem>
+
+        <listitem>
+          <para>Chain to insert the rule into</para>
+        </listitem>
+
+        <listitem>
+          <para>Chain name to display in the message (this can be different
+          from the preceding argument — see the <ulink
+          url="PortKnocking.html">Port Knocking article</ulink> for an example
+          of how to use this).</para>
+        </listitem>
+
+        <listitem>
+          <para>Disposition to report in the message (ACCEPT, DROP,
+          etc)</para>
+        </listitem>
+
+        <listitem>
+          <para>Rate Limit (if passed as "" then $LOGLIMIT is assumed — see
+          the LOGLIMIT option in <ulink
+          url="Documentation.htm#Conf">/etc/shorewall/shorewall.conf</ulink>)
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>Log Tag ("" if none)</para>
+        </listitem>
+
+        <listitem>
+          <para>Command (-A or -I for append or insert). This argument applies
+          to Shorewall 2.2.0 and later only.</para>
+        </listitem>
+
+        <listitem>
+          <para>The remaining arguments are passed "as is" to iptables</para>
+        </listitem>
+      </itemizedlist>
+    </listitem>
+
     <listitem>
       <para>With Shorewall 2.0.2 Beta 1 and later versions, if you run
       commands other than <command>iptables</command> that must be re-run in