mod_evasive is an Apache module which helps defend your server against brute force and denial of service attacks. Setting up mod_evasive gives you a safety net to catch malicious actors before they can start degrading your server's performance.

The module comes with several configuration parameters that let you define the number of concurrent requests a client can make in a set timeframe. Further requests will be blocked for a period after the limit is exceeded.

Installing mod_evasive

Installation steps vary depending on your operating system distribution and Apache release. For the most popular combination of Apache 2.4 on a Debian-based system, use the following steps. Instructions for building from source are also provided in the project's repository.

apt update
    
    
            apt install libapache2-mod-evasive

Installations via apt will enable the module automatically.

You can check this using the apachectl utility:

apachectl -M | grep evasive

You should see the module's name displayed if it's active.

Configuring Blocking Settings

The mod_evasive configuration file can usually be found at /etc/apache2/mods-enabled/evasive.conf. It uses the same format as other Apache config files. A complete reference can be found in the mod_evasive docs.

Here's an example configuration file with several customizations:

<IfModule mod_evasive20.c>
    
    
             DOSPageCount 5
    
    
             DOSSiteCount 10
    
    
             DOSPageInterval 1
    
    
             DOSSiteInterval 2
    
    
             DOSBlockingPeriod 300
    
    
             DOSEmailNotify user@example.com
    
    
            </IfModule>

mod_evasive distinguishes between requests for a page and requests for a site. You can set these two blocking factors independently of each other. This example will block clients which request the same URI five times in a one second interval. A block will additionally be imposed on clients which request more than ten URIs from a single site within a two second interval.

When either of the limits is exceeded, the client will be blocked from making further requests for a period of five minutes (300 seconds). mod_evasive will send an email to user@example.com notifying that the IP address has been blocked.

mod_evasive also supports running an arbitrary system command when a limit is reached. This can be used to integrate the tool with your own application or firewall so you can record a block in your database. Set the DOSSystemCommand setting, using %s to denote the blocked IP address:

DOSSystemCommand /app/blacklisted_ip.php --ip=%s

Whitelisting Known IPs

mod_evasive supports a whitelist of known IPs to aid development and testing. Developers can sometimes create high request volumes while working on a server, whether intentionally or otherwise.

Use the DOSWhiteList setting to specify IP address ranges to ignore. Limits will not be applied to any of these addresses.

DOSWhiteList 127.0.0.1
    
    
            DOSWhiteList 192.168.0.*

How Does It Work?

mod_evasive functions by maintaining a hash table of IP addresses and URIs in a temporary blacklist. The IP address and URI are hashed to create a key that can be used to check whether the client has requested the same page previously.

A block occurs when a URI or site appears in the IP's hash table with greater frequency than you've allowed. This results in a 403 status code being sent back to the client. The status is the only response the client will receive, minimizing the server resources needed to handle requests that are deemed to be spurious or malicious.

Once a cap's been reached the client must wait for the specified DOSBlockingPeriod before it can make another successful request. Trying again during the waiting period results in an even longer block being imposed. Other IP addresses continue to be admitted as usual and shouldn't experience disruption from the denial of service attempt.

The module can cause a performance penalty on very active servers. It needs to record each request and check whether the IP has been blocked, or needs to be blocked. Busy servers with sufficient memory should increase the DOSHashTableSize setting to allow for a larger in-memory hash table. This reduces the time needed to lookup an incoming IP against its other recent requests.

DOSHashTableSize 32768

Testing Your Installation

The best way of testing mod_evasive is to launch a brief flood of requests to check how your server responds. With mod_evasive enabled correctly, you should quickly start seeing 403s and an email alert if it's configured.

The ab command line tool can be used to initiate connections en masse:

ab -n 1000 -c 50 http://...

You should adjust the -n and -c parameters to suit your mod_evasive configuration and anticipated server impact:

• -n - The total number of requests to make.
• -c - The number of concurrent connections to open.

The example above will send 1,000 requests in batches of 50.

ab is a powerful tool which could initiate a genuine denial of service attack. Make doubly sure you've specified the correct server address before you send the requests!

Summary

mod_evasive is a simple but effective module for preventing brute force attacks from impacting your server's operation. You can configure per-page and per-site limits that apply to each client attempting a connection. If the client ends up exceeding the limit, they'll receive a 403 and must concede to a temporary blocking period.

As an administrator, you can opt-in to receive email alerts when a new block is imposed. This keeps you informed of potential attacks and lets you monitor for false positives. You do need a functioning email stack on the server - mod_evasive sends using the system mail transfer agent.

Finally, it's possible to integrate mod_evasive with other parts of your application by running a system command whenever an IP is blacklisted. This capability could be used to flag a database user, create an alert in a third-party monitoring tool, or relay the block to your other servers to protect additional parts of your infrastructure.