forked from extern/shorewall_code
c93817f30b
The invariant sections clause doesn't quite match the official text. It should read: with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts not: with no Invariant Sections, with no Front-Cover, and with no Back-Cover Texts Signed-off-by: Jeremy Sowden <jeremy@azazel.net>
366 lines
15 KiB
XML
366 lines
15 KiB
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/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, no Front-Cover Texts, and 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>
|
|
|
|
<varlistentry>
|
|
<term>log</term>
|
|
|
|
<listitem>
|
|
<para>Added in Shorewall 5.2.5. When specified, successful
|
|
'blacklist' and 'allow' commands will log a message to the system
|
|
log.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>noupdate</term>
|
|
|
|
<listitem>
|
|
<para>Added in Shorewall 5.2.5. Normally, once an address has been
|
|
blacklisted, each time that a packet is received from the packet,
|
|
the ipset's entry for the address is updated to reset the timeout to
|
|
the value specifyed in the <option>timeout</option> option above.
|
|
Setting the <option>noupdate</option> option, inhibits this
|
|
resetting of the entry's timeout. This option is ignored when the
|
|
<option>timeout</option> option is not specified.</para>
|
|
</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.</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>
|
|
|
|
<section id="fail2ban">
|
|
<title>BLACKLIST and Fail2ban</title>
|
|
|
|
<para>The BLACKLIST command can be used as 'blocktype' in
|
|
/etc/fail2ban/actions.d/shorewall.conf. Prior to Shorewall 5.2.5, this
|
|
works best if there is no <emphasis role="bold">timeout</emphasis>
|
|
specified in the DYNAMIC_BLACKLIST setting or if <emphasis
|
|
role="bold">timeout=0</emphasis> is given.</para>
|
|
|
|
<para>Beginning with Shorewall 5.2.5, Shorewall includes new features that
|
|
allow fail2ban to work most seamlessly with Shorewall's ipset-based
|
|
dynamic blacklisting:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>When a <emphasis role="bold">timeout</emphasis> is specified in
|
|
the DYNAMIC_BLACKLIST setting, the dynamic-blacklisting ipset is
|
|
created with default timeout 0. As entries are added by BLACKLIST
|
|
policies or by the <emphasis role="bold">blacklist</emphasis> command,
|
|
the created entry is given the specified timeout value.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The <emphasis role="bold">noupdate</emphasis> option has been
|
|
added. Specifying this option prevents 'timeout 0' ipset entries from
|
|
being changed to finite timeout entries as a result of blacklisted ip
|
|
addresses continuing to send packets to the firewall.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The <emphasis role="bold">blacklist!</emphasis> command has been
|
|
added. specifying that command as the fail2ban 'blocktype' causes
|
|
entries created by fail2ban to persist until fail2ban unbans them
|
|
using the Shorewall <emphasis role="bold">allow</emphasis>
|
|
comand.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>There are a couple of additional things to note:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The documentation in /etc/fail2ban/action.d/shorewall.conf
|
|
states that you should set BLACKLIST=All. A better approach when using
|
|
BLACKLIST as the 'blocktype' is to specify the <emphasis
|
|
role="bold">disconnect</emphasis> option in the setting of
|
|
DYNAMIC_BLACKLIST. With BLACKLIST=All, every packet entering the
|
|
firewall from the net must be checked against the dynamic-blacklisting
|
|
ipset. That is not required when you specify <emphasis
|
|
role="bold">disconnect</emphasis>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The <emphasis role="bold">noupdate</emphasis> option allows
|
|
fail2ban full control when a host is 'unbanned'. The cost of using
|
|
this option is that after the specified <emphasis
|
|
role="bold">timeout</emphasis>, the entry for an attacking host will
|
|
be removed from the dynamic-blacklisting ipset, even if the host has
|
|
continued the attack while blacklisted. This isn't a great concern, as
|
|
the first attempt to access an unauthorized service will result in the
|
|
host being re-blacklisted.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</article>
|