Fail2Ban

QuickBox-tuned intrusion prevention that bans repeat offenders across SSH, nginx auth, and the QuickBox dashboard.

Fail2Ban watches authentication failures and bans abusive addresses. QuickBox ships a prebuilt jail template that reads QuickBox login failures, nginx auth prompts, and SSH attempts from /srv/quickbox/logs/fail2ban.log, then applies bans through the fail2ban systemd service.

🔐 QuickBox-aware bans

Dashboard login failures are appended to /srv/quickbox/logs/fail2ban.log via qb manage fail2ban -o inclog, and the quickbox jail parses them for bans.

🧩 Templated jails

The shipped jail.local enables toggles for sshd, nginx-http-auth, and quickbox jails that all read /srv/quickbox/logs/fail2ban.log, plus a quickbox.conf filter in filter.d/.

🎛️ Interactive thresholds

qb manage fail2ban -o config prompts for bantime (default 600s), findtime (600s), maxretry (5), ignore IPs, and whether to monitor SSH, nginx, and QuickBox logins.

📬 Email-ready aliases

Installation rewrites /etc/aliases with the QuickBox admin email and restarts sendmail so Fail2Ban mailouts route to the right inbox.

When to use Fail2Ban

Symptoms

Repeated SSH password guesses or port scans from the same hosts
QuickBox dashboard login failures start piling up from unknown sources
nginx basic-auth prompts on proxied apps see brute-force attempts
You want a single ban list covering SSH, nginx auth, and the QuickBox dashboard

Resolution

Install Fail2Ban through qb and enable the SSH, nginx, and QuickBox jails in the config wizard
Add trusted admin addresses to ignoreip during setup to avoid locking yourself out
Track and clear bans with fail2ban-client status and unban entries you trust
Keep /srv/quickbox/logs/fail2ban.log intact so QuickBox login failures continue to feed the jails

Config wizard is required

The installer copies QuickBox templates, then calls qb manage fail2ban -o config to set bantime, findtime, maxretry, ignoreip, and jail toggles before restarting the fail2ban service.

Installation


qb install fail2ban

install

Install Fail2Ban with QuickBox templates; copies filter.d/quickbox.conf, seeds /srv/quickbox/logs/fail2ban.log, and invokes the interactive config wizard.

qb install fail2ban

reinstall

Reapply the templates and rerun the wizard to refresh bantime/findtime/maxretry, ignoreip, and jail toggles.

qb reinstall fail2ban

remove

Stop and disable the service, remove the package, and clean the QuickBox software records.

qb remove fail2ban

manage config

Run the interactive wizard that writes /etc/fail2ban/jail.local with your bantime, findtime, maxretry, ignoreip, and SSH/nginx/QuickBox jail states.

qb manage fail2ban -o config

manage unban

Unban a provided address across all jails using fail2ban-client set <jail> unbanip under the hood.

qb manage fail2ban -o unban ${ip}

Directory layout

etc/

├── fail2ban/

│ ├── jail.local# QuickBox-templated jails with SSH/nginx/QuickBox toggles and custom bantime/findtime/maxretry/ignoreip

│ └── filter.d/

│ │ └── quickbox.conf# QuickBox filter that matches offending hosts in the shared log

└── aliases# Installer rewrites mail aliases to the QuickBox admin address

srv/

└── quickbox/

│ └── logs/

│ │ └── fail2ban.log# Central log fed by SSH, nginx auth, and QuickBox dashboard failures

Best practices

Do

Run qb manage fail2ban -o config immediately after install to set bantime, findtime, maxretry, ignoreip, and enable the jails you need.
Whitelist your admin workstation in ignoreip so tests or password typos do not lock you out.
Check /var/log/fail2ban.log or fail2ban-client status after changes to confirm the jails are active.
Keep /srv/quickbox/logs/fail2ban.log owned by www-data (created during install) so dashboard failure logs stay writable.

Don't

Do not delete /srv/quickbox/logs/fail2ban.log; the QuickBox and nginx jails read from it.
Avoid hand-editing jail.local—rerun qb manage fail2ban -o config to regenerate with the correct placeholders.
Do not disable the sshd or quickbox jails if you rely on brute-force protection for shell and dashboard logins.
Do not skip ignoreip updates when tightening bantime/findtime, or you may ban your own admin IP.

Troubleshooting

Locked out or over-blocking

Use fail2ban-client status to list jails and confirm bans, then unban trusted addresses with the manage module. If you tighten bantime/findtime, refresh ignoreip in the config wizard first to protect your admin IPs.

Verify logging inputs

QuickBox login failures and nginx auth prompts are written to /srv/quickbox/logs/fail2ban.log; Fail2Ban summary logs live in /var/log/fail2ban.log. Check both before assuming a jail is inactive, and restart the fail2ban service after template changes.

Resources

Fail2Ban Documentation

Official guide to filters, jails, and actions

QuickBox Support

Project site and support channels for QuickBox Pro

Join the Community

Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.

Dedicated Support

Feature Previews

Community Configs

Active Discussions

Join Discord Server