12.3 Upgrading Procedure for Identity Governance

The following upgrade procedures contain steps on how to upgrade Identity Governance and the components you have installed. Some of the steps are conditional depending on your deployment and the configuration of the different components.

12.3.1 Upgrading Identity Governance Framework Components

NetIQ provides scripts to help you upgrade the required components you installed for Identity Governance. One script scans your installations of Tomcat, ActiveMQ, Java, and PostgreSQL to determine which of those components require updates for the Identity Governance upgrade. The second script helps you upgrade those components, if needed, and leave your existing files intact and disabled.

If you run Identity Governance in a clustered environment, and if you installed components on multiple nodes, you must run the scripts on each of those nodes.

NOTE:These scripts help you upgrade only the framework components installed for Identity Governance. After you upgrade the components, you must then upgrade Identity Governance and Identity Reporting (if applicable).

Download the one of the following appropriate component upgrade scripts for your operating system from the Identity Governance documentation page under the Reference heading:

  • Identity Governance Component Upgrade Scripts - Linux

  • Identity Governance Component Upgrade Scripts - Windows

NOTE:The upgrade component script for Linux does not upgrade PostgreSQL, so you must do so manually. For more information, see Upgrading PostgreSQL for Linux.

Running the Version Compare Script

The version compare script scans your installations of Tomcat, ActiveMQ, Java, and PostgreSQL to determine which of those components require updates for the Identity Governance upgrade.

To run the version compare script:

  1. From a Linux command line or a Windows PowerShell command line, execute the script.

    • Linux: versions.sh

    • Windows: versions.ps1

  2. Provide the path of the component, if different from the default path. The script then:

    • Verifies the component path provided contains files and directories expected for that component.

    • Retrieves the component version for your setup.

    • Compares the installed component version with the required version.

    • Provides feedback for whether you should upgrade the component.

    • Repeats the process for the next component.

Downloading the Identity Governance Components

After you run the version compare script, create a compressed directory in the directory where you stored and unzipped the component upgrade scripts, and then copy the component updates that the script identified as needed.

  • For a Linux installation, download *tar.gz files to /Downloads/idgov-core-upgrader-master/linux/compressed.

  • For a Windows installation, download *.zip files to \Downloads\idgov-core-upgrader-master\windows\compressed.

Running the Upgrade Component Script

The upgrade component script upgrades Tomcat, ActiveMQ, and Java on Linux, and upgrades Tomcat, ActiveMQ, Java, and PostgreSQL on Windows.

NOTE:The upgrade component script does not upgrade your database if:

  • You use Oracle or Microsoft SQL Server as your database

  • You use PostgreSQL on Linux

If you need to upgrade your database in these cases, you must do so manually.

The upgrade component script renames the existing component folders to a name that includes a time stamp matching the time you launched the upgrade component script (all components on Windows; but only Tomcat, ActiveMQ, and Java on Linux). The script creates a new directory with the original directory name, and then places the updated components in that directory.

In addition, the script copies specified files from the old setup, and provides you with the option to see file structure differences. Doing so allows you to manually copy additional files the script did not copy. In theory, you should be able to swap the new and old component folders again if you change your mind.

To run the upgrade component script:

  1. From a Linux command line or a Windows PowerShell command line, execute the script.

    • Linux: upgrade.sh

    • Windows: upgrade.ps1

  2. Provide the requested input when prompted.

    NOTE:For Windows, the prompt to upgrade PostgreSQL defaults to “No.” If you use PostgreSQL as a database, and want to upgrade it using the script, press “Y” or “y” when prompted to upgrade PostgreSQL.

Specifically, the script:

  • Checks whether the replacement file for the component is in the /compressed directory.

    • If not, the script displays the file it was expecting to find, and then proceeds to the next component.

    • If so, the script continues.

  • Offers you the choice of upgrading the current component.

  • Asks for the existing component path.

  • Checks the validity of the provided component path and, if invalid, prompts you for a valid path.

  • Instructs you to terminate the following corresponding services:

    • Tomcat service for Tomcat

    • ActiveMQ service for ActiveMQ

    • Tomcat and ActiveMQ services for Java

    • PostgreSQL (Windows script only)

    NOTE:The Windows script provides the option to terminate services for you, including some applications if files (such as Tomcat logs) are open and locked.

  • (Linux only) Saves component ownership for applying later.

  • Renames the existing component folder with a time stamp indicating the time you launched the upgrade component script.

  • Unpacks the contents of the downloaded component into the same path you provided.

    NOTE:The Java upgrade places a symbolic link in its place, regardless of whether it was originally symbolic.

  • Deletes certain webapps folders from the unpacked content (Tomcat only).

  • Copies known files from the old file structure to the new.

    NOTE:If the script copies an unpacked file, it backs up the file with *-backup.* in its name.

  • (Linux only) Applies the ownership retrieved above, and recursively applies it to the new folder.

    NOTE:Depending on your setup, you could need to apply a different sub-ownership.

  • Gives you the option of viewing file differences, with the following caveats:

    • (Windows only) Tomcat and PostgreSQL can take a significant amount of time generating these differences.

    • File and directory comparison for Linux is more efficient than that for Windows.

