Last Update: 11/13/2012
The Goal:
Fail2Ban is a very flexible and powerful tool to help you improving your security by temporarily banishing hosts IPs trying to have malicious activity against your services. (brute force attack...)
Easy to install and configure, Fail2Ban will permanently read your files logs and look for suspicious connection attempts or activity, based on provided / custom rules.
Depending on your configuration, Fail2Ban will ban the remote IP using Netfilter rules (iptables) and then unban it depending on your settings.
This a very great tool you MUST have in your server if you opened any service like ssh, http/https with basic authentication, smtp...and much more.
Major sources:
Official Fail2ban Wiki:
http://www.fail2ban.org/wiki/index.php/Main_Page
Various articles:
http://www.fanatips.org/Apache_%2F%2F_Nginx_tips/Secure_Nginx_with_fail2ban
http://snippets.aktagon.com/snippets/554-How-to-Secure-an-nginx-Server-with-Fail2Ban
Summary of steps:
Step 1: Requirements
Step 3: Enabling services
Step 4: Test your configuration
Step 5: Adding new customized services, example with Nginx Web Server
FAQ & Issues
Step 1: Requirements
Fail2ban is quite easy to install and setup, still depending on your needs you have some requirements:
Iptables:
Fail2ban will require iptables to banish suspicious hosts, it is not a requirement to setup your iptables Firewall configuration (even if recommended).
Fail2ban will insert a drop line, whenever you are using iptables or not.
Fail2ban will insert a drop line, whenever you are using iptables or not.
It is probably installed by defaut (use the command "iptables" to check), if not:
$ sudo apt-get install iptables
MTA configuration for mail alerting:
If you want Fail2ban to able to send you alerting mails in case of action done (banish, unbanish...), then you need to setup your MTA.
Your system probably only be a client of a mail central hub (eg. your ISP), if this is the case i recommend to install "ssmtp" wich is very light and simple to setup, but you may prefer to use sendmail, postfix or anything else.
If your system is a mail server itself, i guess you already know how to configure it :-)
Installation:
$ sudo apt-get install ssmtp
Configuration (real simple!):
Edit "/etc/ssmtp/ssmtp.conf" and set:
- mailhub: Define here the smtp server of your local ISP (eg. myisp.smtp.com)
- rewriteDomain: if you want the sender domain to be rewritten with the value of your choice
For most of cases, this will be the only modifications required, in case of need see ssmtp configuration pages. (ask Google ^^)
Quick send test:
$ echo "Testing" | mail -s Subject dest@domain.com
If you receive the mail then you're done. (check /var/log/mail* if required)
Step 2: Installation and base configuration
Installation:
Very simple, For Debian/Ubuntu based systems:
$ sudo apt-get install fail2ban
Initial Configuration:
Edit main Fail2Ban configuration file: "/etc/fail2ban/jail.conf" and define:
1. Local hosts to ignore:
# "ignoreip" can be an IP address, a CIDR mask or a DNS host ignoreip = 127.0.0.1/8 192.168.0.0/24 bantime = 600 maxretry = 3
2. Mail alert recipient:
If you want to send alter when an action has been done, set the recipient
# Destination email address used solely for the interpolations in # jail.{conf,local} configuration files. destemail = admin@mydomain.com
3. MTA:
Sendmail is defined as default command called for sending mails, both should work but i prefer to call standard "mail" command:
# email action. Since 0.8.1 upstream fail2ban uses sendmail
# MTA for the mailing. Change mta configuration parameter to mail
# if you want to revert to conventional 'mail'.
mta = mail
4. Default action when a host has banished
In default configuration, when a host has been banned, the information is just logged and no mail report will be sent.
If you want a report to be sent by mail (associated with a whois request report for the concerned IP), set:
If you want a report to be sent by mail (associated with a whois request report for the concerned IP), set:
action = %(action_mw)s
If you want a report to be sent by mail with a log extract (associated with a whois request report for the concerned IP), set:
action = %(action_mwl)s
Step 3: Enabling services
SSH example:
The next step will be to define which Network services you will want to supervise, in default configuration Fail2Ban will only monitor SSH for both login failed and DDOS attacks, extract:
[ssh] enabled = true port = ssh filter = sshd logpath = /var/log/auth.log maxretry = 6
Fail2ban will create multiport iptables rules, so you can add as many ports as you require.
Example if your SSH is running on several port (example 22 for internal and OTHER for external purposes) then you can set:
[ssh]
enabled = true
port = ssh,OTHER
filter = sshd
logpath = /var/log/auth.log
maxretry = 6
In each service section, you can overwrite default vars values or set specific ones for your needs.
Here are some you may need to set.
1. Protocol type:
protocol = all
2. Ban time:
You may want to overwrite the default bantime, then you just need to it in the service concerned section, time is set in seconds, example for 10 minutes banishment:
bantime = 600 # 10 minutes
3. Ports:
As seen before with the SSH example, you can set as many ports as you required in the port section.
You can call them by names if they are present in /etc/services or by the port number.
Each port must be separated by a coma.
4. Action:
Then you will overwrite the action value in your service section:
action_ = %(banaction)s[name=%(__name__)s, port="%(port)s", protocol="%(protocol)s", chain="%(chain)s
Enable your services:
Follow each section to enable if required.
Step 4: Testing your configuration
Testing your configuration is very simple :-)
Just test accessing your SSH host outside of your local network (using your Smartphone or whatever you want!) and put false credentials.
Upon the max retry failures, your host should have been banished, you will see in fail2ban logs:
/var/log/fail2ban.log
2012-11-13 10:41:43,487 fail2ban.actions: WARNING [ss] Ban xxx.xxx.xxx.xxx
Chain fail2ban-ssh (1 references) target prot opt source destination DROP all -- 37.160.52.0 anywhere RETURN all -- anywhere anywhere
Depending on your configuration, XX minutes/days or whatever after having been ban, the host will be unban and the iptables drop rule will be removed.
Powerful, simple, beautiful :-)
One of very great things with Fail2ban is that you can easily add any customized service you would require, you just add to define regex expression that will be used to match patterns and define Network section.
Nginx Web Server Fail2Ban integration:
1. Create Nginx filters
Create each required file with its content:
/etc/fail2ban/filter.d/nginx-auth.conf
# # Auth filter /etc/fail2ban/filter.d/nginx-auth.conf: # # Blocks IPs that fail to authenticate using basic authentication # [INCLUDES] # Read common prefixes. If any customizations available -- read them from # common.local before = common.conf [Definition] failregex = no user/password was provided for basic authentication.*client: <HOST> user .* was not found in.*client: <HOST> user .* password mismatch.*client: <HOST> ignoreregex =
/etc/fail2ban/filter.d/nginx-login.conf
# # Login filter /etc/fail2ban/filter.d/nginx-login.conf: # # Blocks IPs that fail to authenticate using web application's log in page # # Scan access log for HTTP 200 + POST /sessions => failed log in [INCLUDES] # Read common prefixes. If any customizations available -- read them from # common.local before = common.conf [Definition] failregex = ^<HOST> -.*POST /sessions HTTP/1\.." 200 ignoreregex =
/etc/fail2ban/filter.d/nginx-noscript.conf
# Noscript filter /etc/fail2ban/filter.d/nginx-noscript.conf: # # Block IPs trying to execute scripts such as .php, .pl, .exe and other funny scripts. # # Matches e.g. # 192.168.1.1 - - "GET /something.php # [INCLUDES] # Read common prefixes. If any customizations available -- read them from # common.local before = common.conf [Definition] failregex = ^<HOST> -.*GET.*(\.php|\.asp|\.exe|\.pl|\.cgi|\scgi) ignoreregex =
/etc/fail2ban/filter.d/nginx-proxy.conf
# Proxy filter /etc/fail2ban/filter.d/nginx-proxy.conf: # # Block IPs trying to use server as proxy. # # Matches e.g. # 192.168.1.1 - - "GET http://www.something.com/ # [INCLUDES] # Read common prefixes. If any customizations available -- read them from # common.local before = common.conf [Definition] failregex = ^<HOST> -.*GET http.* ignoreregex =
2. Create Nginx configuration
Edit Fail2Ban configuration "/etc/fail2ban/jail.conf" and add:
Note:
If Nginx is listening to non standard http/https port, think to adapt to your configuration
Also, nginx-noscript will prevent any script execution on your sites, if this is not what you need just comment out this section.
/etc/fail2ban/jail.conf
[nginx-auth] enabled = true filter = nginx-auth port = http,https logpath = /var/log/nginx*/*error*.log bantime = 600 # 10 minutes maxretry = 6 [nginx-login] enabled = true filter = nginx-login port = http,https logpath = /var/log/nginx*/*access*.log bantime = 600 # 10 minutes maxretry = 6 [nginx-badbots] enabled = true filter = apache-badbots port = http,https logpath = /var/log/nginx*/*access*.log bantime = 86400 # 1 day maxretry = 1 [nginx-noscript] enabled = true port = http,https filter = nginx-noscript logpath = /var/log/nginx*/*access*.log axretry = 6 bantime = 86400 # 1 day [nginx-proxy] enabled = true port = http,https filter = nginx-proxy logpath = /var/log/nginx*/*access*.log maxretry = 0 bantime = 86400 # 1 day
Finally, restart fail2ban and you're done! (sudo service fail2ban restart)
To test your configuration, just try to access to your basic authentification protected Web Site with bad credentials, as for the SSH example your host will be ban and you'll get the report :-)
FAQ & Issues
- How to prevent Fail2ban from sending alerts mails when stopped/started
When email alerting is configured, fail2ban will send you one mail per jail configured (one per Network service) for each action (stop/start).
This can be as usefull as boring :-)
If you want to disable this behavior:
- Go in "/etc/fail2ban/actions.d/"
- You will find 6 configurations files related to sendmail & mail, depending on what you set (sendmail vs mail) you just have to comment out actionstart and actionstop:
"action_": comment "actionstart" & "actionstop" in action.d/sendmail.conf
"action_mw": comment "actionstart" & "actionstop" in action.d/sendmail-whois.conf
"action_mwl": comment "actionstart" & "actionstop" in action.d/sendmail-whois-lines.conf
"action_": comment "actionstart" & "actionstop" in action.d/mail.conf
"action_mw": comment "actionstart" & "actionstop" in action.d/mail-whois.conf
"action_mwl": comment "actionstart" & "actionstop" in action.d/mail-whois-lines.conf
- Restart fail2ban, you're done!
