Upgrade

Upgrades HashBackup to the latest version.

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

With no options the upgrade command checks the HashBackup, LLC upgrade servers to see if a newer version of HashBackup is available. If not, "You already have the latest version" is shown and upgrade stops. If there is a newer version, the release notes are downloaded and displayed. The release notes explain all changes made since the version you are currently running. Upgrade then downloads the RSA-4096 file signature and new version of HB from the upgrade servers, verifies the file signature matches the program downloaded, and installs the new version, renaming the current version as hb.bak.

Options

The -n option checks for a new version and shows the release notes but does not replace the hb binary. Release notes are written to stderr, so use this command to redirect them to a file:

$ hb upgrade 2>notes.txt

If the file notes.txt is empty, you already have the latest version.

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.

Signatures

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

Database Upgrades

HashBackup may do an automatic database upgrade the first time a new version is used. There have been over 30 database changes since the initial release, on production backups stretching back to 2012.

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 to its original state.

$ 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)

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, or the HashBackup program has not been upgraded regularly, 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 to do that are given when an upgrade fails for this reason.

To ensure you have a version of HB that can read your backup, consider setting the config option copy-executable to True. This stores 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.

Messages

Upgrade sends messages either to stdout or stderr. In an interactive session, both of these normally are tied to the terminal screen so there is no distinction. For shell, cron, or background jobs, the distinction can be important.

The HashBackup version and copyright heading and "You already have the latest version" are sent to stdout. Since these are not very useful in scripts or cron jobs, stdout is usually sent to /dev/null and these messages are suppressed:

$ hb upgrade >/dev/null

All other messages including the release notes are sent to stderr. In a cron job where upgrades are automated, these messages are emailed to you when an upgrade occurs. To send stderr to a file instead, use:

$ hb upgrade >/dev/null 2>notes.txt

Automating Upgrades

To ensure that you have the latest updates to the HashBackup program and your backup database stays up to date, it’s a good idea to setup automated upgrades. This is easy with a system cronjob, either with your regular backup command or as a separate cron job.

To check for upgrades after every backup, the line in /etc/crontab looks like this:

# min     hour     mday     month     wday    user     command
MAILTO=me@email.com
05 02 * * * root /usr/local/bin/hb log backup -c /hbdata /; /usr/local/bin/hb log retain -c /hbdata -s30d12m; /usr/local/bin/hb log selftest -c /hbdata -v4 --inc 1d/30d,1G; /usr/local/bin/hb upgrade >/dev/null

You can adjust the start time in the first two fields, minute first, then hour, the -c backup directory, and other options as necessary. The upgrade is done after the backup so that the HashBackup upgrade server isn’t hit with many simultaneous upgrade requests. Everyone’s backup will take a different amount of time so this puts the upgrade checks on a somewhat random schedule.

To check for upgrades on an independent schedule, use an entry like this to check every day at 12:30AM (change to a random time you like):

# min     hour     mday     month     wday    user     command
MAILTO=me@email.com
30 0 * * * root /usr/local/bin/hb upgrade >/dev/null

Cron will send an email with the release notes when a new version is installed.

OSX systems may not have an /etc/crontab file, but if you create one, it will work. Begin your edit command with sudo to create this system file in /etc.

Private Upgrade Servers

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 below for your private http server. The source is an rsync module, so two colons are used:

$ rsync -a --delete-after --port 8010 upgrade.hashbackup.com::release /my/dir/hbrelease

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

If --delete-after is removed and multiple versions are kept in a directory, only the version matching latest.txt is used for upgrades; the last rsync determines the active version. Upgrade doesn’t check for the highest version in the directory.

To upgrade from your private upgrade server:

$ hb upgrade [-n] http[s]://myserver.mydomain.com/hbrelease

This functions exactly like the official HashBackup upgrade server, using RSA-4096 signature verification to ensure the binary is authentic.

SSL & Private Upgrade Servers

Secure sockets are not needed for upgrades because the RSA signature ensures the executable is authentic and correct, but to use SSL for accessing a private server, a CA cert file can be specified:

$ SSL_CERT_FILE=/etc/ssl/cert.pem hb upgrade https://my.server/path

Installers & Private Upgrade Servers

The Download page has links to installers or "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. It’s important to verify the SHA1 hash of the installer you download. Once the boot binary’s SHA1 is verified, subsequent upgrades are verified by HashBackup with RSA-4096.

Installers can be used with private upgrade servers. The http address of the private server is passed to the installer using environment variables, for example:

$ HB_UPGRADE_URL=http://my.server.com/hbrelease hb init -c mybackup

To use SSL:

$ SSL_CERT_FILE=/etc/ssl/cert.pem HB_UPGRADE_URL=http://my.server.com/hbrelease hb init -c mybackup