<?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/Whitelisting 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>

      <year>2011</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="Intro">
    <title>Introduction</title>

    <para>Shorewall supports two different types of blacklisting; rule-based,
    static and dynamic. The BLACKLIST option in /etc/shorewall/shorewall.conf
    controls the degree of blacklist filtering.</para>

    <para>The BLACKLIST option lists the Netfilter connection-tracking states
    that blacklist rules are to be applied to (states are NEW, ESTABLISHED,
    RELATED, INVALID, NOTRACK). The BLACKLIST option supersedes the
    BLACKLISTNEWONLY option:</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.</para>
      </listitem>
    </orderedlist>

    <important>
      <para>For automatic blacklisting based on exceeding defined threshholds,
      see <ulink url="Events.html">Events</ulink>.</para>
    </important>
  </section>

  <section>
    <title>Rule-based Blacklisting</title>

    <para>Beginning with Shorewall 4.4.25, the preferred method of
    blacklisting and whitelisting is to use the blrules file (<ulink
    url="manpages/shorewall-blrules.html">shorewall-blrules</ulink> (5)).
    There you have access to the DROP, ACCEPT, REJECT and WHITELIST actions,
    standard and custom macros as well as standard and custom actions. See
    <ulink url="manpages/shorewall-blrules.html">shorewall-blrules</ulink> (5)
    for details.</para>

    <para>Example:</para>

    <programlisting>#ACTION         SOURCE                  DEST                    PROTO   DPORT

WHITELIST       net:70.90.191.126       all
DROP            net                     all                     udp     1023:1033,1434,5948,23773
DROP            all                     net                     udp     1023:1033
DROP            net                     all                     tcp     57,1433,1434,2401,2745,3127,3306,3410,4899,5554,5948,6101,8081,9898,23773
DROP            net:221.192.199.48      all
DROP            net:61.158.162.9        all
DROP            net:81.21.54.100        all                     tcp     25
DROP            net:84.108.168.139      all                             
DROP            net:200.55.14.18        all
</programlisting>

    <para>Beginning with Shorewall 4.4.26, the <command>update</command>
    command supports a <option>-b</option> option that causes your legacy
    blacklisting configuration to use the blrules file.</para>
  </section>

  <section>
    <title>Chain-based 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> and <emphasis
        role="bold">reload</emphasis>.</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>
  </section>

  <section>
    <title>Ipset-based Dynamic Blacklisting</title>

    <para>Beginning with Shorewall 5.0.8, it is possible to use an ipset to
    hold blacklisted addresses. The DYNAMIC_BLACKLIST option was expanded
    to:</para>

    <para><emphasis role="bold">DYNAMIC_BLACKLIST=</emphasis>{<emphasis
    role="bold">Yes</emphasis>|<emphasis role="bold">No</emphasis>||<emphasis
    role="bold">ipset</emphasis>[<emphasis
    role="bold">-only</emphasis>][<replaceable>,option</replaceable>[,...]][:[<replaceable>setname</replaceable>][:<replaceable>log_level</replaceable>|:l<replaceable>og_tag</replaceable>]]]}</para>

    <para>When <option>ipset</option> or <option>ipset-only</option> is
    specified, the <command>shorewall blacklist</command> command is used to
    blacklist a single host or a network. The <command>allow</command> command
    is used to remove entries from the ipset. The name of the set
    (<replaceable>setname</replaceable>) and the level
    (<replaceable>log_level</replaceable>), if any, at which blacklisted
    traffic is to be logged may also be specified. The default set name is
    SW_DBL4 and the default log level is <option>none</option> (no logging).
    If <option>ipset-only</option> is given, then chain-based dynamic
    blacklisting is disabled just as if DYNAMIC_BLACKLISTING=No had been
    specified.</para>

    <para>Possible <replaceable>option</replaceable>s are:</para>

    <variablelist>
      <varlistentry>
        <term>src-dst</term>

        <listitem>
          <para>Normally, only packets whose source address matches an entry
          in the ipset are dropped. If <option>src-dst</option> is included,
          then packets whose destination address matches an entry in the ipset
          are also dropped.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>disconnect</option></term>

        <listitem>
          <para>The <option>disconnect</option> option was added in Shorewall
          5.0.13 and requires that the conntrack utility be installed on the
          firewall system. When an address is blacklisted using the
          <command>blacklist</command> command, all connections originating
          from that address are disconnected. if the <option>src-dst</option>
          option was also specified, then all connections to that address are
          also disconnected.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>timeout</option>=<replaceable>seconds</replaceable></term>

        <listitem>
          <para>Added in Shorewall 5.0.13. Normally, Shorewall creates the
          dynamic blacklisting ipset with timeout 0 which means that entries
          are permanent. If you want entries in the set that are not accessed
          for a period of time to be deleted from the set, you may specify
          that period using this option. Note that the
          <command>blacklist</command> command can override the ipset's
          timeout setting.</para>

          <important>
            <para>Once the dynamic blacklisting ipset has been created,
            changing this option setting requires a complete restart of the
            firewall; <command>shorewall restart</command> if RESTART=restart,
            otherwise <command>shorewall stop &amp;&amp; shorewall
            start</command></para>
          </important>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>When ipset-based dynamic blacklisting is enabled, the contents of
    the blacklist will be preserved over
    <command>stop</command>/<command>reboot</command>/<command>start</command>
    sequences if SAVE_IPSETS=Yes, SAVE_IPSETS=ipv4 or if
    <replaceable>setname</replaceable> is included in the list of sets to be
    saved in SAVE_IPSETS.</para>
  </section>

  <section>
    <title>BLACKLIST Policy and Action</title>

    <para>Beginning with Shorewall 5.1.1, it is possible to specify BLACKLIST
    in the POLICY column of <ulink
    url="manpages/shorewall-policy.html">shorewall-policy</ulink>(5) when
    ipset-based dynamic blacklisting is being used. When a packet is disposed
    of via the BLACKLIST policy, the packet's sender is added to the dynamic
    blacklist ipset and the packet is dropped.</para>

    <para>Also available beginning with Shorewall 5.1.1 is a BLACKLIST action
    for use in the rules file, macros and filter table actions. Execute the
    <command>shorewall show action BLACKLIST</command> command for
    details.</para>
  </section>
</article>