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:
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.
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:
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.
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:
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.
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 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:
Log in to SSPR portal as an administrator.
In top-right corner of the page, click Configuration Manager from the drop-down menu.
Click LocalDB.
Click Download LocalDB.
IMPORTANT:The upgrade process may take time depending on the size of the database. Therefore, plan your upgrade accordingly.
Stop the PostgreSQL service that is running on your server.
Rename the postgres directory.
Linux: /opt/netiq/idm/apps
Windows: C:\Netiq\IdentityManager\apps
For example, rename postgres to postgresql_9_3.
Install PostgreSQL version supported on your operating system.
You must choose a location other than the current installation location of PostgreSQL.
Mount the Identity_Applications_version_platform.iso image file and navigate to the products/RBPM/postgre_tomcat_install directory containing the PostgreSQL installation files.
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.
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.
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:
Go to Control Panel > User Accounts > User Accounts > Manage Accounts.
Click Add a user account.
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:
Right click the PostgreSQL directory and go to Properties > Security > Edit.
Select Full Control for the user to provide complete permissions.
Click Apply.
Access the PostgreSQL directory as postgres user.
Linux: Perform the following actions:
Switch to postgres user by using the following command:
su - postgres
Change the directory to postgres/bin directory.
Export the installed PostgreSQL location using the following command:
export PATH=/opt/netiq/idm/apps/postgres/bin:$PATH
Export the PostgreSQL password using the following command:
export PGPASSWORD=<enter the database password>
Windows: Perform the following actions:
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.
Open a command prompt and set PGPASSWORD by using the following command:
set PGPASSWORD=<your pg password>
Change to the newly installed PostgreSQL directory.
For example: C:\Users\postgres>cd C:\NetIQ\IdentityManager\apps1\postgresql962\bin.
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.
If the upgrade fails on Linux and reports cannot write to log file pg_upgrade_internal.log error message, run the upgrade command from a directory that is writable by postgres user. For example, /tmp.
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.
Disable the old PostgreSQL service to ensure that the service does not automatically start.
(Optional) Delete the old data files from the bin directory of the newly installed PostgreSQL service.
Linux: Perform the following actions:
Switch to postgres user and run analyze_new_cluster.sh.
su - postgres
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:
Login as postgres user.
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.
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.
Stop the Tomcat service.
/etc/init.d/idmapps_tomcat_init stop
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.
Run the Identity Applications upgrade program. See, Using the Guided Process to Upgrade or Silently Upgrading the Identity Manager Applications.
After upgrading identity applications restore the WAR files to your original context name. For more information, see Identity Applications.
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.
This section describes the guided process for upgrading the identity applications components.
Log in as a root or administrative user to the server where you want to run upgrade process.
Mount the Identity_Applications.iso image file, navigate to the directory containing the upgrade executable, located by default in the products/RBPM/ directory.
Launch the upgrade program. Execute one of the following files depending on your platform:
Linux: RBPM_upgrade.bin
Windows: RBPM_upgrade.exe
On the Introduction page, you can view Identity Manager components that you can upgrade, then click Next.
Read and accept the license agreement, then click Next.
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.
To proceed with the upgrade, click Next.
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.
Represents the platform of the User Application database.
Specifies the name or IP address of the server that hosts the User Application.
Specifies the port that the database server uses for communication with the User Application.
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
Specifies the name of the database. By default, the database name is idmuserappdb.
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.
Specifies the password for the specified username.
Upgrade Database
The upgrade program updates the schema for the database tables as part of the upgrade process.
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.
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 Manually Creating the Database Schema.
Database Administrator
Represents the name and password for the database administrator.
Specifies the account for a database administrator that can create database tables, views, and other artifacts.
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
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.
When the upgrade process completes, review the upgrade log files from /tmp/rbpm_upgrade/and you need to update few configurations manually, see Post-Upgrade Tasks.
A silent (non-interactive) installation does not display a user interface.
Login as a root user or administrator where you want to upgrade Identity Manager applications.
Open a terminal session.
Specify the values for installation in the properties file.
Linux: products/RBPM/RBPM_Upgrade_Linux.properties
Windows: products\RBPM\RBPM_Upgrade_Win.properties
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.
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:
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.
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
Verify JRE home location.
Linux: tomcat/bin/setenv.sh
Windows: tomcat/bin/setenv.bat
Launch Configuration Update utility and verify the path of your cacerts.
(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.
(Conditional) Navigate to the User Application and restore the customized settings manually by reading the backed-up configuration.
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 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:
Navigate to the User Application directory located in /opt/netiq/idm/apps/UserApplication.
(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
Launch the configupdate utility.
Linux: configupdate.sh
Windows: configupdate.bat
In User Application tab, click Show Advanced Options and perform the following steps:
Check Change RBPM Context Name check box.
Change the RBPM context name to the original context name.
Browse and select the appropriate Roles Driver DN and click OK.
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
(Conditional) If you have completed all the post-upgrade tasks, then start the Tomcat service for Identity Applications.
If OSP and User Applications are deployed on different servers, then update the SSO client parameter using Configuration Update Utility. For more information, see IDM Dashboard in the 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.
After upgrading SSPR, update SSO client parameter using Configuration Update Utility. For more information, see Self Service Password Reset in the SSO Clients Parameters.
To update the SSPR configuration details, perform the following steps:
Log in to SSPR portal as an administrator.
Update the audit server details:
Navigate to Configuration Editor, specify the configuration password.
Select Settings > Auditing > Audit Forwarding > Syslog Audit Server Certificates.
Import these certificates from the sever and click Save.
Import the LocalDB into SSPR:
In top-right corner for the page, click Configuration Manager from the drop-down menu.
Click LocalDB.
Click Import (Upload) LocalDB Archive File.
Configure administrator permissions for SSPR, see 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.