shorewall_code/docs/Dynamic.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<article>
  <!--$Id$-->

  <articleinfo>
    <title>Dynamic Zones</title>

    <authorgroup>
      <author>
        <firstname>Tom</firstname>

        <surname>Eastep</surname>
      </author>
    </authorgroup>

    <pubdate><?dbtimestamp format="Y/m/d"?></pubdate>

    <copyright>
      <year>2009</year>

      <year>2013</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 by the Free Software Foundation; with
      no Invariant Sections, no Front-Cover Texts, and 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>Overview</title>

    <para>There is sometimes a need to be able to define a zone whose members
    are unknown at compile-time. For example, you may wish to require
    authentication of internal users before allowing them access to the
    internet. When a user is authenticated, the user's IP address is added to
    the zone of users permitted web access.</para>

    <para>Shorewall provides basic support for defining such zones. This
    support is based on <ulink
    url="http://ipset.netfilter.org/">ipset</ulink>. Most current
    distributions have ipset, but you may need to install the <ulink
    url="http://xtables-addons.sourceforge.net/">xtables-addons</ulink>
    package.</para>
  </section>

  <section>
    <title>Dynamic Zones</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 specifying the <emphasis
      role="bold">dynamic_shared</emphasis> option in the zones file and using
      the <emphasis role="bold">dynamic</emphasis> 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:<emphasis role="bold">dynamic</emphasis>
rsyncok     eth1:<emphasis role="bold">dynamic</emphasis></programlisting>

      <para>When the <emphasis role="bold">dynamic_shared</emphasis> option is
      specified, a single ipset is created; the ipset has the same name as the
      zone.</para>

      <para>In the above example, <emphasis role="bold">rsyncok</emphasis> is
      a sub-zone of the single zone <emphasis role="bold">loc</emphasis>.
      Making a dynamic zone a sub-zone of multiple other zones is also
      supported.</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="start-stop">
    <title>Dynamic Zone Contents and Shorewall stop/start/restart</title>

    <para>When SAVE_IPSETS=Yes in shorewall.conf, the contents of a dynamic
    zone survive <command>shorewall stop/shorewall start</command> and
    <command>shorewall restart</command>. During <command>shorewall
    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>
</article>