HOWTO fail2ban 0.7.x

HowTo test the new development branch

For quite a long time now, a new branch is in development. This is almost a complete rewrite with a lot of new features and a better design. There is still a lot of work but this new branch is already functional and can be tested.

This HowTo will not delete or modify your current Fail2ban setup. You only have to turn off any previous version during the tests.

Getting the sources

There is two ways of getting the sources:

• nightly tarball
• Subversion

There is no official release of the 0.7 branch (trunk) yet. The best way for getting the sources is Subversion. The instructions are available here but here is a quick reminder:

svn co https://svn.sourceforge.net/svnroot/fail2ban/trunk fail2ban-trunk

The sources are now available in the directory called fail2ban-trunk. If you decide to use the tarball, simply run:

tar xvfj fail2ban-nightly.tar.bz2

You should have a directory called fail2ban-0.7.0-SVN.

Change your current directory to fail2ban-trunk or fail2ban-0.7.0-SVN.

Setup

The configuration folder should look like this:

config/
|-- action.d
|   |-- dummy.conf
|   |-- foo.conf
|   |-- hostsdeny.conf
|   |-- iptables.conf
|   |-- mail-whois.conf
|   `-- mail.conf
|-- fail2ban.conf
|-- filter.d
|   |-- apache-auth.conf
|   |-- sshd.conf
|   `-- vsftpd.conf
`-- jail.conf

The most important file is probably jail.conf. It contains the definition of your jails. A jails is the combination of one filter and one or several actions. More information about the jail concept are available here. You can override configuration files using a .local file. Per example, config/fail2ban.local overrides the settings in config/fail2ban.conf.

For this tutorial, we will setup a configuration similar to what previous versions do: parse SSH logs, ban hosts using iptables and send notification e-mails.

SSH filter setup

The default configuration for the SSH filter should not require too much changes. However, you could have to change the path of the logs file. Create config/filter.d/sshd.local and add the following content.

[Definition]

logpath=/var/log/pwdfail/current

Thus, we do not have to change config/filter.d/sshd.conf. This is quite useful when upgrading or if you want to save your own changes. Adapt the value of logpath to point to your SSH daemon log file.

Iptables action setup

The Iptables script should be fine. However, some settings have to be set in config/jail.conf.

Jail setup

We are now able to define our first jail. Actually, config/jail.conf is a bit messy... I suggest your erase all the sections in this file and add this.

[ssh]

enabled = true
filter = sshd
action = iptables[name=ssh,port=22,protocol=tcp]
         mail[name=SSH,dest=toto@titi.com]
maxretry = 3

The filter option is the name of a file in config/filter.d without the .conf extension. The action field is more interesting. Here, we set as first action the iptables script. Action script can have parameters. Have a look at config/action.d/iptables.conf. Please, be aware that no spaces are allowed in the parameters field. This will be fixed in the future. We define a second action. It will send a notification e-mail. Just replace the dest parameter with your e-mail address. Be aware that the mail script uses the mail command of the system. Ensure this command works on your box.

Client/Server

Fail2ban is now composed of two parts: a server and a client. The server listens on a socket and waits for commands. It monitors log files and executes actions. The client part is used to communicate with the server. It converts the config/ settings into commands which are sent to the server through a Unix socket.

For this tutorial, I suggest you use two terminal or better, screen. Moreover, you need to have root access.

In the first terminal, start the server in foreground:

# ./fail2ban-server -f

Nothing should be display. A socket file should have been created in /tmp:

# ls /tmp/fail2ban.sock
/tmp/fail2ban.sock

Open a second terminal. We will first test whether the configuration directory can be parse correctly. Runs the following command:

# ./fail2ban-client -d

Check that no exceptions are triggered. Here you should get a lot of output like:

['set', 'loglevel', 3]
['set', 'logtarget', 'STDERR']
['add', 'ssh']
['set', 'ssh', 'bantime', 600]
['set', 'ssh', 'logpath', '/var/log/pwdfail/current']
['set', 'ssh', 'maxretry', 3]

These are the commands which will be sent to the server. You could send them manually with:

# ./fail2ban-client set loglevel 3

But it would be a bit annoying. There is a special command to send the configuration to the server:

# ./fail2ban-client loadconf

The server should now start monitoring the log file. Look at the server terminal. If you do not see anything, output are maybe redirected into the log file /var/log/fail2ban.log. You can change this in config/fail2ban.conf or, better, create your own config/fail2ban.local. You can also change this in realtime with:

# ./fail2ban-client set logtarget STDERR

All of this without restarting the server which is carefully watching your log files during the operation. Mmmmhhh... Three retries are a bit too agressive? Change the setting with:

# ./fail2ban-client set ssh maxretry 5

You do not need to restart anything. The changes are taken into account directly. Maybe you saw the RRDTool plot at the end of the Screenshots page. The information for this graph come from the following command:

# ./fail2ban-client status ssh
fail2ban.client : INFO   OK : [('filter', [('Currently failed', 0), ('Total fail
ed', 17)]), ('action', [('Currently banned', 0), ('Total banned', 2)])]

The output formatting of the client application in not yet really pretty. There is still lots of work in this area (any help is welcome).

You can stop the server with the following command:

# ./fail2ban-client quit

Warning

There is still a lot of work to do. Here are some known issues.

• You can start several servers at the same time but can only communicate with the last created. You must kill the others manually.
• Running several time the loadconf option is not recommanded. Restart the server first.

If you want to help with Python programming, documentation, etc, do not hesitate to contact me.