Upgrading PostgreSQL for Linux

If you need to upgrade your Linux installation of PostgreSQL, you need to perform preliminary steps before you upgrade. Extra preparation is not needed for Windows installations, unless your PostgreSQL database contains more than just Identity Governance and Identity Reporting. In that case, you should back up and restore your personal databases.

On Linux, the PostgreSQL upgrade process is through a repository.

To upgrade to the required version of PostgreSQL:

  1. Add the PostgreSQL repository.

  2. For either SLES or RHEL, install postgresql11-server through the package manager.

  3. At the command line, type the following to back up the Identity Governance and Identity Reporting databases:

    • "${PATH_TO_POSTGRESQL}/bin/pg_dump" -h "localhost" -p "5432" -U "postgres" -Fc "igops" > "igops.dump"

    • (For upgrades from Identity Governance 3.5) "${PATH_TO_POSTGRESQL}/bin/pg_dump" -h "localhost" -p "5432" -U "postgres" -Fc "igarc" > "igarc.dump"

    • "${PATH_TO_POSTGRESQL}/bin/pg_dump" -h "localhost" -p "5432" -U "postgres" -Fc "igdcs" > "igdcs.dump"

    • "${PATH_TO_POSTGRESQL}/bin/pg_dump" -h "localhost" -p "5432" -U "postgres" -Fc "igwf" > "igwf.dump"

    • "${PATH_TO_POSTGRESQL}/bin/pg_dump" -h "localhost" -p "5432" -U "postgres" -Fc "igara" > "igara.dump"

    • "${PATH_TO_POSTGRESQL}/bin/pg_dump" -h "localhost" -p "5432" -U "postgres" -Fc "igrpt" > "igrpt.dump"

    • (Conditional; on-premises setups) "${PATH_TO_POSTGRESQL}/bin/pg_dumpall" -h "localhost" -p "5432" -U "postgres" --roles-only > "roles.sql"

    • (Conditional; cloud-based setups) "${PATH_TO_POSTGRESQL}/bin/pg_dumpall" -h "localhost" -p "5432" -U "postgres" --roles-only --no-role-passwords > "roles.sql"

      NOTE:Use --no-role-passwords only for cloud-based setups where SU (or root) access is not allowed and, therefore, the passwords cannot be retrieved. Upon restoration, administrators must restore their passwords manually.

    NOTE:Perform these commands as a PostgreSQL user.

  4. Stop the PostgreSQL service.

  5. Rename the PostgreSQL data folder, and then create a new /data folder.

  6. (Optional) Rename the PostgreSQL /bin folder, and then create a new /bin folder.

  7. Place your PostgreSQL password as the only line in a file as follows:

    vi /tmp/pg_secret_to_remove

  8. Use a package manager to install the new version of PostgreSQL.

  9. Configure PostgreSQL 11 as follows:

    • export FILE_CONTAINING_PG_PASSWORD="/tmp/pg_secret_to_remove"

    • export PATH_TO_POSTGRESQL_DATA="/opt/netiq/idm/apps/postgres/data"

    • export ADMIN_POSTGRESQL="postgres"

    • For SLES: runuser -l postgres -c "/usr/lib/postgresql11/bin/initdb --auth='md5' --pwfile='${FILE_CONTAINING_PG_PASSWORD}' --username='${ADMIN_POSTGRESQL}' --pgdata='${PATH_TO_POSTGRESQL_DATA}'"

    • For RHEL: runuser -l postgres -c "/usr/pgsql-11/bin/initdb --auth='md5' --pwfile='${FILE_CONTAINING_PG_PASSWORD}' --username='${ADMIN_POSTGRESQL}' --pgdata='${PATH_TO_POSTGRESQL_DATA}'"

    • unset PGSETUP_INITDB_OPTIONS

  10. Remove the file in which you placed your PostgreSQL password.

    rm /tmp/pg_secret_to_remove

  11. Copy the following older files to the new directory.

    • pg_hba.conf

    • postgresql.conf

  12. Type the appropriate command to enable and restart the PostgreSQL service.

    • SLES: postgresql.service

    • RHEL: postgresql-11.service

  13. At the command line, type the following to restore the Identity Governance and Identity Reporting databases:

    • "${PATH_TO_NEW_POSTGRESQL}/bin/psql" -h "localhost" -p "5432" -U "postgres" -d "postgres" -f "roles.sql"

    • "${PATH_TO_NEW_POSTGRESQL}/bin/createdb" -h "localhost" -p "5432" -U "postgres" -T template0 "igops"

    • "${PATH_TO_NEW_POSTGRESQL}/bin/pg_restore" -h "localhost" -p "5432" -U "postgres" -d "igops" -Fc "igops.dump"

    • For Identity Governance 3.5: "${PATH_TO_NEW_POSTGRESQL}/bin/createdb" -h "localhost" -p "5432" -U "postgres" -T template0 "igarc"

    • For Identity Governance 3.5: "${PATH_TO_NEW_POSTGRESQL}/bin/pg_restore" -h "localhost" -p "5432" -U "postgres" -d "igarc" -Fc "igarc.dump"

    • "${PATH_TO_NEW_POSTGRESQL}/bin/createdb" -h "localhost" -p "5432" -U "postgres" -T template0 "igdcs"

    • "${PATH_TO_NEW_POSTGRESQL}/bin/pg_restore" -h "localhost" -p "5432" -U "postgres" -d "igdcs" -Fc "igdcs.dump"

    • "${PATH_TO_NEW_POSTGRESQL}/bin/createdb" -h "localhost" -p "5432" -U "postgres" -T template0 "igwf"

    • "${PATH_TO_NEW_POSTGRESQL}/bin/pg_restore" -h "localhost" -p "5432" -U "postgres" -d "igwf" -Fc "igwf.dump"

    • "${PATH_TO_NEW_POSTGRESQL}/bin/createdb" -h "localhost" -p "5432" -U "postgres" -T template0 "igara"

    • "${PATH_TO_NEW_POSTGRESQL}/bin/pg_restore" -h "localhost" -p "5432" -U "postgres" -d "igara" -Fc "igara.dump"

    • "${PATH_TO_NEW_POSTGRESQL}/bin/createdb" -h "localhost" -p "5432" -U "postgres" -T template0 "igrpt"

    • "${PATH_TO_NEW_POSTGRESQL}/bin/pg_restore" -h "localhost" -p "5432" -U "postgres" -d "igrpt" -Fc "igrpt.dump"

    NOTE:Perform these commands as a PostgreSQL user only.

