Pre-upgrade tasks and considerations

This topic will help you make pre-upgrade decisions and complete any required pre-upgrade tasks.

General considerations

During any upgrade, schema changes will be required. Ensure that appropriate planning and precautions have taken place before upgrading. In particular, ensure that you have:

  • Permission to perform a schema change.
  • The latest backups of the data store and configuration files.
  • Interrupted replication on the OneSpan Authentication Serverinstance to be upgraded.
  • Interrupted replication on any OneSpan Authentication Server instances which replicate TO the instance to be upgraded.
  • Successfully completed any previous upgrade, including data migration.

Before initializing the upgrade process, ensure that you have successfully completed any previous upgrade and migrated all data. If the data migration has not been successfully completed, the upgrade installation process will be canceled, and the following error message will be displayed: "The installation procedure has been canceled - data migration from the previous upgrade has not been completed. Please finish migrating the data from the previous to the currently installed version of OneSpan Authentication Server before proceeding with this upgrade!"

Once the upgrade starts, it cannot be rolled back. In addition, the upgrade script only supports upgrades from completely installed and completely configured instances of OneSpan Authentication Server.

Ensure that your data store and configuration files are backed up before starting the upgrade process.

Licenses for a previous version of OneSpan Authentication Server will be valid for this release. Therefore, you can upgrade without loading a new license key.

Administrative privileges

To perform an installation/upgrade you must be logged on using a built-in administrator on the system where OneSpan Authentication Server is to be installed. A normal user ID with administrator privileges is not sufficient.

Verifying system requirements

Ensure that your host machine complies with the system requirements for this release of OneSpan Authentication Server (see System requirements).

If required, perform a distribution upgrade before upgrading OneSpan Authentication Server.

Database setup

If you are upgrading an installation of OneSpan Authentication Server that does not use the embedded MariaDB package, you need to prepare the database manually.

When upgrading an instance of OneSpan Authentication Server that uses the embedded MariaDB database server with database encryption enabled, the data-at-rest encryption key and certificate files will not be deleted and still be used after the upgrade.

Replication and upgrades

If the OneSpan Authentication Server instance to be upgraded has replication enabled, you will need to break replication both to and from that instance before upgrading.

It is recommended that you break the replication at the network level using the system firewall.

Do not disable the replication on the servers. Do not remove the replication configuration from the server. Otherwise, replication messages are omitted, leaving the server databases not synchronized and in different states!

Global server settings

In environments where OneSpan Authentication Server uses ODBC as data store, the global server settings are stored in the database with a creation time, i.e. the date and time of the installation. If a new version of OneSpan Authentication Server introduces new global server settings, the new settings are also stored with a creation time, in this case the date and time of the upgrade.

Replication requires fully synchronous databases, i.e. records need to have the same creation time; even the same records will not be replicated if their creation time differs!

If the OneSpan Authentication Server instance is part of a replication environment where each instance has its own ODBC database, the newly created global server settings will have different creation times set on each instance, since you will update each instance at different times. This means that global server settings introduced with a new version will NOT be replicated in the future if their creation time differs on each OneSpan Authentication Server instance.

For instance, OneSpan Authentication Server 3.8 introduces Message Delivery Component (MDC) message settings as global server settings:

  • If you upgrade an existing single installation, the current message settings are migrated from the local server configuration file to the global server settings in the database.
  • If you upgrade several OneSpan Authentication Server instances within a replicated environment where each instance has its own ODBC database, each instance migrates its own message settings to its global server settings without replicating it to the other instances during the upgrade; this means that the global configuration settings of each instance may differ from each other after an upgrade.
  • If you upgrade several OneSpan Authentication Server instances within a replicated environment where all instances use the same ODBC database, only the MDC message settings from the first instance are migrated to the global server settings and are not overwritten when upgrading the other instances.

For more information about replication, refer to the OneSpan Authentication Server Administrator Guide, Section "Replication".

Rolling upgrades

A rolling upgrade involves upgrading multiple OneSpan Authentication Server instances while keeping the authentication service alive. Environments that require a rolling upgrade typically support high-availability services, where the authentication service absolutely cannot be taken offline.

An environment that requires a rolling upgrade typically has the following characteristics:

  • There are multiple instances of OneSpan Authentication Server running on multiple servers.
  • All OneSpan Authentication Server instances either use the same database as their data store, or each one instance has its own data store.
  • The OneSpan Authentication Server upgrades involved will require a database schema update.
  • User load distribution between all OneSpan Authentication Server instances is managed by a third-party application.

Rolling upgrades are only supported for deployments where each OneSpan Authentication Server instance uses an ODBC data store.

Before proceeding with a rolling upgrade, you must first address the different usability and load management issues involved. For more information, refer to the OneSpan Authentication Server Administrator Guide.

RADIUS backup

If you modified the RADIUS dictionary, you will need to back up the RADIUS dictionary file (radius.dct) before upgrading OneSpan Authentication Server. To do so, copy the file to a different location and return it after completing the upgrade. This file is typically located (and should be restored) here:

/etc/vasco/ias