Request Demo

Upgrading to a newer version Last updated: June 24, 2024 17:02

This article applies only to the self-hosted server installation. The SaaS deployment upgrades are always handled by the SaaS provider.

Upgrade overview

  • Upgrade of your Dwarfguard deployment always incurs (short) downtime of the application, therefore you need to carefully plan for it.
  • While upgrade of the server deployment happens immediately, upgrade of your device agents happens gradually - device agents are updated once they connect to the upgraded server.
  • Upgrade is not supported from any version to any version. If your deployment is old, you may need several upgrade steps to get to the actual version. Before the actual upgrade is attempted, the newer package always check if the existing deployment version is upgradable to the new version and stops and tells you if it is not.
  • New version you are going to upgrade to needs to be supported by your license. You can check your license capabilities by executing /opt/dwarfg_/licman -n -c | grep "Latest"
  • There are three upgrade types possible:
    • automatic upgrade - upgrades server deployment, keeps device data, upgrades agents when they come
    • manual upgrade - manual steps are provided to upgrade server deployment, keeps device data, upgrades agents when they come
    • agent-only upgrade - reinstall server deployment, device data history is lost, upgrades agents when the come
  • The patchlevel version upgrades are always automatic
  • The minor version upgrades are always automatic
  • The major version upgrades maybe of any type, depending on how much functionality is changed by the major version

Upgrading your deployment

Note that this covers single-deployment scenario. If you have multiple deployments on your server, you will need to run the upgrade from the particular deployment directly.

  1. Uncompress the new installation package.
  2. cd dwarfg_install
  3. ./upgrade.sh
    1. The upgrade script will first tell you that you must run the upgrade from the old deployment.
    2. Afterwards, it will scan your deployments.
    3. For each and every deployment found, the exact command (that you can simply copy and paste) to start the upgrade will be printed. Example:
      • To upgrade domain dwarfg_, use command on following line:
      • /opt/dwarfg_/dwarfg_upgrade.sh upgrade /tmp/dwarfg_install/appdir/
    4. If exactly one deployment is found, the new upgrade script will offer to autostart the upgrade from the old deployment for you. Example:
      • One deployment found. Do you want to autostart the upgrade? (Y for yes)
  4. Press 'Y' followed by Enter
  5. If automatic upgrade from the old version to the new package is supported, it will be started.
  6. Upgrade has several phases:
    1. Backup of the existing deployment (stop, backup, start).
    2. Basic upgrade of the deployment (stop, remove SW while keeping data in DB and selected settings, new SW deploy)
    3. Data upgrade (DB migration, upgrades scripts execution (if needed))
    4. New version start
  7. If any phase above results in failure of the upgrade, automatic recovery from the backup is attempted. If the automated recovery fails, proceed with manual recovery as described below - your data are backed up and you may safely recover

Manual recovery / restore

  1. Locate the backup you want to restore
    1. In case of single-deployment failed upgrade it is always the last one so you can simply use this:
      • ls -t /opt/backup_dwarfg/| head -1
    2. Make sure that it contains the file named backup_finished that marks the backup as successfully finished. If it does not, you need to use another backup.
    3. NOTE: to check for all usable backups you can use e.g. this command:
      • for i in /opt/backup_dwarfg/*; do if [ -f "$i/backup_finished" ] ; then basename "$i"; fi; done
    4. NOTE: examples of the backup directories with comments:
      • dwarfg_krondor%0.8.0 ... backup directory for domain krondor, application version 0.8.0
      • rot_1710003051_dwarfg_krondor%0.8.0 ... rotation of old backup for domain krondor, application version 0.8.0
      • rot_1710015769_dwarfg_krondor%0.8.0 ... another old backup
    5. Note the directory, you will need it later on.
  2. Remove the old deployment if it still exists
    1. Execute (as root) /opt/dwarfg_<domain>/cleanup.sh script
  3. Make sure there are no left-overs (may have been left there during unsuccessful upgrade)
    1. The /opt/dwarfg_<domain> directory must not be there. Remove manually if still present.
    2. The /srv/dwarfg_<domain> directory must not be there. Remove manually if still present.
    3. The /opt/cache_dwarfg/dwarfg_deployments/ must be empty (talking about single-deployment scenario - in multi-deployment, make sure the particular deployment name is not there). Remove the deployment file if still there.
  4. Run restore
    1. Enter subdirectory data under your selected backup (see instruction number 1).
    2. Run ./dwarfg_upgrade.sh script.
    3. Select option "Restore Dwarfguard" interactively.
    4. If you see message like this:
      • Reserving deployment failed (conflict: 1_dwarfg_mydomain), aborting restore.
    5. It means there is some left-over in the /opt/cache_dwarfg/dwarfg_deployments/ directory you need to clean up.