shorewall_code/docs/ipsets.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>Shorewall and Ipsets</title>

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

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

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

    <copyright>
      <year>2005</year>

      <year>2008</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 id="Ipsets">
    <title>What are Ipsets?</title>

    <para>Ipsets are an extension to Netfilter/iptables that are currently
    available in Patch-O-Matic-ng (<ulink
    url="http://www.netfilter.org">http://www.netfilter.org</ulink>). Using
    ipsets requires that you patch your kernel and iptables and that you build
    and install the ipset utility from <ulink
    url="http://ipset.netfilter.org/">http://ipset.netfilter.org/</ulink>.</para>

    <para>Ipset allows you to create one or more named sets of addresses then
    use those sets to define Netfilter/iptables rules. Possible uses of ipsets
    include:</para>

    <orderedlist>
      <listitem>
        <para>Blacklists. Ipsets provide an efficient way to represent large
        sets of addresses and you can maintain the lists without the need to
        restart or even refresh your Shorewall configuration.</para>
      </listitem>

      <listitem>
        <para>Zone definition. Using the /etc/shorewall/hosts file, you can
        define a zone based on the (dynamic) contents of an ipset. Again, you
        can then add or delete addresses to the ipset without restarting
        Shorewall.</para>
      </listitem>
    </orderedlist>

    <para>See the ipsets site (URL above) for additional information about
    ipsets.</para>
  </section>

  <section id="Support">
    <title>Shorewall Support for Ipsets</title>

    <para>Support for ipsets was introduced in Shorewall version 2.3.0. In
    most places where a host or network address may be used, you may also use
    the name of an ipset prefaced by "+".</para>

    <para>Example: "+Mirrors"</para>

    <para>When using Shorewall, the names of ipsets are restricted as
    follows:</para>

    <itemizedlist>
      <listitem>
        <para>They must begin with a letter (after the '+').</para>
      </listitem>

      <listitem>
        <para>They must be composed of letters, digits or underscores
        ("_").</para>
      </listitem>
    </itemizedlist>

    <para>To generate a negative match, prefix the "+" with "!" as in
    "!+Mirrors".</para>

    <para>Example 1: Blacklist all hosts in an ipset named "blacklist"</para>

    <para><filename>/etc/shorewall/blacklist</filename><programlisting>#ADDRESS/SUBNET         PROTOCOL        PORT
+blacklist</programlisting></para>

    <para>Example 2: Allow SSH from all hosts in an ipset named "sshok:</para>

    <para><filename>/etc/shorewall/rules</filename><programlisting>#ACTION      SOURCE      DEST     PROTO    DEST PORT(S)
ACCEPT       +sshok      $FW      tcp      22</programlisting></para>

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

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

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

  <section id="Dynamic">
    <title>Defining Dynamic Zones using Ipsets</title>

    <para>The use of ipsets provides a much better way to define dynamic zones
    than is provided by the native Shorewall implementation. To define a
    dynamic zone of hosts <emphasis role="bold">dyn</emphasis> that is a
    sub-zone of zone <emphasis role="bold">loc</emphasis> and that interfaces
    through interface eth3, use:</para>

    <para>/etc/shorewall/zones:</para>

    <programlisting>#ZONE         TYPE         OPTIONS            IN OPTIONS        OUT OPTIONS
loc           ipv4
dyn:loc       ipv4</programlisting>

    <para>/etc/shorewall/interfaces:</para>

    <programlisting>#ZONE         INTERFACE     OPTIONS
loc           eth3          …</programlisting>

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

    <programlisting>#ZONE         HOSTS         OPTIONS
dyn           eth3:+Dyn</programlisting>

    <para>Now create an ipmap named <emphasis role="bold">Dyn</emphasis> and
    you're all set. You can add and delete addresses from Dyn without having
    to touch Shorewall.</para>
  </section>
</article>