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>

      <year>2015</year>

      <year>2017</year>

      <year>2019</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.4.0 then please see the documentation appropriate for your
    version.</emphasis></para>
  </caution>

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

    <para>Ipsets are an extension to Netfilter/iptables that are available in
    <ulink url="http://xtables-addons.sourceforge.net/">xtables-addons</ulink>
    if they are not available in your current distribution. Instructions for
    installing xtables-addons may be found in the <ulink
    url="Dynamic.html">Dynamic Zones article</ulink>. Note that xtables-addons
    might not be required with the 'ipset' package provided by your
    distribution. See also the section <ulink
    url="configuration_file_basics.htm#capabilities">capabilities</ulink> in
    the <ulink url="configuration_file_basics.htm">configuration file basics
    article</ulink> and the <ulink url="Shorewall-Lite.html#Shorecap">Shorecap
    program</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>
    </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, dashes ("-") 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/blrules</filename><programlisting>#ACTION      SOURCE           DEST     PROTO    DPORT
DROP         net:+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    DPORT
ACCEPT       net:+sshok       $FW      tcp      22</programlisting></para>

    <para>The name of the ipset can be optionally followed by a
    comma-separated list of flags enclosed in square brackets ([...]). Each
    flag is either <emphasis role="bold">src</emphasis> or <emphasis
    role="bold">dst</emphasis> and specifies whether it is the SOURCE address
    or port number or the DESTINATION address or port number that should be
    matched. The number of flags must be appropriate for the type of ipset. If
    no flags are given, Shorewall assumes that the set takes a single flag and
    will select the flag based on the context. For example, in the blacklist
    file and when the ipset appears in the SOURCE column of the rules file,
    <emphasis role="bold">src</emphasis> is assumed. If the ipset appears in
    the DEST column of the rules file, <emphasis role="bold">dst</emphasis> is
    assumed. Note that by using <emphasis role="bold">[dst]</emphasis> in the
    blacklist file, you can coerce the rule into matching the destination IP
    address rather than the source.</para>

    <para>Beginning with Shorewall 4.4.14, multiple source or destination
    matches may be specified by placing multiple set names in '+[...]' (e.g.,
    +[myset,myotherset]). When so enclosed, the set names need not be prefixed
    with a plus sign.</para>

    <para>Shorewall can save/restore your ipset contents with certain
    restrictions:</para>

    <orderedlist>
      <listitem>
        <para>You must set SAVE_IPSETS=Yes in <ulink
        url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5).</para>
      </listitem>

      <listitem>
        <para>You must have at least one entry in the other configuration
        files that uses an ipset.</para>
      </listitem>

      <listitem>
        <para>You cannot use an ipset in <ulink
        url="manpages/shorewall-stoppedulres.html">shorewall-stoppedrules</ulink>
        (5) (<ulink
        url="manpages/shorewall-routestopped.html">shorewall-routestopped</ulink>
        (5)).</para>
      </listitem>

      <listitem>
        <para>The <command>restore</command> command cannot restore ipset
        contents saved by the <command>save</command> command unless the
        firewall is first stopped.</para>
      </listitem>
    </orderedlist>

    <para>Beginning with Shorewall 4.6.4, you can save selective ipsets by
    setting SAVE_IPSETS to a comma-separated list of ipset names. You can also
    restrict the group of sets saved to ipv4 sets by setting
    SAVE_IPSETS=ipv4.</para>

    <para>With Shorewall 4.6.4, the SAVE_IPSETS option may specify a list of
    ipsets to be saved. When such a list is specified, only those ipsets
    together with the ipsets supporting dynamic zones are saved. Shorewall6
    support for the SAVE_IPSETS option was also added in 4.6.4. When
    SAVE_IPSETS=Yes in <ulink
    url="manpages/shorewall.conf.html">shorewall6.conf(5)</ulink>, only ipv6
    ipsets are saved. For Shorewall, if SAVE_IPSETS=ipv4 in <ulink
    url="manpages/shorewall.conf.html">shorewall.conf(5)</ulink>, then only
    ipv4 ipsets are saved. Both features require ipset version 5 or
    later.</para>

    <para>Although Shorewall can save the definition of your ipsets and
    restore them when Shorewall starts, in most cases you must use the ipset
    utility to initially create and load your ipsets. The exception is that
    Shorewall will automatically create an empty iphash ipset to back each
    dynamic zone.</para>
  </section>

  <section>
    <title>Shorewall6 and Shorewall-init Support for Ipsets</title>

    <para>Ipset support in Shorewall6 was added in Shorewall 4.4.21.</para>

    <para>Beginning with Shorewall 4.6.4, SAVE_IPSETS is available in <ulink
    url="manpages/shorewall.conf.html">shorewall6-conf(5)</ulink>. When set to
    Yes, the ipv6 ipsets will be saved. You can also save selective ipsets by
    setting SAVE_IPSETS to a comma-separated list of ipset names.</para>

    <para>Prior to Shorewall 4.6.4, SAVE_IPSETS=Yes in <ulink
    url="manpages/shorewall.conf.html">shorewall.conf(5)</ulink> won't work
    correctly because it saves both IPv4 and IPv6 ipsets. To work around this
    issue, Shorewall-init is capable restoring ipset contents during 'start'
    and saving them during 'stop'. To direct Shorewall-init to save/restore
    ipset contents, set the SAVE_IPSETS option in
    /etc/sysconfig/shorewall-init (/etc/default/shorewall-init on Debian and
    derivatives). The value of the option is a file name where the contents of
    the ipsets will be save to and restored from. Shorewall-init will create
    any necessary directories during the first 'save' operation.</para>

    <para>If you configure Shorewall-init to save/restore ipsets, be sure to
    set SAVE_IPSETS=No in shorewall.conf and shorewall6.conf.</para>

    <para>If you configure SAVE_IPSETS in <ulink
    url="manpages/shorewall.conf.html">shorewall.conf(5)</ulink> and/or <ulink
    url="manpages/shorewall.conf.html">shorewall6.conf(5)</ulink> then do not
    set SAVE_IPSETS in shorewall-init.</para>
  </section>
</article>