Fail2ban Cheat Sheet for Sysadmins

Fail2ban is a critical tool for safeguarding servers against brute-force attacks by monitoring logs and banning malicious IPs. This cheat sheet provides the most important concepts and commands for managing Fail2ban effectively.

1. Core Concepts

• Jail: A Fail2ban unit that defines which logs to monitor, filter rules, and actions (e.g., banning an IP). Example: SSH protection with sshd.
• Filter: A regex-based rule set to identify bad behavior in logs.
• Action: The response triggered by Fail2ban (e.g., banning an IP using iptables).
• Ban Time: How long IPs stay banned (seconds).
• Max Retry: Maximum failed login attempts before banning an IP.

2. Service Management

Start Fail2ban service:

sudo systemctl start fail2ban

Stop Fail2ban service:

sudo systemctl stop fail2ban

Restart Fail2ban service (for major configuration changes):

sudo systemctl restart fail2ban

Reload Fail2ban service (for minor configuration changes):

sudo fail2ban-client reload

Enable Fail2ban at startup:

sudo systemctl enable fail2ban

Check Fail2ban service status:

sudo systemctl status fail2ban

3. Reload vs Restart

Action	When to Use	Impact
fail2ban-client reload	Use for minor configuration changes like adjusting bantime, maxretry, or adding new jails.	Reloads the active configuration without disrupting bans. Active jails remain functional.
systemctl restart fail2ban	Use for major changes, like adjustments in /etc/fail2ban/fail2ban.conf, or when changing Fail2ban actions.	Fully restarts Fail2ban, reinitializing all settings. Active ban lists are cleared unless ban persistence is configured (see Section 10).

Best Practice: Begin with reload. If changes are not applied or functional issues occur, use restart.

4. Key Configuration Files

• Main Configuration: /etc/fail2ban/fail2ban.conf
• Jail Configuration: /etc/fail2ban/jail.conf or /etc/fail2ban/jail.local (use jail.local for custom settings to avoid overwrites during updates).
• Log File: /var/log/fail2ban.log

5. Managing Jails

View active jails:

sudo fail2ban-client status

Get detailed status of a specific jail:

sudo fail2ban-client status <jail_name>

Ban an IP manually in a jail:

sudo fail2ban-client set <jail_name> banip <IP_address>

Unban an IP from a jail:

sudo fail2ban-client set <jail_name> unbanip <IP_address>

Unban all IPs from a specific jail:

sudo fail2ban-client set <jail_name> unbanip --all

6. Sample Jail Configuration

Customize /etc/fail2ban/jail.local to protect SSH:

[DEFAULT]
# Defaults for all jails
# Whitelist specific IPs or ranges
ignoreip = 127.0.0.1/8 192.168.1.0/24
# 1 hour ban duration
bantime = 3600
# Time window to detect multiple failed attempts
findtime = 600
# Max failed attempts before banning
maxretry = 3
# Log backend, usually auto-detected
backend = auto

[sshd]
# Enable the SSH jail
enabled = true
# Override port if not default
port = ssh
# Path to SSH authentication log
logpath = /var/log/auth.log
# Use the SSH filter for matching logs
filter = sshd

After editing:

# Reload Fail2ban to apply changes
sudo fail2ban-client reload

7. Analyzing Logs

Monitor Fail2ban activity:

sudo tail -f /var/log/fail2ban.log

Find banned IPs in the logs:

grep 'Ban' /var/log/fail2ban.log

8. Create a Custom Jail

To protect Apache from login-related brute-force attacks:

Add this to /etc/fail2ban/jail.local:

[apache-auth]
enabled = true
port = http,https
filter = apache-auth
logpath = /var/log/apache2/error.log
maxretry = 3
bantime = 3600

Create the filter /etc/fail2ban/filter.d/apache-auth.conf:

[Definition]
failregex = .*client <HOST>.*authorization failed.*
ignoreregex =

Reload Fail2ban to apply:

sudo fail2ban-client reload

Test the custom filter:

sudo fail2ban-regex /var/log/apache2/error.log /etc/fail2ban/filter.d/apache-auth.conf

9. Debugging

Dump the effective configuration (all parsed settings — useful for verifying what Fail2ban is actually using):

sudo fail2ban-client -d

Test configuration for syntax errors:

sudo fail2ban-client --test

View system logs for Fail2ban:

journalctl -u fail2ban

10. Persistent Bans Across Restarts

On most distributions, Fail2ban already enables ban persistence via SQLite by default. If bans are not surviving restarts, check whether dbfile is explicitly set in your configuration. You can confirm or set it in /etc/fail2ban/jail.local:

[DEFAULT]
dbfile = /var/lib/fail2ban/fail2ban.sqlite3

Restart Fail2ban to apply:

sudo systemctl restart fail2ban

11. iptables Integration

To view the iptables rules created by Fail2ban:

sudo iptables -L -n

To remove Fail2ban-specific rules, target its chains directly (e.g., for the sshd jail):

sudo iptables -F f2b-sshd

Avoid iptables -F without specifying a chain. It flushes all rules across the entire firewall, not just Fail2ban's.

12. Security Best Practices

• Always whitelist critical IPs using ignoreip to prevent accidental bans.
• Customize jail.local for site-specific setups (avoid editing jail.conf).
• Regularly monitor /var/log/fail2ban.log for suspicious activity or misconfigurations.
• Periodically test your filters using: sudo fail2ban-regex <logfile> <filter_file>.
• Enable email alerts for ban events by customizing the action parameter in your jails.

Fail2ban is a powerful tool to lock down your system against brute-force attacks. Regularly monitor logs, refine filters, and keep configs well-maintained for optimal performance and security.