Fail2Ban

QuickBox-tuned intrusion prevention with a full dashboard control center — jail management, allowlist, manual ban/unban, intelligent recommendations, and live blocking analytics.

Fail2Ban watches authentication failures and bans abusive addresses. QuickBox ships a prebuilt jail configuration covering SSH, nginx auth, the v4 dashboard, and individual installed applications. The complete management surface lives in the dashboard at Security Settings → Fail2Ban, and live blocking reports appear on the System Dashboard when the package is installed.

Dashboard jail control center

Enable or disable individual jails, edit bantime, findtime, and maxretry inline, and view the currently banned IP list — all from the Fail2Ban tab at /settings/security.

Intelligent recommendations

The Recommendations panel analyzes your installed apps, user count, and ban-pattern history to surface per-install suggestions with one-click apply actions grouped by severity.

System Dashboard blocking reports

When fail2ban is installed, the System Dashboard gains a Fail2Ban Protection widget — bans by country, top blocked IPs, access-vector breakdown by jail, and a ban-event timeline with 24h / 7d / 30d windows.

Templated jails with per-app coverage

Base jails cover sshd, nginx-http-auth, and qbx-v4dashboard. A second drop-in (qbx-apps.conf) holds disabled stanzas for 27+ installed apps — each activates automatically when the relevant package is installed.

Allowlist and manual ban/unban

Add or remove IP addresses and CIDR ranges from the allowlist. Manually ban a specific IP into a chosen jail, or unban from all jails simultaneously. A lockout-protection guard warns before you remove your own connected IP.

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 accumulating from unknown sources
nginx basic-auth prompts on proxied apps see brute-force attempts
You want a single ban list covering SSH, nginx auth, the v4 dashboard, and installed apps

Resolution

Install from the dashboard — the install options form lets you set bantime, findtime, maxretry, jails, and allowlist IPs before the first install
After install, use the Fail2Ban tab at Security Settings to enable jails, tune thresholds, and manage the allowlist
Add trusted admin workstation IPs to the allowlist to avoid locking yourself out
Use the System Dashboard Fail2Ban widget to monitor ban activity across windows without leaving the dashboard

Installation

Dashboard install (recommended)

Install Fail2Ban from App Dashboard → Package Management. When you click Install, an options form opens before the install begins:

Field	Default	Range
Ban Duration (seconds)	3600 (1 hour)	60–86400
Failure Window (seconds)	600	60–86400
Max Attempts	5	1–100
Active Jails	sshd, nginx	sshd and/or nginx
Email Alerts	off	on / off
Allowlist IPs / CIDRs	(empty)	space-separated

The qbx-v4dashboard jail (dashboard login protection) is always enabled and cannot be disabled from the install form. The recidive repeat-offender jail is enabled by default as well — see the Fail2Ban tab docs for what it does. Loopback addresses (127.0.0.1/8, ::1) and the server’s primary IP are always added to the allowlist automatically.

Default ban duration raised to 1 hour

New installs default to a 1-hour ban duration (3600 s). Older installs that were originally provisioned with the legacy 600-second (10-minute) default keep that value until you change it — adjust bantime on any jail card in the dashboard Fail2Ban tab, or rerun the CLI config wizard.

Tune settings before you click Install

The install options form is the easiest moment to set your bantime, maxretry, and allowlist. You can change everything later from the Fail2Ban tab, but starting with the right values means protection is calibrated from the first ban event.

Fail2Ban can also be removed and reinstalled from the dashboard Package Management tab at any time.

CLI install


qb install fail2ban

When run without a TTY (dashboard, scripts, automation), sane defaults are applied automatically. When run in an interactive terminal, the config wizard prompts for all settings.

--f2b-bantime <seconds>

Ban duration in seconds (default: 3600; range: 60–86400). Passed directly from the dashboard install options form.

qb install fail2ban --f2b-bantime 7200

--f2b-findtime <seconds>

Failure-counting window in seconds (default: 600; range: 60–86400).

qb install fail2ban --f2b-findtime 900

--f2b-maxretry <n>

Attempts before a ban triggers (default: 5; range: 1–100).

qb install fail2ban --f2b-maxretry 3

--f2b-jails "<csv>"

Comma-separated jails to enable from: sshd,nginx (default: both). The qbx-v4dashboard jail is always enabled.

