55.5 Upgrading Identity Applications and Supporting Components

This section provides information about upgrading Identity Applications and supporting software, which includes updating the following components:

  • Identity Manager User Application

  • One SSO Provider (OSP)

  • Self-Service Password Reset (SSPR)

  • Tomcat, JDK, and ActiveMQ

NetIQ provides an upgrade program to upgrade these components. This program is located in the products/RBPM/ directory in the Identity Manager installation package. Navigate to the directory that contains following upgrade files:

  • Linux: RBPM_upgrade.bin

  • Windows: RBPM_upgrade.exe

You can run the upgrade program only in GUI and in the silent mode. Console mode is not supported.

The upgrade program updates the components to the following versions:

  • Tomcat – 8.5.9

  • ActiveMQ – 5.14

  • Java – 1.80_112

  • One SSO Provider – 6.1.3

  • Self-Service Password Reset – 4.1.0.0

This section provides information about the following topics:

55.5.1 Understanding the Upgrade Program

The upgrade process reads the configuration values from the existing components. This information includes ism-configuration.properties, server.xml, SSPRConfiguration, and other configuration files. The upgrade process uses these configuration files and internally invokes the upgrade program. The process also creates a backup of the current installation.

55.5.2 Prerequisites and Considerations for Upgrade

Before performing an upgrade, review the following considerations:

  • Identity Manager is upgraded to version 4.5.5: You cannot upgrade or migrate to version 4.6 from versions lesser than 4.5.5. For more information about how to upgrade to Identity Manager 4.5, see Upgrading Identity Manager in the NetIQ Identity Manager Setup Guide.

  • System Requirements: The upgrade process requires at least 3 GB free disk space for storing the current configuration and the temporary files that are created during upgrade. Ensure that your server has sufficient space to store the back-up and additional free space available for upgrade.

    On a Linux server, if you have installed the identity applications in a separate partition other than the root partition, ensure that the partition has sufficient space to store the backup configuration. Also, ensure that /tmp directory has enough space for storing the logs and temporary files. If this directory does not have the required space, set IATEMPDIR environment variable to a directory on a partition that has sufficient free space. This will redirect the upgrade program to store the files in that directory.

    To set IATEMPDIR to a directory:

    1. Open a terminal and enter the following command:

      export IATEMPDIR=/opt/custom_tmp 

      where /opt/custom_tmp is the path to the directory that has sufficient free disk space.

    2. Start the upgrade program from the command line.

    On a Windows server, the upgrade program stores the temporary files in a directory specified in the %TEMP% environment variable. If this directory does not have the required space, set TEMP and TMP environment variables to a directory on your file system that has sufficient free space. This will redirect the upgrade program to store the files in that directory.

    To set these environment variables to a different directory, complete the following steps before starting the upgrade:

    1. Open the command prompt and enter the following command:

                      SET TMP=D:\custom_tmp
                      SET TEMP=D:\custom_tmp

      where D:\custom_tmp is the path to the directory that has sufficient free disk space.

    2. Start the upgrade program from the command line.

  • Tomcat as an application server: This version of Identity Manager supports only Tomcat as an application server.

    NOTE:Ensure you have installed Tomcat application server using the convenience installer during Identity Manager 4.5 installation. The upgrade process allows you to upgrade only Tomcat that has been installed using the convenience installer.

    If you are running your identity applications on an application server other than Tomcat, migrate the application server to Tomcat. For more information, see Section 59.6, Migrating from Websphere or JBoss to Tomcat Web Application Server.

  • Database platform is upgraded: This program does not upgrade the database platform for the identity applications. Manually upgrade your current version of the database to a supported version. For upgrading the PostgreSQL database, see Upgrading the PostgreSQL Database.

  • Roles and Resource Service driver package is upgraded: For more information, see Upgrading Installed Packages in the NetIQ Designer for Identity Manager Administration Guide.

  • User Application context name is set to the default name: If you have configured User Application’s context name other than default IDMProv, change the context name. For more information, see Changing the Custom Context Name for User Application.

  • Self Service Password Reset: If you are upgrading from SSPR 4.0, ensure you have updated CATALINA_OPTS property and -Dsspr.application.Path is set to the folder where your SSPR configuration is stored.

    For example,

    Linux: export CATALINA_OPTS="-Dsspr.applicationPath=/home/sspr_data

    Windows: set CATALINA_OPTS="-Dsspr.applicationPath=C:\sspr_data

    Backup your SSPR LocalDB before upgrading. To export or download LocalDB, perform the following steps:

    1. Log in to SSPR portal as an administrator.

    2. In top-right corner for the page, click Configuration Manager from the drop-down menu.

    3. Click LocalDB.

    4. Click Download LocalDB.

