Step 7: Upgrade the Identity Manager Product (Sun Identity Manager 8.1 Upgrade)

Sun Identity Manager 8.1 Upgrade

Step 7: Upgrade the Identity Manager Product

To upgrade the Identity Manager product itself, you might be required to do the following:

Update the Repository Database Tables

Most major releases and some minor releases of Identity Manager include database table changes. Consequently, you might have to modify the sample SQL scripts for your environment.

You must also update the database tables if you made any of the following modifications:

Changed the database instance name
Changed the name of the database account that owns the database tables
Separated the owner of the database tables from the database account used to connect to the database
Made more advanced DBA changes, such as configuring specific table spaces and growth characteristics for different sets of tables and indexes

You must remember any changes that you make to the sample SQL scripts for each Identity Manager version and use source control to manage these changes. In the future, you will have to make similar changes to the sample SQL scripts for subsequent Identity Manager versions.

Upgrade the Identity Manager Product

You can use either of the following methods to upgrade the Identity Manager product:

Use the Identity Manager installer program as described in To Use the Identity Manager Installer.
Use the Identity Manager manual upgrade process as described in Upgrading Manually.

Both methods produce the same results.

Note –

In some environments you might prefer using the manual upgrade procedure. For example:

If you want to fully automate the upgrade as part of a repeatable upgrade procedure
If you have restricted access to your Production environment or cannot start the console

Upgrading the Identity Manager product might modify objects in the Identity Manager repository and in some file system artifacts such as .jsp files, Identity Manager product JARs, and third-party JARs.

When upgrading the Identity Manager product, be aware of the following:

If you copy files from the installation media to your own location, you must put the idm.war and install.class files in the same directory.
Use only one Identity Manager server to import update.xml, and have only one Identity Manager server running during the upgrade.

If you start any other Identity Manager servers during the upgrade, you must stop and restart those servers before making them available.
If your application server is installed on a machine running a UNIX® system, change directories to the $WSHOME/bin directory and run the following command to allow the scripts in this directory to be executed:
```
chmod -R +x *
```
For UNIX environments, be sure that you have an install directory in one of the following locations and that you can write to that directory:

For Linux/HP-UX

/var/opt/sun/install

For Solaris^TM

/var/sadm/install

Previously installed hotfixes are archived in the $WSHOME/patches/HotfixName directory.
The upgrade program has three steps: the upgrade pre-process step, the upgrade step, and the upgrade post-process step. The upgrade post-process step runs in a separate Java virtual machine and the default heap size for this step is 1024 MB. If you experience out-of-memory exceptions during an upgrade, set this value higher. To specify a custom value, set the JAVA_OPTS environment variable using the form —Xmx<heap size> where heap size is a value, such as 2048m. An example is -Xmx2048m.

To Use the Identity Manager Installer

Use the Identity Manager installation and upgrade program to upgrade your Development environment.

Use one of the following methods to start the installer:
- To use the GUI installer, run install.bat (for Windows) or install (for UNIX).
  
  The installer displays the Welcome screen.
- To activate the installer in nodisplay mode, change to the directory where the software is located, and type:
  
  install -nodisplay
  
  The installer displays the Welcome text, and then presents a list of questions to gather installation information in the same order as the GUI installer.
  
  If no display is present, the installer defaults to the nodisplay option.
  
  The installer does not install an older version of the software over a newer version. In this situation, an error message displays and the installer exits.

On the Welcome screen, click Next.

On the Install or Upgrade? screen, select Upgrade and click Next.

On the Select Installation Directory screen, select the directory where the earlier Identity Manager version is located and click Next.

The installer displays progress bars for the pre-upgrade and post-upgrade processes and then proceeds to Installation Summary screen.

For detailed information about the installation, click Details, view the log file, and click Close to exit the installer.

Remove all of the compiled Identity Manager files from the work directory of the application server.

Upgrading Manually

In some environments, you might want to perform the upgrade steps manually instead of using the Identity Manager installation and upgrade program.

Make sure that you set the JAVA_HOME environment variable.
Make sure that the bin directory in the JAVA_HOME directory is in your path.
Any previously installed hotfixes will be archived to the $WSHOME/patches/HotfixName directory.

Note –

The instructions in this section are based on installing Identity Manager on a Tomcat application server. Depending on your application server, you might have to use slightly different commands.

Refer to the appropriate chapter in Part II, Installing Identity Manager, in Sun Identity Manager 8.1 Installation for application server-specific instructions.

To Perform a Manual Upgrade on a Windows Platform

Perform the following steps to upgrade Identity Manager manually on a supported Windows platform:

Stop the application server and Gateway.

Update the Identity Manager database.

