shorewall_code/docs/blacklisting_support.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 Blacklisting Support</title>

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

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

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

    <copyright>
      <year>2002-2006</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>

  <section id="Intro">
    <title>Introduction</title>

    <para>Shorewall supports two different forms of blacklisting; static and
    dynamic. The BLACKLISTNEWONLY option in /etc/shorewall/shorewall.conf
    controls the degree of blacklist filtering:</para>

    <orderedlist>
      <listitem>
        <para>BLACKLISTNEWONLY=No -- All incoming packets are checked against
        the blacklist. New blacklist entries can be used to terminate existing
        connections.</para>
      </listitem>

      <listitem>
        <para>BLACKLISTNEWONLY=Yes -- The blacklists are only consulted for
        new connection requests. Blacklists may not be used to terminate
        existing connections. Only the source address is checked against the
        blacklists.</para>
      </listitem>
    </orderedlist>

    <important>
      <para><emphasis role="bold">Only the source address is checked against
      the blacklists</emphasis>. Blacklists only stop blacklisted hosts from
      connecting to you — they do not stop you or your users from connecting
      to blacklisted hosts .</para>

      <variablelist>
        <varlistentry>
          <term>UPDATE</term>

          <listitem>
            <para>Beginning with Shorewall 4.4.12, you can also blacklist by
            destination address. See <ulink
            url="manpages/shorewall-blacklist.html">shorewall-blacklist</ulink>
            (5) and <ulink url="manpages/shorewall.html">shorewall</ulink> (8)
            for details.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </important>

    <important>
      <para><emphasis role="bold">Dynamic Shorewall blacklisting is not
      appropriate for blacklisting 1,000s of different addresses. Static
      Blacklisting can handle large blacklists but only if you use
      ipsets</emphasis>. Without ipsets, the blacklists will take forever to
      load, and will have a very negative effect on firewall
      performance.</para>
    </important>
  </section>

  <section id="Static">
    <title>Static Blacklisting</title>

    <para>Shorewall static blacklisting support has the following
    configuration parameters:</para>

    <itemizedlist>
      <listitem>
        <para>You specify whether you want packets from blacklisted hosts
        dropped or rejected using the BLACKLIST_DISPOSITION setting in <ulink
        url="manpages/shorewall.conf.html"><filename>/etc/shorewall/shorewall.conf</filename>.</ulink></para>
      </listitem>

      <listitem>
        <para>You specify whether you want packets from blacklisted hosts
        logged and at what syslog level using the BLACKLIST_LOGLEVEL setting
        in <ulink
        url="manpages/shorewall.conf.html"><filename>/etc/shorewall/shorewall.conf</filename></ulink>.</para>
      </listitem>

      <listitem>
        <para>You list the IP addresses/subnets that you wish to blacklist in
        <ulink
        url="manpages/shorewall-blacklist.html"><filename>/etc/shorewall/blacklist</filename></ulink>.
        You may also specify PROTOCOL and Port numbers/Service names in the
        blacklist file.</para>
      </listitem>

      <listitem>
        <para>You specify the interfaces whose incoming packets you want
        checked against the blacklist using the <quote>blacklist</quote>
        option in <ulink
        url="manpages/shorewall-interfaces.html"><filename>/etc/shorewall/interfaces</filename></ulink>.</para>
      </listitem>

      <listitem>
        <para>The black list is refreshed from
        <filename>/etc/shorewall/blacklist</filename> by the <quote><ulink
        url="starting_and_stopping_shorewall.htm"><command>shorewall
        refresh</command></ulink></quote> command.</para>
      </listitem>
    </itemizedlist>

    <para>Users with a large static black list may want to set the
    DELAYBLACKLISTLOAD option in shorewall.conf (added in Shorewall version
    2.2.0). When DELAYBLACKLISTLOAD=Yes, Shorewall will enable new connections
    before loading the blacklist rules. While this may allow connections from
    blacklisted hosts to slip by during construction of the blacklist, it can
    substantially reduce the time that all new connections are disabled during
    "shorewall [re]start".</para>

    <para>Beginning with Shorewall 2.4.0, you can use <ulink
    url="ipsets.html">ipsets</ulink> to define your static blacklist. Here's
    an example:</para>

    <programlisting>#ADDRESS/SUBNET         PROTOCOL        PORT