55.5.3 Upgrading the PostgreSQL Database

IMPORTANT:The upgrade process may take time depending on the size of the database. Therefore, plan your upgrade accordingly.

  1. Stop the PostgreSQL service that is running on your server.

  2. Rename the postgres directory.

    Linux: /opt/netiq/idm/apps

    Windows: C:\Netiq\IdentityManager\apps

    For example, rename postgres to postgresql_9_3.

  3. Install PostgreSQL version supported on your operating system.

    You must choose a location other than the current installation location of PostgreSQL.

    1. Mount the Identity_Applications_version_platform.iso image file and navigate to the products/RBPM/postgre_tomcat_install directory containing the PostgreSQL installation files.

    2. Install the PostgreSQL application.

      • Linux (GUI): Run ./TomcatPostgreSQL.bin

      • Linux (Console): Run ./TomcatPostgreSQL.bin -i console

      • Windows: Run TomcatPostgreSQL.exe

      Select only PostgreSQL option during installation.

    NOTE:Do not provide any database details in PostgreSQL details page. Ensure that Create database login account and Create empty database are deselected.

  4. Stop the newly installed PostgreSQL service.

    • Linux (SLES 12 SP1 or later and RHEL 7.x or later): Run the systemctl stop postgresql-9.6.service command.

    • Linux (SLES 11 SP4 or later): Run the /etc/init.d/postgresql-9.x stop command.

    • RHEL 6.x or Later: Run the /etc/init.d/postgresql-9.6 stop command.

    • Windows: Go to Services, search for PostgreSQL 9.6 service, and stop the service.

      NOTE:Appropriate user can perform stop operations after providing valid authentication.

  5. Change the permissions for the newly installed PostgreSQL directory.

    • Linux: Run the following command:

      chown -R postgres:postgres <postgres directory path>

      For example,

      chown -R postgres:postgres /opt/netiq/idm/apps/postgres

    • Windows: Perform the following actions:

      To create a postgres user:

      1. Go to Control Panel > User Accounts > User Accounts > Manage Accounts.

      2. Click Add a user account.

      3. In the Add a User page, specify postgres as the user name and provide a password for the user.

      To provide permissions to postgres user to the existing and newly installed PostgreSQL directories:

      1. Right click the PostgreSQL directory and go to Properties > Security > Edit.

      2. Select Full Control for the user to provide complete permissions.

      3. Click Apply.

  6. Access the PostgreSQL directory as postgres user.

    • Linux: Perform the following actions:

      1. Switch to postgres user by using the following command:

        su - postgres

      2. Change the directory to postgres/bin directory.

      3. Export the installed PostgreSQL location using the following command:

        export PATH=/opt/netiq/idm/apps/postgres/bin:$PATH

      4. Export the PostgreSQL password using the following command:

        export PGPASSWORD=<enter the database password>

    • Windows: Perform the following actions:

      1. Login to the server as postgres user.

        Before logging in, make sure that postgres can connect to the Windows server by verifying if a remote connection is allowed for this user.

      2. Open a command prompt and set PGPASSWORD by using the following command:

        set PGPASSWORD=<your pg password>
      3. Change to the newly installed PostgreSQL directory.

        For example: C:\Users\postgres>cd C:\NetIQ\IdentityManager\apps1\postgresql962\bin.

  7. Upgrade PostgreSQL from new PostgreSQL bin directory.

    • Linux: Run the following command.

      pg_upgrade --old-datadir <old_postgres_location\data> --new-datadir <new_postgres_location\data> --old-bindir <old_postgres_location\bin> --new-bindir <new_postgres_location\bin>

      For example, ./pg_upgrade --old-datadir /opt/netiq/idm/apps/postgresql_9_3/data/ --new-datadir /opt/netiq/idm/apps/postgres/data/ --old-bindir /opt/netiq/idm/apps/postgresql_9_3/bin --new-bindir /opt/netiq/idm/apps/postgres/bin/

      After a successful upgrade, it displays the message to run analyze_new_cluster.sh and delete_old_cluster.sh.

    • Windows: Run the following command and click Enter:

      pg_upgrade.exe --old-datadir "C:\NetIQ\IdentityManager\apps1\postgres\data" --new-datadir "C:\NetIQ\IdentityManager\apps1\postgresql962\data" --old-bindir "C:\NetIQ\IdentityManager\apps1\postgres\bin" --new-bindir "C:\NetIQ\IdentityManager\apps1\postgresql962\bin"

      If the upgrade is successful on Linux, you will see messages similar to the below in the command prompt.

      Performing Consistency Checks
      -----------------------------
      Checking cluster versions                                     ok
      Checking database user is the install user                    ok
      Checking database connection settings                         ok
      Checking for prepared transactions                            ok
      Checking for reg* system OID user data types                  ok
      Checking for contrib/isn with bigint-passing mismatch         ok
      Creating dump of global objects                               ok
      Creating dump of database schemas                             ok
      Checking for presence of required libraries                   ok
      Checking database user is the install user                    ok
      Checking for prepared transactions                            ok
      
      If pg_upgrade fails after this point, you must re-initdb the new cluster before continuing.
      
      Performing Upgrade
      ------------------
      Analyzing all rows in the new cluster                         ok
      Freezing all rows on the new cluster                          ok
      Deleting files from new pg_clog                               ok
      Copying old pg_clog to new server                             ok
      Setting next transaction ID and epoch for new cluster         ok
      Deleting files from new pg_multixact/offsets                  ok
      Copying old pg_multixact/offsets to new server                ok
      Deleting files from new pg_multixact/members                  ok
      Copying old pg_multixact/members to new server                ok
      Setting next multixact ID and offset for new cluster          ok
      Resetting WAL archives                                        ok
      Setting frozenxid and minmxid counters in new cluster         ok
      Restoring global objects in the new cluster                   ok
      Restoring database schemas in the new cluster                 ok
      Copying user relation files                                   ok
      Setting next OID for new cluster                              ok
      Sync data directory to disk                                   ok
      Creating script to analyze new cluster                        ok
      Creating script to delete old cluster                         ok
      
      Upgrade Complete
      ----------------
      Optimizer statistics are not transferred by pg_upgrade so,
      once you start the new server, consider running:
          analyze_new_cluster.sh
      
      Running this script will delete the old cluster's data files:
          delete_old_cluster.sh

      You should see similar messages for Windows.

  8. Start the upgraded PostgreSQL database service.

    • Linux (SLES 12 SP1 or later or RHEL 7.x or later): Run the systemctl start postgresql-9.6.service command.

    • Linux (SLES 11 SP4 or later): Run the /etc/init.d/postgresql-9.x start command.

    • RHEL 6.x or Later: Run the /etc/init.d/postgresql-9.6 start command.

    • Windows: Go to Services, search for PostgreSQL 9.6 service, and start the service.

      NOTE:Appropriate user can perform start operations after providing valid authentication.

  9. Disable the old PostgreSQL service to ensure that the service does not automatically start.

  10. (Optional) Delete the old data files from the bin directory of the newly installed PostgreSQL service.

    • Linux: Perform the following actions:

      1. Switch to postgres user and run analyze_new_cluster.sh.

        su - postgres
      2. Navigate to /opt/netiq/idm/apps/postgres/bin and run the following scripts:

        • ./analyze_new_cluster.sh

        • ./delete_old_cluster.sh

        Ensure that scripts are executed without errors.

    • Windows: Perform the following actions:

      1. Login as postgres user.

      2. Navigate to the bin directory and run analyze_new_cluster.bat and delete_old_cluster.bat files.

        For example: C:\NetIQ\IdentityManager\apps1\postgresql961\bin

    NOTE:You must run this step only if you want to delete the old data files.

