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 qbpro_ABC123DEF456GHI789JKL012MNO345PQ

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

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

Change the default server 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:

• Dashboard interface language
• System messages and notifications
• CLI output language
• Error messages

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:

/home/[USERNAME]/.QuickBox/software/rtorrent/backup/.rtorrent.rc_YEAR-MONTH-DAY_HOUR:MINUTE

Example backup filename:

.rtorrent.rc_2024-11-24_14:30

Rollback Application

Roll back an application to a previous version:

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

Example:

# Rollback Overseerr to previous version
qb manage software -o rollback -o app -u john -s overseerr

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:

/home/[USERNAME]/.QuickBox/software/[SOFTWARE_NAME]/backup/

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

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:

# 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, QuickBox version)
• Resource usage (CPU, memory, disk, network)
• Server performance metrics (load average, uptime)
• User count and seat usage
• Software updates available per user

Heartbeat Interval:

• Runs every 5 minutes via cron job
• Configured in /etc/cron.d/quickbox

Privacy:

• All data is sent securely to v3.quickbox.io
• Used for license validation and dashboard integration
• No personal user data is transmitted

Theme Management

Switch Dashboard Theme

Change the dashboard visual theme:

# Switch to Spectre theme (modern dark theme)
qb manage theme -o spectre
 
# Switch to Smoked theme (classic dark theme)
qb manage theme -o smoked
 
# Switch to Defaulted theme (original theme)
qb manage theme -o defaulted

Available Themes:

What changes:

• Dashboard color scheme
• Syntax highlighting for code blocks
• Button and component styling
• Overall visual aesthetic

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

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:

• -lp, --listen-port - Server listen port (default: 51820)
• -cai, --client-allowed-ips - Client allowed IPs (default: 0.0.0.0/0,::/0)
• -cidr, --cidr - Network CIDR (default: server_ip/24)
• -pur, --post-up-rule - iptables rules after interface up
• -pdr, --post-down-rule - iptables rules after interface down
• -noc, --number-of-clients - Number of client configs to generate (default: 1)

Client Options:

• -cn, --client-name - Client configuration name
• -cai, --client-allowed-ips - Allowed IPs for routing through VPN

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 all services are running
qb status
 
# 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 dashboard
qb dashboard restart
 
# Clear browser cache and hard refresh

Related Commands

Need Help?