Before Upgrading or Downgrading

When upgrading (or downgrading) HST Server, Aspera recommends the following preparation to ensure a smooth process, minimal transfer disruption, and peace-of-mind that your original configuration is backed up in case of any problems.

Upgrading

  • The HST Server installer automatically checks for an older version of the product on your system. If an older version is found, the installer automatically removes it before installing the new version.
  • Although the installer performs your upgrade automatically, Aspera highly recommends completing the tasks below before upgrading. If you do not follow these steps, you risk installation errors or losing your former configuration settings.
  • You cannot upgrade directly between different Aspera transfer products (such as from HST Endpoint or Desktop Client to HST Server). To upgrade, you need to back up the configuration, uninstall the product, and perform a fresh install of the new version of the product.
  • When upgrading from Connect Server versions older than 3.2.1, the Connect Server system-level security settings are not preserved and must be reconfigured.

Downgrading

Older installers do not check for newer versions of the application. You must prepare your machine as described below then uninstall the newer version before continuing with your downgrade.

Note: Installers of versions 3.7.4 and older do not support systemd. When downgrading to one of these versions on an OS that uses systemd, you must manually start Aspera services because the installer cannot start them automatically. Run the following commands to start the services:
# systemctl start asperacentral
# systemctl start asperahttpd
# systemctl start asperarund
# systemctl start asperanoded

Newer versions of the Redis database are not compatible with older versions of the application. Your downgrade process depends on whether a backup of the older Redis DB is available, either as a separate backup file or as part of your backup of the var directory from the older version.

  • With a backup: Follow the steps below to prepare your machine. Uninstall the application (for instructions, see Uninstalling). Copy the older Redis DB file into the var directory before installing the older (downgrade) version.

    /opt/aspera/var/

  • Without a backup: Follow the steps below to prepare your machine. Uninstall the application (for instructions, see Uninstalling) and delete the var and etc directories from your machine. Then do a fresh installation of the older version. The configuration files in the etc directory may be compatible with older versions, but not all configurations may be read.

    /opt/aspera/var/

    /opt/aspera/etc/

Preparing for an Upgrade or Downgrade

  1. Verify the current version of HST Server.
    The steps that are required to prepare for an upgrade depend on your version. To view the current product and version, click Tools > License in the GUI orrun the following command:
    # ascp -A
  2. Review product release notes.
    Review the release notes for the versions that were released since your current version. In particular, the Breaking Changes section highlights changes that may require you to adjust your workflow, configuration, or usage.
  3. If you were using asperawatchdor Watch Folders, set a docroot or restriction for the user running those services, if it is not already set.
    For more information on setting docroots or restrictions for users, see Updating the Docroot or Restriction of a Running Watch Folder Service. Ensure that the pathname being watched (the source_dir of the Watch Folder) is in the user's docroot or restriction.
  4. If you were using asperawatchd or Watch Folders, prepare your Watch Folders for upgrade.
    Due to changes in the way watches are managed as of 3.8.0, the entire watch hierarchy is re-transferred after upgrade unless one of the following actions is taken to prepare your system:
    1. Archive files in the source directory before upgrade. This prevents asperawatchfolderd from considering all files in the source as new files and re-transferring them.
    2. Update the configuration of existing Watch Folders to set "overwrite" to NEVER. For instructions, see Managing Watch Folders with aswatchfolderadmin or Managing Watch Folders with the API. After upgrade, Watch Folders only transfers files that do not exist at the target. Once the first drops complete, you can reset "overwrite" to your preferred setting.
  5. If your product is enabled with an entitlement rather than a license, configure a longer timeout for the Aspera License Entitlement Engine (ALEE). This prevents disruptions during upgrade installation if your connection to the ALEE server is slow.
    1. Open /opt/aspera/alee/bin/asperalee-init.sh.
    2. Locate the line in which JVM_OPTIONS are declared and modify the line to add the timeout options (new text in bold): 
      JVM_OPTIONS="-Xmx64M -Xms8M -Dhttp.connect_timeout=20000 -Dhttp.socket_timeout=60000 -Dlocback.configurationFile=...

      This sets the connect timeout to 20 seconds and the socket timeout to 60 seconds.

    3. Restart the ALEE service: 
      # /opt/aspera/alee/bin/asperalee-init.sh restart
  6. Stop or allow to complete any FASP transfers that were initiated by the computer that you are upgrading.
    FASP transfers cannot proceed during your Aspera product upgrade.
    • Close the application GUI.
    • Stop (and resume after upgrade) or allow to complete any Ascp, Ascp 4, or Aspera Sync transfers in the command line.
  7. If your node is used by IBM Aspera on Cloud, back up the entire Redis database to migrate your AoC data.
    Stop asperanoded and create the backup file by running the following commands:
    # systemctl stop asperanoded
# /opt/aspera/bin/asredis -p 31415 BGREWRITEAOF
    The backup is stored as appendonly.aof in the following location:
    /opt/aspera/var/appendonly.aof
  8. Back up configuration and settings files.
    These files are found in the etc and var folders.
    • /opt/aspera/etc/ (contains server configuration, web configuration, user settings, license info)
    • /opt/aspera/var/ (contains Pre- and Post-Processing scripts, HST Serverweb UI (deprecated) settings)
  9. Back up the Redis database.
    The Redis database is backed up as part of backing up the var directory, but Aspera recommends backing it up separately as well, particularly if it is stored on a different machine.
    # sudo /opt/aspera/bin/asnodeadmin -b /filepath/database.backup
  10. If you used the HST Server web UI (deprecated), back up its customization files.
    Back up the following folder, which you can use as a template to modify the new one after installation:
    /opt/aspera/var/webtools/
  11. If you modified the daemon startup scripts for Aspera Central and asperanoded (for example, as part of an Aspera API integration), back up the modified files. These files are overwritten during an upgrade and you will need to copy your modifications into the new files after upgrading.
  12. If upgrading from version 2.1.x: Update the configuration file version number.
    If you are upgrading from Connect Server version 2.1.x and have HTTP Fallback configured, avoid upgrading errors by modifying the aspera.conf version number. Open aspera.conf with a text editor run with admin privileges:
    /opt/aspera/etc/aspera.conf

    Remove the version="2" from the opening tag <CONF>: 

    <CONF version="2">
...
  13. If upgrading from version 2.0.1 and earlier: Back up and restore web UI (deprecated) authentication information.
    If the existing installation is version 2.0.1 or below, you may need to restore the HST Server authentication information after the installation. Back up this file:
    /var/opt/aspera/webpasswd

    After the upgrade, you can restore the file to the following directory: 

    /opt/aspera/etc/