Enter the following commands to set your environment:
set ISPATH=Path-to-install-software set WSHOME=Path-to-Identity-Manager-Installation OR Staging-Directory set TEMP=Path-to-Temporary-Directory
Note –
If you have a space in the path to the Identity Manager installation directory, you must specify the WSHOME environment variable without double quotes ("), as shown in the following example.

Do not use trailing slashes (\) when specifying the path even if the path contains no spaces.
set WSHOME=c:\Program Files\Apache Group\Tomcat 6.0\idm
or
set WSHOME=c:\Progra~1\Apache~1\Tomcat~1\idm
The following path will not work:
set WSHOME="c:\Program Files\Apache Group\Tomcat 6.0\idm"

Run the pre-process.

mkdir %TEMP%
cd /d %TEMP%
jar -xvf %ISPATH%\IDM.WAR\
WEB-INF\lib\idm.jar WEB-INF\lib\idmcommon.jar
set TMPLIBPTH=%TEMP%\WEB-INF\lib
set CLASSPATH=%TMPLIBPTH%\idm.jar;\
%TMPLIBPTH%\idmcommon.jar;
java -classpath %CLASSPATH% -Dwaveset.home=%WSHOME%\
   com.waveset.install.UpgradePreProcess

Install the software.
cd %WSHOME% jar -xvf %ISPATH%\IDM.WAR

Run the post-process.
java -classpath %CLASSPATH% -Dwaveset.home=%WSHOME% com.waveset.install.UpgradePostProcess
Note –
- The upgrade post-process step runs in a separate Java virtual machine. The default heap size for this step is 1024 MB. If you experience out-of-memory exceptions during this step, set the maximum heap size value higher. To specify a custom value, set the JAVA_OPTS environment variable using the form —Xmx<heap size> where heap size is a value, such as 2048m. An example is -Xmx2048m.
- The installer supports upgrading installations that have renamed, deleted, or disabled the default Configurator account.
  
  The installer prompts you for the user name and password to import the update.xml during the upgrade post process. If the user name or password is typed incorrectly, you will be prompted (up to three times) to enter the correct name or password. The error will be displayed in the text box behind it.
  
  For manual installation, you must provide the -U username -P password flags to pass the credentials to the UpgradePostProcess procedure.

If you installed into a staging directory, create a .war file for deployment to your application server.

Remove the Identity Manager files from the application server work directory.

To Perform a Manual Upgrade on a UNIX Platform

Perform the following steps to upgrade Identity Manager manually on a supported UNIX platform:

Stop the application server and Gateway.

Update the Identity Manager database.

Set your environment.

export ISPATH=Path-to-Install-Software export WSHOME=Path-to-Identity-Manager-Installation-or-Staging Directory 
export TEMP=Path-to-Temporary-Directory

Run the pre-process.

mkdir $TEMP
cd $TEMP
jar -xvf $ISPATH/idm.war \
WEB-INF/lib/idm.jar WEB-INF/lib/idmcommon.jar
CLASSPATH=$TEMP/WEB-INF/lib/idm.jar:\
$TEMP/WEB-INF/lib/idmcommon.jar:
java -classpath $CLASSPATH -Dwaveset.home=$WSHOME \
com.waveset.install.UpgradePreProcess

Install the software.
cd $WSHOME jar -xvf $ISPATH/idm.war

Run the post-process.
java -classpath $CLASSPATH -Dwaveset.home=$WSHOME com.waveset.install.UpgradePostProcess
Note –
- The upgrade post-process step runs in a separate Java virtual machine. The default heap size for this step is 1024 MB. If you experience out-of-memory exceptions during this step, set the maximum heap size value higher. To specify a custom value, set the JAVA_OPTS environment variable using the form —Xmx<heap size> where heap size is a value, such as 2048m. An example is -Xmx2048m.
- The installer supports upgrading installations that have renamed, deleted, or disabled the default Configurator account.
  
  The installer prompts you for the user name and password to import the update.xml during the upgrade post process. If the user or password is typed incorrectly, you will be prompted (up to three times) to enter the correct name or password. The error will be displayed in the text box behind it.
  
  For manual installation, you must provide the -U username -P password flags to pass the credentials to the UpgradePostProcess procedure.

Change directory to $WSHOME/bin/solaris or $WSHOME/bin/linux, and set permissions on the files in the directory so that they are executable.

If you installed into a staging directory, create a .war file for deployment to your application server.

Remove the Identity Manager files from the application server work directory.

Troubleshooting Upgrade

If you encounter problems during the upgrade, check the upgrade log files located in the $WSHOME/patches/logs directory. The file names for the logs are based on a time stamp and the stage of the upgrade.

Upgrade All Gateway Instances

Upgrade every Sun Identity Manager Gateway installation in your environment. Newer versions of Identity Manager server do not work with older versions of the Gateway.

To Upgrade the Identity Manager Gateway

Stop the Gateway service.
gateway -k

If using at least Windows 2000, exit all instances of the Services MMC plug-in.

Remove the Gateway service.
gateway -r

Back up and delete the existing Gateway files.

Extract the new Gateway files.

If you are installing the newly upgraded Gateway on a system that is not the Identity Manager server, then copy the gateway.zip file from the Identity Manager installation package.

Unpack the gateway.zip file into the directory where Gateway was installed.

Install the Gateway service.
gateway -i

Start the Gateway service.
gateway -s

Upgrade All PasswordSync Instances

Unless the Release Notes specify otherwise, newly installed versions of the Identity Manager server provide limited, temporary support for older versions of PasswordSync. This support is provided so that Identity Manager can continue to run while you upgrade your PasswordSync instances. All instances of PasswordSync should be updated to the same version as Identity Manager Server as soon as possible.

To upgrade PasswordSync, you must uninstall each PasswordSync installation in your environment and reboot. Use the add/modify programs feature from the Windows Control Panel to ensure correct removal.

Replace each installation with the new PasswordSync version and reboot. Use the appropriate binary file for the operating system on which you are installing. The binary for 32-bit Windows is called IdmPwSync_x86.msi and the binary for 64-bit Windows is called IdmPwSync_x64.msi.

Note –

You must reboot Windows twice: Once after uninstalling PasswordSync, and once after installing the new version. The two reboots are necessary due to the way the Windows Security Service loads the PasswordSync DLL.

For installation instructions, see Installing and Configuring PasswordSync on Windows in Sun Identity Manager 8.1 Business Administrator’s Guide.