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.
Installations via apt will enable the module automatically.
You can check this using the apachectl utility:
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:
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:
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.
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.
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:
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.
