qb fix - System Repair

The qb fix commands provide a powerful toolkit to address common issues and perform system repairs. With a focus on simplicity and effectiveness, these commands enable you to troubleshoot and resolve various problems that may arise on your server, ensuring smooth and uninterrupted operations.

Fix Python

Fix Python configuration and install missing extensions:

qb fix python

What it does:

• Installs/repairs Python build dependencies and runtime packages (pip, docopt, virtualenv, etc.)
• Ensures compiled Python 3.11 and 3.13 are present and functional, with pip/bootstrap synced
• Applies PEP 668 safeguards (--break-system-packages when needed) and avoids downgrading system pip
• Syncs baseline modules across 3.11, 3.13, and system Python; logs FIX_PYTHON to system_log

Distro-specific behavior:

When to use:

• Python apps won’t start or show ModuleNotFoundError
• After distro/OS upgrades that changed Python
• Broken virtualenvs or missing compiled Python runtimes (3.11/3.13)
• Before/after installing Python-based QuickBox apps

Fix PHP

Repair, verify, and manage the QuickBox per-application PHP stack:

qb fix php                          # Fix PHP 8.1 (default, backward compatible)
qb fix php [VERSION]                # Fix a specific PHP version
qb fix php [VERSION] --hold         # Lock PHP packages to prevent apt upgrades
qb fix php [VERSION] --remove-hold  # Unlock PHP packages to allow apt upgrades

QuickBox uses per-application PHP isolation rather than a single system-wide PHP version. Each application gets its own FPM pool running on the PHP version it requires. The qb fix php command repairs, verifies, and manages all installed PHP versions and their pool configurations.

PHP versions managed:

Full fix (no flags)

When run without --hold or --remove-hold, the command performs a comprehensive repair of the target PHP version.

For PHP 8.1 (when installed):

• Configures the Sury PHP repository for your distribution (Debian or Ubuntu)
• Temporarily unholds packages, refreshes apt, and reinstalls/repairs the full extension chain (40+ packages including FPM, CLI, opcache, memcached, msgpack, imagick, intl, etc.)
• Configures php.ini for both FPM and CLI (upload limits, memory, OPcache, session security)
• Removes Apache 2 if present to avoid conflicts (QuickBox uses nginx exclusively)
• Regenerates the php8.1-fpm default pool config and re-enables required modules
• Cleans up stale SourceGuardian binaries from pre-v4 builds
• Re-holds PHP 8.1 packages to prevent accidental upgrades; updates the php symlink to php8.1

For PHP 8.4 (when installed):

• Configures the Sury PHP repository (same as 8.1, idempotent)
• Temporarily unholds packages, refreshes apt, and installs/repairs the extension chain (including php8.4-apcu, php8.4-mysql, and other 8.4-specific packages)
• Configures php.ini for both FPM and CLI
• Enables PHP 8.4 modules and re-holds packages after repair

For PHP 8.3:

• Currently a stub — runs pool verification only (no apps are assigned to 8.3 yet)

Cross-version pool verification

After repairing the target version, the command also verifies FPM pools for all other installed PHP versions. For example, running qb fix php 8.1 will also check PHP 8.3 and 8.4 pools, and vice versa. This ensures the entire PHP stack is consistent, not just the targeted version.

For all PHP versions (8.1, 8.3, 8.4), pool verification:

• Checks that the FPM service is enabled and running, restarting it if stopped
• Queries the database to verify each application’s pool config file exists (e.g., rutorrent.conf, phpmyadmin.conf, nextcloud.conf)
• Reports the number of active isolated pools per version
• Flags orphaned installations where a pool directory exists but the FPM service is not enabled
• Reloads FPM services to pick up any configuration changes

Version hold management

The --hold and --remove-hold flags provide quick-path operations that skip the full repair and exit immediately after applying the hold change.

# Lock PHP 8.1 packages to prevent apt from upgrading them
qb fix php 8.1 --hold
 
# Unlock PHP 8.4 before a planned upgrade, then re-lock after
qb fix php 8.4 --remove-hold
apt-get upgrade
qb fix php 8.4

Holds cover all packages for the target version (e.g., php8.1*) plus shared dependencies like php-pear and libfcgi0ldbl. The full fix operation automatically re-applies holds at the end, so you typically only need --hold after manual apt changes or --remove-hold before a planned upgrade.

Examples

# Default: fix PHP 8.1 (backward compatible with older command)
qb fix php
 
# Fix PHP 8.4 specifically (e.g., Nextcloud showing 502 errors)
qb fix php 8.4
 
# Lock PHP 8.1 to prevent apt upgrades
qb fix php 8.1 --hold
 