+Blacklistports[dst]
+Blacklistnets[src,dst]
+Blacklist[src,dst]
#LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE</programlisting>

    <para>In this example, there is a portmap ipset
    <emphasis>Blacklistports</emphasis> that blacklists all traffic with
    destination ports included in the ipset. There are also
    <emphasis>Blacklistnets</emphasis> (type <emphasis>nethash</emphasis>) and
    <emphasis>Blacklist</emphasis> (type <emphasis>iphash</emphasis>) ipsets
    that allow blacklisting networks and individual IP addresses. Note that
    [src,dst] is specified so that individual entries in the sets can be bound
    to other portmap ipsets to allow blacklisting (<emphasis>source
    address</emphasis>, <emphasis>destination port</emphasis>) combinations.
    For example:</para>

    <programlisting>ipset -N SMTP portmap --from 1 --to 31
ipset -A SMTP 25
ipset -A Blacklist 206.124.146.177
ipset -B Blacklist 206.124.146.177 -b SMTP</programlisting>

    <para>This will blacklist SMTP traffic from host 206.124.146.177.</para>
  </section>

  <section id="Dynamic">
    <title>Dynamic Blacklisting</title>

    <para>Beginning with Shorewall 4.4.7, dynamic blacklisting is enabled by
    setting DYNAMIC_BLACKLIST=Yes in <filename>shorewall.conf</filename>.
    Prior to that release, the feature is always enabled.</para>

    <para>Once enabled, dynamic blacklisting doesn't use any configuration
    parameters but is rather controlled using /sbin/shorewall[-lite] commands.
    <emphasis role="bold">Note</emphasis> that <emphasis
    role="bold">to</emphasis> and <emphasis role="bold">from</emphasis> may
    only be specified when running <emphasis role="bold">Shorewall 4.4.12 or
    later</emphasis>.</para>

    <itemizedlist>
      <listitem>
        <para>drop [to|from] <emphasis>&lt;ip address list&gt;</emphasis> -
        causes packets from the listed IP addresses to be silently dropped by
        the firewall.</para>
      </listitem>

      <listitem>
        <para>reject [to|from]<emphasis>&lt;ip address list&gt;</emphasis> -
        causes packets from the listed IP addresses to be rejected by the
        firewall.</para>
      </listitem>

      <listitem>
        <para>allow [to|from] <emphasis>&lt;ip address list&gt;</emphasis> -
        re-enables receipt of packets from hosts previously blacklisted by a
        <emphasis>drop</emphasis> or <emphasis>reject</emphasis>
        command.</para>
      </listitem>

      <listitem>
        <para>save - save the dynamic blacklisting configuration so that it
        will be automatically restored the next time that the firewall is
        restarted.</para>

        <para><emphasis role="bold">Update:</emphasis> Beginning with
        Shorewall 4.4.10, the dynamic blacklist is automatically retained over
        <command>stop/start</command> sequences and over
        <command>restart</command>.</para>
      </listitem>

      <listitem>
        <para>show dynamic - displays the dynamic blacklisting
        configuration.</para>
      </listitem>

      <listitem>
        <para>logdrop [to|from] <emphasis>&lt;ip address list&gt;</emphasis> -
        causes packets from the listed IP addresses to be dropped and logged
        by the firewall. Logging will occur at the level specified by the
        BLACKLIST_LOGLEVEL setting at the last [re]start (logging will be at
        the 'info' level if no BLACKLIST_LOGLEVEL was given).</para>
      </listitem>

      <listitem>
        <para>logreject [to|from}<emphasis>&lt;ip address list&gt;</emphasis>
        - causes packets from the listed IP addresses to be rejected and
        logged by the firewall. Logging will occur at the level specified by
        the BLACKLIST_LOGLEVEL setting at the last [re]start (logging will be
        at the 'info' level if no BLACKLIST_LOGLEVEL was given).</para>
      </listitem>
    </itemizedlist>

    <para>Dynamic blacklisting is not dependent on the
    <quote>blacklist</quote> option in
    <filename>/etc/shorewall/interfaces</filename>.</para>

    <example id="Ignore">
      <title>Ignore packets from a pair of systems</title>

      <programlisting>    <command>shorewall[-lite] drop 192.0.2.124 192.0.2.125</command></programlisting>

      <para>Drops packets from hosts 192.0.2.124 and 192.0.2.125</para>
    </example>

    <example id="Allow">
      <title>Re-enable packets from a system</title>

      <programlisting>    <command>shorewall[-lite] allow 192.0.2.125</command></programlisting>

      <para>Re-enables traffic from 192.0.2.125.</para>
    </example>

    <example>
      <title>Displaying the Dynamic Blacklist</title>

      <programlisting>    <command>shorewall show dynamic</command></programlisting>

      <para>Displays the 'dynamic' chain which contains rules for the dynamic
      blacklist. The <firstterm>source</firstterm> column contains the set of
      blacklisted addresses.</para>
    </example>
  </section>
</article>