55.5.4 Changing the Custom Context Name for User Application

If you specified User Application’s context name other than the default IDMProv, complete the following steps to change the context name to the default context name IDMProv:

NOTE:You can verify the context name in portal.context property of ism-configuration.properties file.

  1. Stop the Tomcat service.

    /etc/init.d/idmapps_tomcat_init stop
  2. Navigate to webapps folder and rename the folder which has non-default context name to IDMProv.

    Linux: /opt/netiq/idm/apps/tomcat/webapps

    Windows: C:\Netiq\IdentityManager\apps\tomcat\webapps

    For example, if the portal.context name in the ism-configuration.properties file is IDMDev, then change the folder name from IDMDev to IDMProv.

  3. Run the Identity Applications upgrade program. See, Section 55.5.6, Using the Guided Process to Upgrade or Section 55.5.7, Silently Upgrading the Identity Manager Applications.

  4. After upgrading identity applications restore the WAR files to your original context name. For more information, see Identity Applications.

55.5.5 System Requirements

The upgrade process creates a back-up of the current configuration for the installed components. Ensure that your server has sufficient space to store the back-up and additional free space available for upgrade.

55.5.6 Using the Guided Process to Upgrade

This section describes the guided process for upgrading the identity applications components.

  1. Log in as a root or administrative user to the server where you want to run upgrade process.

  2. Mount the Identity_Applications.iso image file, navigate to the directory containing the upgrade executable, located by default in the products/RBPM/ directory.

  3. Launch the upgrade program. Execute one of the following files depending on your platform:

    • Linux: RBPM_upgrade.bin

    • Windows: RBPM_upgrade.exe

  4. On the Introduction page, you can view Identity Manager components that you can upgrade, then click Next.

  5. Read and accept the license agreement, then click Next.

  6. Review the Deployed Applications page, then click Next.

    This page lists the currently installed components. It also lists the version and installation directories of Tomcat and JRE. If other applications are deployed on the server, the upgrade process displays a warning that those applications might not work properly after the upgrade.

    For example, Identity Reporting or user-defined war files. You must restore them manually from the back-up created by the upgrade process.

  7. To proceed with the upgrade, click Next.

  8. Complete the guided process, using the following parameters. This program autopopulates the values for existing components. Ensure that the correct values are specified for the parameters.

    • One SSO Provider

      Represents the path to a directory where the upgrade program creates the application files for OSP. If the path is not correct, browse to the path where OSP is installed.

    • SSPR

      Represents the path to a directory where the upgrade program creates the application files for SSPR. If the path is not correct, browse to the path where SSPR is installed.

    • User Application

      Represents the path to a directory where the upgrade program creates the application files for the User Application. If the path is not correct, browse to the path where User Application is installed.

    • Database Connection

      Represents the settings for connecting to the User Application database, Identity Applications also connects to this database. The upgrade program includes these details in the User Application configuration file.

      Database Platform

      Represents the platform of the User Application database.

      Database Host

      Specifies the name or IP address of the server that hosts the User Application.

      Database Port

      Specifies the port that the database server uses for communication with the User Application.

      Database Driver JAR

      Specifies jar file for the database platform.

      The database vendor provides the driver JAR file, which represents the jar for the database server. For example, for PostgreSQL, you might specify postgresql-9.4-1212.jdbc42.jar, by default in the /opt/netiq/idm/apps/postgres folder on Linux and C:\netiq\idm\apps\postgres on Windows. Similarly, specify the appropriate jar files for your database platform.

    • Database Credentials

      Database Name

      Specifies the name of the database. By default, the database name is idmuserappdb.

      Database Username

      Specifies the name of an account that allows the User Application to access and modify data in the databases. By default, the database username is idmadmin.

      Database Password

      Specifies the password for the specified username.

    • Upgrade Database

      Upgrade Database Now

      The upgrade program updates the schema for the database tables as part of the upgrade process.

      Upgrade Database at Application Startup

      The upgrade program leaves instructions to update the schema for the database tables when the User Application starts for the first time after the upgrade.

      Write SQL to File

      Generates a SQL script that the database administrator can run to update the databases. If you choose this option, you must also specify a name for Schema File. The setting is in the SQL Output File configuration.You might select this option if you do not have permissions to create or modify a database in your environment. For more information about generating the tables with the file, see Section 39.2, Manually Creating the Database Schema.

    • Database Administrator

      Represents the name and password for the database administrator.

      Database Username

      Specifies the account for a database administrator that can create database tables, views, and other artifacts.

      Password

      Specifies the password for the database administrator.

    • Backup Folder

      Depending on where you installed the components, the process creates the backup directory in that location and appends a time stamp (indicating the time of backup) to the backed-up directory.

      For example,

      • Tomcat – /opt/netiq/idm/apps/tomcat_backup_02262017_033634

      • OSP and SSPR - /opt/netiq/idm/apps/osp_sspr_backup_02262017_033634

      • ActiveMQ - /opt/netiq/idm/apps/activemq_backup_02262017_033634

      • User Application - /opt/netiq/idm/apps/UserApplication_backup_02262017_033634

  9. Review the Pre-Upgrade Summary page, then click Install.

    The upgrade process stops the Tomcat service and starts the upgrade, which might take some time to complete.

  10. When the upgrade process completes, review the upgrade log files from /tmp/rbpm_upgrade/and you need to update few configurations manually, see Section 55.5.8, Post-Upgrade Tasks.

