Upgrading Shares

Important: IBM Aspera supports direct upgrades to the current General Availability (GA) version from only two GA versions prior to the current release. To upgrade to the latest version, you must be within two GA versions of the current version. Upgrading from older version requires upgrading in steps. For example, if you are four GA versions behind, upgrade to two GA versions behind (GA - 2), and then upgrade to the current GA version.
Important: To upgrade an IBM Aspera Shares HA deployment please follow the Upgrading the HA Environment instructions.
Warning:

Review the following prior to performing any upgrade:

  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: You can only upgrade to this release from an installation of 1.5 or higher.
  1. Download IBM Aspera Shares.
  2. Stop Shares services.
    Go to Start Menu > Control Panel > Administrative Tools > Services. Stop the following services:
    • Aspera Nginx Services
    • Aspera Delayed Job Service
    • Aspera Web Services
    • Aspera Stats Collector
  3. Back up your system before performing an upgrade.
    1. Create a backup directory.
      Run the following in a Command Prompt, where C:\backups is your backup directory:
      > mkdir C:\backups
    2. Run the backup command.
      > cd C:\shares\www
      > bundle exec rake backup DIR=C:\backups
    3. Copy the files in C:\backups to the backup machine.
    4. Copy the following files to the backup machine:
      • C:\shares\nginx\conf\cert.pem
      • C:\shares\nginx\conf\cert.key
      • C:\shares\www\config\database.yml
  4. Install the new version of Shares by running the executable file and follow the onscreen instructions.
  5. If you are upgrading from a version of Shares prior to 1.9.6, choose to generate new Diffie-Hellman parameters or use pre-generated parameters..
    If you choose not to generate parameters now, you must generate new parameters at a later date to ensure the highest security standard for your Shares installation. For instructions on how to generate new parameters, see Generating New Diffie-Hellman Parameters.
  6. If the system is configured to serve Connect locally, point Shares to the new Connect SDK location.
    Note: For more information on serving Connect locally, see Serving Connect from a Local Location.
    To ensure the system continues to serve Connect locally after upgrade, go to the_aspera_web_plugin_install.html.haml file, located in the following location:
    C:\Shares\www\app\views\node\shared\
    Find the following line:
    - connect_autoinstall_location = '//d3gcli72yxqn2z.cloudfront.net/connect/v4'
    • To programmatically set the domain name of the server, change the line to the following:
      - connect_autoinstall_location = "//#{ request.host_with_port }/connect/v4"
    • To manually set the domain name of the server, change the line to the following, replacing shares.example.com with the Shares server domain.
      - connect_autoinstall_location = '//shares.example.com/connect/v4'
    Find the following line under function loadConnectScript:
    var url = window.location.protocol + CONNECT_AUTOINSTALL_LOCATION + '/' + script + '.min.js';
    Replace it with the line below, deleting .min:
    var url = window.location.protocol + CONNECT_AUTOINSTALL_LOCATION + '/' + script + '.js';
  7. If Shares will be referenced as multiple IP addresses or hostnames (for example, as localhost or as shares.example.com), add those IP addresses or hostnames to the AcceptedHosts parameter in the Shares configuration file (C:\Shares\www\config\shares.yml).

    The AcceptedHosts parameter lists the IP addresses or hostnames by which a user or client can reference the Shares server. Add multiple IP addresses and hostnames as a comma-separated list in the AcceptedHosts section in the shares.yml file. For example:

    AcceptedHosts: [localhost, shares.example.com, 10.0.1.128]  # 10.0.1.128 is the server IP address
  8. Restart all Shares services.
    From the Windows Start Menu search for Services and click the best-matched result to open the Services application. Start and stop any of the following Shares services:
    • IBM Aspera Shares Nginx
    • IBM Aspera Shares Delayed Job 1
    • IBM Aspera Shares Web Services
    • IBM Aspera Shares Stats Collector
  9. When upgrading from Shares 1.9.12, you must manually migrate the database.
    Important: You must use the following workaround if your Shares server is running Shares 1.9.14.174845. The issues has already been fixed by the installer if your server is running a newer revision. You can find the revision number in the bottom-left of the footer in the Shares UI, or in the name of the Shares Windows installer.
    The Stats Collector service installed with Shares 1.9.12 for Windows uses an improperly configured database schema (version 6). Shares 1.9.14 attempts to upgrade the schema to version 6, but cannot upgrade because the schema is already at version 6.

    Follow the steps below to manually migrate the database.

    1. Open cmd.exe with the Run as Administrator option.
    2. Revert schema version to 5 using manual SQL statement:
      > cd C:\Shares\www
      > rails db -p
      USE stats_collector;
      UPDATE sc_version SET schema_version=5;
    3. Comment out the following line in the sc_schema_mig_v5_to_v6.sql file located in the C:\Shares\statscollector\dbscripts\mysql folder:
      ALTER TABLE `fasp_files` ADD COLUMN `bytes_processed` bigint;
      For example:
      /* ALTER TABLE `fasp_files` ADD COLUMN `bytes_processed` bigint; */
    4. Run the database migration command:
      > C:\Shares\statscollector\bin\aspera-stats-collector.bat admin db-migrate
  10. When upgrading from Shares 1.9.12, you must rename any SAML group that has special characters in its name.

    Due to a security upgrade included in version 1.9.12 and later, Shares escapes special characters found in the SAML assertion, affecting SAML group IDs and names. Since the encoded version of the text does not match existing SAML group IDs or names, Shares creates new SAML groups. Shares escapes these special characters:

    Special character Encoded character
    & &
    < &lt;
    > &gt;
    " &quot;
    ' &#x27;
    / &#x2F;

    Associate newly created groups with the existing SAML groups:

    1. If needed, remove any new group that was created with an escaped, special character in its name.
    2. Modify both the SAML IDs and names of existing SAML groups to use escaped, special characters.
Shares is now running and accessible from the IP address or domain name configured during installation.
Note: If after upgrading, Shares does not load in the browser, check to see if Nginx is running on the Shares machine. If Nginx is not running, and trying to restart the service manually results in the error message below, follow the instructions in Disabling IPv6 Support in Shares to disable Nginx from listening to IPv6 ports.
nginx: [emerg] socket() [::]:80 failed (97: Address family not supported by protocol)