Document new Dynamic Zone implementation

Signed-off-by: Tom Eastep <teastep@shorewall.net>

Shorewall/manpages/shorewall-zones.xml

@@ -227,6 +227,19 @@ c:a,b     ipv4</programlisting>
               </listitem>
             </varlistentry>
 
+            <varlistentry>
+              <term><emphasis role="bold">dynamic_shared</emphasis></term>
+
+              <listitem>
+                <para>Added in Shorewall 4.5.9. May only be specified in the
+                OPTIONS column and indicates that only a single ipset should
+                be created for this zone if it has multiple dynamic entries in
+                <ulink url="shorewall-hosts.html">shorewall-hosts</ulink>(5).
+                Without this option, a separate ipset is created for each
+                interface.</para>
+              </listitem>
+            </varlistentry>
+
             <varlistentry>
               <term><emphasis
               role="bold">reqid=</emphasis><emphasis>number</emphasis></term>
@@ -348,9 +361,9 @@ c:a,b     ipv4</programlisting>
     shorewall-ipsets(5), shorewall-maclist(5), shorewall-masq(5),
     shorewall-nat(5), shorewall-nesting(8), shorewall-netmap(5),
     shorewall-params(5), shorewall-policy(5), shorewall-providers(5),
-    shorewall-proxyarp(5), shorewall-rtrules(5),
+    shorewall-proxyarp(5), shorewall-rtrules(5), shorewall-routestopped(5),
-    shorewall-routestopped(5), shorewall-rules(5), shorewall.conf(5),
+    shorewall-rules(5), shorewall.conf(5), shorewall-secmarks(5),
-    shorewall-secmarks(5), shorewall-tcclasses(5), shorewall-tcdevices(5),
+    shorewall-tcclasses(5), shorewall-tcdevices(5), shorewall-tcrules(5),
-    shorewall-tcrules(5), shorewall-tos(5), shorewall-tunnels(5)</para>
+    shorewall-tos(5), shorewall-tunnels(5)</para>
   </refsect1>
 </refentry>

Shorewall/manpages/shorewall.xml

@@ -24,12 +24,14 @@
 
       <arg rep="norepeat">-<replaceable>options</replaceable></arg>
 
-      <arg choice="plain"><option>add</option></arg>
+      <arg choice="plain"><option>add {</option></arg>
 
       <arg choice="plain"
       rep="repeat"><replaceable>interface</replaceable>[:<replaceable>host-list</replaceable>]</arg>
 
-      <arg choice="plain"><replaceable>zone</replaceable></arg>
+      <arg choice="plain"><replaceable>zone</replaceable><option>
+      |</option><replaceable> zone host-list</replaceable><option>
+      }</option></arg>
     </cmdsynopsis>
 
     <cmdsynopsis>
@@ -109,12 +111,14 @@
 
       <arg rep="norepeat">-<replaceable>options</replaceable></arg>
 
-      <arg choice="plain"><option>delete</option></arg>
+      <arg choice="plain"><option>delete {</option></arg>
 
       <arg choice="plain"
       rep="repeat"><replaceable>interface</replaceable>[:<replaceable>host-list</replaceable>]</arg>
 
-      <arg choice="plain"><replaceable>zone</replaceable></arg>
+      <arg choice="plain"><replaceable>zone</replaceable><option>
+      |</option><replaceable> zone host-list</replaceable><option>
+      }</option></arg>
     </cmdsynopsis>
 
     <cmdsynopsis>
@@ -746,6 +750,15 @@
               <command>add</command> by <command>delete</command> and run the
               same command again. Then enter the correct command.</para>
             </caution></para>
+
+          <para>Beginning with Shorewall 4.5.9, the <emphasis
+          role="bold">dynamic_shared</emphasis> zone option (<ulink
+          url="shorewall-zones.html">shorewall-zones</ulink>(5)) allows a
+          single ipset to handle entries for multiple interfaces. When that
+          option is specified for a zone, the <command>add</command> command
+          has the alternative syntax in which the
+          <replaceable>zone</replaceable> name precedes the
+          <replaceable>host-list</replaceable>.</para>
         </listitem>
       </varlistentry>
 
@@ -861,6 +874,15 @@
           url="shorewall-interfaces.html">shorewall-interfaces</ulink>(5)
           file. A <emphasis>host-list</emphasis> is comma-separated list whose
           elements are a host or network address.</para>
