Update ipsets document

docs/ipsets.xml

@@ -22,6 +22,8 @@
 
       <year>2008</year>
 
+      <year>2010</year>
+
       <holder>Thomas M. Eastep</holder>
     </copyright>
 
@@ -62,6 +64,11 @@
         contents of an ipset</ulink>. Again, you can then add or delete
         addresses to the ipset without restarting Shorewall.</para>
       </listitem>
+
+      <listitem>
+        <para>In most configuration files when an address list is accepted,
+        the list may include ipsets using the syntax described below.</para>
+      </listitem>
     </orderedlist>
 
     <para>See the ipsets site (URL above) for additional information about
@@ -94,6 +101,24 @@
     <para>To generate a negative match, prefix the "+" with "!" as in
     "!+Mirrors".</para>
 
+    <para>When an ipset name appears in the SOURCE column of a file, Shorewall
+    generates a 'src' match ("-m set --match-set
+    <replaceable>set-name</replaceable> <emphasis role="bold">src</emphasis>")
+    and when the name appears in the DEST column, a 'dst' match is generated
+    (-m set --match-set <replaceable>set-name</replaceable> <emphasis
+    role="bold">dst</emphasis>"). Some set types allow matching on more than
+    one address and require a comma-separated list of 'src' and/or 'dst'
+    flags. This list may be enclosed in square brackets ("[...]") following
+    the set name.</para>
+
+    <para>Example: +setlist[src,dst]</para>
+
+    <para>If the flags are homogenous, you may use an integer to represent the
+    number of entries. In other words, <emphasis role="bold">[2]</emphasis> is
+    equivalent to <emphasis role="bold">[src,src]</emphasis> in the SOURCE
+    column and is equivalent to <emphasis role="bold">[dst,dst]</emphasis> in
+    the DEST column.</para>
+
     <para>Example 1: Blacklist all hosts in an ipset named "blacklist"</para>
 
     <para><filename>/etc/shorewall/blacklist</filename><programlisting>#ADDRESS/SUBNET         PROTOCOL        PORT
@@ -103,50 +128,22 @@
 
     <para><filename>/etc/shorewall/rules</filename><programlisting>#ACTION      SOURCE      DEST     PROTO    DEST PORT(S)
 ACCEPT       net:+sshok  $FW      tcp      22</programlisting></para>
+  </section>
 
-    <para>Shorewall is not in the ipset load/reload business because the
-    Netfilter rule set is never cleared. That means that there is no
-    opportunity for Shorewall to load/reload your ipsets since that cannot be
-    done while there are any current rules using ipsets.</para>
+  <section>
+    <title>Saving/Restoring Ipsets</title>
 
-    <para>So:</para>
+    <para>The SAVE_IPSETS option in <ulink
+    url="manpages/shorewall.conf.html">shorewall.conf </ulink>(5) allows you
+    to have Shorewall automatically save your ipset contents during
+    <command>shorewall stop</command> and restore them during
+    <command>shorewall start</command>. SAVE_IPSETS is implicitly set to
+    <option>Yes</option> when the configuration includes one or more <ulink
+    url="Dynamic.html">dynamic zones</ulink>.</para>
 
-    <orderedlist numeration="upperroman">
-      <listitem>
-        <para>Your ipsets must be loaded before Shorewall starts. You are free
-        to try to do that with the following code in
-        <filename>/etc/shorewall/init (it works for me; your mileage may
-        vary)</filename>:</para>
-
-        <programlisting>if [ "$COMMAND" = start ]; then
-    ipset -F
-    ipset -X
-    ipset -R &lt; /etc/shorewall/ipsets
-fi</programlisting>
-
-        <para>The file <filename>/etc/shorewall/ipsets</filename> will
-        normally be produced using the <command>ipset -S</command>
-        command.</para>
-
-        <para>The above will work most of the time but will fail in a
-        <command>shorewall stop</command> - <command>shorewall start</command>
-        sequence if you use ipsets in your routestopped file (see
-        below).</para>
-      </listitem>
-
-      <listitem>
-        <para>Your ipsets may not be reloaded until Shorewall is stopped or
-        cleared.</para>
-      </listitem>
-
-      <listitem>
-        <para>If you specify ipsets in your routestopped file then Shorewall
-        must be cleared in order to reload your ipsets.</para>
-      </listitem>
-    </orderedlist>
-
-    <para>As a consequence, scripts generated by the Perl-based compiler will
-    ignore <filename>/etc/shorewall/ipsets</filename> and will issue a warning
-    if you set SAVE_IPSETS=Yes in <filename>shorewall.conf</filename></para>
+    <para>When SAVE_IPSETS=Yes, Shorewall disallows ipsets to be specified in
+    <ulink
+    url="manpages/shorewall-routestopped.html">shorewall-routestopped</ulink>
+    (8). </para>
   </section>
 </article>