55.5.7 Silently Upgrading the Identity Manager Applications

A silent (non-interactive) installation does not display a user interface.

  1. Login as a root user or administrator where you want to upgrade Identity Manager applications.

  2. Open a terminal session.

  3. Specify the values for installation in the properties file.

    • Linux: products/RBPM/RBPM_Upgrade_Linux.properties

    • Windows: products\RBPM\RBPM_Upgrade_Win.properties

  4. To launch the upgrade program for your platform, enter the following command:

    • Linux: RBPM_Upgrade.bin -i silent -f RBPM_Upgrade_Linux.properties

    • Windows: RBPM_Upgrade.exe -i silent -f RBPM_Upgrade_Win.properties

    NOTE:If the RBPM_Upgrade_Linux.properties file is in a different directory from the installer script, you must specify the absolute path to the file. The script unpacks the necessary files to a temporary directory and then launches the silent installation.

55.5.8 Post-Upgrade Tasks

After completing the upgrade, you must restore the customized settings for Tomcat, SSPR, OSP, or Identity Applications, manually.

Perform the post-upgrade steps for the required components:

Java

Verify the certificates in newly upgrade JRE location: jre/lib/security/cacerts with your older JRE location. Manually import the missed certificates into your cacerts.

  1. Import java cacerts using keytool command:

    keytool -import -trustcacerts -file Cerificate_Path -alias ALIAS_NAME -keystore cacerts

    NOTE:After upgrade, JRE is stored in the identity applications install location. For example: /opt/netiq/idm/apps/jre

  2. Verify JRE home location.

    Linux: tomcat/bin/setenv.sh

    Windows: tomcat/bin/setenv.bat

  3. Launch Configuration Update utility and verify the path of your cacerts.

