Skip to content

Updating AdminBolt ​

Keeping your AdminBolt control panel up to date ensures you have access to the latest features, security patches, and improvements. This guide explains how to update your AdminBolt installation.

Updating from the admin panel ​

The usual way to update is the System Updates view (see System Updates for the full reference):

System Updates

  1. Log in to the Admin Panel.
  2. Open Settings > System > System Updates (/admin/settings/system-updates). The page checks for updates automatically and shows your Current Version and the Latest Version.
  3. If a newer version is available, the release notes appear inline under What's New. Click Install update to apply it.
  4. Use Check for updates at any time to re-run the check.

The update is downloaded and installed, and the necessary services are restarted.

Updating from the command line ​

Server administrators can update from the shell:

  • The AdminBolt panel and agent packages are upgraded with the system package manager (yum / dnf on RHEL/AlmaLinux).
  • bolt-cli check-for-updates [--force] checks for a new version and notifies administrators.
  • bolt-cli run-upgrade-steps [--retry-failed] [--only <id>] [--list] runs any pending one-shot upgrade steps.

See the CLI Reference for the full command list.

Going back to an earlier panel version ​

An update changes the panel database, and an older panel does not work with the changed database. Since panel 1.9.5, dnf downgrade bolt-panel, and any package change that would take the panel back with it, such as a bolt-agent downgrade or undoing an upgrade from the dnf history, stops before anything is downloaded or changed. Another release of the same version is not refused.

The message names the installed version and the one you asked for, and explains how to restore the backup made before the upgrade:

  1. Copy the files of that backup, which all carry the same time in their names, from the backup folder the message names into a new, empty directory.

  2. Install the older version and restore the backup in one step:

    bash
    sudo BOLT_RESTORE_BACKUP=<that directory> dnf downgrade bolt-panel-<version>

BOLT_RESTORE_BACKUP must name the directory you copied the backup to, not the backup folder itself; that folder is refused, because the downgrade writes a fresh backup of the current state there before it restores. Make sure the directory holds the complete backup of the version you are going back to.

To run the other package updates while leaving the panel as it is, add --exclude=bolt-panel to the dnf command.

Updating to 1.8.0 ​

1.8.0 reorganises the admin area. The sidebar is now twelve task-oriented groups, Dashboard, Customers, Backups, Web Server, Email, SSL, Health, Cluster, Logs, Migration, Modules, and Settings, and the server's configuration screens sit under Settings, apart from the web server's, which are tabs of Web Server. Nothing was taken away in the move: the screens you used are still there, grouped by subject rather than listed flat.

You do not have to update anything you saved. With one exception noted below, every address from an older panel answers with a permanent redirect to its new location, so bookmarks, links stored in earlier notifications, and anything you scripted against a panel URL keep working and land on the right screen.

  • Looking for a screen by its old name? Where pages moved in 1.8.0 maps every old address to its new one.
  • Still running an older panel? The complete guide for panels before 1.8.0 stays available under /1.7/. Use the version picker in the top navigation to switch between 1.9.1 (latest) and 1.7 (panels before 1.8.0).

The exception: the standalone Apache Profiles page was removed and its address does not redirect. Apache profile behaviour is configured on the Apache tab of Web Server in the sidebar. See Profiles.

The Web Server screens are not under Settings: they are tabs of the Web Server entry in the sidebar, and their /admin/settings/... addresses redirect there.

What an update reconciles ​

Beyond the packages themselves, each upgrade brings parts of the server back in line with what the current release expects:

  • Managed cron entries are reconciled on every upgrade, so a server missing one picks it up on the next update rather than only on a fresh install. This covers the sweep that issues and renews certificates for hosting domains. Since panel 1.9.4 this includes the panel's scheduler entry, which prints nothing and stays single; see The panel's scheduler entry.
  • Mailing list recipients are repaired once by the update to 1.9.4. Before panel 1.9.1, deleting a subscriber in one account could remove the same address from another account's list on the mail server. The update adds back every recipient whose subscription is still active in the panel, in the delivery mode and moderator status the subscription has. It removes nothing: recipients that are only on the mail server stay. Addresses the mail server removed after their mail bounced are not added back, and their subscriptions are marked Bouncing. Administrators get a notification titled Mailing list recipient repair that names the lists with recipients restored, bounced addresses, addresses the mail server does not accept (add them by hand), lists that could not be checked, and lists the 1.9.1 update changed, whose owners should check their recipients. A list that could not be checked is left unchanged, and the upgrade step reports a failure until it can be checked; see Updating from the command line to retry failed steps. While a list is being repaired, removing one of its subscribers is refused with "This mailing list is being repaired, so nothing was changed." for a few minutes.
  • JetBackup hooks are installed on hosts that ran JetBackup before AdminBolt shipped its integration, so backups and restores cover every account resource rather than the home directory alone. An hourly check puts them back if a JetBackup update replaces them.
  • The web server package. Since panel 1.9.6, the update moves a server that took the custom httpd 2.4.65 build back to the AlmaLinux httpd package, which serves sites on the Remi (CGI) handler and gets the distribution's security updates. A server that is not on that build is left as it is. When the move cannot run, the update says why and names the command that runs it again, a bolt-cli run-upgrade-steps call for that one step; the next update tries it again too.
  • The panel package. Since panel 1.9.6, installing or updating the panel package brings in no other PHP build for /usr/bin/php.
  • Webmail and the shipped fail2ban jails, panel login protection among them, come back up after an update that does not include those components itself.

Two things are worth doing by hand after upgrading to 1.6.0:

  • Admin sign-in. Admin accounts are now owned by the panel and have their own passwords. Existing installs keep signing in with the password they use today and are asked to set a panel password on the next sign-in. See Admin Management.
  • Existing virtual hosts. Run bolt-cli rebuild-apache-vhosts once to regenerate the configuration of every non-parked domain from the current templates. New and changed domains do this on their own; the command is for sites created before the upgrade.

After updating ​

  1. Clear your browser cache to ensure you are seeing the latest interface.
  2. Check the dashboard for notices about steps the update left for you to take.
  3. Test key features to make sure everything is working as expected.

Troubleshooting ​

  • If an update fails, the panel shows an error state with a View log option; the update log is at /usr/local/bolt/web/bolt-update.log.
  • Since panel 1.9.5, an update that stopped before it finished is shown on System Updates with Repair and finish the update. See When an update stops before it finishes.
  • If the system cannot be updated automatically (for example a package conflict), the panel shows the steps to resolve it over SSH.
  • On servers where the AdminBolt package repository is not configured, update checks are skipped cleanly rather than failing. Configure the repository to receive panel updates.
  • Make sure your server meets the system requirements.
  • If problems persist, contact support or check the forums.