<?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><ip address list></emphasis> - causes packets from the listed IP addresses to be silently dropped by the firewall.</para> </listitem> <listitem> <para>reject [to|from]<emphasis><ip address list></emphasis> - causes packets from the listed IP addresses to be rejected by the firewall.</para> </listitem> <listitem> <para>allow [to|from] <emphasis><ip address list></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><ip address list></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><ip address list></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 && 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>