qb update - QuickBox Updates

The qb update function offers you a convenient and flexible way to manage updates for your QuickBox installation. With this feature, you have full control over the update process, allowing you to manually check for updates and choose when to apply them.

Quick Reference

Check for Updates

Check if a new version of QuickBox is available:

qb update check

What it does:

• Looks up the latest released QuickBox version and records it on your server, so the dashboard knows whether an update is available
• Downloads the changelogs for the current release so they can be read in the dashboard
• Does not print a version comparison in the terminal; it finishes quietly when the check succeeds

A cron job runs qb update check --cron automatically at 6:30 AM and 6:30 PM server time, so you only need to run it by hand when you want an immediate answer. After a check, admins see an Update badge on System > Changelog in the dashboard sidebar whenever a newer release exists.

What a version looks like: QuickBox Pro versions have four numbers, for example 3.2.2.7114. The last number is the build number and increases with every release.

Update QuickBox

Update the QuickBox CLI and the dashboard together:

qb update quickbox

Update process:

1. Downloads the latest QuickBox CLI version
2. Applies updates to core system files and libraries
3. Downloads and installs the latest dashboard
4. Streams live output continuously throughout all steps
5. Restarts the dashboard service and waits for it to come back online
6. Resumes streaming post-dashboard steps (database sync, autocomplete, manpage, etc.)
7. Confirms update complete when all steps finish

What gets updated:

• QuickBox core system
• CLI tools (qb command)
• Dashboard
• System libraries
• Configuration files (preserved with migration)
• Documentation
• The PHP of ruTorrent, phpMyAdmin and Nextcloud, up to its security fixes (see What an update does for PHP)

What is NOT affected:

• User data
• Installed applications
• User configurations
• Database content

qb manage db -o backup

What an update does for PHP

Every qb update quickbox runs qb fix php, then clears old PHP holds and applies the security floor in its finishing steps. The dev and beta channel updates do the same. Each step is quiet when there is nothing to do.

• Moves each PHP app to its supported PHP. PHP 8.1 is past its upstream end of life, so ruTorrent, phpMyAdmin and Nextcloud are moved up to the newest PHP they support (8.4 today). The new pool must answer the application’s page, and nginx must still serve it, before the old pool is removed. If the installed release of an application does not support the newer PHP, if the check cannot run, or if any step fails, the application stays on its current PHP and keeps working, and the next update tries again. See Fix PHP for each check.
• Repairs the PHP-FPM pool of each PHP application. Missing PHP packages are installed, and a PHP-FPM service is restarted only when something changed or it was not running.
• Clears old PHP holds. Earlier QuickBox releases put apt holds on PHP packages, and a held package never receives security fixes. The update removes every apt hold on a php* package and on libfcgi0ldbl.
• Applies the security floor. It runs qb fix php --security, which brings the PHP of ruTorrent, phpMyAdmin and Nextcloud up to the lowest build that carries the current PHP security fixes. It updates only the installed packages of each PHP version those applications run on, and restarts only the PHP-FPM service that needs it. A PHP version already at its floor is left alone. If your package source has no fixed build for your release yet, nothing changes and the next update tries again. See Fix PHP for the exit codes and --check.
• Retires the leftover system PHP (v4 dashboard servers). QuickBox applications each run in their own PHP-FPM pool, so a PHP that nothing uses is removed. That includes PHP 8.1 and 8.3 once the applications have moved off them. This step is part of qb fix php, runs only on a server with the v4 dashboard, and a second run changes nothing:
  • In QuickBox’s own default nginx site (/etc/nginx/sites-enabled/default), a catch-all .php handler that sends requests to a shared PHP socket is replaced by a 404 response. A .php request that no application location handles is refused: never run and never sent as source. Each application still routes its own .php files to its own pool. The original is saved first as /etc/nginx/sites-available/default.php-retire.{time}.bak, and it is put back if nginx rejects the change.
  • The default www pool of a PHP version that an application runs on is moved aside to www.conf.retired.
  • A PHP version that no application pool and no nginx site uses is stopped, disabled and removed. If removing it would also remove anything other than PHP packages, it is kept.
  • The php command points at the PHP version ruTorrent runs on (its plugins run php), and that version’s CLI is installed if it is missing. A PHP version an application pool runs on is never removed.

Update the Dashboard

Update the dashboard on its own:

qb update dashboard

The dashboard streams live progress output during the update and restarts automatically when the new version is ready.

When the CLI is behind: on the stable channel, qb update dashboard first refreshes the latest-version check. If your QuickBox CLI is older than the latest release, it runs the full qb update quickbox update instead, which updates the CLI first and then the dashboard. If the CLI is already current, only the dashboard is updated. On the dev and beta channels the dashboard is updated first, and the CLI update follows when the CLI is behind.

