Kernel-enforced bans
Protect against IPv4 and IPv6 sources with nftables, iptables or ipset. The nftables backend communicates directly with the kernel through netlink.
Enforcement architecture →Protection, from event to enforcement
Read the signs.
Stop the repeat.
Turn service failures and scan detections into durable firewall bans. Set the policy, keep the history, and inspect what fail2zig installed.
- 01ReadFile and journal events
- 02DetectMatch a known failure
- 03DecideApply your jail policy
- 04EnforceInstall kernel protection
- 05InspectCheck health and ownership
01 / Detection
Start with the services you run.
Compiled filters recognize supported authentication failures, web probes, mail rejections and scan events. Read service logs from files or use trusted journal origins for SSH.
Sixteen built-in filter names include internal repeat-offender handling. For other supported patterns, bounded JSON rules and offline rule testing let you check your actual input.
Explore filters and rule limits → A failure becomes a policy input · illustration
Failed password for invalid user admin from 203.0.113.42 port 43210
ssh2 - Filter
- sshd
- Source address
- 203.0.113.42
- Next step
- Evaluate jail policy
A matching event enters policy evaluation. Thresholds and ignore rules determine what happens next.
02 / Policy
Your thresholds.
Your response.
Give each jail its own retry threshold, observation window and ban duration. Preserve trusted addresses with ignore lists and extend bans as repeat offenses accumulate.
The internal recidive filter works across jails using confirmed bans. It
carries repeat-offender policy beyond a single service.
SSH policy excerpt · native TOML
# Three failures in ten minutes
[jails.sshd]
filter = "sshd"
source = "journald"
maxretry = 3
findtime = "10m"
bantime = "1h"
# Increase repeat-offense bans, up to a week
bantime_increment_enabled = true
bantime_increment_multiplier = 2
bantime_increment_formula = "exponential"
bantime_increment_max_bantime = "1w"03 / Enforcement & continuity
Protection with a memory.
State that survives restart
SQLite retains source progress, retry state, ban ownership and effect intent. Persistent state keeps a restart from becoming a fresh start for repeat offenders.
Source continuity →Explicit resource limits
Bounded processing controls records, queues and admission. Critical receipts, active ownership and unresolved enforcement intent are retained under pressure.
Resource boundaries →Automatic bans cover the source across host ports and protocols in the daemon’s network namespace. Host INPUT protection does not establish protection for Docker forwarded traffic.
04 / Operations
Know what happened.
See what’s installed.
Inspect source health, active bans and retained firewall observations from the same
executable. Expand operator tables with --details or use JSON for
structured output.
Firewall observation, introduced in 0.4.2, shows the latest retained inspection of fail2zig-owned protection. It does not refresh rules or prove end-to-end packet reachability.
Read the observation contract → An operator’s inspection sequence
- Is protection ready?
fail2zig status --details- Are the sources healthy?
fail2zig jails --details- Which bans are tracked?
fail2zig list --details- What did the kernel inspection find?
fail2zig firewall show --details
Put it to work
One executable. A familiar workflow.
The daemon, administration, offline rule testing and supported fail2ban migration ship together. Find your service, review its log format, then configure your first jail.