qb manage - Server Management

The qb manage functions provide a powerful and comprehensive set of tools to efficiently manage various aspects of your server. Designed with user convenience in mind, these functions empower you to effortlessly control critical elements of your QuickBox-powered environment.

Whether it’s swapping language settings, checking the status of your main API activation, managing data distribution, or ensuring data integrity through backups and rollbacks, the qb manage functions offer a comprehensive solution for server administrators and enthusiasts alike.

Quick Reference

API Key Management

List API Keys

View and manage QuickBox API keys:

qb manage api

Displays:

• Active API keys
• Key status and activation info
• Additional management options

Add API Key

Add a new API key to your QuickBox installation:

qb manage api -k YOUR_LICENSE_KEY

Example:

qb manage api -k qbp_YOUR_API_KEY

What happens:

• License key is validated
• API key is registered to your server
• Dashboard and CLI features are activated

Remove API Key

Deactivate and remove your API key:

qb manage api -o deactivate

What happens:

• API key is deactivated on the server
• License seat is freed for use on another server
• Some features may become unavailable

Database Management

QuickBox supports both SQLite3 (default) and MySQL databases. You can seamlessly switch between them and perform maintenance operations.

Switch Database Type

Switch to MySQL

# Basic MySQL setup (uses defaults)
qb manage db -o mysql
 
# Custom MySQL configuration
qb manage db -o mysql --user='dbuser' --pass='password' --port='3306' --host='localhost' --name='quickbox'

Default values:

• user: admin
• pass: (randomly generated)
• port: 3306
• host: localhost
• name: qbpro

Installation process:

1. Checks if MySQL server is installed
2. Prompts to install MySQL server and client if needed
3. Configures MySQL with provided credentials
4. Migrates data from SQLite to MySQL
5. Saves credentials to /root/.my.cnf, readable only by root

Switch to SQLite

qb manage db -o sqlite

What happens:

• Migrates data from MySQL back to SQLite3
• Retains MySQL installation (doesn’t uninstall)
• Updates QuickBox to use SQLite database

Backup Database

Create a manual backup of your QuickBox database:

qb manage db -o backup

Backup Details:

• Creates a snapshot of the entire QuickBox database
• Saves to dated directory structure
• Retains 5 most recent backups automatically
• Can be used for disaster recovery

Backup Locations:

• MySQL: /opt/quickbox/backup/system/[DATE_TIME]/db/qbpro.sql
• SQLite: /opt/quickbox/backup/system/[DATE_TIME]/db/qbpro.db

Automatic Backups:

QuickBox automatically backs up the database every 24 hours at 3:30 AM (server time) as part of the maintenance routine. This is configured in /etc/cron.d/quickbox:

30 3 * * * root /usr/local/bin/qb manage db -o maintenance --cron

Database Maintenance

Perform comprehensive database maintenance:

qb manage db -o maintenance

Maintenance Tasks:

1. Cleans up unneeded data
2. Optimizes database tables
3. Checks and repairs tables if needed
4. Boosts efficiency and prevents data issues
5. Creates backup before maintenance

Automatic Maintenance:

Maintenance runs automatically every 24 hours at 3:30 AM (server time):

30 3 * * * root /usr/local/bin/qb manage db -o maintenance --cron

Error Handling:

• Automatically attempts repairs if errors are encountered
• Unrecoverable errors trigger MotD (Message of the Day) alert
• Notifies system administrator via CLI

Why Maintenance is Important:

• Keeps database healthy and performant
• Prevents data corruption
• Maintains system efficiency
• Protects your data integrity

Restore Database

Restore QuickBox database from a previous backup:

qb manage db -o restore

Restore Process:

1. Presents selection menu with all available backups
2. Displays backup date/time for each file
3. Allows you to choose which backup to restore
4. Automatically restores selected backup
5. Returns database to the state at backup time

Use Cases:

• Recover from data corruption
• Undo unwanted changes
• Restore after failed migration
• Return to known-good state

Dashboard Access Configuration

Set Dashboard URL

Configure the server web root for dashboard access:

qb manage webroot -o [DOMAIN or IP]

Examples:

# Use domain name
qb manage webroot -o myserver.example.com
 
# Use IP address
qb manage webroot -o 192.168.1.100