# Unlock PHP 8.4 before a planned upgrade
qb fix php 8.4 --remove-hold

When to use:

Fix Database

Reconcile duplicate user_software rows against live config truth, and (on legacy SQLite v3 installs) repair the database symlink:

qb fix database                 # dry-run (default) -- reports only
qb fix database --apply         # execute the reconciliation
qb fix database --cron          # apply mode with reduced output for scheduled runs

How the reconciler decides which row to keep

Legacy install bugs can leave multiple rows in the user_software table for the same (user_id, software_name) pair. The reconciler walks every duplicate group and consults the v4 dashboard on 127.0.0.1 for the app’s live config file — the file the service is actually reading. v3 Bash never parses app config files directly; it asks v4 (the authority) for the raw file contents via GET /api/system/apps/:appId/config and then greps the expected port fields out of the returned string.

For each duplicate group, one of three things happens:

Apps with truth mapping today: sonarr, sonarr4k, radarr, radarr4k, lidarr, readarr, prowlarr, jellyfin, qbittorrent, deluge, rtorrent, rutorrent, plex. Any other app with duplicate rows still gets deduped — it just uses the MAX(id) fallback directly.

Example session

A dry-run identifies a duplicate sonarr group for user@host:

$ qb fix database
Checking QuickBox database...
v4-dashboard detected -- skipping legacy SQLite symlink repair
Running truth-aware reconciliation (dry-run)
Found 1 duplicate group in user_software
 
Group: user@host / sonarr (2 rows)
  Truth source: v4 (config.xml) -- Port=9020, SslPort=9878
  Row id=42 port=9020 secure=9878  <- MATCH (would keep)
  Row id=37 port=8989 secure=9898  <- would delete
 
Dry-run summary: would keep 1, delete 1, update 0
Re-run with --apply to execute.

Re-running with --apply commits the change:

$ qb fix database --apply
Checking QuickBox database...
Running truth-aware reconciliation
Group: user@host / sonarr (2 rows)
  Truth source: v4 -- keeping id=42 (KEPT_BY_TRUTH)
  Deleted 1 row
Reconciliation complete: kept 1, deleted 1, updated 0

SQLite symlink repair (legacy v3-only)

On servers that do not have the v4 dashboard installed, qb fix database also repairs the legacy /srv/quickbox/db/qbpro.db symlink pointing at /opt/quickbox/config/db/qbpro.db, creates a backup (keeping the newest 3), and ensures www-data read access. When v4 is installed this step is skipped automatically — v4 manages its own database at /etc/v4-dashboard/data/db/qbpro.db through Prisma.

When to use:

Fix Permissions (per-user apps)

Normalize system groups and application directories for a user:

qb fix permissions -u username
# or
qb fix perms -u username

What it does:

• Preserves existing groups from /etc/group, then ensures www-data is present; adds sudo only for shell users (shell_level = 1)
• Recursively sets ownership of /opt/<username> to the user and group
• Sets directories under /opt/<username> to 0755
• Logs FIX_PERMISSIONS <username> to system_log

How it differs from qb fix home:

• qb fix home -u username targets /home/<username> (files 0664, dirs 0755, home 0750, special handling for .ssh, .bin, rclone, Nextcloud)
• qb fix permissions -u username targets /opt/<username> and group membership — use it if/when app installs/upgrades change ownership/ACLs. QuickBox handles this automatically during installs/reinstalls/updates, but this command is available when something fails or manual changes break the flow.

How QuickBox automatically maintains app config permissions

QuickBox runs a background service, qbpermmon.service, that automatically corrects ownership, file modes, and ACLs on monitored app config paths. Drift is detected and corrected within a minute of occurring.

How it works:

• The binary (/usr/local/bin/qbpermmon) sweeps every monitored path on a 60-second interval. For each entry in the matrix, it stats the path and compares owner, group, and mode against the canonical values. If they already match, nothing happens. If they differ, the service runs chown + setfacl + chmod to restore the canonical state.
• Enforcement is matrix-driven: a single config file (/opt/quickbox/config/system/qbpermmon.matrix.sh) declares the canonical owner, group, mode, and ACL for every monitored path. All 53 entries across 29 apps are defined there. If an app isn’t in the matrix, its paths aren’t monitored.
• For each entry that needs correction, the service enforces all three of owner + group, file mode, and ACL in one pass — not just a chmod. Plex is the only app in the fleet with a dedicated system user (plex:plex); all other apps use the installing user.
• Drift is detected at the next 60-second sweep — typical detection latency is well under a minute. The trade-off is near-zero CPU when nothing is wrong (the stat per path costs microseconds and only adds up to a few milliseconds per minute across the whole matrix).

