shorewall_code/Shorewall-docs2/blacklisting_support.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article>
  <!--$Id$-->

  <articleinfo>
    <title>Shorewall Blacklisting Support</title>

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

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

    <pubdate>2004-10-25</pubdate>

    <copyright>
      <year>2002-2004</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>Introduction</title>

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

    <orderedlist>
      <listitem>
        <para>BLACKLISTNEWONLY=No --&nbsp; All incoming packets are checked
        against the blacklist. New blacklist entries can be used to terminate
        existing connections. Versions of Shorewall prior to 1.4.8 behave in
        this manner.</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>
    </important>

    <important>
      <para><emphasis role="bold">Neither form of Shorewall blacklisting is
      appropriate for blacklisting 1,000s of different addresses</emphasis>.
      The blacklists will take forever to load and will have a very negative
      effect on firewall performance.</para>
    </important>
  </section>

  <section>
    <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="Documentation.htm#Config"><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="Documentation.htm#Config"><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="Documentation.htm#Blacklist"><filename>/etc/shorewall/blacklist</filename></ulink>.
        Beginning with Shorewall version 1.3.8, 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="Documentation.htm#Interfaces"><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>
  </section>

  <section>
    <title>Dynamic Blacklisting</title>

    <para>Dynamic blacklisting support was added in version 1.3.2. Dynamic
    blacklisting doesn't use any configuration parameters but is rather
    controlled using /sbin/shorewall commands:</para>

    <itemizedlist>
      <listitem>
        <para>drop <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 <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 <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>
      </listitem>

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

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

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

      <programlisting>    <command>shorewall 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>
      <title>Re-enable packets from a system</title>

      <programlisting>    <command>shorewall allow 192.0.2.125</command></programlisting>

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