Difference between revisions of "FAQ english"

From Fail2ban
Jump to: navigation, search
(How to ask for help or submit a bug report?)
(Troubleshooting: add faq about missing information - requested in gh-471)
 
(66 intermediate revisions by 36 users not shown)
Line 1: Line 1:
== '''General''' ==
+
== '''Troubleshooting''' ==
  
=== What is {{Fail2ban}}? ===
+
=== I get emails containing "Here are/is more information about <ip>" and then nothing ===
  
{{Fail2ban}} scans log files like <tt>/var/log/pwdfail</tt> or <tt>/var/log/apache/error_log</tt> and bans IP that makes too many password failures. It updates firewall rules to reject the IP address. These rules can be defined by the user. {{Fail2ban}} can read multiple log files such as sshd or Apache web server ones.
+
You are using a mail-whois*/sendmail-whois* action and you don't have the ''whois'' executable installed.
  
=== Is {{Fail2ban}} free software? ===
+
=== I have Postfix on my system but no "mail" command. How can I get e-mail notifications? ===
  
{{Fail2ban}} is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
+
'''As of version 0.8.1, "mail" actions are deprecated. Please use the "sendmail" ones instead. E.g. sendmail-whois instead of mail-whois in your jail.[conf|local].'''
  
=== What do you need to run {{Fail2ban}}? ===
+
You probably have the ''sendmail'' command. Copy ''/etc/fail2ban/action.d/mail-whois.conf'' to ''/etc/fail2ban/action.d/mail-whois.local'', edit this file and replace ''mail'' with ''sendmail''. Here is an example:
 
+
Take a look at [[Requirements]] section
+
 
+
=== How to ask for help or submit a bug report? ===
+
 
