Guides

fail2ban integration guides

Complete, tested setups for the services people most often protect with fail2ban. Each guide gives you the filter, the jail, the log path, a test command and the gotchas specific to that service.

Updated 3 min readChecked against fail2ban 1.1.1

Every guide below follows the same pattern: find the log line a failed login or attack produces, match it with a filter (stock or custom, tested with fail2ban-regex), enable a jail in /etc/fail2ban/jail.local or jail.d/, make sure the ban lands where the traffic actually flows, and verify with fail2ban-client status <jail>. If fail2ban isn't installed yet, start with install fail2ban.

SSH and the system#

SSHThe sshd jail done right: systemd backend, custom ports, aggressive mode for key-only servers, OpenSSH 9.8+ sshd-session.Proxmox web UIBan brute force on the Proxmox VE login on port 8006, plus PBS and PMG.OpenWrt routersdropbear and LuCI jails on a router, nftables, and banIP as the lightweight option.

Web servers and reverse proxies#

Nginxnginx-http-auth, botsearch, limit-req with limit_req_zone, bad requests, forbidden, and a 404/401/403 filter.ApacheAll nine stock Apache jails, apache2 vs httpd log paths, the LogLevel trap, a 404 filter.Nginx Proxy ManagerNPM's own log format, a tested filter and bans in DOCKER-USER.TraefikAccess log setup, the traefik-auth modes, Docker Compose, real client IPs.CaddyA JSON access-log filter for client_ip and status codes with the ts epoch timestamp.CloudflareRestore real visitor IPs and ban at Cloudflare's edge with an API token, including Tunnel.

Self-hosted apps#

WordPresswp-login.php and xmlrpc.php brute force, with the WP fail2ban plugin or without any plugin.NextcloudFilter for Login failed in nextcloud.log, log paths for Docker, AIO and snap.VaultwardenThe stock vaultwarden filter, LOG_FILE, a stricter admin-page jail.JellyfinDenied-login filter and a setup that survives Jellyfin's daily log files.Home AssistantContainer and Core setups, the built-in IP ban, and Home Assistant OS limits.Gitea & ForgejoBan password spraying on self-hosted Git servers, including GitLab's stock filter.MySQL & MariaDBMake the database log failed logins, then ban password sprayers.Minecraft serversA tested filter for whitelist and session rejections in latest.log, and the limits for game servers.

Mail and VoIP#

Postfix & DovecotThe postfix, postfix-sasl and dovecot jails against SMTP AUTH and IMAP guessing.Asterisk & FreePBXBan SIP REGISTER floods on TCP and UDP before they make calls on your account.

VPN#

OpenVPNBan failed TLS handshakes, certificate checks and password logins.WireGuardWhy there's no WireGuard jail, and the one workaround.

Firewalls and ban actions#

UFWBan through UFW rules or alongside UFW in nftables.nftablesThe default ban action on Debian 13 and Ubuntu 24.04: tables, sets, inspection.firewalldThe firewalld actions on Fedora, RHEL, Rocky and AlmaLinux, and their traps.iptables & ipsetThe rewritten 1.1.1 iptables action, ipset for large ban lists.

Operations and integrations#

Docker containersWhy bans miss published ports, chain = DOCKER-USER, the nftables forward hook, reading container logs.AbuseIPDB reportingReport banned IPs automatically.Prometheus & GrafanaExporters and scripts for Prometheus, node_exporter and Zabbix.Web UI & dashboardsThird-party web interfaces, from Webmin to Docker-based UIs.

Which guide do I need?#

  • Your service runs in Docker (NPM, Vaultwarden, Nextcloud AIO, Jellyfin…): read the app's guide and Docker containers. A ban in the default INPUT chain doesn't stop traffic Docker forwards to a container.
  • Your site is behind Cloudflare or another proxy: fail2ban must see the visitor's address, not the proxy's. Fix that first; see Cloudflare and fail2ban bans the proxy IP.
  • On Ubuntu 24.04: the package sets backend = systemd for all jails, so every jail that reads a log file needs backend = auto — all examples in these guides include it.
  • No guide for your app? Write a filter for its log line with the filter generator, test it, and follow writing a custom filter. The jail.local generator builds the jail.

FAQ#

How do I protect a new service with fail2ban?#

Find the log line the service writes on a failed login and confirm it contains the client IP. Write a filter whose failregex matches that line with <HOST> or <ADDR>, test it with fail2ban-regex <logfile> <filter>, then add a jail with enabled = true, the logpath, the port and backend = auto, and reload fail2ban.

Why does fail2ban ban IPs but my Docker app is still reachable?#

Docker forwards published ports to containers through the FORWARD chain, while fail2ban bans in INPUT by default. Use an iptables action with chain = DOCKER-USER, or an nftables chain on the forward hook, for every jail that protects a container.

Install fail2banHow to install fail2ban on Ubuntu, Debian, Rocky, Fedora, Arch, Docker and from source (1.1.1), then enable the sshd jail, start the service and verify it.jail.local exampleA complete fail2ban jail.local example for SSH, nginx and recidive, explained line by line, plus a minimal version, distro notes and how to add a custom jail.Filter libraryAll 96 built-in fail2ban filters in one searchable list: sshd, nginx, Apache, Postfix, Dovecot, recidive and more, with regexes and sample log lines.jail.local generatorFree fail2ban jail.local generator. Pick your distro, firewall and services, set bantime, findtime, maxretry and ignoreip, and copy a clean, commented config.All problemsfail2ban troubleshooting: match your symptom or exact error message to the fix, and use a 6-step debugging routine that finds most fail2ban problems in minutes.

Spotted something wrong or out of date? Tell us — every page is checked against the current fail2ban release.