Skip to content

Migrating to 5.10.0

Before you begin

In this section, <OLD_IS_HOME> is the directory that the current Identity Server resides in, and <NEW_IS_HOME> is the directory that WSO2 Identity Server 5.10.0 resides in.

If you are using DB2

Move indexes to the TS32K Tablespace. The index tablespace in the IDN_OAUTH2_ACCESS_TOKEN and IDN_OAUTH2_AUTHORIZATION_CODE tables need to be moved to the existing TS32K tablespace in order to support newly added table indexes. SQLADM or DBADM authority is required in order to invoke the ADMIN_MOVE_TABLE stored procedure. You must also have the appropriate object creation authorities, including authorities to issue the SELECT statement on the source table, and to issue the INSERT statement on the target table.

Click here to see the stored procedure

Replace the <TABLE_SCHEMA_OF_IDN_OAUTH2_ACCESS_TOKEN_TABLE> and <TABLE_SCHEMA_OF_IDN_OAUTH2_AUTHORIZATION_CODE_TABLE> tags with the respective schema for the table.

CREATE BUFFERPOOL BP32K IMMEDIATE SIZE 250 AUTOMATIC PAGESIZE 32K;

CREATE LARGE TABLESPACE TS32K PAGESIZE 32K MANAGED by AUTOMATIC STORAGE BUFFERPOOL BP32K;

CALL SYSPROC.ADMIN_MOVE_TABLE(
<TABLE_SCHEMA_OF_IDN_OAUTH2_ACCESS_TOKEN_TABLE>,
'IDN_OAUTH2_ACCESS_TOKEN',
(SELECT TBSPACE FROM SYSCAT.TABLES WHERE 
TABNAME = 'IDN_OAUTH2_ACCESS_TOKEN' AND 
TABSCHEMA = <TABLE_SCHEMA_OF_IDN_OAUTH2_ACCESS_TOKEN_TABLE>),
'TS32K',
(SELECT TBSPACE FROM SYSCAT.TABLES WHERE 
TABNAME = 'IDN_OAUTH2_ACCESS_TOKEN' AND 
TABSCHEMA = <TABLE_SCHEMA_OF_IDN_OAUTH2_ACCESS_TOKEN_TABLE>),
'',
'',
'',
'',
'',
'MOVE');

CALL SYSPROC.ADMIN_MOVE_TABLE(
<TABLE_SCHEMA_OF_IDN_OAUTH2_AUTHORIZATION_CODE_TABLE>,
'IDN_OAUTH2_AUTHORIZATION_CODE',
(SELECT TBSPACE FROM SYSCAT.TABLES WHERE 
TABNAME = 'IDN_OAUTH2_AUTHORIZATION_CODE' AND 
TABSCHEMA = <TABLE_SCHEMA_OF_IDN_OAUTH2_AUTHORIZATION_CODE_TABLE>),
'TS32K',
(SELECT TBSPACE FROM SYSCAT.TABLES WHERE 
TABNAME = 'IDN_OAUTH2_AUTHORIZATION_CODE' AND 
TABSCHEMA = <TABLE_SCHEMA_OF_IDN_OAUTH2_AUTHORIZATION_CODE_TABLE>),
'',
'',
'',
'',
'',
'MOVE');

If you recieve an error due to missing SYSTOOLSPACE or SYSTOOLSTMPSPACE tablespaces, create those tablespaces manually using the following script prior to executing the stored procedure given above. For more information, see SYSTOOLSPACE and SYSTOOLSTMPSPACE table spaces in the IBM documentation.

CREATE TABLESPACE SYSTOOLSPACE IN IBMCATGROUP
  MANAGED BY AUTOMATIC STORAGE USING STOGROUP IBMSTOGROUP
  EXTENTSIZE 4;