+
First of all, try to find an answer on this website. Read the [[FAQ]], [[Manual]] and visit [[HOWTOs]]. Search the [http://sourceforge.net/mail/?group_id=121032 mailing lists] archives and look at the [http://sourceforge.net/tracker/?group_id=121032 trackers]. If you did not found any answer, subscribe to this [https://lists.sourceforge.net/lists/listinfo/fail2ban-users mailing list] and ask your question there. Registration is required in order to avoid spam.
+
 
+
If you are convinced that you found a bug, you can directly open a new tracker [http://sourceforge.net/tracker/?group_id=121032&atid=689044 here].
+
 
+
Try to increase the verbosity of {{Fail2ban}}. Use '''-vvv''' for '''fail2ban-client''' and '''fail2ban''' (only for 0.6.x). Set '''loglevel''' to '''4''' in ''/etc/fail2ban/fail2ban.conf'' (only for > 0.6).
+
 
+
In any case, when asking for support, please provide the following information:
+
 
+
* The version of {{Fail2ban}} you are running (use '''-V''' or '''--version''')
+
* The version of Python
+
* How you installed {{Fail2ban}} (sources, .deb, .rpm, etc)
+
* Relevant parts of the configuration files of {{Fail2ban}}
+
* Logging output of {{Fail2ban}} using the DEBUG mode ('''-vvv''' and '''loglevel = 4''')
+
 
+
And of course, do not forget to describe clearly your problem.
+
 
+
== '''Installation''' ==
+
 
+
=== Are there RPM/DEB packages for {{Fail2ban}}? ===
+
 
+
Sure. Please take a look at [[Downloads]] section
+
 
+
=== How can I install {{Fail2ban}} from a RPM/DEB/gentoo package? ===
+
 
+
If you are using rpm:
+
 
+
rpm -ivh fail2ban-X.X.X.rpm
+
 
+
If you are required to install a src.rpm (source package) please follow these instructions:
+
 
+
rpm --rebuild fail2ban-X.X.X.src.rpm
+
 
+
After that, binary rpm will be placed at <tt>/usr/src/RPM/RPMS/ix86</tt>
+
 
+
rpm -ihv /usr/src/RPM/RPMS/ix86/fail2ban-X.X.X.rpm
+
 
+
Please check that your PATH is <tt>/usr/src/RPM/RPMS/ix86/</tt> before doing anything else.
+
 
+
If you want to install {{Fail2ban}} from a .deb package:
+
 
+
dpkg -i fail2ban-X.X.X.deb
+
 
+
If you want to install {{Fail2ban}} on gentoo:
+
 
+
emerge fail2ban
+
 
+
== '''Configuration''' ==
+
 
+
=== What is the main configuration file for {{Fail2ban}}? ===
+
 
+
{{Fail2ban}} configuration process is rather simple. There is only one configuration file, where {{Fail2ban}} can be whole configurated, this file is located at:
+
<tt>/etc/fail2ban.conf</tt>
+
 
+
You are able to edit this file using any editor we want: vim, emacs, joe, ae...
+
 
+
Configuration file must be edited by '''root'''
+
 
+
=== How can {{Fail2ban}} be configured? ===
+
 
+
This step is fully detailed at [[HOWTOs]] chapter
+
 
+
=== Can I exclude failed logins for selected users from resulting in a ban? ===
+
 
+
(I don't know, perhaps that's a feature request.)
+
 
+
== '''Security''' ==
+
 
+
=== What do I have to consider when using {{Fail2ban}} ===
+
 
+
Especially on systems wich provide ssh/CGI/PHP services to unknown users it is possible to block other users from ssh and probably other access as a unprivileged user may issue:
+
 
+
logger -p auth.warning -t 'sshd[123]' 'Illegal user user1 from 1.2.3.4'
+
 
+
Or the malicious user may write via PHP's openlog()/syslog() to syslog.
+
 
+
Solution #1:
+
This security hazard can be handled via ownership/permissions of /dev/log, which allows logging to all the users by default. Just add a group log, add all daemons, and root to that group and be happy.
+
 
+
== '''Troubleshooting''' ==
+
 
+
=== I have Postfix on my system but no "mail" command. How can I get e-mail notifications? ===
+
 
+
You have probably the ''sendmail'' command. Copy ''/etc/fail2ban/action.d/mail-whois.conf'' to ''/etc/fail2ban/action.d/mail-whois.local'', edit this file and replace ''mail'' with ''sendmail''. Here is an example:
+
  
 
  actionban = echo -en "From:root <fail2ban>
 
  actionban = echo -en "From:root <fail2ban>
Line 114: Line 26:
 
=== Why do my CVS users using SSH getting blocked? ===
 
=== Why do my CVS users using SSH getting blocked? ===
  
If your are using the Eclipse CVS integration with SSH, then each access of the CVS results in a failed access before a valid one is done. As a consequence your CVS users get banned from time to time.
+
If you are using the Eclipse CVS integration with SSH, then each access of the CVS results in a failed access before a valid one is done. As a consequence your CVS users get banned from time to time.
  
 
=== I get the error "Please check the format and your locale settings" ===
 
=== I get the error "Please check the format and your locale settings" ===
Line 132: Line 44:
  
 
  # locale -a
 
  # locale -a
 +
 +
=== How do I increase verbosity? ===
 +
 +
In order to increase the verbosity of {{Fail2ban}}, use the command line option '''-vvv''' for '''fail2ban-client''' and '''fail2ban''' (only for 0.6.x). Set '''loglevel''' to '''4''' in ''/etc/fail2ban/fail2ban.conf'' (only for > 0.6.x).
  
 
[[Category:Documentation]]
 
[[Category:Documentation]]
 +
 +
=== Fail2ban-client is unable to contact server ===
 +
Did you make sure to run fail2ban-client status using sudo?
 +
 +
$ fail2ban-client status
 +
ERROR  Unable to contact server. Is it running?
 +
 +
$ sudo fail2ban-client status
 +
Status
 +
|- Number of jail: 1
 +
`- Jail list: ssh
 +
 +
=== Fail2ban is running but not banning SSH bruteforce ===
 +
'''NB''':This example is based on a Debian system, but can be easily done on any distro.
 +
 +
The package is well installed:
 +
 +
# dpkg -l |grep fail                                             
 +
ii  fail2ban                      0.8.1-2                        bans IPs that
 +
cause multiple authentication
 +
 +
The service is running:
 +
 +
# /etc/init.d/fail2ban status                                     
 +
Status of authentication failure monitor: fail2ban is running
 +
 +
SSH jail is set up and ready:
 +
 +
# sudo fail2ban-client status                                         
 +
Status                                                                         
 +
|- Number of jail:      1                                                     
 +
`- Jail list:          ssh
 +
 +
SSH bruteforce logs are identified by fail2ban:
 +
 +
# fail2ban-regex /var/log/auth.log /etc/fail2ban/filter.d/sshd.conf
 +
....
 +
Success, the total number of match is 30
 +
 +
So, check that all your logs are synchronized: all logs files (auth.log, syslog,..) must use the same time reference (if your server is not very busy, there will probably be an important difference between the output of [http://unixhelp.ed.ac.uk/CGI/man-cgi?date ]date command and the last event logged in syslog. You can force to generate a log in syslog using the [http://unixhelp.ed.ac.uk/CGI/man-cgi?logger+1 logger] command and check then with the output of date command)
 +
 +
# date                                                           
 +
Wed Nov 28 13:49:02 CET 2007                                                   
 +
# tail -2 /var/log/auth.log                                       
 +
Nov 28 13:39:12 <SERVERNAME> sudo: pam_unix(sudo:session): session opened for user roo
 +
t by <user>(uid=0)                                                             
 +
Nov 28 13:39:12 <SERVERNAME> sudo: pam_unix(sudo:session): session closed for user roo
 +
t
 +
 +
'''If time reference is not the same everywhere, then fail2ban won't ban any IP!'''
 +
 +
If you change your timezone remember to restart syslogd so fail2ban will see the correct time in the log files.
 +
 +
 +
Check if backend = auto. And set backend = polling. In some cases fail2ban won't be notified by gamin, but will chose to use it when auto is set.
 +
 +
=== Fail2ban is failing to ban VSFTPD bruteforce ===
 +
'''Scenario:''' VSFTP configuration is set for PAM authentication, using xferlog in standard format.  Fail2ban for vsftpd is watching /var/log/secure
 +
*'''Problem:'''  PAM sends failed login information to /var/log/secure, but the remote server's IP address has been replaced by a DNS name.  Resulting DNS name does not resolve or does not resolve correctly, thus fail2ban is unable to ban the IP address.
 +
*'''Fix:''' Configure VSFTP for "dual_log_enable=YES", and have fail2ban watch /var/log/vsftpd.log instead.  This log file shows the incoming ip address instead of the DNS name.
 +
 +
'''Scenario:''' Timestamps in /var/log/vsftpd.log are in GMT instead of the local time zone.
 +
*'''Problem:''' Fail2ban won't ban if the timestamps it finds don't match its idea of the current time.
 +
*'''Fix:''' Add "use_localtime=YES" to /etc/vsftpd/vsftpd.conf and restart the vsftpd service.
 +
'''NB''': This will also cause file timestamps in directory listings and other timestamps displayed to clients to be in your local time zone. If this is unacceptable, then you may wish to configure fail2ban to monitory /var/log/secure, whose timestamps are in the local time zone, but this may cause other problems as described above.

Latest revision as of 12:48, 4 December 2013

Troubleshooting

I get emails containing "Here are/is more information about <ip>" and then nothing

You are using a mail-whois*/sendmail-whois* action and you don't have the whois executable installed.

I have Postfix on my system but no "mail" command. How can I get e-mail notifications?

As of version 0.8.1, "mail" actions are deprecated. Please use the "sendmail" ones instead. E.g. sendmail-whois instead of mail-whois in your jail.[conf|local].

You probably have the sendmail command. Copy /etc/fail2ban/action.d/mail-whois.conf to /etc/fail2ban/action.d/mail-whois.local, edit this file and replace mail with sendmail. Here is an example:

actionban = echo -en "From:root <fail2ban>
            To: <dest>
            Subject: [Fail2Ban] <name>: banned <ip>
            Hi,\n
            The IP <ip> has just been banned by Fail2Ban after
            <failures> attempts against <name>.\n\n
            Here are more information about <ip>:\n
            `whois <ip>`\n
            Regards,\n
            Fail2Ban"|sendmail -t  

mail.conf can be modified too.

Why do my CVS users using SSH getting blocked?

If you are using the Eclipse CVS integration with SSH, then each access of the CVS results in a failed access before a valid one is done. As a consequence your CVS users get banned from time to time.

I get the error "Please check the format and your locale settings"

The error looks like this:

ERROR: time data did not match format: data=Mar 21 10:00:50 fmt=%b %d %H:%M:%S
ERROR: Please check the format and your locale settings.

This is a known bug. Since 0.6.1, Fail2ban uses your locale settings for date and time format. However, some daemons do not take care of locale and write their log messages using the POSIX standard. Please look at this bug for more details.

You can try to override the LANG variable:

# LANG=en_US /etc/init.d/fail2ban restart

You can get all the available locale with:

# locale -a

How do I increase verbosity?

In order to increase the verbosity of Fail2ban, use the command line option -vvv for fail2ban-client and fail2ban (only for 0.6.x). Set loglevel to 4 in /etc/fail2ban/fail2ban.conf (only for > 0.6.x).

Fail2ban-client is unable to contact server

Did you make sure to run fail2ban-client status using sudo?

$ fail2ban-client status
ERROR  Unable to contact server. Is it running?

$ sudo fail2ban-client status
Status
|- Number of jail:	1
`- Jail list:		ssh

Fail2ban is running but not banning SSH bruteforce

NB:This example is based on a Debian system, but can be easily done on any distro.

The package is well installed:

# dpkg -l |grep fail                                               
ii  fail2ban                      0.8.1-2                         bans IPs that 
cause multiple authentication

The service is running:

# /etc/init.d/fail2ban status                                      
Status of authentication failure monitor: fail2ban is running

SSH jail is set up and ready:

# sudo fail2ban-client status                                           
Status                                                                          
|- Number of jail:      1                                                       
`- Jail list:           ssh

SSH bruteforce logs are identified by fail2ban:

# fail2ban-regex /var/log/auth.log /etc/fail2ban/filter.d/sshd.conf
....
Success, the total number of match is 30

So, check that all your logs are synchronized: all logs files (auth.log, syslog,..) must use the same time reference (if your server is not very busy, there will probably be an important difference between the output of [1]date command and the last event logged in syslog. You can force to generate a log in syslog using the logger command and check then with the output of date command)

# date                                                             
Wed Nov 28 13:49:02 CET 2007                                                    
# tail -2 /var/log/auth.log                                        
Nov 28 13:39:12 <SERVERNAME> sudo: pam_unix(sudo:session): session opened for user roo
t by <user>(uid=0)                                                              
Nov 28 13:39:12 <SERVERNAME> sudo: pam_unix(sudo:session): session closed for user roo
t

If time reference is not the same everywhere, then fail2ban won't ban any IP!

If you change your timezone remember to restart syslogd so fail2ban will see the correct time in the log files.


Check if backend = auto. And set backend = polling. In some cases fail2ban won't be notified by gamin, but will chose to use it when auto is set.

Fail2ban is failing to ban VSFTPD bruteforce

Scenario: VSFTP configuration is set for PAM authentication, using xferlog in standard format. Fail2ban for vsftpd is watching /var/log/secure

  • Problem: PAM sends failed login information to /var/log/secure, but the remote server's IP address has been replaced by a DNS name. Resulting DNS name does not resolve or does not resolve correctly, thus fail2ban is unable to ban the IP address.
  • Fix: Configure VSFTP for "dual_log_enable=YES", and have fail2ban watch /var/log/vsftpd.log instead. This log file shows the incoming ip address instead of the DNS name.

Scenario: Timestamps in /var/log/vsftpd.log are in GMT instead of the local time zone.

  • Problem: Fail2ban won't ban if the timestamps it finds don't match its idea of the current time.
  • Fix: Add "use_localtime=YES" to /etc/vsftpd/vsftpd.conf and restart the vsftpd service.

NB: This will also cause file timestamps in directory listings and other timestamps displayed to clients to be in your local time zone. If this is unacceptable, then you may wish to configure fail2ban to monitory /var/log/secure, whose timestamps are in the local time zone, but this may cause other problems as described above.