Apps with automatic protection:

The matrix currently covers the *arr stack (Sonarr, Radarr, Lidarr, Readarr, Prowlarr), media servers (Plex Media Server), request and discovery tools (Jellyseerr, Overseerr, Seerr, Ombi), indexers (Jackett, NZBHydra2), download clients (rTorrent, SABnzbd, qBittorrent, Deluge, NZBGet, Transmission, pyLoad), reading apps (Kavita, Komga, LazyLibrarian), media management (Bazarr, Medusa), and utilities (Autobrr, Syncthing, rclone, TheLounge).

Limits — what qbpermmon is not:

• It does not touch /opt/<username> or app binary directories. For those, use qb fix permissions -u username.
• It does not repair home directory structure or .ssh permissions. For those, use qb fix home -u username.
• Coverage is strictly matrix-driven. Paths not listed in the matrix are not monitored.
• Runs as root; failures and corrective actions surface to journalctl -u qbpermmon.

Fix dlindex

Re-render every user’s per-user nginx download index config so already-deployed installs pick up the latest symlink hardening, dynamic download-path discovery, and qbpermmon drop-ins for custom NAS paths:

qb fix dlindex                  # walk every user in user_information
qb fix dlindex -u username      # single user

What it does:

Each torrent client install (Deluge, qBittorrent, rTorrent, Transmission) ships a per-user nginx fancyindex view of its download directory — the https://<server>/<username>.<client>.downloads URLs you can browse with a web browser. Those URL configs live at /etc/nginx/software/<username>.dlindex.conf and are rendered at install time from the templates under /opt/quickbox/install/templates/dlindex/.

qb fix dlindex re-renders that per-user config from the current templates. For each user it:

• Resolves the user’s installed torrent clients via user_software.
• Discovers each client’s actual download path and validates it against the allowlist (/home/<user>/, /mnt/, /media/).
• Writes the rendered <user>.dlindex.conf with www-data:www-data ownership.
• Adds a qbpermmon drop-in for any validated /mnt or /media leaf, so the permission monitor keeps custom NAS paths readable by www-data.
• Tests the nginx configuration (nginx -t) and reloads nginx only on PASS — a broken config is never applied.
• Emits one NDJSON status line per user; the server-wide walk also writes a FIX_DLINDEX entry to system_log. Single-user mode logs FIX_DLINDEX_<username>.

Users whose home directory is missing (deleted accounts that still have a row in user_information) are skipped with "reason":"home_missing".

When to use:

Fix Dashboard

Re-run the v4 dashboard update pipeline:

qb fix dashboard

What it does:

• Equivalent to running qb update dashboard
• Re-downloads and rebuilds the v4 dashboard from upstream
• Restarts the v4-dashboard.service
• Useful when the dashboard update failed partway through or the build is corrupted

When to use:

Fix Version

Force update QuickBox to the latest upstream version:

qb fix version

What it does:

• Downloads all CLI binaries fresh from central.quickbox.io (the release proxy)
• Replaces the following components with the latest upstream versions:

Binaries refreshed:

• fix (the fix system itself), qb (CLI handler), manage (management binary)

Modules refreshed:

• Fix modules: dbFix, homeFix, permFix, phpFix, pythonFix
• Management modules: apiSettings, dbSettings, fail2banSettings, langSettings, mountSettings, nginxSettings, softwareSettings, telemetrySettings, themeSettings, trackerSettings, wbSettings, wgSettings, dnsSettings
• Update pipeline: pipeline, pipeline-environment, pipeline-dependencies, pipeline-download, pipeline-system, pipeline-nginx, pipeline-dashboard, pipeline-database, pipeline-services, pipeline-finalize, dashboardUpdate

After downloading, it re-executes itself through the update pipeline to apply all changes.

Channel detection: If dev (/opt/qb_dev) or beta (/opt/qb_beta) flags are present, the command routes to the appropriate channel-specific updater (devpull/betapull) instead.

When to use:

What’s preserved:

• User accounts and passwords
• All installed applications and their data
• Application configurations
• Database content
• User files and downloads

What gets updated:

• CLI binaries (qb, fix, manage)
• All fix and management modules (20+ files)
• The full update pipeline (environment, dependencies, download, system, nginx, dashboard, database, services, finalize)

Common Workflows

Use these as quick checklists. Details and caveats live in the sections above so we avoid repeating full instructions.

Application Won’t Start

Systematic troubleshooting approach:

# 1. Check if it's a permission issue
qb fix home -u username
 
# 2. Restart the application
systemctl restart [application]@username
 