What this affects:

• Dashboard URL configuration
• SSL certificate validation
• Reverse proxy settings
• Application redirect URLs

Language Configuration

Set Server Language

Set the server’s command-line language. This is a single, server-wide, admin-only setting that regenerates the operating-system locale and controls the language of qb output. It is separate from the dashboard’s per-user display language:

qb manage lang -o [LANGUAGE_CODE]

Supported Languages:

Examples:

# Set to English (short code)
qb manage lang -o en
 
# Set to Spanish (full name)
qb manage lang -o spanish
 
# Set to French
qb manage lang -o fr

What changes:

• The server’s operating-system locale (the QuickBox locale file is applied, the target UTF-8 entry is enabled in /etc/locale.gen, and the locale is reconfigured)
• The language of qb command output, system messages, and error messages
• Chinese additionally installs the Simplified Chinese language packs and Noto fonts

This is a single, server-wide setting. It does not set any individual user’s dashboard language.

Tracker Management

Enable/Disable Public Trackers

Control whether public trackers are allowed for all users:

qb manage trackers -o [enable|disable]

Enable Public Trackers:

qb manage trackers -o enable

Allows all users to add public trackers to their torrent clients.

Disable Public Trackers:

qb manage trackers -o disable

Blocks public trackers system-wide for all users.

Use Cases:

• Enable: Open servers, personal use, testing
• Disable: Private tracker communities, compliance with tracker rules, bandwidth management

Application Backup & Recovery

The qb manage software command provides comprehensive backup, rollback, and restore capabilities for your installed applications.

Backup Application Config (Partial)

Backup only the configuration files for an application:

qb manage software -o backup -u [USERNAME] -s [APPLICATION]

Example:

# Backup Sonarr config for user 'john'
qb manage software -o backup -u john -s sonarr

What gets backed up:

• Application configuration files
• User settings and preferences
• API keys and integrations
• Does NOT include the application binary

Use cases:

• Before making config changes
• Before upgrading settings
• Preserving custom configurations

Backup Application + Config (Full)

Backup both the application binary and configuration:

qb manage software -o backup -o app -u [USERNAME] -s [APPLICATION]

Example:

# Full backup of Radarr for user 'john'
qb manage software -o backup -o app -u john -s radarr

What gets backed up:

• Application binary/executable
• All configuration files
• User settings and preferences
• Complete application state

Use cases:

• Before application upgrades
• Version rollback capability
• Complete disaster recovery

Backup All Users (rTorrent Only)

Backup rTorrent configs for all users at once:

qb manage software -o backup -s rtorrent

Special Case:

For rTorrent, the username flag (-u) is not required. This command backs up all existing rTorrent users’ .rtorrent.rc files.

Backup Location:

Example backup filename:

Rollback Application

Roll back an application to a previous version:

qb manage software -o rollback -o app -u [USERNAME] -s [APPLICATION]

Example:

# Rollback Seerr to previous version
qb manage software -o rollback -o app -u john -s seerr

Rollback Process:

1. Lists all available backups for the application
2. Allows you to select which backup to restore
3. Stops the application service
4. Replaces current version with backed-up version
5. Restarts the application service

Backup Storage Location:

Use cases:

• New version has bugs
• Application won’t start after upgrade
• Feature regression
• Compatibility issues

Restore Application Config

Restore a previously backed-up configuration:

qb manage software -o restore -u [USERNAME] -s [APPLICATION]

Example:

# Restore Bazarr config from backup
qb manage software -o restore -u john -s bazarr

What happens:

1. Shows list of available config backups
2. Allows selection of backup to restore
3. Stops application service
4. Restores selected configuration
5. Restarts application service

Use cases:

• Undo unwanted config changes
• Restore working configuration
• Recover from misconfiguration

Restore Default Config

Reset an application to its default installation configuration:

qb manage software -o default -u [USERNAME] -s [APPLICATION]

Example:

# Restore SABnzbd to default config
qb manage software -o default -u john -s sabnzbd

What happens:

• Replaces current config with default from installation
• Removes all custom settings
• Resets API keys and integrations
• Returns application to “fresh install” state

Use cases:

• Start over after extensive misconfiguration
• Remove all custom settings
• Troubleshoot complex issues
• Learn default settings again