+
+          <para>Beginning with Shorewall 4.5.9, the <emphasis
+          role="bold">dynamic_shared</emphasis> zone option (<ulink
+          url="shorewall-zones.html">shorewall-zones</ulink>(5)) allows a
+          single ipset to handle entries for multiple interfaces. When that
+          option is specified for a zone, the <command>delete</command>
+          command has the alternative syntax in which the
+          <replaceable>zone</replaceable> name precedes the
+          <replaceable>host-list</replaceable>.</para>
         </listitem>
       </varlistentry>
 

Shorewall6/manpages/shorewall6-zones.xml

@@ -178,7 +178,7 @@ c:a,b     ipv6</programlisting>
               <listitem>
                 <para>Added in Shorewall 4.4.11 Beta 2 - A zone composed of
                 Linux-vserver guests. The zone contents must be defined in
-                <ulink url="shorewall-hosts.html">shorewall-hosts</ulink>
+                <ulink url="shorewall6-hosts.html">shorewall6-hosts</ulink>
                 (5).</para>
 
                 <para>Vserver zones are implicitly handled as subzones of the
@@ -225,6 +225,20 @@ c:a,b     ipv6</programlisting>
               </listitem>
             </varlistentry>
 
+            <varlistentry>
+              <term><emphasis role="bold">dynamic_shared</emphasis></term>
+
+              <listitem>
+                <para>Added in Shorewall 4.5.9. May only be specified in the
+                OPTIONS column and indicates that only a single ipset should
+                be created for this zone if it has multiple dynamic entries in
+                <ulink
+                url="shorewall6-hosts.html">shorewall6-hosts</ulink>(5).
+                Without this option, a separate ipset is created for each
+                interface.</para>
+              </listitem>
+            </varlistentry>
+
             <varlistentry>
               <term><emphasis
               role="bold">reqid=</emphasis><emphasis>number</emphasis></term>

Shorewall6/manpages/shorewall6.xml

@@ -24,12 +24,13 @@
 
       <arg rep="norepeat">-<replaceable>options</replaceable></arg>
 
-      <arg choice="plain"><option>add</option></arg>
+      <arg choice="plain"><option>add {</option></arg>
 
       <arg choice="plain"
       rep="repeat"><replaceable>interface</replaceable>[:<replaceable>host-list</replaceable>]</arg>
 
-      <arg choice="plain"><replaceable>zone</replaceable></arg>
+      <arg choice="plain"><replaceable>zone | zone host-list
+      </replaceable><option>}</option></arg>
     </cmdsynopsis>
 
     <cmdsynopsis>
@@ -98,6 +99,23 @@
       <arg choice="opt"><replaceable>pathname</replaceable></arg>
     </cmdsynopsis>
 
+    <cmdsynopsis>
+      <command>shorewall6</command>
+
+      <arg
+      choice="opt"><option>trace</option>|<option>debug</option><arg><option>nolock</option></arg></arg>
+
+      <arg rep="norepeat">-<replaceable>options</replaceable></arg>
+
+      <arg choice="plain"><option>delete {</option></arg>
+
+      <arg choice="plain"
+      rep="repeat"><replaceable>interface</replaceable>[:<replaceable>host-list</replaceable>]</arg>
+
+      <arg choice="plain"><replaceable>zone | zone host-list
+      </replaceable><option>}</option></arg>
+    </cmdsynopsis>
+
     <cmdsynopsis>
       <command>shorewall</command>
 
@@ -649,6 +667,15 @@
               <command>add</command> by <command>delete</command> and run the
               same command again. Then enter the correct command.</para>
             </caution></para>
+
+          <para>Beginning with Shorewall 4.5.9, the <emphasis
+          role="bold">dynamic_shared</emphasis> zone option (<ulink
+          url="shorewall6-zones.html">shorewall6-zones</ulink>(5)) allows a
+          single ipset to handle entries for multiple interfaces. When that
+          option is specified for a zone, the <command>add</command> command
+          has the alternative syntax in which the
+          <replaceable>zone</replaceable> name precedes the
+          <replaceable>host-list</replaceable>.</para>
         </listitem>
       </varlistentry>
 
@@ -759,6 +786,15 @@
           url="shorewall6-interfaces.html">shorewall6-interfaces</ulink>(5)
           file. A <emphasis>host-list</emphasis> is comma-separated list whose
           elements are a host or network address.</para>
+
+          <para>Beginning with Shorewall 4.5.9, the <emphasis
+          role="bold">dynamic_shared</emphasis> zone option (<ulink
+          url="shorewall6-zones.html">shorewall6-zones</ulink>(5)) allows a
+          single ipset to handle entries for multiple interfaces. When that
+          option is specified for a zone, the <command>delete</command>
+          command has the alternative syntax in which the
+          <replaceable>zone</replaceable> name precedes the
+          <replaceable>host-list</replaceable>.</para>
         </listitem>
       </varlistentry>
 

