Upgrading Faspex from Before 4.2.0

Upgrading to Faspex 4.2.0 and later from a version prior to 4.2.0 requires additional steps to upgrade to a newer version of MySQL.

Warning:

Prior to performing any upgrade, IBM Aspera strongly recommends customers:

  1. Perform a full environment back up and ensure the back up is successful. In case the upgrade fails, the only reliable, short-term fix is to roll back the environment using the back up.
  2. Test the upgrade in a test environment comparable to the production environment.
  3. If upgrading the test environment is successful, upgrade the production environment, but do not bring the production environment back online.
  4. Prior to bringing the production environment back online, the customer must test the application to determine if an immediate rollback is needed. Otherwise, customers risk losing all data generated between upgrade and rollback.
Note: Aspera does not support a direct upgrade from Faspex versions prior to 3.1.1. Instead, first upgrade to version 3.9.3 before upgrading to 4.0+.

Before You Begin...

Before beginning the installation process for Faspex, you must be logged into your computer as an admin (or domain admin if you are in an Active Directory environment).

  1. Apply the latest Windows update on your server.
  2. Download the latest version of IBM Aspera High-Speed Transfer Server, and IBM Aspera Faspex installers from the following locations:
  3. Make sure your MySQL password and your svcAspera password are easily accessible.
  4. Check the requirements in IBM Aspera High-Speed Transfer Server Admin Guide: Before Upgrading.
  5. Install HSTS.

    Run the installer and follow the on-screen instructions to upgrade HSTS to the latest version.

Upgrading Faspex from Before 4.2.0

  1. Back up your Faspex MySQL database by running the following asctl command: 
     asctl faspex:backup_database

    The asctl command uses mysqldump to backup Faspex's three MySQL databases to C:\Program Files (x86)\Aspera\Faspex\Backup\time_stamp-version_number.revision_number

    For example, the directory name may be 2016-04-15_140547-Faspex.4.0.0.100400.

  2. Stop all Faspex services.

    Before upgrading, stop all services related to Faspex, including Faspex, MySQL, and Apache. Use the following command:

     asctl all:stop

Warning: Faspex 4.2.0 and later uses a new version of MySQL included in the IBM Aspera Common Components. If you are upgrading from a version prior to 4.2.0, you must first back up and empty your MySQL database (/opt/aspera/common/mysql/data). You cannot upgrade the Common Components until you have backed up and emptied your database. When running the upgrade script, you are required to provide the path to a back up.

  1. If your server is using a remote database, you must set the SKIP_MYSQL_UPGRADE environment variable to true: 
     set "SKIP_MYSQL_UPGRADE=true"
    Important: If you are using a local database, do not skip the MySQL upgrade.
  2. If your server is not using a remote database, you must clear your MySQL database before upgrading to upgrade successfully.
    Delete all the files and sub-directories in C:\Program Files (x86)\Common Files\Aspera\Common\mysql\data.
  3. Launch the Faspex installer.

    Double-click the Faspex installer to begin the installation process.

    Note: If your Windows Operating System has User Account Control (UAC) enabled, confirm or enter the admin password to allow the installer to make changes to your computer.
  4. Click Install.

    Once the IBM Aspera Faspex Setup Wizard completes, you are prompted to finish the installation. By default, the Launch asctl to continue the Faspex setup checkbox is selected. Once you click Finish, the installer automatically runs the setup command. If you do not want to run the setup command automatically, then clear the Launch asctl to continue the Faspex setup checkbox.

    If Faspex doesn't automatically run the setup command or an error halts the process, then you can run the command manually, as shown below.
     asctl faspex:upgrade
  5. Provide Faspex with the database backup when prompted: 
    Please provide the location of the Faspex database backup (e.g. backup/20XX-XX-XX_XXXXXX-Faspex.4.1.1.XXXXXX):
  6. Confirm that your previous Faspex settings are still applicable.
    When prompted, enter y to continue, n to change settings.
  7. If Faspex and HSTS are installed on the same server, restart the service.
    You can restart the Aspera NodeD service from the Computer Management window. Go to Control Panel > Administrative Tools > Computer Management > Services and Applications > Services. Select Aspera NodeD and click Restart.

Logging In

  1. Open a supported browser and enter the Faspex hostname or IP address followed by /aspera/faspex in the browser URL. For example:

    http://faspex.asperasoft.com/aspera/faspex

    or
    http://198.51.100.24/aspera/faspex
    Note: For security reasons, Faspex versions 4.0.3 and later by default only allow login using the hostname that is configured in the faspex.yml configuration file (the hostname you designated during installation). If you try to log in to the application from an unlisted hostname or perform a GET request with an unlisted hostname, Faspex returns the error, "Invalid hostname". To access Faspex from an alternate hostname, follow the instructions in Configuring the Faspex Web Server.
  2. Log in with your credentials.
    If SAML configurations are available, you can choose to log in with a configured SAML provider or with your Faspex user credentials.

    If your administrator configured Faspex to use a default SAML configuration, Faspex automatically redirects you to the SAML login page. Login with your SAML credentials or login locally by bypassing the redirect.

    If you need to login with your Faspex user credentials or if you need to log in using another SAML configuration, you can bypass the redirect by adding login?local=true to the end of the URL. For example: https://192.51.100.24/aspera/faspex/login?local=true.

  3. If prompted, install IBM Aspera Connect.

    You must have the latest version of Connect installed to transfer packages using Faspex. Faspex prompts you to install the Connect Browser if you do not have it installed or if your version is not the latest. If you install Connect, refresh your browser to start using Connect.

    For more information, see Faspex and Connect.

  4. If your license is out-of-date or expired, you must first update the license before you can access Faspex.
    Faspex prompts you to update your license . You cannot interact with Faspex until entering and saving a valid license.For more information, see Updating Your License.
  5. If you are upgrading from a version of Faspex prior to 4.0.1 and you had SAML configured, you need to add your SAML configuration metadata to your SAML Identity Provider (IdP) again. Metadata URLs now contain numbers to support multiple SAML configurations.
    For information about configuring the IdP, see Configuring Your Identity Provider (IdP).