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

Info

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

Tip

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.

Install from the CLI (automation)

The CLI runs the same installer. Without a TTY (dashboard, scripts) it applies the dialog defaults; in an interactive terminal the config wizard prompts for every setting. The install-options form fields above map directly to --f2b-* flags (--f2b-bantime, --f2b-findtime, --f2b-maxretry, --f2b-jails, --f2b-ignoreip, --f2b-notify):

bash

qb install fail2ban
qb install fail2ban --f2b-bantime 7200 --f2b-jails "sshd"   # override at install
qb reinstall fail2ban           # re-apply templates and config
qb remove fail2ban              # stop service, remove package, clean up config
qb manage fail2ban -o config    # interactive config wizard
qb manage fail2ban -o unban     # unban a provided IP from all jails

Install options

Option	Description	Example
`--f2b-bantime <seconds>`	Ban duration in seconds (default 3600; min 60, max 86400). qb install fail2ban --f2b-bantime 7200	qb install fail2ban --f2b-bantime 7200
`--f2b-findtime <seconds>`	Observation window for counting failures (default 600; min 60, max 86400). qb install fail2ban --f2b-findtime 900	qb install fail2ban --f2b-findtime 900
`--f2b-maxretry <n>`	Failed attempts before a ban (default 5; min 1, max 100). qb install fail2ban --f2b-maxretry 3	qb install fail2ban --f2b-maxretry 3
`--f2b-jails "<jail,...>"`	Comma-separated subset of sshd,nginx (default both enabled). qb install fail2ban --f2b-jails "sshd"	qb install fail2ban --f2b-jails "sshd"
`--f2b-ignoreip "<ip ...>"`	Space-separated IPs/CIDRs appended to the allowlist. qb install fail2ban --f2b-ignoreip "10.0.0.1 192.168.1.0/24"	qb install fail2ban --f2b-ignoreip "10.0.0.1 192.168.1.0/24"
`--f2b-notify <on\|off>`	Enable the email-on-ban action (default off). qb install fail2ban --f2b-notify on	qb install fail2ban --f2b-notify on

Full flag reference: CLI Reference.

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

Info

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

Warning

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.

Shell-confinement jails

QuickBox confines standard (non-admin) users to a restricted shell that logs every forbidden command, warning, and containment event. Fail2Ban ships two jails that watch those logs and ban the SSH address behind repeated abuse. They are opt-in and disabled by default — turning them on is a deliberate choice, matching the per-app jail model.

Jail	Tier	What it watches	Ban threshold
`qbx-lshell`	Accumulating	Forbidden commands and user warnings in the restricted shell	4 — a single fat-fingered command never bans
`qbx-lshell-abuse`	Severe	Session kick-outs and containment kills (process-limit and command-timeout terminations)	1 — bans on first sight

The accumulating tier tolerates the occasional mistake: a legitimate user who fat-fingers one forbidden command is nowhere near the threshold. The severe tier reacts immediately to the events that only happen during genuine abuse — being kicked out of the shell, or tripping the process cap or command timeout.

Local logins can never be banned

Info

The restricted-shell log line records the SSH client address, or a literal - for a local (non-SSH) login. Both jails require a real IP to ban, so a local login is never matched by either jail — you cannot lock yourself out from the console.

Enable from the dashboard

The two shell jails appear in the Application & Security Jails panel of the Fail2Ban tab (Security Settings → Fail2Ban). Each jail toggles independently — enable one or both.

Upgraded servers: “Set up monitoring”

Note

On a server that was installed before the shell jails existed, the jail stanzas may not be present yet. In that case the jail shows a Set up monitoring action instead of a toggle. Clicking it deploys the missing filter and jail definitions (via the authoritative CLI) and then enables monitoring — after which the normal per-jail toggle governs. If you don’t see the shell jails at all, run qb reinstall fail2ban once to lay down the current jail file.

“Enabled — awaiting activity”

Info

A shell jail can be enabled before it has anything to watch. The restricted-shell log directory stays empty until a confined user’s first forbidden command, warning, or containment event, so a freshly enabled jail may read Enabled — awaiting activity rather than showing an active state. This is honest labelling, not an error: the header active-count reflects your toggle right away, and the jail starts matching as soon as there is restricted-shell activity to watch.

Enable from the CLI

A dedicated non-interactive utility manages both shell jails together:

bash

# Enable both shell-confinement jails (deploys any missing filter/jail files first)
qb manage fail2ban -o lshell-enable
 
# Disable both shell-confinement jails
qb manage fail2ban -o lshell-disable
 
# Report the current state (absent / disabled / enabled, plus live ban counts)
qb manage fail2ban -o lshell-status

Enable / disable flip both jails in one call.
Before any change, the command deploys any missing shell filter files, appends any missing jail stanzas from the shipped config, verifies they converged, and fails loudly if it cannot — it never silently half-configures. This also means running lshell-enable on an older server self-heals a missing jail file (the same job the dashboard’s “Set up monitoring” performs).
Status is three-state: absent (“not configured — run qb reinstall fail2ban”), disabled, or enabled — and when the service is running it also reports live banned counts.

Dashboard and CLI agree — dashboard wins a tie

Tip

The dashboard and the CLI control the same two jails. When both have set a jail’s state, the dashboard’s per-jail setting takes precedence: it is written to a drop-in (jail.d/qbx-dashboard.conf) that is read last and therefore wins. The CLI reflects that effective state in lshell-status and aligns any existing dashboard override when you flip a jail, so the two surfaces never silently disagree.

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

Note

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 plus the two shell-confinement jails (qbx-lshell, qbx-lshell-abuse). Each starts disabled; the relevant app install script or the shell-jail toggle enables it.

qbx-dashboard.conf

Per-jail enable/disable overrides written by the dashboard. Read last, so a dashboard toggle wins over the base stanza.

filter.d/

qbx-v4dashboard.conf

Filter matching v4 dashboard login failures from the systemd journal

qbx-lshell.conf

Filter matching forbidden-command and user-warning lines in the restricted-shell logs (accumulating tier)

qbx-lshell-abuse.conf

Filter matching shell kick-outs and containment kills — process-limit and command-timeout terminations (severe tier)

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

lshell/

<user>-YYYYMMDD.log

Per-user, per-day restricted-shell logs. Source for the qbx-lshell and qbx-lshell-abuse jails (matched by the /var/log/lshell/*.log glob). Each security line ends in the SSH client address (or - for a local login).

Service management

bash

# 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

Warning

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

Info

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

Note

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

Note

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 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 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.

They are the two shell-confinement jails. qbx-lshell (accumulating tier, maxretry 4) watches for repeated forbidden commands and user warnings in the restricted-shell logs, so a single fat-fingered command never bans. qbx-lshell-abuse (severe tier, maxretry 1) bans on first sight of a session kick-out or a containment kill (a process-limit or command-timeout termination). Both are disabled by default and opt-in — enable them from the Fail2Ban tab or with qb manage fail2ban -o lshell-enable.

From the dashboard, open Security Settings → Fail2Ban and toggle the two jails in the Application & Security Jails panel — they toggle independently. From the CLI, run qb manage fail2ban -o lshell-enable (both jails), -o lshell-disable, or -o lshell-status to check state. On a server upgraded from before the jails existed, use the “Set up monitoring” action on the jail (or run qb manage fail2ban -o lshell-enable, which self-heals a missing jail file); if the jails are missing entirely, run qb reinstall fail2ban once.

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

Restricted Shell Policy

Edit the restricted-shell policy whose logs the two shell-confinement jails watch

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