github
/
fail2ban
mirror of https://github.com/fail2ban/fail2ban
1
0
Fork 0
Code Issues Releases Wiki Activity

Created How fail2ban works (markdown)

master
Serg G. Brester 2017-03-09 21:22:26 +01:00
parent 627669256d
commit 7167ce3645
1 changed files with 50 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
How-fail2ban-works.md Normal file

@ -0,0 +1,50 @@
Fail2Ban scans log files resp. journals (using specified regular expressions also known as filter-rules) and executes configured actions to ban failures having too many attempts (matched specified filter-rules). It does this e. g. by updating system firewall rules to reject new connections from those IP addresses, for a configurable amount of time.
But you can write resp. configure your own action to [ban something other as host/IP, like user or e-mail](How-to-ban-something-other-as-host-(IP-address),-like-user-or-mail,-etc.).
Fail2Ban comes out-of-the-box ready to read many standard log files, such as those for sshd and Apache, and is easy to configure to read any log file you choose, for any error you choose.
**But fail2ban is just a tool, so it should be [properly configured](Properly-fail2ban-configuration).**
***
**[Q]** Fail2ban does not detect some authentication failures resp. banning does not occurred
**[A]** There can be many reasons:
- corresponding jail for scanning the log file or systemd journal is not enabled (or idle). See [here](Properly-fail2ban-configuration) how the jail can be enabled.
- the proper path to the log files (parameter `logpath`) resp. proper journal control parameter `journalmatch` should be set for this jail.
- the IP goes to ban if it makes at least `maxretry` failures within `findtime` seconds. So if you've configured `maxretry=5` and `findtime=10m` (default values) then it needs at least 5 failures (5 attempts) within 10 minutes to ban an IP.<br/>
Each failure (attempt) will be logged in `fail2ban.log` as:<br/>
` INFO [jail] Found 192.0.2.25`<br/>
First if you'll see at least 5 such lines with this IP address within 10 minutes, the IP goes banned and you should see:<br/>
` NOTICE [jail] Ban 192.0.2.25`<br/>
- each failure should match a regular expressions (from stock fail2ban or local customized in jail.local, some filter from `/etc/fail2ban/filter.d`, etc). It may be, that the expression or some part of it is not good enough.
You can use another fail2ban tool `fail2ban-regex` to check resp. build your own `failregex`.
- the banning action is not specified resp. something going wrong by execution of the ban-action. For example if iptables action used, you can verify it by checking of iptables entries, where you should find the fail2ban jail name (prefixed with `f2b-`) as chain and the rule corresponding the IP address.<br/>
Mostly you'll see then too many log-lines like following in the `fail2ban.log`:<br/>
` NOTICE [jail] 192.0.2.25 already banned`<br/>
***
**[Q]** Fail2ban detects resp. incorrectly blocks some authentication attempts as failure (e. g. bans my IP address).
**[A]** It may be, that the expression is not good enough or the matching just occurs in pre-authentication step (e. g. by handshake) and so even per success login you have one failure (in sense of your configuration of fail2ban), so normally for the "fix" in this case, it will be enough to increase `maxretry` resp. to decrease `findtime` for this jail.
Why this IP was banned you can find in the `fail2ban.log` (search for lines before `[affected-jail-name] Found <IP>`) if your log-level more precise as INFO.<br/>
Otherwise take a look in the corresponding log file on the time from which fail2ban logged the failure.
Or try to use `fail2ban-regex` with log-file and filter-file as arguments.<br/>
E. g. if you'll see why the IP-address was banned in sshd jail:
```
# auth.log:
fail2ban-regex --print-all-matched /var/log/auth.log /etc/fail2ban/filter.d/sshd | grep 192.0.2.25
# or systemd journal:
fail2ban-regex --print-all-matched systemd-journal /etc/fail2ban/filter.d/sshd | grep 192.0.2.25
```
If your fail2ban version is larger as 0.9 and database was not disabled, you can quick find there corresponding log-matches for this IP, e. g. by executing of following script:
``` bash
# set your IP and db-path ...
?sudo? python -c "ip='192.0.2.25'; db='/var/lib/fail2ban/fail2ban.sqlite3'; import sys, logging; logging.basicConfig(stream=sys.stdout, level=logging.ERROR); from fail2ban.server.database import Fail2BanDb; db = Fail2BanDb(db); t = db.getBansMerged(ip=ip); print(('%d attempts, matches:\n %s' % (t.getAttempt(), '\n '.join(t.getMatches())) ) if t else 'NOT FOUND')"
```
Following script shows all failures of all IPs across all jails:
```bash
?sudo? python -c "db='/var/lib/fail2ban/fail2ban.sqlite3'; import sys, logging; logging.basicConfig(stream=sys.stdout, level=logging.ERROR); from fail2ban.server.database import Fail2BanDb; db = Fail2BanDb(db); t = db.getBansMerged(); print('\n'.join((('%s - %d attempts, matches:\n %s' % (t.getIP(), t.getAttempt(), '\n '.join(t.getMatches())) ) for t in t)))"
```