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>

      <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, 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>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>. As of this writing, ipset
    is not included in the standard kernel distribution; so to use dynamic
    zones, you must be running kernel 2.6.20 or later and have installed the
    <ulink
    url="http://xtables-addons.sourceforge.net/">xtables-addons</ulink>.</para>
  </section>

  <section id="xtables-addons">
    <title>Installing xtables-addons</title>

    <para>The xtables-addons are fairly easy to install. You do not need to
    recompile your kernel.</para>

    <para><trademark>Debian</trademark> users can find xtables-addons-common
    and xtables-addons-source packages in <firstterm>testing</firstterm>. The
    kernel modules can be built and installed with the help of
    module-assistant. As of this writing, these packages are in the
    <firstterm>admin</firstterm> group rather than in the
    <firstterm>network</firstterm> group!!??</para>

    <para>For other users, the basic steps are as follows:</para>

    <orderedlist>
      <listitem>
        <para>Install gcc and make</para>
      </listitem>

      <listitem>
        <para>Install the headers for the kernel you are running. In some
        distributions, such as <trademark>Debian</trademark> and
        <trademark>Ubuntu</trademark>, the packet is called kernel-headers.
        For other distrubutions, such as OpenSuSE, you must install the
        kernel-source package.</para>
      </listitem>

      <listitem>
        <para>download the iptables source tarball</para>
      </listitem>

      <listitem>
        <para>untar the source</para>
      </listitem>

      <listitem>
        <para>cd to the iptables source directory</para>
      </listitem>

      <listitem>
        <para>run 'make'</para>
      </listitem>

      <listitem>
        <para>as root, run 'make install'</para>
      </listitem>

      <listitem>
        <para>Your new iptables binary will now be installed in
        /usr/local/sbin. Modify shorewall.conf to specify
        IPTABLES=/usr/local/sbin/iptables</para>
      </listitem>

      <listitem>
        <para>Download the latest xtables-addons source tarball</para>
      </listitem>

      <listitem>
        <para>Untar the xtables-addons source</para>
      </listitem>

      <listitem>
        <para>cd to the xtables-addons source directory</para>
      </listitem>

      <listitem>
        <para>run './configure'</para>
      </listitem>

      <listitem>
        <para>run 'make'</para>
      </listitem>

      <listitem>
        <para>As root, cd to the xtables-addons directory and run 'make
        install'.</para>
      </listitem>

      <listitem>
        <para>Restart shorewall</para>
      </listitem>

      <listitem>
        <para>'shorewall show capabilities' should now indicate<emphasis
        role="bold"> Ipset Match: Available</emphasis></para>
      </listitem>
    </orderedlist>

    <para>You will have to repeat steps 10-13 each time that you receive a
    kernel upgrade from your distribution vendor. You can install
    xtables-addons before booting to the new kernel as follows
    (<emphasis>new-kernel-version</emphasis> is the version of the
    newly-installed kernel - example <emphasis
    role="bold">2.6.28.11-generic</emphasis>. Look in the /lib/modules
    directory to get the full version name)</para>

    <orderedlist>
      <listitem>
        <para>cd to the xtables-addons source directory</para>
      </listitem>

      <listitem>
        <para>run 'make clean'</para>
      </listitem>

      <listitem>
        <para>run './configure
        --with-kbuild=/lib/modules/<emphasis>new-kernel-version</emphasis>/build
        --with-ksource=/lib/modules/<emphasis>new-kernel-version</emphasis>/source'</para>
      </listitem>

      <listitem>
        <para>run 'make'</para>
      </listitem>

      <listitem>
        <para>As root, cd to the xtables-addons source directory and run 'make
        install'.</para>
      </listitem>

      <listitem>
        <para>As root, run 'depmod -a
        <emphasis>new-kernel-version'</emphasis></para>
      </listitem>
    </orderedlist>
  </section>

  <section id="defining">
    <title>Defining a Dynamic Zone</title>

    <para>A dynamic zone is defined by using the keyword dynamic in the zones
    host list.</para>

    <para>Example:</para>

    <blockquote>
      <para><filename>/etc/shorewall/zones</filename>:<programlisting>#NAME        TYPE             OPTIONS
loc          ipv4
webok:loc    ipv4</programlisting><filename>/etc/shorewall/interfaces</filename>:</para>

      <programlisting>#ZONE       INTERFACE      BROADCAST        OPTIONS
loc         eth0           -                …
</programlisting>

      <para><filename>/etc/shorewall/hosts</filename>:</para>

      <programlisting>#ZONE       HOSTS          OPTIONS
webok       eth0:dynamic</programlisting>
    </blockquote>

    <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
    <firstterm>iphash</firstterm>. If you want to use a different type of
    ipset, such as <firstterm>macipmap</firstterm>, then you will want to
    manually create that ipset yourself before the next Shorewall
    start/restart.</para>

    <para>The dynamic zone capability was added to Shorewall6 in Shorewall
    4.4.21. One limitation of that support is that you may not have an ipv6
    dynamic zone with the same name and same interface as an ipv4 dynamic
    zone.</para>
  </section>

  <section>
    <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:</para>

    <blockquote>
      <para><command>shorewall add</command> <replaceable>interface:address
      ...</replaceable> <replaceable>zone</replaceable></para>
    </blockquote>

    <para>Example:</para>

    <blockquote>
      <para><command>shorewall add 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
    be used directly.</para>
  </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>interface:address
      ...</replaceable> <replaceable>zone</replaceable></para>
    </blockquote>

    <para>Example:</para>

    <blockquote>
      <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
    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 webok</command>
eth0:
   192.168.3.4
   192.168.3.9</programlisting>
    </blockquote>
  </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
    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>

  <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>