CREATE USER TEMPORARY TABLESPACE SYSTOOLSTMPSPACE IN IBMCATGROUP
  MANAGED BY AUTOMATIC STORAGE USING STOGROUP IBMSTOGROUP
  EXTENTSIZE 4;
  1. If you have manually added any custom OSGI bundles to the <OLD_IS_HOME>/repository/components/dropins directory, copy those OSGI bundles to the <NEW_IS_HOME>/repository/components/dropins directory.

    Important

    You may need to update the custom components to work with WSO2 Identity Server 5.10.0. Refer Migrating custom components. If applicable, migrate Data Publishers and Custom Scope validators.

  2. If you have manually added any JAR files to the <OLD_IS_HOME>/repository/components/lib directory, copy and paste those JARs in the <NEW_IS_HOME>/repository/components/lib directory.

  3. Copy the .jks files from the <OLD_IS_HOME>/repository/resources/security directory and paste them in the <NEW_IS_HOME>/repository/resources/security directory.

    Note

    In WSO2 Identity Server 5.10.0, it is required to use a certificate with the RSA key size greater than 2048. If you have used a certificate that has a weak RSA key (key size less than 2048) in the previous IS version, add the following configuration to <NEW_IS_HOME>/repository/conf/deployment.toml to configure internal and primary keystores.

    [keystore.primary]
    file_name = "primary.jks"
    type = "JKS"
    password = "wso2carbon"
    alias = "wso2carbon"
    key_password = "wso2carbon"
    
    [keystore.internal]
    file_name = "internal.jks"
    type = "JKS"
    password = "wso2carbon"
    alias = "wso2carbon"
    key_password = "wso2carbon"

    Make sure to point the internal keystore to the keystore that is copied from the previous WSO2 Identity Server version. The primary keystore can be pointed to a keystore with a certificate that has a strong RSA key.

  4. If you have created tenants in the previous WSO2 Identity Server version that contain resources, copy the content from <OLD_IS_HOME>/repository/tenants directory, to the <NEW_IS_HOME>/repository/tenants directory.

  5. If you have created secondary user stores in the previous WSO2 IS version, copy the content in the <OLD_IS_HOME>/repository/deployment/server/userstores directory to the <NEW_IS_HOME>/repository/deployment/server/userstores directory.

  6. Ensure that you have migrated the configurations into the new version as advised in preparing for migration section.

  7. Migrate Log4j2 configurations.

  8. Replace the <NEW_IS_HOME>/repository/conf/email/email-admin-config.xml file with <OLD_IS_HOME>/repository/conf/email/email-admin-config.xml.

  9. Follow the steps given below to perform database updates:

    1. To download the migration resources, visit the latest release tag and download the wso2is-migration-x.x.x.zip under Assets. Unzip it to a local directory.

      Note

      • x.x.x of wso2is-migration-x.x.x.zip denotes the version number of the most recently-released migration resources.
      • The directory where the wso2is-migration-x.x.x.zip is unziped will be referred to as <IS_MIGRATION_TOOL_HOME>.
    2. Copy the org.wso2.carbon.is.migration-x.x.x.jar file in the <IS_MIGRATION_TOOL_HOME>/dropins directory into the <NEW_IS_HOME>/repository/components/dropins directory.

    3. Copy migration-resources directory to the <NEW_IS_HOME> root directory.

    4. Ensure that the property values are as follows in the <NEW_IS_HOME>/migration-resources migration-config.yaml file.

      migrationEnable: "true"
      
      currentVersion: "5.7.0"
      
      migrateVersion: "5.10.0"

      Note

      Here, the currentVersion is the current WSO2 Identity Server version that you are using.

    If you are using PostgreSQL

    During the migration, "uuid-ossp" extension is created in the database. In order to create this extension, the database user should have the 'Superuser' permission. If the user is not already a superuser, assign the permission before starting the migration.

    ALTER USER <user> WITH SUPERUSER;
  10. If you are migrating your user stores to the new user store managers with the unique ID capabilities, Follow the guidelines given in the Migrating User Store Managers before moving to the next section.

  11. Start the WSO2 Identity Server 5.10.0 with the following command to execute the migration client.

    1. Linux/Unix:

      sh wso2server.sh -Dmigrate -Dcomponent=identity
    2. Windows:

      wso2server.bat -Dmigrate -Dcomponent=identity
  12. Stop the server once the migration client execution is complete.

Executing the sync tool

Warning

Proceed with this step only if you have opted in for Zero down time migration. If not, your migration task is complete now. You can omit the following steps.

  1. Start the data sync tool with the following command pointing to the sync.properties file. This will start syncing data created in the old WSO2 Identity Server database after taking the database dump to the new WSO2 Identity Server database.

    sh wso2server.sh -DsyncData -DconfigFile=<path to sync.properties file>/sync.properties

  2. Monitor the logs in the sync tool to see how many entries are synced at a given time and to keep track of the progress in the data sync process. The following line will be printed in the logs in each table you have specified, that has no data to be synced.

    [2019-02-27 17:26:32,388]  INFO {org.wso2.is.data.sync.system.pipeline.process.BatchProcessor} -  No data to sync for: <TABLE_NAME>

    Info

    If you have some traffic to the old version of the WSO2 Identity Server, the number of entries to be synced might not become zero at any time. In that case, observe the logs to decide on a point where the number of entries that are synced is low.

  3. When the data sync is complete, switch the traffic from the old setup to the new setup.

  4. Allow the sync client to run for some time to sync the entries that were not synced before switching the deployments. When the number of entries synced by the sync tool becomes zero, stop the sync client.

Verifying the migration

After the migration is complete, proceed to the following verification steps.

  • Monitor the system health (CPU, memory usage etc).
  • Monitor the WSO2 logs to see if there are errors logged in the log files.
  • Run functional tests against the migrated deployment to verify that all the functionalies are working as expected.

If you see any problems in the migrated system, revert the traffic back to the previous setup and investigate the problem.

Top