<?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> <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 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> </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>The method described in this section is still supported in the later releases.</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> <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:<emphasis role="bold">dynamic</emphasis></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.</para> </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 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="deleting"> <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>ipse t</command> command must be used directly.</para> </section> <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 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> <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>