Security Settings

The Security Settings page provides network-level and policy-level controls to protect your QuickBox Pro server. It is organized into five tabs: Settings for username and IP policies, Firewall Rules for viewing active firewall state, Geo-Lock for restricting streaming access by country, Geo-Block for blocking dashboard access from specific countries, and Fail2Ban for per-app brute-force protection, allowlist management, and manual ban/unban controls.

Overview

Settings tab

The Settings tab contains two sections for managing username restrictions and network enforcement.

Disallowed usernames

Maintain a list of usernames that are blocked from registration. This prevents users from registering with names that could be confused with system accounts or admin identities.

• Add usernames to the disallowed list one at a time
• Usernames are matched case-sensitively — add entries in lowercase for best coverage
• Both the dashboard and the CLI enforce the disallowed list during user creation

Network enforcement

The network enforcement section lets you manually block IP addresses or CIDR ranges at the firewall level:

• Add a block — Enter an IP address or CIDR range, provide a reason, and select a duration
• Rollback safety — When you add a manual block, a 30-second countdown begins. You must click Confirm before the timer expires, or the block is automatically rolled back. This prevents accidental lockouts
• Duration options — 30 minutes, 2 hours, 24 hours, or permanent

Firewall Rules tab

The Firewall Rules tab provides a view of all active iptables rules on your server, plus tools to harden your system and organize rules with plain-language labels. Rules are classified by origin so you can quickly identify where each rule came from:

You can filter rules by origin using the chip row, search across all rule fields, and delete individual QuickBox or Geo Policy rules. Bulk selection and deletion is also supported. Custom-labeled rules appear as their own filter chips between the QuickBox built-ins and the Unknown bucket.

Rules that have expired or been rolled back appear faded in the list to distinguish them from active rules.

Quick Harden

The Quick Harden dropdown sits in the top toolbar of the Firewall Rules tab, next to the Refresh button. It applies a curated hardening profile in a single click — no manual iptables commands required.

Available profiles

Each profile writes its DROP rules in the exact format the Firewall Rules classifier already knows — qbx:hardening:<profile> — so the rules appear labeled and organized immediately after you apply them.

How it works

1. Open the Quick Harden dropdown in the toolbar
2. Select a profile — for example, Block RPC (111)
3. QuickBox writes the corresponding DROP rules into the QBX_ENFORCEMENT chain with a recognizable comment (qbx:hardening:rpc) and immediately persists them to disk so they survive a server reboot
4. The rules appear in the Firewall Rules viewer classified as QuickBox origin and are ready for filtering, deletion, and labeling like any other QuickBox-managed rule

Custom rule labels

Every rule in the Firewall Rules tab can be given a plain-language label. Labels serve two purposes: they help you remember what a rule is for, and they group rules into their own filter chip in the chip row so you can quickly isolate a named set.

Adding a label to a rule

Each rule row has a small tag icon to the right of the rule details (alongside the delete and exemptions buttons):

• If the rule has no label, the icon is neutral — click it to open the label input
• If the rule already has a label, the icon switches to a pencil to signal that a label exists and is editable
• Type your label and press Enter to save. Leave the input empty and press Enter to remove an existing label
• Labels can contain letters, numbers, spaces, and common punctuation. Maximum 80 characters

Once saved, the label appears as a badge on the rule row and the rule is grouped under its own chip in the chip row. Clicking the chip filters the view to only rules sharing that label.

Label durability — QuickBox rules vs foreign rules

How a label is stored depends on which chain owns the rule:

Manage Labels panel

When you have labeled at least one rule, a Manage Labels button appears to the right of the chip row. Clicking it expands an inline panel below the chip row with a list of every label you have created:

• Rename — click the pencil icon next to a label to rename it. The new name is applied to every rule sharing that label at once
• Remove — click the trash icon to strip the label from all rules in that group. For QuickBox rules, this reverts the iptables comment back to the original; for foreign rules, the database entry is deleted

The panel stays open while you work. Close it with the X button in the panel header when you are done.

Fail2Ban tab

The Fail2Ban tab is the dashboard control center for brute-force protection. It is visible once the Fail2Ban package is installed (see the Fail2Ban application docs for install steps). Everything on this tab takes effect immediately — no command-line work needed.

Permanent record strip

A short two-tile strip at the top of the tab summarizes the all-time picture from QuickBox’s durable security event ledger:

• Offending IPs ever seen — distinct attacker IPs ever recorded by Fail2Ban on this server. Sourced from a forever-retention store, so this number only ever goes up — it never drops when bans expire or the Fail2Ban service restarts.
• Permanent bans — IPs that currently carry a forever ban (ban time -1). These stay counted until you explicitly unban them.

Recommendations