Because of this, treat qb update dashboard as a QuickBox update with the dashboard as the entry point, and follow the Pre-Update Checklist first.

Before Updating

Pre-Update Checklist

Follow these steps for a smooth update:

1. Check for updates and read release notes:

   bash

   qb update check
   qb news

2. Backup your database:

   bash

   qb manage db -o backup

3. Check disk space:

   bash

   df -h

   Ensure you have at least 1GB free space.

4. Notify users (if multi-user server):

   • Inform users of planned maintenance
   • Choose low-traffic time for update

5. Review the dashboard service:

   bash

   systemctl status v4-dashboard

Update Workflow

Standard Update Process

Complete update workflow:

# 1. Check what's new
qb update check
qb news
 
# 2. Backup database
qb manage db -o backup
 
# 3. Perform update
qb update quickbox
 
# 4. Verify update was successful
qb update check
 
# 5. Check the dashboard service is running
systemctl status v4-dashboard
 
# 6. Test dashboard access
# Visit your dashboard URL in a browser

Troubleshooting Updates

If the update fails or causes issues:

# 1. Check system logs
journalctl -xe
 
# 2. Re-run the dashboard update as a fix action
qb fix dashboard
 
# 3. Reset the install to the current available release
qb fix version
 
# 4. Fix common follow-on issues
qb fix permissions
qb fix php
 
# 5. Restart the dashboard service if it did not come back
systemctl restart v4-dashboard
 
# 6. Restore from backup if needed
qb manage db -o restore
 
# 7. If issues persist, contact support

Update Frequency

How Often to Update

Recommended update schedule:

Version Information

Check Current Version

Your installed QuickBox version is shown on the System Dashboard’s Diagnostics panel (Core Version / Dashboard Version) and by the sidebar status indicator. From the CLI, bare qb shows QuickBox - <version> in the interactive menu title bar. Run qb update check to refresh the latest-release information the dashboard compares against:

qb update check

Update Types

Understanding Update Releases

QuickBox versions use four numbers, such as 3.2.2.7114:

• Release line (the first three numbers, for example 3.2.2)

  • Identifies the QuickBox Pro release line you are on

• Build number (the last number, for example 7114)

  • Increases with every release, including bug fixes, security patches, and performance improvements
  • Install builds that carry security fixes promptly

Servers on the development or beta channels show a channel marker with the build number, such as dev.3.2.2.7114 or 3.2.2.7114-beta.

Common Issues

Update Check Fails

# Check internet connectivity
ping -c 3 quickbox.io
 
# Check DNS resolution
nslookup quickbox.io
 
# Try again
qb update check

Update Stalls or Takes Unexpectedly Long

The update pipeline streams live output throughout. If the terminal goes silent for more than a couple of minutes, the most common causes are network issues, low disk space, or a failed download from the release proxy.

# Check available disk space
df -h
 
# Free up log files if needed (admin only)
qb clean system_logs -o 7 -u yourusername
 
# Retry the update
qb update quickbox

If the stall occurs during the dashboard restart phase, the dashboard will automatically come back online once the new binary is ready — you do not need to intervene unless the terminal has been idle for several minutes with no output at all.

Services Not Starting After Update

# Check the dashboard service status
systemctl status v4-dashboard
 
# Fix permissions
qb fix permissions
 
# Restart the dashboard service
systemctl restart v4-dashboard
 
# If still failing, restore from backup
qb manage db -o restore

”Packages kept back” After Running apt upgrade

QuickBox does not hold PHP packages, and every update removes the holds that earlier releases left behind (see What an update does for PHP). Patch and security updates within a PHP version (for example php8.1-* or php8.4-*) install normally with apt upgrade, and apt never moves an application to another PHP version, because the version is part of the package name; only qb fix php does that.

If apt upgrade or apt-get upgrade still reports kept back or held PHP packages, the hold was placed by an older QuickBox install and has not been cleared yet. qb update quickbox clears every PHP hold, and qb fix php [VERSION] --remove-hold clears the hold on one PHP version.

The following packages have been kept back:
  php8.1-bcmath php8.1-cli php8.1-common php8.1-fpm php8.1-opcache

Some non-PHP packages are also held on purpose by their applications, for example the libtorrent and Transmission packages, so a short kept-back list is not by itself a problem. You do not need to take action unless an application is actually broken. To see exactly what is held:

apt-mark showhold

For the PHP-specific steps, see Fix PHP: packages kept back.

Best Practices

Rollback Updates

If an update causes issues, you can rollback:

# Restore previous database backup
qb manage db -o restore
 
# Select the backup from before the update
 
# Restart the dashboard service
systemctl restart v4-dashboard

Related Commands

Need Help?

Having trouble with updates? Get help from our support team and community: