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>

      <year>2010</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>

  <caution>
    <para><emphasis role="bold">This article applies to Shorewall 4.4 and
    later. If you are running a version of Shorewall earlier than Shorewall
    4.3.5 then please see the documentation for that
    release.</emphasis></para>
  </caution>

  <section id="Ipsets">
    <title>What are Ipsets?</title>

    <para>Ipsets are an extension to Netfilter/iptables that are currently
    available in <ulink
    url="http://xtables-addons.sourceforge.net/">xtables-addons</ulink>.
    Instructions for installing xtables-addons may be found in the <ulink
    url="Dynamic.html">Dynamic Zones article</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
        <ulink url="Dynamic.html">define a zone based on the (dynamic)
        contents of an ipset</ulink>. Again, you can then add or delete
        addresses to the ipset without restarting Shorewall.</para>
      </listitem>

      <listitem>
        <para>In most configuration files when an address list is accepted,
        the list may include ipsets using the syntax described below.</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>When an ipset name appears in the SOURCE column of a file, Shorewall
    generates a 'src' match ("-m set --match-set
    <replaceable>set-name</replaceable> <emphasis role="bold">src</emphasis>")
    and when the name appears in the DEST column, a 'dst' match is generated
    (-m set --match-set <replaceable>set-name</replaceable> <emphasis
    role="bold">dst</emphasis>"). Some set types allow matching on more than
    one address and require a comma-separated list of 'src' and/or 'dst'
    flags. This list may be enclosed in square brackets ("[...]") following
    the set name.</para>

    <para>Example: +setlist[src,dst]</para>

    <para>If the flags are homogenous, you may use an integer to represent the
    number of entries. In other words, <emphasis role="bold">[2]</emphasis> is
    equivalent to <emphasis role="bold">[src,src]</emphasis> in the SOURCE
    column and is equivalent to <emphasis role="bold">[dst,dst]</emphasis> in
    the DEST column.</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       net:+sshok  $FW      tcp      22</programlisting></para>
  </section>

  <section>
    <title>Saving/Restoring Ipsets</title>

    <para>The SAVE_IPSETS option in <ulink
    url="manpages/shorewall.conf.html">shorewall.conf </ulink>(5) allows you
    to have Shorewall automatically save your ipset contents during
    <command>shorewall stop</command> and restore them during
    <command>shorewall start</command>. SAVE_IPSETS is implicitly set to
    <option>Yes</option> when the configuration includes one or more <ulink
    url="Dynamic.html">dynamic zones</ulink>.</para>

    <para>When SAVE_IPSETS=Yes, Shorewall disallows ipsets to be specified in
    <ulink
    url="manpages/shorewall-routestopped.html">shorewall-routestopped</ulink>
    (8). </para>

    <para>SAVE_IPSET support was added in Shorewall 4.4.6.</para>
  </section>
</article>