The Recommendations panel surfaces per-install suggestions grouped by severity (Urgent, Recommended, Info). Each suggestion has a one-click apply action — for example, “enable the jail for this app” or “raise the bantime on SSH.” The engine looks at three things:

• Which apps are installed and whether their associated jails are enabled
• How many users are active on the server (multi-user hardening)
• Observed ban patterns in your ban history (behavioral analysis)

Dismissed recommendations stay dismissed across page loads. The recommendations engine is conservative: it only suggests changes that improve protection, never weaken it.

Application Jails

The Application Jails section lists every installed app that has a Fail2Ban jail template available, with an enable/disable switch per app. Toggling activates brute-force protection for that app immediately — no qb update <app> required.

Each row carries a verification badge:

Jails

Each configured jail — qbx-v4dashboard, sshd, nginx-http-auth, recidive (see below), and any per-app jails you have enabled — appears as a card with:

• An enable/disable toggle
• Live fail count and ban count
• Inline editing for bantime, findtime, and maxretry
• An expandable list of currently banned IPs with per-IP unban

Recidive — repeat-offender escalation

The recidive jail watches Fail2Ban’s own log for IPs that keep coming back. If the same IP is banned five or more times within a day by other jails, recidive re-bans it for a full week across all ports — not just the port that triggered the original bans. It only ever escalates IPs that other jails have already banned, so it can never lock out a clean visitor.

Recidive is enabled by default. You can adjust its thresholds (findtime, maxretry, bantime) on the recidive jail card just like any other jail, or disable it from the toggle.

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.

Manual Ban / Unban

The bottom of the tab has two cards for one-off IP actions:

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

Auto-protect apps on install

A feature flag in General Settings → Feature Flags controls whether QuickBox automatically enables Fail2Ban protection for new app installs:

• Off (default) — Installing a new app does not enable its Fail2Ban jail. You opt in per-app from the Application Jails section of the Fail2Ban tab.
• On — Installing or reinstalling any supported app automatically enables its jail at install time, provided the app has a verified jail template.

The flag is labeled Auto-protect apps on install and lives directly under Mask banned IP addresses in the Feature Flags section. Per-app toggling from the Fail2Ban tab remains available regardless of this flag.

System Dashboard — Fail2Ban Protection card

When Fail2Ban is installed, the System Dashboard (/system/dashboard) shows a Fail2Ban Protection card. The widget is hidden when Fail2Ban is not installed. The card splits into two groups so you can read the live picture and the historical record without confusing them.

Permanent record (all-time, never resets)

These two tiles come from QuickBox’s durable security event ledger. They count distinct IPs (not ban events) and never decrease — even when Fail2Ban purges old state or restarts.

Live & recent activity (live count vs rolling window)

These four tiles mix a live point-in-time figure with three windowed figures. Use the 24h / 7d / 30d selector in the card header to change the window for the bottom three tiles. The live tile is always current; it does not change when you switch the window.

The widget also contains:

• Active Bans (Live) — a paginated, searchable table of every IP currently blocked, with country, jail, and how long ago each was banned.
• Bans by Country — a ranked horizontal bar chart of source countries for the selected window.
• Top Blocked IPs — a ranked table of the IPs with the most bans in the window. Clicking a jail name jumps to the Fail2Ban tab for configuration.
• Access-Vector Breakdown — a bar chart showing active vs total bans per jail. Click a bar to drill into that jail’s configuration.
• Ban Events Timeline — an area chart of ban activity across the selected window.

Geo-Lock tab

Geo-Lock restricts streaming sessions to specific countries. It operates as an allowlist — only sessions originating from countries you specify are permitted to continue. Sessions from other countries are terminated.

This feature is part of the Streaming Dashboard and applies to Emby and Jellyfin streaming sessions, not general dashboard access. Use Geo-Lock when you want to ensure media streaming only happens from expected locations.

Geo-Block tab

Geo-Block restricts dashboard access by country. It operates as a blocklist — requests from countries you specify are blocked at both the application level and the network level.

How Geo-Block works

1. Select the countries you want to block
2. Click Apply Rules to enable enforcement
3. When a request arrives from a blocked country, it is rejected at the application level and the IP is added to the firewall automatically
4. Subsequent requests from that IP are blocked at the network level (kernel-level iptables) before reaching the application

Managing Geo-Block

• Country selection — Choose countries from the list to add to the blocklist
• Exempt IPs — Add specific IP addresses or CIDR ranges that should bypass geo-blocking (useful for VPNs or trusted proxies)
• IP test tool — Test any IP address to see if it would be blocked by your current configuration
• Enable/disable — Toggle enforcement on or off. Disabling does not immediately remove existing firewall rules — they expire naturally

Geo-Lock vs Geo-Block

Both features use the same geolocation service to determine a visitor’s country based on their IP address. Private and local network addresses are always allowed regardless of either policy.

CLI equivalents

Best practices

FAQ

Related pages