Fail2ban

intermediate

Intrusion prevention framework that bans malicious IPs.

Overview

Fail2ban is an intrusion prevention system written in Python that protects Linux and Unix web servers from brute-force attacks by monitoring log files and banning IP addresses that show suspicious activity. Originally developed by Cyril Jaquier in 2004, fail2ban works by parsing log files through regular expressions, identifying patterns that indicate malicious behavior like repeated failed login attempts, and automatically creating firewall rules to block offending IP addresses for specified time periods. The LinuxServer.io implementation provides a containerized version that maintains full access to system logs while running in isolation. This Docker configuration creates a fail2ban instance with host networking and elevated privileges necessary to manipulate iptables rules and monitor system logs effectively. The container requires NET_ADMIN and NET_RAW capabilities to create and manage firewall rules, while mounting the host's /var/log directory read-only to monitor various service logs including SSH, web servers, and other applications. The setup enables real-time log analysis and automated IP banning without requiring complex host system modifications. System administrators managing servers exposed to the internet, homelab enthusiasts running self-hosted services, and security-conscious organizations will benefit from this automated defense mechanism. The containerized approach allows fail2ban deployment alongside other dockerized services while maintaining the ability to protect both containerized and host-based applications through centralized log monitoring and unified firewall management.

Key Features

Automated IP blocking based on configurable regex patterns in log files
Support for multiple jail configurations targeting different services simultaneously
Integration with iptables, firewalld, and other firewall backends for rule management
Configurable ban times with progressive penalty increases for repeat offenders
Email notifications for administrator alerts when bans occur
Whitelist functionality to prevent accidental blocking of trusted IP addresses
Built-in filters for common services like SSH, Apache, Nginx, and Postfix
Real-time log parsing with immediate response to detected intrusion attempts

Common Use Cases

1Protecting SSH servers from brute force authentication attempts
2Securing web servers running WordPress, Nextcloud, or other web applications
3Defending mail servers against spam relay attempts and authentication attacks
4Protecting game servers from DDoS attacks and connection flooding
5Securing home lab environments with publicly accessible services
6Corporate server hardening for development and staging environments
7Protecting API endpoints from automated abuse and credential stuffing attacks

Prerequisites

Docker host with iptables firewall system installed and configured
Minimum 512MB RAM for log processing and pattern matching operations
Root or sudo access required for container privileged operations
Active log files from services you want to protect (SSH, web servers, etc.)
Understanding of regex patterns for custom jail configuration
Network access knowledge for troubleshooting blocked legitimate traffic

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  fail2ban: 
3    image: linuxserver/fail2ban:latest
4    container_name: fail2ban
5    restart: unless-stopped
6    cap_add: 
7      - NET_ADMIN
8      - NET_RAW
9    environment: 
10      PUID: 1000
11      PGID: 1000
12      TZ: UTC
13    volumes: 
14      - fail2ban_config:/config
15      - /var/log:/var/log:ro
16    network_mode: host
17
18volumes: 
19  fail2ban_config:

.env Template

.env

1# Configure jails in /config/fail2ban

Usage Notes

1Docs: https://docs.linuxserver.io/images/docker-fail2ban/
2Configure jails in /config/fail2ban/jail.local
3Check status: docker exec fail2ban fail2ban-client status sshd
4Unban IP: docker exec fail2ban fail2ban-client set sshd unbanip 1.2.3.4
5View banned: docker exec fail2ban fail2ban-client status
6Mount log files read-only from services you want to protect

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  fail2ban:
5    image: linuxserver/fail2ban:latest
6    container_name: fail2ban
7    restart: unless-stopped
8    cap_add:
9      - NET_ADMIN
10      - NET_RAW
11    environment:
12      PUID: 1000
13      PGID: 1000
14      TZ: UTC
15    volumes:
16      - fail2ban_config:/config
17      - /var/log:/var/log:ro
18    network_mode: host
19
20volumes:
21  fail2ban_config:
22EOF
23
24# 2. Create the .env file
25cat > .env << 'EOF'
26# Configure jails in /config/fail2ban
27EOF
28
29# 3. Start the services
30docker compose up -d
31
32# 4. View logs
33docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/fail2ban/run | bash

Troubleshooting

fail2ban-server not starting: Check that iptables is installed on the Docker host and the container has proper capabilities
IP addresses not being banned despite failed attempts: Verify log file paths are correctly mounted and jail filters match your log format
Legitimate users getting blocked: Review jail configuration thresholds and add trusted IPs to ignoreip whitelist
Cannot access fail2ban-client commands: Ensure container is fully started and use 'docker exec -it fail2ban bash' to access the shell
Bans not persisting after container restart: Check that fail2ban database files are properly stored in the persistent config volume
High CPU usage during log parsing: Reduce findtime values or limit the number of active jails monitoring large log files

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

fail2ban

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download