Peer Listen Port (VPN Port Forwarding)

Pin a torrent client’s peer listen port and turn off its random-port behaviour, so the client stays reachable on the port your VPN provider forwards. This is the CLI equivalent of the Port forwarding section on the VPN Control page. The dashboard sets the port automatically when a route is enabled, and this command lets you set it by hand.

qb manage software -o listen-port -s [CLIENT] -u [USERNAME] --port [1024-65535]

# Pin qBittorrent's peer port to 51413 for user 'john'
qb manage software -o listen-port -s qbittorrent -u john --port 51413

Supported clients (-s): qbittorrent, rtorrent, deluge, transmission.

What happens:

• Writes the fixed port into the client’s config and turns off its random-port setting.
• Restarts the client only if it was running (the edit is applied while it is stopped, then it is started again).
• Idempotent — if the port is already pinned, nothing is changed and the client is not disturbed.

Requirements:

• --port must be a high port between 1024 and 65535.
• The user must exist and the client must be installed for that user; otherwise the command reports an error and makes no change.

Telemetry Management

Read more about telemetry in the Telemetry Overview.

Enable/Disable Heartbeat Telemetry

Control whether your server sends heartbeat telemetry to v3.quickbox.io. Telemetry is off by default on new installs:

# View current telemetry status
qb manage telemetry -o status
 
# Enable telemetry (sends heartbeat every 5 minutes)
qb manage telemetry -o on
 
# Disable telemetry
qb manage telemetry -o off

What telemetry includes:

• System information (OS, hostname, public and local IP, QuickBox and dashboard versions)
• Resource usage (CPU, memory, disk, network, latest speed test)
• Server performance metrics (load average, uptime)
• Each user’s username, email, active status, and last login
• Seat usage and the software updates available per user

Heartbeat Interval:

• Runs every 5 minutes by default via cron job, once telemetry is on
• Configured in /etc/cron.d/quickbox

Privacy:

• All data is sent securely to v3.quickbox.io
• Used for license validation and dashboard integration
• Not anonymous: it includes usernames, email addresses, and IP addresses (see the Telemetry Overview for the full list)

Nginx Authentication Management

Enable/Disable Basic Auth

Control nginx basic authentication for application reverse proxies:

# Enable basic authentication for an application
qb manage nginx -o enable -u username -s sonarr
 
# Disable basic authentication
qb manage nginx -o disable -u username -s radarr

Supported Applications:

• Applications with nginx reverse proxy configs
• User-specific apps: Sonarr, Radarr, Bazarr, Lidarr, etc.
• System apps: Netdata, Nextcloud, ruTorrent, Tautulli, TheLounge, Transmission, WebConsole, ZNC

What this affects:

• HTTP basic authentication prompt
• Access control for web interfaces
• Security for public-facing applications

Use cases:

• Enable: Add extra security layer for public servers
• Disable: Easier access for trusted networks, API integrations

Fail2ban Management

Configure Fail2ban

Configure fail2ban intrusion prevention:

# Interactive configuration wizard
qb manage fail2ban -o config
 
# Unban an IP address
qb manage fail2ban -o unban

Configuration Options:

• Ban time: How long to ban IPs (default: 10m)
• Find time: Time window for failed attempts (default: 10m)
• Max retries: Failed attempts before ban (default: 5)
• Ignored IPs: Whitelist IPs (e.g., your home IP)
• SSH monitoring: Monitor SSH login attempts
• Nginx monitoring: Monitor web login attempts

Example Configuration:

# Config wizard prompts:
Ban time for incorrect login (Default 10m) [5m/3h/12d]: 30m
Time between incorrect logins for ban (Default 10m): 15m
Max number of retries within time (Default 5): 3
IPs ignored by fail2ban (Default none) [1.1.1.1,2.2.2.2]: 192.168.1.100
Monitor SSH Logins? ([y]/n): y
Monitor Nginx Logins? ([y]/n): y

Restricted-shell jails

Enable, disable, or check the two jails that watch the restricted-shell logs and ban abusive SSH addresses. Both jails are opt-in and disabled by default:

# 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 state: absent / disabled / enabled, plus live ban counts when running
qb manage fail2ban -o lshell-status