qb install fail2ban --f2b-jails "sshd"

--f2b-ignoreip "<ip ...>"

Space-separated IPs or CIDR ranges to add to the allowlist. Loopback and the server IP are always included.

qb install fail2ban --f2b-ignoreip "10.0.0.1 192.168.1.0/24"

--f2b-notify <on|off>

Send email on ban events (default: off). Requires sendmail to be configured.

qb install fail2ban --f2b-notify on

Other CLI commands:


qb reinstall fail2ban    # Re-apply templates and re-run config (interactive) or re-apply defaults
qb remove fail2ban       # Stop service, remove package, clean up sudoers and config
qb manage fail2ban -o config   # Interactive config wizard: bantime, findtime, maxretry, ignoreip, jails
qb manage fail2ban -o unban    # Unban a provided IP from all jails

Dashboard control center

The Fail2Ban tab is at Security Settings → Fail2Ban (/settings/security?tab=fail2ban). It is admin-only.

Jail control

Each configured jail (qbx-v4dashboard, sshd, nginx-http-auth, and any per-app jails) appears as a card showing:

Enable/disable toggle
Current fail count and ban count
Inline threshold editing for bantime, findtime, and maxretry
Expandable list of currently banned IPs with per-IP unban

Changes take effect immediately. Use the Reload Config button at the top of the tab to hot-reload the fail2ban service after bulk changes.

qbx-v4dashboard jail

The qbx-v4dashboard jail monitors dashboard login failures via the systemd journal (SYSLOG_IDENTIFIER=v4-dashboard). It is always enabled and cannot be toggled off — dashboard login protection is a core safeguard.

Allowlist (ignoreip)

The allowlist section lists all IPs and CIDR ranges that are never banned by any jail. 127.0.0.1/8 and ::1 are permanently protected and cannot be removed.

To add an entry, type an IP address or CIDR (e.g. 203.0.113.42 or 10.0.0.0/8) and click Add.

Lockout-protection guard

When you attempt to remove an allowlist entry that covers your own connected IP address, the dashboard shows a targeted danger-tone warning before proceeding. Removing your own IP means fail2ban can ban the address you are managing the dashboard from if you exceed any jail threshold. Ensure you have an alternative way back in before confirming.

Manual ban / unban

The Manual Ban / Unban section lets you:

Ban — enter an IP and choose a jail from the dropdown, then click Ban IP to immediately ban that address in the selected jail
Unban — enter an IP and click Unban from All Jails to remove it from every jail simultaneously

Intelligent recommendations

The Recommendations panel appears at the top of the Fail2Ban tab and is driven by per-install analysis:

Installed-app awareness — suggests enabling the relevant jail when a proxied app is installed and its jail is disabled
Multi-user hardening — recommends tighter thresholds when multiple users are active on the server
Behavioral analysis — surfaces pattern-based recommendations from observed ban history

Recommendations are grouped by severity (Urgent, Recommended, Info) and include one-click actions to enable a jail or update a threshold directly from the suggestion card.

Config backup and restore

Fail2Ban’s jail configuration can be backed up and restored from the dashboard (Application Backups tab, or by expanding Fail2Ban in Application Control). This is a Config Only flow — there is no Full Backup or rollback, because Fail2Ban is a system service with no per-user install directory.

A config backup captures the jail configuration files:

/etc/fail2ban/jail.local
/etc/fail2ban/jail.d/qbx-base.conf
/etc/fail2ban/jail.d/qbx-apps.conf
/etc/fail2ban/jail.d/qbx-dashboard.conf

Backups are stored in the triggering admin’s QuickBox software namespace:


/home/<admin-username>/.QuickBox/software/fail2ban/backup/

Because the jail configs live under root-owned /etc/fail2ban/, the backup is written into the admin’s home tree rather than alongside the source. A restore writes the configuration back to /etc/fail2ban/, and the restored files stay root-owned.

Admin-only

Fail2Ban config backup and restore are admin-only, like the rest of the Fail2Ban surface. There is no shipped default-config restore — restore re-applies one of your own backups.

For the backup workflow, role visibility, and where backups live on disk, see App Management → Application Backups.

System Dashboard blocking reports

When fail2ban is installed, the System Dashboard (/system/dashboard) includes a Fail2Ban Protection widget. The widget is hidden when fail2ban is not installed.