Tomcat

  1. (Conditional) To restore the customized files from the backup taken earlier by the upgrade process, perform the following tasks:

    • Restore customized https certificates. To restore these certificates, copy the Java Secure Socket Extension (JSSE) contents from the backed up server.xml to the new server.xml file in the /tomcat/conf directory.

    • Do not copy the configuration files from the backed-up Tomcat directory to the new Tomcat directory. Start with the default configuration of the new version and make changes as needed. For more information, see this Apache Website.

      Verify that new server.xml file has the following entries:

      <Connector port="8543" protocol="HTTP/1.1" 
             maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
             clientAuth="false" sslProtocol="TLS" 
             keystoreFile="path_to_keystore_file"
             keystorePass="keystore_password" />

      or

      <Connector port="8543" protocol="org.apache.coyote.http11.Http11NioProtocol" 
             maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
             clientAuth="false" sslProtocol="TLS" 
             keystoreFile="path_to_keystore_file"
             keystorePass="keystore_password" />
    • If you have customized keystore files, include the correct path in the new server.xml file.

  2. (Conditional) Navigate to the User Application and restore the customized settings manually by reading the backed-up configuration.

Identity Applications

Restore the customized identity applications configurations from the backup taken during the upgrade process.

Manually create the compound indexes for each attribute that you want to use to sort users in Identity Manager Dashboard, see Section 37.4.5, Creating Compound Indexes.