docs/Dynamic.xml

@@ -180,11 +180,121 @@
     </orderedlist>
   </section>
 
+  <section>
+    <title>Dynamic Zones -- Shorewall 4.5.9 and Later</title>
+
+    <para>Prior to Shorewall 4.5.9, when multiple records for a zone appear in
+    <filename>/etc/shorewall/hosts</filename>, Shorewall would create a
+    separate ipset for each interface. This meant that an add or delete
+    command was required for each of the interface, when the address involved
+    was reachable via multiple interfaces.</para>
+
+    <para>Beginning with Shoreawll 4.5.9, it is possible to have a single
+    ipset shared among all interfaces. This also simplifies management of
+    dynamic zone contents for dynamic zones associated with only a single
+    interface.</para>
+
+    <para>The earlier implementation described below is still available in
+    these later releases.</para>
+
     <section id="defining">
       <title>Defining a Dynamic Zone</title>
 
-    <para>A dynamic zone is defined by using the keyword dynamic in the zones
+      <para>A dynamic zone is defined by specifying the
-    host list.</para>
+      <option>dynamic_shared</option> option in the zones file and using the
+      <option>dynamic</option> keyword in the hosts list.</para>
+
+      <para><filename>/etc/shorewall/zones</filename>:<programlisting>#NAME        TYPE             OPTIONS
+net          ipv4
+rsyncok:loc  ipv4             <emphasis role="bold">dynamic_shared</emphasis></programlisting><filename>/etc/shorewall/interfaces</filename>:</para>
+
+      <programlisting>#ZONE       INTERFACE      BROADCAST        OPTIONS
+loc         eth0           -                …
+loc         eth1           -                …</programlisting>
+
+      <para><filename>/etc/shorewall/hosts</filename>:</para>
+
+      <programlisting>#ZONE       HOSTS          OPTIONS
+rsyncok     eth0:<option>dynamic</option>
+rsyncok     eth1:<option>dynamic</option></programlisting>
+
+      <para>When the <option>dynamic_shared</option> option is specified, a
+      single ipset is created; the ipset has the same name as the zone.</para>
+    </section>
+
+    <section id="Adding">
+      <title>Adding a Host to a Dynamic Zone.</title>
+
+      <para>Adding a host to a dynamic zone is accomplished by adding the
+      host's IP address to the appropriate ipset. Shorewall provldes a command
+      for doing that:<blockquote>
+          <para><command>shorewall add</command> <replaceable>zone
+          address</replaceable> ...</para>
+        </blockquote></para>
+
+      <para>Example:</para>
+
+      <blockquote>
+        <para><command>shorewall add rsyncok 70.90.191.124</command></para>
+      </blockquote>
+    </section>
+
+    <section id="delete">
+      <title>Deleting a Host from a Dynamic Zone</title>
+
+      <para>Deleting a host from a dynamic zone is accomplished by removing
+      the host's IP address from the appropriate ipset. Shorewall provldes a
+      command for doing that:</para>
+
+      <blockquote>
+        <para><command>shorewall delete</command>
+        <replaceable>zone</replaceable> <replaceable>address</replaceable>
+        ...</para>
+      </blockquote>
+
+      <para>Example:</para>
+
+      <blockquote>
+        <para><command>shorewall delete rsyncok 70.19.191.124</command></para>
+      </blockquote>
+
+      <para>The command can only be used when the ipset involved is of type
+      iphash. For other ipset types, the <command>ipset</command> command must
+      be used directly.</para>
+    </section>
+
+    <section id="listing">
+      <title>Listing the Contents of a Dynamic Zone</title>
+
+      <para>The shorewall show command may be used to list the current
+      contents of a dynamic zone.</para>
+
+      <blockquote>
+        <para><command>shorewall show dynamic</command>
+        <replaceable>zone</replaceable></para>
+      </blockquote>
+
+      <para>Example:</para>
+
+      <blockquote>
+        <programlisting><command>shorewall show dynamic rsyncok</command>
+rsyncok:
+   70.90.191.122
+   70.90.191.124</programlisting>
+      </blockquote>
+    </section>
+  </section>
+
+  <section id="Version-4.5.9">
+    <title>Dynamic Zones -- Shorewall 5.4.8 and Earlier.</title>
+
+    <para/>
+
+    <section id="defining1">
+      <title>Defining a Dynamic Zone</title>
+
+      <para>A dynamic zone is defined by using the keyword <emphasis
+      role="bold">dynamic</emphasis> in the zones host list.</para>
 
       <para>Example:</para>
 
