Configuring Fail2Ban:

Overview:

0. Intention
1. Fail2Ban Overview
2. Install Fail2Ban
3. Configure jail.local
4. Configure defaults-debian.local
5. Permanence and Persistence <optional>
6. Restart the Service
7. Closing Thoughts

0) Introduction & Intention

This write-up is intended to be a walkthrough for configuring Fail2Ban to help thwart brute-force attempts targeting an ssh server. Check here for the explanation of how to install and set-up an SSH server. I'll be configuring Fail2Ban on a Debian box hosted by Digital Ocean. While there are many other great options out there, this is simply my preferred platform and should provide some fairly solid guidelines for most distributions.

1) Fail2Ban Overview

Fail2Ban is a nifty tool that monitors for failed login attempts and bans the offending source IP, via iptables, once the failed attempts meet a user-defined threshold.

Fail2Ban utilizes 2 types of files for configurations; *.conf and *.local; the *.local files over-ride the settings in the *.conf. Occasionally, updates to the Fail2Ban applications may over-write the a *.conf file with a new version that alters the default configurations. This may be done to increase stability or security, or to incorporate new features. For this reason, best practice is to leave the *.conf files untouched, and only edit the *.local.

You can create a clean *.local file and add only the configurations you need. However, a common method is to copy a *.conf file to *.local. From there, you simply modify the settings that you want to explicitly alter, and then comment out all of the rest. This makes it easier to implement quick alterations without having to remember every option and the associated command syntax. The 2 primary configuration files ( as of version 0.9.6 ) are

/etc/fail2ban/jail.conf

and

/etc/fail2ban/jail.d/defaults-debian.conf

2) Install Fail2Ban

Fail2Ban is included in the repositories for most linux distributions, so the initial install is pretty straightforward:

 sudo apt-get install fail2ban

Next, make a *.local copy of each file:

    cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local
    cp /etc/fail2ban/jail.d/defaults-debian.conf /etc/fail2ban/jail.d/defaults-debian.local
                                

3) Configure jail.local

This file holds the various options that will be applied to Fail2Ban globally, as well as to each service Fail2Ban will protect. The options presented here are some basic settings which should work for most installs but, as always, it is highly encouraged to review what each option does and to adjust them as appropriate. Requirements may vary based on environment, implementation, threat model, etc.

Under the [DEFAULT] entry, Fail2Ban will be configured to look for connections that fail 5 times within 600 seconds (10 minutes). Connections from that IP will be banned for 600 seconds. To do so, add/edit the following entries:

    [DEFAULT]
    bantime = 600
    findtime = 600
    maxentry = 5
                                

Located further in the file is a section for jails, which should include an entry for SSH servers. Under that entry should be the following:

    [sshd]
    
    port    = ssh
    logpath = %(sshd_log)s
    backend = %(sshd_backend)s
                                

If the above code doesn't exist, be sure to add it. All other lines in this file should be commented out.

If your IP address doesn't change on the machine you SSH with, you could tell Fail2Ban to ignore connections from your ip (or subnet) by adding it to the ignoreip entry under the [DEFAULT] block. Multiple ip addresses can be specified by separating them with a space or comma.

    [DEFAULT]
    ....
    ignoreip = 127.0.0.1/8
                                

4) Configure defaults-debian.local

This file specifies the services Fail2Ban will be applied to. Edit it to ensure it contains the following text, if it doesn't already:

    [sshd]
    enabled = true
                                

5) Permanence and Persistence <optional>>

The current configuration will ban an offending IP for 1 hour, at which point the ban will expire. A few additional modifications can be made to make the bans permanent.

In the /etc/fail2ban/jail.local file, you can change the bantime to -1. A good recommendation is to comment out the existing entries and write a new one:

    # "bantime" is the number of seconds that a host is banned.
    bantime  = 600
                                

    # Permanent ban
    bantime = -1
                                

This adjustment creates bans that are permanent (don't expire) but they are not yet persistent. If the Fail2Ban service is restarted, such as by a system reboot, then then bans will be cleared.

First, create a file to hold the list of IP address bans that should persist through service restarts:

    touch persistence.lst
                                

Next, check your /etc/fail2ban/jail.conf file to verify the default ban action.

    # ACTIONS
    ....
    banaction = iptables-multiport
                                

iptables-multiport is the default setting, but there are other possible options for banaction to be set to. Each action has a unique configuration file associated with it, which will need to be edited in order to complete the persistence. So in this case, the corresponding file for iptables-multiport is /etc/fail2ban/action.d/iptables-multiport.conf. Add an additional line at the end of the actionstart block:

    cat /etc/fail2ban/persistence.lst | while read IP; do iptables -I f2b-<name> 1 -s $IP -j DROP; done
                                

An additional line will also need to be added at the end of the actionban block:

    echo <ip> >> /etc/fail2ban/persistence.lst
                                

The following command can also be used to manually ban/unban an ip:

    sudo fail2ban-client set   
                                

In this case, the jail can be any jail specified in the /etc/fail2ban/jail.d/defaults-debian.local file, such as 'sshd'. The action is either 'ban' or 'unban', and the IP is whatever IP address you would like the action to affect.

6) Restart the Service

Finally, restart the Fail2ban service to ensure the new configuration entries are loaded

    sudo service fail2ban restart 
                                

You can verify that Fail2Ban is running using this command:

    service fail2ban status
                                

Here are some other commands for viewing additional status information:

    fail2ban-client status
    fail2ban-client status sshd # specifically view ssh status info
                                

7) Closing Thoughts

This breakdown should hopefully give you a basic understanding of how to configure Fail2Ban to help protect an SSH server. These are the settings that I recommend, although it is important to keep in mind that your needs and your environment will determine which, if any, of these recommendations work for you. You should always keep your threat model in mind when implementing configuration changes, and never blindly follow advice on the internet. Remember: Trust, but verify! Do you think I missed something? Did a step not work? Could this simply be the most bestest article you've ever seen on the interwebz? Feel free to stop by the channel and let us know what you think. You can send your flames or flattery for this article to PrettyKittie via IRC or email.

Recommended Reading

• Fail2Ban Home
• And a huge thanks to David Egan/Carawebs for this gem which filled in the missing pieces I needed to get the persistence to work properly!