Before upgrading or downgrading

When upgrading or downgrading, the following preparation ensures a smooth process, minimal transfer disruption so that your original configuration is backed up in case of any problems.

Upgrading

  • s
  • The 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.

    On a Windows system, the installer displays the following message when an older version of the product is detected:

    Message when an older version is detected
  • Although the installer runs your upgrade automatically, completing the tasks before upgrading. If you do not follow these steps, you might get installation errors or losing your former configuration settings.
  • You cannot upgrade directly between different Aspera transfer products, such as from HSTS or HSTE. To upgrade, you need to back up the configuration, uninstall the product, and run a fresh installation of the new version of the product.

Downgrading

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

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 database 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 these steps to prepare your system. Uninstall the application, for instructions, see Uninstalling. Copy the older Redis database file into the var directory before installing the older (downgrade) version.

    C:\Program Files\Aspera\Enterprise Server\var\

  • Without a backup: Follow these steps to prepare your machine. Uninstall the application, 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 might be compatible with older versions, but not all configurations might be read.

    C:\Program Files\Aspera\Enterprise Server\var\

    C:\Program Files\Aspera\Enterprise Server\etc\

Preparing for an upgrade or downgrade

  1. Verify the current version of HSTS.
    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 or run 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 might require you to adjust your workflow, configuration, or usage.
  3. Confirm your Aspera service account.
    The Aspera service account was created when you first installed HSTS on your computer and you need to provide the account information during the upgrade. By default, the username for the Aspera services account is svcAspera; however, this is not a requirement and you can select a different user to run the services.

    To identify which user is designated as your Aspera service account:

    1. Open the services manager:
      Windows 10 and 11: Go to Search from the taskbar and type Services.

      Windows Server 2016, 2019, 2022: Go to Search from the taskbar and type Services.

    2. Find the account associated with the Aspera services, such as Aspera Central, and record the username.
    If you forgot the Aspera service account password or would like to change the designated Aspera service account, follow the instructions in Managing the Aspera service account.
  4. If you are using the Aspera Watch service or Watch Folders, set a docroot or restriction for the user running those services.
    For more information about setting docroots or restrictions for users, see Updating the docroot or restriction of a running Watch Folder service. Ensure that the path that is being watched is in the user's docroot or restriction. Make sure to add the source_dir of the Watch Folder.
  5. If you were using the Aspera Watch service or Watch Folders, prepare your Watch Folders for upgrade.
    Due to changes in the way Watch Folders are managed, the entire watch hierarchy is retransferred 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 the Aspera Watch Folders service from considering all files in the source as new files and retransferring 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. When the first drops complete, you can reset overwrite to your preferred setting.
  6. If you have a consumption-based entitlement (metered license) rather than a perpetual license, configure a longer timeout for the entitlement service (ALEE). This prevents disruptions during upgrade installation if your connection to the ALEE service is slow.
    1. Open C:\Program Files\Aspera\Enterprise Server\alee\bin\asperalee-init.bat.
    2. Add timeout options to the set SERVICE_OPTIONS section. The new option is in bold:
      ...
       ++JvmOptions=-Xmx64M^
       ++JvmOptions=-Xms8M^
       ++JvmOptions=-verbose:gc^
       ++JvmOptions=-XX:+PrintGCDetails^
       ++JvmOptions=-Xloggc:"%LOG_PATH%/gc.log"^
       ++JvmOptions=-XX:+PrintCommandLineFlags^
      ++JvmOptions=-Dhttp.connect_timeout=20000^
       ++JvmOptions=-Dhttp.socket_timeout=60000
      ...

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

    3. Restart the ALEE service:
      > C:\Program Files\Aspera\Enterprise Server\alee\bin\asperalee-restart
  7. Stop or allow to complete all FASP transfers that are running on the system that you are upgrading.
    FASP transfers cannot proceed during your Aspera product upgrade. After the upgrade, remotely initiated transfers are resumed by the remote client and the locally initiated transfers are not resumed.
    • Stop Hot Folders by clicking Stop.
    • Close the application GUI.
    • Stop and resume after upgrade or allow to complete any Ascp, Ascp4, or Aspera Sync transfers that are using the command line.
    • Stop and resume after upgrade or allow to complete any streaming transfers.
  8. Back up the Redis database.
    Stop the Aspera Node Service by going to Services, clicking IBM Aspera NodeD, and clicking Stop. Create the Redis backup file by running the following command:
    > asredis -p 31415 BGREWRITEAOF
    The backup is stored as appendonly.aof in the following location:
    C:\Program Files\Aspera\Enterprise Server\var\appendonly.aof
  9. Back up configuration and settings files.
    These files are found in the etc and var folders. Their location depends on the version of your previous installation and the operating system.

    High-Speed Transfer Server

    • C:\Program Files\Aspera\Enterprise Server\etc\

      Contains configuration files, shared remote hosts.

    • C:\Program Files\Aspera\Enterprise Server\var\
    • AppData\Roaming\Aspera\Enterprise Server

      Contains the individual user's remote hosts and Hot Folders configuration.

      To determine the current user's AppData path, run the following command in a Command Prompt window:

      echo %APPDATA%
  10. Back up the Redis database.
    The Redis database is backed up as part of backing up the var directory, but back it up separately to keep an extra copy as well, particularly if it is stored on a different machine.
    > asnodeadmin -b C:\filepath\database.backup
  11. If you modified the daemon startup scripts for Aspera Central and the Aspera Node Service. 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.