@@ -205,9 +315,9 @@ webok       eth0:dynamic</programlisting>
 
       <para>Once the above definition is added, Shorewall will automatically
       create an ipset named <emphasis>webok_eth0</emphasis> the next time that
-    Shorewall is started or restarted. Shorewall will create an ipset of type
+      Shorewall is started or restarted. Shorewall will create an ipset of
-    <firstterm>iphash</firstterm>. If you want to use a different type of
+      type <firstterm>iphash</firstterm>. If you want to use a different type
-    ipset, such as <firstterm>macipmap</firstterm>, then you will want to
+      of ipset, such as <firstterm>macipmap</firstterm>, then you will want to
       manually create that ipset yourself before the next Shorewall
       start/restart.</para>
 
@@ -215,12 +325,12 @@ webok       eth0:dynamic</programlisting>
       4.4.21.</para>
     </section>
 
-  <section>
+    <section id="adding1">
       <title>Adding a Host to a Dynamic Zone</title>
 
-    <para>Adding a host to a dynamic zone is accomplished by adding the host's
+      <para>Adding a host to a dynamic zone is accomplished by adding the
-    IP address to the appropriate ipset. Shorewall provldes a command for
+      host's IP address to the appropriate ipset. Shorewall provldes a command
-    doing that:</para>
+      for doing that:</para>
 
       <blockquote>
         <para><command>shorewall add</command> <replaceable>interface:address
@@ -238,34 +348,36 @@ webok       eth0:dynamic</programlisting>
       be used directly.</para>
     </section>
 
-  <section id="delete">
+    <section id="deleting">
       <title>Deleting a Host from a Dynamic Zone</title>
 
-    <para>Deleting a host from a dynamic zone is accomplished by removing the
+      <para>Deleting a host from a dynamic zone is accomplished by removing
-    host's IP address from the appropriate ipset. Shorewall provldes a command
+      the host's IP address from the appropriate ipset. Shorewall provldes a
-    for doing that:</para>
+      command for doing that:</para>
 
       <blockquote>
-      <para><command>shorewall delete</command> <replaceable>interface:address
+        <para><command>shorewall delete</command>
-      ...</replaceable> <replaceable>zone</replaceable></para>
+        <replaceable>interface:address ...</replaceable>
+        <replaceable>zone</replaceable></para>
       </blockquote>
 
       <para>Example:</para>
 
       <blockquote>
-      <para><command>shorewall delete eth0:192.168.3.4 webok</command></para>
+        <para><command>shorewall delete eth0:192.168.3.4
+        webok</command></para>
       </blockquote>
 
       <para>The command can only be used when the ipset involved is of type
-    iphash. For other ipset types, the <command>ipset</command> command must
+      iphash. For other ipset types, the <command>ipse t</command> command
-    be used directly.</para>
+      must be used directly.</para>
     </section>
 
-  <section id="listing">
+    <section id="listing1">
       <title>Listing the Contents of a Dynamic Zone</title>
 
-    <para>The shorewall show command may be used to list the current contents
+      <para>The shorewall show command may be used to list the current
-    of a dynamic zone.</para>
+      contents of a dynamic zone.</para>
 
       <blockquote>
         <para><command>shorewall show dynamic</command>
@@ -281,26 +393,20 @@ eth0:
    192.168.3.9</programlisting>
       </blockquote>
     </section>
+  </section>
 
   <section id="start-stop">
     <title>Dynamic Zone Contents and Shorewall stop/start/restart</title>
 
-    <para>The contents of a dynamic zone survive <command>shorewall
+    <para>When SAVE_IPSETS=Yes in shorewall.conf, the contents of a dynamic
-    stop/shorewall start</command> and <command>shorewall restart</command>.
+    zone survive <command>shorewall stop/shorewall start</command> and
-    During <command>shorewall stop</command>, the contents of the ipsets are
+    <command>shorewall restart</command>. During <command>shorewall
-    saved in the file <filename>${VARDIR}/ipsets.save</filename> (usually
+    stop</command>, the contents of the ipsets are saved in the file
+    <filename>${VARDIR}/ipsets.save</filename> (usually
     <filename>/var/lib/shorewall/ipsets.save</filename>). During
     <command>shorewall start</command>, the contents of that file are restored
     to the sets. During both <command>shorewall start</command> and
     <command>shorewall restart</command>, any new ipsets required as a result
     of a configuration change are added.</para>
   </section>
-
-  <section id="restrictions">
-    <title>Restrictions</title>
-
-    <para>When using dynamic zones, you may not use ipsets in your <ulink
-    url="manpages/shorewall-routestopped.html">/etc/shorewall/routestopped</ulink>
-    file.</para>
-  </section>
 </article>