The widget contains:

Panel	Description
Currently Banned	Count of active bans across all jails
Bans Last 24h	New bans in the past 24 hours
Busiest Jail	Jail with the most bans
Bans by Country	Ranked horizontal bar chart, top 10 source countries
Top Blocked IPs	Ranked table of the most-banned IPs with jail and country
Access-Vector Breakdown	Bar chart showing active vs total bans per jail
Ban Events Timeline	Area chart of ban events over the selected window

Use the 24h / 7d / 30d window selector in the widget header to change the reporting window. Clicking a jail name in the Top Blocked IPs table or a bar in the access-vector chart navigates to the Fail2Ban configuration tab.

Directory layout

etc/

├── fail2ban/

│ ├── jail.local# QuickBox-templated global defaults: bantime, findtime, maxretry, ignoreip, and email action

│ ├── jail.bak# Automatic backup of the previous jail.local created before each config update

│ ├── jail.d/

│ │ ├── qbx-base.conf# Base jail stanzas: sshd, nginx-http-auth, and qbx-v4dashboard (always enabled). Managed by v3.

│ │ └── qbx-apps.conf# Per-app jail stanzas for 27+ packages (Plex, Sonarr, Jellyfin, etc.). Each starts disabled; the relevant app install script enables it.

│ └── filter.d/

│ │ ├── qbx-v4dashboard.conf# Filter matching v4 dashboard login failures from the systemd journal

│ │ └── qbx-*.conf# Per-app filters (qbx-plex.conf, qbx-jellyfin.conf, etc.) deployed alongside each app

├── aliases# Installer rewrites mail aliases to the QuickBox admin address so Fail2Ban email alerts route correctly

└── sudoers.d/

│ └── qbx-fail2ban# Sudoers drop-in granting the dashboard the privileges needed to manage fail2ban jails without root

opt/

└── quickbox/

│ └── logs/

│ │ └── fail2ban.log# Shared log written by nginx auth failures and phpMyAdmin login failures — input for the nginx-http-auth jail

var/

└── log/

│ └── fail2ban.log# Fail2Ban service log: ban and unban events across all jails

Service management


# Check status
systemctl status fail2ban
 
# Start / stop / restart
systemctl start fail2ban
systemctl stop fail2ban
systemctl restart fail2ban
 
# View active jails and ban counts
fail2ban-client status
 
# View a specific jail
fail2ban-client status qbx-v4dashboard
fail2ban-client status sshd
 
# Unban an IP from all jails (CLI)
qb manage fail2ban -o unban 203.0.113.42

Best practices

Do

Add your admin workstation IP to the allowlist in the install options form (or before tightening bantime/maxretry) so password typos cannot lock you out.
Use the Recommendations panel — it surfaces jail gaps and threshold suggestions specific to your install.
After bulk changes in the dashboard, click Reload Config to hot-reload fail2ban without a full service restart.
Check the System Dashboard Fail2Ban widget regularly to spot unusual ban spikes by country or jail.
Review per-app jail coverage in the Fail2Ban tab after installing new applications — the suggestions engine will surface any jails that should be enabled.

Don't

Do not remove your own IP from the allowlist without a confirmed fallback route back to your server.
Avoid hand-editing jail.d/qbx-base.conf or jail.d/qbx-apps.conf — these files are managed by v3 and will be overwritten on reinstall. Use the dashboard or qb manage fail2ban -o config instead.
Do not disable both the sshd and qbx-v4dashboard jails simultaneously if you rely on brute-force protection for shell and dashboard access.
Do not delete /opt/quickbox/logs/fail2ban.log — the nginx-http-auth and phpMyAdmin jails read from it.

Troubleshooting

Locked out after config change

Use fail2ban-client status to list active jails and confirm bans, then unban trusted addresses with qb manage fail2ban -o unban <ip> or via the dashboard Manual Unban field. If you tightened bantime or maxretry, add your admin IP to the allowlist before retrying.

Verify log inputs

The qbx-v4dashboard jail reads from the systemd journal (no log file needed). The nginx-http-auth jail reads from the nginx error log. The phpMyAdmin jail reads from /opt/quickbox/logs/fail2ban.log. Check fail2ban-client status <jail> before assuming a jail is inactive, then verify the appropriate log source.

Service installed but not running

