<!-- $Id: mod_ban.html,v 1.8 2009/12/08 00:24:42 castaglia Exp $ -->
<!-- $Source: /cvsroot/proftp/proftpd/doc/contrib/mod_ban.html,v $ -->
<html>
<head>
<title>ProFTPD module mod_ban</title>
</head>
<body bgcolor=white>
<hr>
<center>
<h2><b>ProFTPD module <code>mod_ban</code></b></h2>
</center>
<hr><br>
<p>
The <code>mod_ban</code> module is designed to add dynamic "ban"
lists to <code>proftpd</code>. A ban prevents the banned user, host, or
class from logging in to the server; it <b>does not</b> prevent the banned
user, host, or class from <i>connecting</i> to the server.
<b><code>mod_ban</code> is not a firewall</b>. The module also provides
automatic bans that are triggered based on configurable criteria.
<p>
This module is contained in the <code>mod_ban.c</code> file for
ProFTPD 1.2.<i>x</i>/1.3.<i>x</i>, and is not compiled by default.
nstallation instructions are discussed <a href="#Installation">here</a>.
Detailed documentation on <code>mod_ban</code> usage can be found
<a href="#Usage">here</a>.
<p>
The most current version of <code>mod_ban</code> is distributed with the
proftpd source.
<h2>Author</h2>
<p>
Please contact TJ Saunders <tj <i>at</i> castaglia.org> with any
questions, concerns, or suggestions regarding this module.
<h2>Directives</h2>
<ul>
<li><a href="#BanControlsACLs">BanControlsACLs</a>
<li><a href="#BanEngine">BanEngine</a>
<li><a href="#BanLog">BanLog</a>
<li><a href="#BanMessage">BanMessage</a>
<li><a href="#BanOnEvent">BanOnEvent</a>
<li><a href="#BanTable">BanTable</a>
</ul>
<h2>Control Actions</h2>
<ul>
<li><a href="#ban"><code>ban</code></a>
<li><a href="#permit"><code>permit</code></a>
</ul>
<p>
<hr>
<h3><a name="BanControlsACLs">BanControlsACLs</a></h3>
<strong>Syntax:</strong> BanControlsACLs <em>actions|"all" "allow"|"deny" "user"|"group" list</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config<br>
<strong>Module:</strong> mod_ban<br>
<strong>Compatibility:</strong> 1.2.10rc1 and later
<p>
The <code>BanControlsACLs</code> directive configures access lists of
<em>users</em> or <em>groups</em> who are allowed (or denied) the ability to
use the <em>actions</em> implemented by <code>mod_ban</code>. The default
behavior is to deny everyone unless an ACL allowing access has been explicitly
configured.
<p>
If "allow" is used, then <em>list</em>, a comma-delimited list
of <em>users</em> or <em>groups</em>, can use the given <em>actions</em>; all
others are denied. If "deny" is used, then the <em>list</em> of
<em>users</em> or <em>groups</em> cannot use <em>actions</em> all others are
allowed. Multiple <code>BanControlsACLs</code> directives may be used to
configure ACLs for different control actions, and for both users and groups.
<p>
The <em>actions</em> provided by <code>mod_ban</code> are "ban"
and "permit".
<p>
Examples:
<pre>
# Allow only user root to ban and permit users
BanControlsACLs all allow user root
</pre>
<p>
<hr>
<h3><a name="BanEngine">BanEngine</a></h3>
<strong>Syntax:</strong> BanEngine <em>on|off</em><br>
<strong>Default:</strong> off<br>
<strong>Context:</strong> server config<br>
<strong>Module:</strong> mod_ban<br>
<strong>Compatibility:</strong> 1.2.10rc1 and later
<p>
The <code>BanEngine</code> directive enables or disables the banning of
sessions by <code>mod_ban</code>. If it is set to <em>off</em> this module
does no banning. Use this directive to disable the module instead of
commenting out all <code>mod_ban</code> directives.
<p>
<hr>
<h3><a name="BanLog">BanLog</a></h3>
<strong>Syntax:</strong> BanLog <em>path|"none"</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config<br>
<strong>Module:</strong> mod_ban<br>
<strong>Compatibility:</strong> 1.2.10rc1 and later
<p>
The <code>BanLog</code> directive is used to a specify a log file for
<code>mod_ban</code> reporting and debugging. The <em>path</em> parameter
must be the full path to the file to use for logging. Note that this path must
<b>not</b> be to a world-writeable directory and, unless
<code>AllowLogSymlinks</code> is explicitly set to <em>on</em>
(generally a bad idea), the path must <b>not</b> be a symbolic link.
<p>
If <em>path</em> is "none", no logging will be done at all.
<p>
<hr>
<h3><a name="BanMessage">BanMessage</a></h3>
<strong>Syntax:</strong> BanMessage <em>mesg</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config<br>
<strong>Module:</strong> mod_ban<br>
<strong>Compatibility:</strong> 1.2.10rc1 and later
<p>
The <code>BanMessage</code> directive configures a message that will be
sent to clients that have been banned. This message may contain the
following variables:
<ul>
<li><code>%a</code>: client IP address
<li><code>%c</code>: client class (if none, will be empty)
<li><code>%u</code>: USER name (if none, will be empty)
</ul>
<p>
Example:
<pre>
BanMessage "Host %a has been banned"
</pre>
<p>
<hr>
<h3><a name="BanOnEvent">BanOnEvent</a></h3>
<strong>Syntax:</strong> BanOnEvent <em>event freq expires [mesg]</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config<br>
<strong>Module:</strong> mod_ban<br>
<strong>Compatibility:</strong> 1.2.10rc1 and later
<p>
The <code>BanOnEvent</code> directive is used to configure a "rule"
that is triggered whenever the named <em>event</em> occurs. The currently
supported events are:
<pre>
AnonRejectPasswords
ClientConnectRate
MaxClientsPerClass
MaxClientsPerHost
MaxClientsPerUser
MaxConnectionsPerHost
MaxHostsPerUser
MaxLoginAttempts
TimeoutIdle
TimeoutLogin
TimeoutNoTransfer
</pre>
An event is generated whenever one of these limits is reached by a client.
<p>
The <em>freq</em> parameter should be formatted as:
<pre>
<i>N</i>/hh:mm:ss
</pre>
where <i>N</i> is the number of occurrences, and <code>hh:mm:ss</code>
specifies a number of hours, minutes, and seconds. This parameter says
that if <i>N</i> occurrences of <em>event</em> happen within the given
time interval, then a ban is automatically added. The IP address of
the connecting client is banned when the following event rules are
triggered: <code>AnonRejectPasswords</code>, <code>MaxClientsPerHost</code>,
<code>MaxConnectionsPerHost</code>, <code>MaxLoginAttempts</code>,
<code>TimeoutIdle</code>, and <code>TimeoutNoTransfer</code>. The class of
the connected client, if any, is banned when a rule for
<code>MaxClientsPerClass</code> is triggered. Rules for
<code>MaxClientsPerUser</code> and <code>MaxHostsPerUser</code> will cause
the connected username to be banned.
<p>
The <em>duration</em> should be formatted as:
<pre>
hh:mm:ss
</pre>
and specifies the numbers of hours, minutes, and seconds that the an
automatic ban generated a <code>BanOnEvent</code> rule lasts. Unlike
bans added via the <a href="#ban">ban</a> <code>ftpdctl</code> control
action, automatic bans do not have infinite lifetimes.
<p>
An optional message, to be displayed to banned clients, can be configured.
If no such optional message is configured using the <code>BanOnEvent</code>
directive, then any <code>BanMessage</code> message will be displayed.
<p>
For example:
<pre>
# Configure a rule to automatically ban scripts looking for anonymous
# servers to which they can upload
BanOnEvent AnonRejectPasswords 1/01:00:00 99:99:99
# Ban clients which connect too frequently. This rule bans clients
# which connect more than 5 times within one minute. Include a special
# message just for them.
BanOnEvent ClientConnectRate 5/00:01:00 04:00:00 "Stop connecting frequently"
</pre>
<p>
See also: <a href="#BanMessage"><code>BanMessage</code></a>
<p>
<hr>
<h3><a name="BanTable">BanTable</a></h3>
<strong>Syntax:</strong> BanTable <em>path</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config<br>
<strong>Module:</strong> mod_ban<br>
<strong>Compatibility:</strong> 1.2.10rc1 and later
<p>
The <code>BanTable</code> directive configures a <em>path</em> to a file
that <code>mod_ban</code> uses for handling its ban data. The given
<em>path</em> must be an absolute path. <b>Note</b>: this directive is
<b>required</b> for <code>mod_ban</code> to function. It is recommended
that this file <b>not</b> be on an NFS mounted partition.
<p>
Note that ban data <b>is not</b> kept across daemon stop/starts. That is,
once <code>proftpd</code> is shutdown, all current ban data is lost.
<p>
<hr>
<h2>Control Actions</h2>
<p>
<hr>
<h3><a name="ban"><code>ban</code></a></h3>
<strong>Syntax:</strong> ftpdctl ban <em>class|host|info|user name1 [name2 ...]</em><br>
<strong>Purpose:</strong> Add a ban or display ban information<br>
<p>
The <code>ban</code> action is used to add bans to the <code>mod_ban</code>
lists. For example, to ban a user:
<pre>
ftpdctl ban user dave
</pre>
To ban specific hosts, you can use either IP addresses or DNS names:
<pre>
ftpdctl ban host 1.2.3.4 5.6.7.8
ftpdctl ban host gw.evil.com
</pre>
Banning a class works the same way:
<pre>
ftpdctl ban class anonftp
</pre>
<p>
The <em>info</em> parameter is used to view information on current bans.
Example listing:
<pre>
# ftpdctl ban info
ftpdctl: Banned Hosts:
ftpdctl: 127.0.0.1
</pre>
Or, if you wish to see more information, use the <code>-v</code> option:
<pre>
# ftpdctl ban info -v
ftpdctl: Banned Hosts:
ftpdctl: 127.0.0.1
ftpdctl: Reason: MaxLoginAttempts autoban at Wed May 19 14:59:25 2004
ftpdctl: Expires: Wed May 19 14:59:55 2004 (in 24 seconds)
</pre>
It is also possible to see the state of ban event rules, using the
<code>-e</code> option:
<pre>
# ftpdctl ban info -e
ftpdctl: No bans
ftpdctl:
ftpdctl: Ban Event Entries:
ftpdctl: Event: MaxLoginAttempts
ftpdctl: Source: 127.0.0.1
ftpdctl: Occurrences: 1/2
ftpdctl: Entry Expires: 589 seconds
</pre>
This shows that no bans are currently in effect, and that a
<code>BanOnEvent</code> has been configured for the
<code>MaxLoginAttempts</code> event. That event has occurred once, and
will need to happen one more time within 589 seconds in order for an
automatic ban to be added.
<p>
See also: <a href="#permit"><code>permit</code></a>
<p>
<hr>
<h3><a name="permit"><code>permit</code></a></h3>
<strong>Syntax:</strong> ftpdctl permit <em>class|host|user name1 [name2 ...]</em><br>
<strong>Purpose:</strong> Permit banned clients to connect<br>
<p>
The <code>permit</code> action is used to remove a ban for users, hosts,
and classes:
<pre>
ftpdctl permit user dave
ftpdctl permit host 1.2.3.4 gw.evil.com
ftpdctl permit class anonftp
</pre>
<p>
See also: <a href="#ban"><code>ban</code></a>
<p>
<hr>
<h2><a name="Installation">Installation</a></h2>
To install <code>mod_ban</code>, copy the <code>mod_ban.c</code> file
into:
<pre>
<i>proftpd-dir</i>/contrib/
</pre>
after unpacking the latest proftpd-1.2.<i>x</i> source code. Then follow the
usual steps for using third-party modules in proftpd, making sure to include
the <code>--enable-ctrls</code> configure option, which <code>mod_ban</code>
requires:
<pre>
./configure --enable-ctrls --with-modules=mod_ban
make
make install
</pre>
<p>
<hr>
<h2><a name="Usage">Usage</a></h2>
The <code>mod_ban</code> module implements its bans by checking if a client
is banned, either by host or by class, when that client connects to the
server. Banned clients are immediately disconnected. Banned users are
checked after the client has sent the <code>USER</code> and <code>PASS</code>
commands; if that user has been banned, the client is immediately disconnected.
<p>
Here is an example <code>mod_ban</code> configuration, demonstrating how
to configure an automatic ban for <code>MaxLoginAttempts</code>:
<pre>
MaxLoginAttempts 1
<IfModule mod_ban.c>
BanEngine on
BanLog /var/log/proftpd/ban.log
BanTable /var/data//proftpd/ban.tab
# If the same client reaches the MaxLoginAttempts limit 2 times
# within 10 minutes, automatically add a ban for that client that
# will expire after one hour.
BanOnEvent MaxLoginAttempts 2/00:10:00 01:00:00
# Allow the FTP admin to manually add/remove bans
BanControlsACLs all allow user ftpadm
</IfModule>
</pre>
<p>
By default, the <code>mod_ban</code> module allocate size for 512 bans.
In practice, this has seemed to work well. However, if you need to allocate
space for more bans, you will need to recompile proftpd, and use the
<code>CFLAGS</code> environment variable like so:
<pre>
./configure CFLAGS="-DBAN_LIST_MAXSZ=<em>1024</em>" ...
</pre>
or whatever your necessary ban list size is.
<p><a name="FAQ"></a>
<b>Frequently Asked Questions</b><br>
<font color=red>Question</font>: Why does <code>mod_ban</code> not store ban
data across daemon stop/starts?<br>
<font color=blue>Answer</font>: The <code>mod_ban</code> module was not
designed to add yet another ACL mechanism to <code>proftpd</code>. For
persistent access control, there is the <code><Limit LOGIN></code>
section, the <code>mod_wrap</code> module, the <code>/etc/ftpusers</code>
file, and various other mechanisms. The purpose of <code>mod_ban</code>
is to provide dynamic, short-lived bans.
<p>
<font color=red>Question</font>: What about having <code>proftpd</code> delay
sending responses to clients, say by 30 seconds or so?<br>
<font color=blue>Answer</font>: This is a bad idea. It would allow
malicious clients, who <i>knew</i> they were banned, to tie up your
<code>proftpd</code> processes, since those processes would be taking up
space, waiting before sending responses back to the client. This makes it
possible for those clients to use the delaying as a Denial of Service attack,
eventually tying up your available system resources with waiting
<code>proftpd</code> processes.
<p>
<font color=red>Question</font>: It looks like the <code>BanTable</code> file
I configured is untouched:
<pre>
-rw-r--r-- 1 ftp ftp 0 2007-01-13 23:18 ban.table
</pre>
Does this mean that something is wrong, or that <code>mod_ban</code> is not
using that file?<br>
<p>
<font color=blue>Answer</font>: A <code>BanTable</code> file <i>is</i> needed,
just not in an obvious way. The <code>mod_ban</code> module stores its ban
information in a SysV shared memory segment. The configured
<code>BanTable</code> file is used <i>a)</i> to generate a unique name/ID for
the shared memory segment to use (and to see if a segment for that name/ID
already exists), and <i>b)</i> for locking, as when multiple sessions are
trying to update the shared memory segment at the same time. But
<code>mod_ban</code> does not write any data into that file itself, and hence
the last-modified-time of the file, and the file size, does not change much.
<p><a name="BanWhitelist">
<font color=red>Question</font>: How can I configure a whitelist of IP
addresses, to be excluded from the effects of <code>mod_ban</code>?<br>
<font color=blue>Answer</font>: This can be done using a combination of
<a href="../howto/Classes.html">Classes</a> and the <a href="mod_ifsession.html"><code>mod_ifsession</code></a> module. For example:
<pre>
<Class whitelist>
From ...
</Class>
<IfClass whitelist>
# Turn the mod_ban module off for whitelisted clients
BanEngine off
</IfClass>
<IfClass !whitelist>
# Make sure the mod_ban module is on for clients that are not whitelisted
BanEngine on
</IfClass>
</pre>
Note that it is <b>important</b> to have <i>both</i>
<code><IfClass></code> sections in your configuration.
<p>
<hr><br>
Author: <i>$Author: castaglia $</i><br>
Last Updated: <i>$Date: 2009/12/08 00:24:42 $</i><br>
<br><hr>
<font size=2><b><i>
© Copyright 2004-2009 TJ Saunders<br>
All Rights Reserved<br>
</i></b></font>
<hr><br>
</body>
</html>