12.3.2 Upgrading Identity Governance and Its Core Components

Before you start the upgrade procedure, ensure that you review the considerations in Planning to Upgrade Identity Governance.

To upgrade Identity Governance and its core components:

  1. Purge any unwanted data from the database before upgrading. For more information, see Identifying Purgeable Data in the Identity Governance User and Administration Guide.

  2. (Optional) Run reports for any review run details you want to make available after the upgrade.

  3. Launch the Identity Governance Configuration Utility in console mode, then issue the export-sql (or es) command to generate a SQL file that contains your current environment system properties. Move the file to another location, so you can compare it with a similar file you create after upgrading. For more information, see Section 14.1.3, Using the Identity Governance Configuration Utility.

  4. Stop Identity Governance (and Apache Tomcat). For more information, see Section 3.4.3, Starting and Stopping Apache Tomcat.

  5. (Conditional) If you are using PostgreSQL, back up and export your full Identity Governance data and confirm that you can restore it with no problems.

    Include all of the Identity Governance databases (default names). If you installed Identity Reporting, back up the Identity Reporting database (default name) as well.

    • igops

    • igarc (if upgrading from Identity Governance 3.5)

    • igdcs

    • igwf

    • igara

    • igrpt

    For more information, see the PostgreSQL Documentation for your version of PostgreSQL.

  6. (Conditional) If you are using Oracle, perform the following steps:

    1. Back up the following schemas:

      • igops

      • igarc (if upgrading from Identity Governance 3.5)

      • igdcs

      • igwf

      • igara

      • igrpt

    2. (Conditional) If your Oracle database has virtual columns, run the following command to identify virtual columns:

      select distinct c.table_name, e.extension_name 
          from sys.user_tab_cols c 
            inner join sys.user_stat_extensions e on e.table_name = c.table_name
          where c.virtual_column = 'YES' and e.droppable = 'YES';
    3. (Conditional) If your Oracle database has virtual columns, run the following script, modified for your specific environment details, to drop extended statistics and virtual columns:

      declare
        v_owner varchar2(255);
        v_table varchar2(255);
        v_extension varchar2(32000);
      begin
        select SYS_CONTEXT('USERENV', 'SESSION_USER') into v_owner from DUAL;
        for rec in (
          select distinct c.table_name, dbms_lob.substr(e.extension, 32000, 1) as extension, 
          from sys.user_tab_cols c 
            inner join sys.user_stat_extensions e on e.table_name = c.table_name
          where c.virtual_column = 'YES' and e.droppable = 'YES'
        )
        loop
          v_table := rec.table_name;
          v_extension := rec.extension    execute immediate 'call dbms_stats.drop_extended_stats(:v_owner, ;
      :v_table, :v_extension)' using v_owner, v_table, v_extension;
        end loop;
      end;

    For more information, see the Oracle documentation for the version of Oracle you have.

  7. (Conditional) If you are using MS SQL, back up the following databases:

    • igops

    • igarc (if upgrading from Identity Governance 3.5)

    • igdcs

    • igwf

    • igara

    • igrpt

    For more information, see the Microsoft SQL documentation.

  8. Move your generated reports (pdf and csv files) from the Reporting home folder to a backup directory.

  9. Perform the following steps to upgrade OSP:

    1. Move your trust store files to a backup location. The files are located in the following directories.

      • Linux:

        • /opt/netiq/idm/apps/osp/osp.pkcs12

        • /opt/netiq/idm/apps/osp/osp-truststore.pkcs12

        • /opt/netiq/idm/apps/tomcat/conf/apps-truststore.pkcs12

      • Windows:

        • \opt\netiq\idm\apps\osp\osp.pkcs12

        • \opt\netiq\idm\apps\osp\osp-truststore.pkcs12

        • \opt\netiq\idm\apps\tomcat\conf\apps-truststore.pkcs12

    2. Run the OSP upgrade installer.

  10. Run the Identity Governance installer.

  11. (Optional) Install the current version of Identity Reporting on the same server or a different server if needed. For more information, see Section 7.0, Installing Identity Reporting.

  12. (Conditional) If you are upgrading in a Windows environment, reboot the Windows server.

  13. Remove the localhost folder located in the /opt/netiq/idm/apps/tomcat/work/Catalina folder in Linux, or the C:\netiq\idm\apps\tomcat\work\Catalina folder in Windows.

  14. (Conditional) Add the virtual columns back into the Oracle database. For more information, see Tips and Tricks Invisible Columns in Oracle Database 12c.

  15. Delete all files and folders from the /opt/netiq/idm/apps/tomcat/temp folder in Linux, or from the C:\netiq\idm\apps\tomcat\temp folder in Windows.

  16. Move existing logs to a backup location.

  17. (Conditional) If you are integrated with an IDP (for example Access Manager), you can either:

    • Move the newly created trust store files (osp.pkcs12 and osp-truststore.pkcs12) to a different location, and then move the original trust store files (osp.pkcs12 and osp-truststore.pkcs12) back to the OSP installation folder, or

    • Update the IDP with the newly-created certificates.

  18. Clear your internet browser cache and remove cookies.

  19. Copy the generated pdf and csv report files to the location you specified during the installation.

  20. Start Tomcat. For more information, see Section 3.4.3, Starting and Stopping Apache Tomcat.

  21. (Conditional) Log in to Identity Governance to review any customized settings you have made to the user interface. Because of changed or additional element IDs and the different navigation settings, customizations you made to your previous environment might not work as expected. Adjust your customizations as needed.

  22. (Conditional) If you are collecting identities from a source that supports change events, run the Identity Source Migration and Upgrade utility to convert your existing source to use change event processing. If you are already using a change event collector, you can also use the utility to upgrade the configuration. For more information, see Migrating an Identity Collector to a Change Event Identity Collector in the Identity Governance User and Administration Guide.

  23. Publish the collected data again to populate the business roles and other items. For more information, see Publishing the Collected Data in the Identity Governance User and Administration Guide.

  24. If needed, run the Identity Governance Configuration Utility to restore your values for Workflow Settings > Notification System. For more information, see Section 14.1.3, Using the Identity Governance Configuration Utility.

  25. If needed, run the Identity Governance Configuration Utility with the -es option to get a list of system settings for your upgraded environment. Compare it to the list you generated before upgrading and restore any additional custom settings for your environment. For more information, see Section 14.1.3, Using the Identity Governance Configuration Utility.

  26. If you used the Identity Governance Configuration Utility to make changes in Step 23 or Step 24, restart Tomcat for these changes to take effect.