If you have renamed the custom context folder name to IDMProv before running the upgrade program, you should change the context folder name to original context name using configupdate utility. For example, the original custom context name is IDMDev and it is renamed to IDMProv.

Complete the following steps to change the context name back to the original context name:

  1. Navigate to the User Application directory located in /opt/netiq/idm/apps/UserApplication.

  2. (Optional) To launch the configupdate utility in GUI mode, ensure that the use_console option is set to false in configupdate.sh.properties or configupdate.bat.properties file.

    This step is required because the upgrade utility changes the value of this option to true.

    Alternatively, launch the configupdate utility and pass an additional command line argument on Linux.

    ./configupdate.sh use_console=false
  3. Launch the configupdate utility.

    Linux: configupdate.sh

    Windows: configupdate.bat

  4. In User Application tab, click Show Advanced Options and perform the following steps:

    1. Check Change RBPM Context Name check box.

    2. Change the RBPM context name to the original context name.

    3. Browse and select the appropriate Roles Driver DN and click OK.

    4. Change the permission and ownership of the WAR file using the following command.

      chmod 755 <Original_Context_Name>.war; chown -R novlua:novlua <Original_Context_Name>.war

      For example, if the original custom context name is IDMDev:

      chmod 755 IDMDev.war; chown -R novlua:novlua IDMDev.war
  5. (Conditional) If you have completed all the post-upgrade tasks, then start the Tomcat service for Identity Applications.

One SSO Provider

If OSP and User Applications are deployed on different servers, then update the SSO client parameter using Configuration Update Utility. For more information, see Section 40.4.3, IDM Dashboard in the Section 40.4, SSO Clients Parameters.

By default, the LogHost entry located at /etc/logevent.conf file is set to localhost.

To modify the LogHost entry, manually restore the customized OSP configurations from the backup taken during the upgrade process.

Self-Service Password Reset

After upgrading SSPR, update SSO client parameter using Configuration Update Utility. For more information, see Section 40.4.8, Self Service Password Reset in the Section 40.4, SSO Clients Parameters.

To update the SSPR configuration details, perform the following steps:

  1. Log in to SSPR portal as an administrator.

  2. Update the audit server details:

    1. Navigate to Configuration Editor, specify the configuration password.

    2. Select Settings > Auditing > Audit Forwarding > Syslog Audit Server Certificates.

    3. Import these certificates from the sever and click Save.

  3. Import the LocalDB into SSPR:

    1. In top-right corner for the page, click Configuration Manager from the drop-down menu.

    2. Click LocalDB.

    3. Click Import (Upload) LocalDB Archive File.

  4. Configure administrator permissions for SSPR, see Section 32.3, Post-Installation Tasks

    NOTE:If you are upgrading from SSPR 4.0 to SSPR 4.1, the customized location of SSPR configurations is changed to the default location of SSPR 4.1. You can find additional information about the configuration locations in the setenv.sh file. However, this change does not affect the behavior of the components.

    For example, if the pre-upgrade of SSPR configuration is -Dsspr.applicationPath='/home/sspr-data, then after the upgrade, the path changes to -Dsspr.applicationPath=/opt/netiq/idm/apps/osp_sspr/sspr/sspr_data and restores all the associated configurations in this location.

To verify that the upgrade is successful, launch the upgraded components.

For example, launch Identity Manager Dashboard, click About. Check whether the application displays the new version, such as 4.6.0.