Migration

Overview

The article describes how to migrate to the new DirX Access version.

We strongly recommend using DirX Directory backup before starting the migration process to back up current DirX Access application repository.

We strongly recommend backing up the current DirX Access installation before starting the migration process.

Basic procedure

Uninstall the DirX Access binaries with {installation_directory}/UninstallerData/ Uninstall DirX Access.exe.
Install new DirX Access binaries with DirX Access installer
- For silent installation, use the same dirxaccess.properties file with the same property values from your old installation
  - Check the Running the Installer article whether there are new properties available
- For automatic migration of application repository, set the same application repository location or the location of a copy of the existing/old application repository
Read the section Automatic migration of application repository * Read the section Advanced Information
Start DirX Access Services instance
Manual re-deployment of PEPs, FEPs and Authentication Applications

Automatic migration of application repository

The existing/old DirX Access application repository (configuration and policy data and shadow user tree) can be automatically migrated to the new version during the first startup of the first DirX Access Server instance. Automatic migration of the application repository is supported from version 8.3 and can be done directly to the intended version via the intended version, because it is done step by step between versions automatically and the latest version contains all the steps to achieve the intended state.

The migration level of the application repository is identified via several parameters. The dxaBootParameter attribute of the ou=DirX Access root node of the application repository contains:

migration.level.config parameter
- For migration level of the application repository configuration data
migration level.policy parameter
- For migration level of the application repository policy data
migration.level.apprepo parameter
- For migration level of the application repository shadow user tree

These parameters ideally contain the new version number in case the automatic migration has been successful. The parameters contain an earlier version number than the new version number in case the automatic migration failed for some reason and has been unsuccessful. The version number identifies the last successful step of the migration process. It is possible to run the migration process several times. The migration will continue from the version stated in the parameters.

The log information can be found in {installation_directory}/Services/instances /{instance}/logs/server.log. Expected messages for successful migration are:

Successful migration from version {version_number} to {version_number}{migration_level_parameter_name})

Deactivation

There is wrapper.java.additional.[X]=-Dnet.atos.dirx.access.migration.disabled=true switch to completely deactivate any migration operation. The switch has to be manually applied to all intended instances to the [installation folder]/Services/instances/[instance]/ etc/wrapper.conf file. The [X] string is a placeholder to insert the last wrapper.java.additional number of the wrapper.conf file. By default, (if the switch is missing), the switch is false.

Advanced Information

The section describes advanced information which is version- and configuration object-specific.

Cluster configuration object in version 8.9

DirX Access version 8.9 contains a new cluster configuration object for storing the configuration attributes shared by all DirX Access Services instances running in the same cluster. This feature is part of the new approach in this version which specifies that all DirX Access Services instances configured by a single Application Repository form always belong to the same cluster.

Automatic migration of the Application Repository can handle the creation of a new cluster configuration object. The new object is created from the Services configuration object whose identifier is specified in the service.config.server.id property of {installation_directory}/Services/instances /{instance}/etc/dirxaccess.properties file.

Single Container since version 9.0.1

Version 9.0 contains a major architectural change - shift from two types of containers (Services and WebApplications) to a single type (Services) containing all the functionality.

Corresponding configuration structure has been changed having two effects:

The automated migration takes care of the translation of the configuration parameters from the older versions to the new configuration structure, if possible.
Parameters without further meaning in the new version are removed without replacement.

All the applications deployed originally in the WebApplications container have to be redeployed in the Services container. Due to the single-container architecture, this action is simpler as corresponding files are copied only within the DirX Access installation folder. The web applications can be deployed at the same ports as previously in the WebApplications container. As this container could have been on a different server, the ports configuration shall be reviewed.

Migration of Callouts for version 9.0.1

Version 9.0 is following the path towards the clearly defined internal Java interface. From this reason, the Callout interfaces have changed their package names. All package names are now written in respective sections in the Integration Guide.

However, this change has its implications on the migration process. Namely, all references at the configured callouts are automatically removed from the configuration. Not doing so might lead to an impossibility of the start of the DirX Access Services container.

Mainly, before the start of the services container, any third-party plug-in modules added according to the description in the Employing External Plug-in Modules section of the Integration Guide shall be removed and re-built against the new interfaces.

Carving out the Distributed Cache in version 9.1

Version 9.1 contains a major architectural change – carving out the originally embedded distributed cache and persistence service into the DirX Access Cache Server component. This makes the DirX Access Server itself more robust and stable and drives it towards the microservices architecture. Any upgrade or patching is also simplified.