# 3. If PHP-based, fix the relevant PHP version
qb fix php 8.1    # ruTorrent, phpMyAdmin
qb fix php 8.4    # Nextcloud
 
# 4. If Python-based, fix Python
qb fix python
 
# 5. Check logs for errors
journalctl -u [application]@username -f

After System Upgrade

Post-upgrade maintenance routine:

# 1. Fix Python (often breaks during upgrades)
qb fix python
 
# 2. Fix PHP
qb fix php
 
# 3. Fix user permissions
qb fix home -u username
 
# 4. Update QuickBox if needed
qb update quickbox

Dashboard Not Working

v4 Dashboard (current) troubleshooting:

# 1. Check the dashboard service
systemctl status v4-dashboard
 
# 2. Restart the dashboard service
systemctl restart v4-dashboard
 
# 3. If still broken, re-run the dashboard update pipeline
qb fix dashboard
 
# 4. Check Nginx is running
systemctl status nginx
nginx -t
systemctl restart nginx
 
# 5. If still broken, force a full system refresh
qb fix version

Multiple Users Having Issues

When all users experience problems:

# 1. Fix PHP (system-wide)
qb fix php
 
# 2. Fix Python (system-wide)
qb fix python
 
# 3. Fix each user's permissions
for user in user1 user2 user3; do
  echo "Fixing $user..."
  qb fix home -u $user
done
 
# 4. If issues persist, fix QuickBox
qb fix version

Troubleshooting Guide

”Command Not Found” After Fix

# Reload shell configuration
source ~/.bashrc
 
# Or logout and login again
exit

Fix Commands Don’t Resolve Issue

# 1. Check system logs
journalctl -xe
 
# 2. Generate support logs
qb generate logs
 
# 3. Ask for help in Discord
# Include the generated support logs

Permission Fix Doesn’t Work

# 1. Check if user exists
id username
 
# 2. Verify home directory
ls -la /home/username
 
# 3. Manual permission fix
chown -R username:username /home/username
chmod 755 /home/username
 
# 4. Try automated fix again
qb fix home -u username

PHP Fix Fails

# Check which PHP versions are installed
dpkg -l | grep php-fpm
 
# Check FPM status for each version
systemctl status php8.1-fpm
systemctl status php8.4-fpm
 
# Check installed extensions for a specific version
php8.1 -m
php8.4 -m
 
# Check if packages are held (preventing upgrades)
apt-mark showhold | grep php
 
# Fix a specific version
qb fix php 8.1
qb fix php 8.4
 
# If apt holds are interfering with a planned upgrade
qb fix php 8.4 --remove-hold

”The following packages have been kept back” (held PHP packages)

When apt upgrade or apt-get upgrade reports packages kept back or held — typically php8.1-bcmath, php8.1-cli, php8.1-fpm, php8.1-common, or related packages like libboost-dev — this is expected and intentional. QuickBox holds these packages to prevent an uncontrolled apt upgrade from breaking your PHP stack or its per-application FPM pools.

What the output looks like:

The following packages have been kept back:
  php8.1-bcmath php8.1-cli php8.1-common php8.1-fpm php8.1-opcache libboost-dev
0 upgraded, 0 newly installed, 0 to remove and 15 not upgraded.

To repair and re-apply the holds safely:

qb fix php

This temporarily unholds the packages, refreshes and reinstalls the full PHP extension chain, then re-applies the holds — all in one step.

To deliberately upgrade held PHP packages:

# 1. Remove the hold so apt can upgrade
qb fix php 8.1 --remove-hold
 
# 2. Run the upgrade
apt-get upgrade
 
# 3. Re-apply the hold and verify pools
qb fix php 8.1

Python Fix Doesn’t Help

# Check Python versions
python3 --version
python3.11 --version
python3.13 --version
 
# Check pip for each version
python3.11 -m pip --version
python3.13 -m pip --version
 
# Try fix again
qb fix python

Best Practices

Prevention Tips

Avoid Permission Issues

# Always use proper commands for file operations
# Instead of: cp /source /home/user/
# Use: sudo -u username cp /source /home/username/
 
# Or fix after copying
cp /source /home/username/
qb fix home -u username

Maintain Healthy System

# Regular maintenance prevents issues
qb clean memory          # Weekly
qb update check          # Weekly
qb fix php               # After updates (fixes PHP 8.1 + verifies all versions)
qb fix php 8.4           # After updates if Nextcloud is installed
qb fix python            # After updates

Before Major Changes

Preparation checklist:

• Create system snapshot or backup
• Document current working state
• Test changes in isolation first
• Have rollback plan ready
• Note which applications are currently working
• Backup critical configurations manually

Related Commands

Need Help?