Commands‎ > ‎


Checks to see if an upgrade to the HashBackup executable is available and optionally installs the new version.

$ hb upgrade [-n] [-p] [--force] [server]

With no options, the upgrade command will check the 
HashBackup LLC upgrade servers to see if a newer version of HashBackup is available and will display the change log.  The change log explains changes made since the version you are currently running.  Upgrade will then ask if you want to install this new version.  If not, it exits.  If you do want to install, it downloads the executable and file signature from the upgrade servers, verifies the file signature, and then installs the new version, renaming the current executable as hb.bak.

To ensure the program you are downloading is an authentic version of HashBackup, the download package is signed with a private RSA4096 key during the build process.  The private key is not stored on the download server.  The upgrade command uses the matching public key built in to the HB executable to verify the file signature to prevent installing a corrupt or fake version of HashBackup.

The -n option checks for a new version and shows the change log but does not replace the hb binary.

With --force, upgrade performs all steps and does not ask for confirmation before installing the new version.  This is required for cron jobs or shell scripts that periodically download and automatically install upgrades.  A reasonable period to check for upgrades is every week.  Adding >/dev/null after the --force option prevents a cron email when there is no upgrade available; an email will only be sent when an upgrade occurs, and it will contain the change log.

The -p option upgrades to the preview release rather than the official release.  The preview release is to try out upcoming changes on non-production backups and provide early feedback before release.  -p must be used every time you want the preview version.

Private Upgrade Server

A private HashBackup upgrade server is easily configured and sites with more than 10 copies are encouraged to use a private server.  To create an HB upgrade server, run a cron job on your private server - no more than once a day please - to mirror the HashBackup release with rsync.  Adjust the target for your http server.  The source is an rsync module, so two colons are used, and this is all on one line though it may wrap here:

    rsync -a --delete-after --port 8010 /var/www/hbrelease

To mirror the preview release, use ::preview instead of ::release.  To archive past releases omit --delete-after


To upgrade using your local servers from your private upgrade server:

    hb upgrade [--force] http[s]://

This functions just like the official HB upgrade server, including using RSA4096 signature verification to ensure the binary is authentic.

Database Upgrades

HashBackup may do an automatic database upgrade the first time the new version is used.  If it has been a while since you have upgraded, there may be multiple database upgrades, as in the example below.  If there is any problem during the upgrade, the database is rolled back.

$ hb versions -c hb

HashBackup build #1961 Copyright 2009-2017 HashBackup, LLC

Current database rev: 24

Upgrading database to rev: 29

Copying /hb/hb.db to /hb/hb.db.orig before upgrade

  Upgrade to rev 25...

    Update directories

    Update flags

  Upgrade to rev 26...

    Update part 1

    Update part 2

  Upgrade to rev 27...

    Fix multiple C records

  Upgrade to rev 28...

    Update dest.db

  Upgrade to rev 29...

    Update stats for interrupted backups

Database upgraded to rev 29

Backup directory: /hb

... (normal hb versions output) 

Backup Compatibilty

New releases of HashBackup automatically perform database upgrades whenever the database format changes to support new features.  But if no HashBackup commands have been run on a backup within the last year, the latest release of HashBackup may not be able to upgrade the backup because it is too old.  In that case it may be necessary to download and run an older version of HashBackup to partially upgrade the database, then run newer versions to fully upgrade the database.  The instructions for how to do this are given when an upgrade fails.

To ensure you have a version of HB that can read your backup, consider setting the config option copy-executable to True. This will store a copy of the HB executable on every remote destination.  Or make sure to run HashBackup against your backup at least a few times a year with the latest release to keep the database upgraded.  For more information, see "Using HashBackup for Archiving" on the Backup command page.

Boot Binary

The Download page has "boot binaries" - a smaller executable program that acts like the regular HB command but on the first run, contacts the upgrade server, downloads the latest version, verifies the RSA signature, overwrites itself, then re-runs the original command.  This is useful for automated scripts that create VM images.  It's important to verify the SHA1 hash of the boot binary you download using the secure link on the Download page.  Once the boot binary's SHA1 is verified, subsequent upgrades are verified with RSA4096.