The Fail2Ban tab shows a banner when the service is installed but stopped. Configuration is displayed from the last known state. Start the service via systemctl start fail2ban to restore protection. The System Dashboard widget also shows a notice when the service is stopped.

Per-app jail not activating

Per-app jails in qbx-apps.conf start disabled and are enabled by the relevant app’s install script. If an app is already installed and its jail is not active, the Recommendations panel will surface an enable-jail suggestion with a one-click action.

FAQ

The Package Management install options form maps directly to the v3 CLI flags. You can set ban duration (--f2b-bantime, 60–86400 s), failure window (--f2b-findtime), max attempts (--f2b-maxretry), which jails to enable at install (sshd and/or nginx — dashboard protection is always on), email alerts, and additional allowlist IPs/CIDRs. All values can be changed afterward from the Fail2Ban tab.

`qbx-base.conf` (in `/etc/fail2ban/jail.d/`) holds three base jails: `sshd` (SSH brute-force), `nginx-http-auth` (nginx basic-auth failures), and `qbx-v4dashboard` (dashboard login failures via the systemd journal). The `qbx-v4dashboard` jail is always enabled. SSH and nginx are enabled by default but can be toggled from the install form or the dashboard tab.

`qbx-apps.conf` contains disabled jail stanzas for 27+ packages including Plex, Sonarr, Jellyfin, Emby, Radarr, Lidarr, qBittorrent, Deluge, Nextcloud, and more. Each stanza starts with `enabled = false` and is activated automatically by the app's own install script. You can also enable any jail manually from the Fail2Ban tab, or via the Recommendations panel if the app is already installed.

The lockout-protection guard detects whether the entry you are removing covers your current connected IP (exact match or IPv4 CIDR containment). If it does, the dashboard shows a danger-tone warning explaining that removing the entry could let fail2ban ban the IP you are managing the dashboard from. You can still proceed after confirming.

The suggestions engine looks at three things: which apps are installed and whether their associated jails are enabled (installed-app awareness), how many users are active on the server (multi-user hardening recommendations), and observed ban patterns in the ban history (behavioral analysis). Suggestions come grouped by severity — Urgent, Recommended, and Info — with one-click actions to apply the recommended change immediately.

The Fail2Ban Protection widget is only shown when fail2ban is installed. If the package is installed but the widget is missing, check that the fail2ban service is running (`systemctl status fail2ban`) and that the dashboard is fully loaded. The widget hides itself during the summary load phase; a brief delay on first page load is normal.

Yes — `qb manage fail2ban -o config` launches the interactive terminal wizard that prompts for bantime, findtime, maxretry, ignoreip, and jail toggles for the base jails. Dashboard users should use the Fail2Ban tab, which provides the same controls without a TTY. The wizard writes `/etc/fail2ban/jail.local` and `jail.d/qbx-base.conf` and restarts the service.

Yes. Fail2Ban installs, removes, and reinstalls from the Package Management tab. Dashboard installs open the options form before the install begins so you can configure thresholds and jails before protection goes live. On reinstall the same options form is shown, letting you reconfigure without touching the CLI.

Yes — General Settings has an opt-in Auto-protect apps on install feature flag (off by default). When it is on, installing or reinstalling any app with a verified Fail2Ban jail template automatically enables that jail at install time. Per-app toggling from the Fail2Ban tab is always available regardless of this flag.

The recidive jail is repeat-offender escalation. It watches Fail2Ban's own log and re-bans any IP that other jails have already banned five or more times within a day. The escalation is for a full week and applies to all ports, not just the port that triggered the original bans. Because it can only escalate IPs that other jails have already banned, it cannot lock out a clean visitor. Enabled by default on new installs; thresholds (findtime, maxretry, bantime) are editable on the recidive jail card.

New installs default to 3600 seconds (1 hour) so protection is meaningful out of the box — 600 seconds (10 minutes) was too short to discourage even casual brute-force tooling. Older installs that were originally provisioned with the 600-second default keep that value until you change it; edit bantime on any jail card in the dashboard Fail2Ban tab or rerun the CLI config wizard to bring them up to the new default.

Resources

Fail2Ban Documentation

Official guide to filters, jails, and actions

QuickBox Security Settings

Dashboard Security Settings — Fail2Ban jail control, Firewall Rules, Quick Harden, Geo-Lock, and Geo-Block

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