• Enable and disable flip both jails (qbx-lshell and qbx-lshell-abuse) together.
• Before any change, missing shell filter and jail files are deployed and verified — the command fails loudly rather than half-configure, and running lshell-enable on an older server self-heals a missing jail file.
• If lshell-status reports absent, run qb reinstall fail2ban once to lay down the current jail file.

See the Fail2Ban documentation for the jail tiers, dashboard control, and precedence rules.

Mount Management

Update Mount Space

Update user mount space calculations in the database:

qb manage mount -o space -u username

What it does:

• Calculates disk space used for user mounts
• Updates database with current mount usage
• Handles mergerfs mounts and rclone configurations
• Useful for quota tracking and disk management

Use cases:

• After large file transfers
• Periodic space auditing
• Quota enforcement verification
• Dashboard disk usage accuracy

WireGuard VPN Management

Add WireGuard Client

Add a VPN client configuration:

# Add client with default settings
qb manage wireguard add --client -cn my-vpn-server
 
# Add client with custom settings
qb manage wireguard add --client -cn my-vpn -cai '0.0.0.0/0,::/0' -cidr '192.168.1.0/24'

Add WireGuard Server

Set up a WireGuard VPN server:

# Basic server setup
qb manage wireguard add --server -lp 51820 -noc 5
 
# Advanced server setup
qb manage wireguard add --server \
  -lp 51820 \
  -cai '0.0.0.0/0,::/0' \
  -cidr '192.168.1.0/24' \
  -pur 'iptables -A FORWARD -i %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE' \
  -pdr 'iptables -D FORWARD -i %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE' \
  -noc 10

Server Options:

Client Options:

Utility Commands:

# Calculate optimal MTU for endpoint
qb manage wireguard calc --mtu --endpoint example.com --protocol ipv4
 
# Calculate CIDR from IP range
qb manage wireguard calc --cidr

Common Workflows

Initial Server Setup

Setting up a new QuickBox server:

# 1. Add your license key
qb manage api -k YOUR_LICENSE_KEY
 
# 2. Set the dashboard URL (use your domain)
qb manage webroot -o myserver.example.com
 
# 3. Set preferred language
qb manage lang -o en
 
# 4. Configure database (optional, defaults to SQLite)
qb manage db -o mysql
 
# 5. Configure tracker policy
qb manage trackers -o disable  # or enable, based on needs

Switching to MySQL

Migrating from SQLite to MySQL:

# 1. Backup current database
qb manage db -o backup
 
# 2. Switch to MySQL
qb manage db -o mysql
 
# 3. Verify migration was successful
# Check dashboard and applications
 
# 4. If issues occur, restore from backup
qb manage db -o restore

Upgrading Applications Safely

Safe upgrade workflow:

# 1. Backup application with binary
qb manage software -o backup -o app -u john -s radarr
 
# 2. Update the application via its maintenance script
qb update radarr -u john
 
# 3. Test application functionality
 
# 4. If issues occur, rollback
qb manage software -o rollback -o app -u john -s radarr

Disaster Recovery

Recovering from system issues:

# 1. Restore database from last known good backup
qb manage db -o restore
 
# 2. Restore application configs
qb manage software -o restore -u john -s sonarr
qb manage software -o restore -u john -s radarr
 
# 3. Verify the dashboard service is running
systemctl status v4-dashboard
 
# 4. Check dashboard access

Troubleshooting

API Key Issues

# Check current API key status
qb manage api
 
# Remove and re-add API key
qb manage api -o deactivate
qb manage api -k YOUR_LICENSE_KEY

Database Problems

# Run maintenance to fix corruption
qb manage db -o maintenance
 
# If that fails, restore from backup
qb manage db -o restore
 
# Check database service
systemctl status mysql  # for MySQL

Application Won’t Start After Upgrade

# Rollback to previous version
qb manage software -o rollback -o app -u username -s application
 
# Or restore config only
qb manage software -o restore -u username -s application
 
# Or reset to defaults (last resort)
qb manage software -o default -u username -s application

Language Not Changing

# Set language again
qb manage lang -o english
 
# Restart the dashboard service
systemctl restart v4-dashboard
 
# Clear browser cache and hard refresh

Related Commands

Need Help?