|
| |
| Sun Java[TM] System Identitiy Manager 7.0 Upgrade | |
Chapter 3
Upgrading Identity Manager in a Test EnvironmentThis section provides guidelines for setting up and deploying the upgrade in a test environment. The information is organized as follows:
Creating a Test EnvironmentYou want to create a test environment that mimics your production environment as closely as possible. Duplicate the following items, using the same hardware and software versions for your test environment that you use in the production environment:
- Application server
- Database server
- Gateway server
- Web Server (optional component)
- Common client machine with the corporate image and same browser
- Resources and other integrated applications
Resources and other integrated applications should have the same general configuration in the test environment as in the production environment. For example, active directory domains, organizations, groups, numbers, and the format of users should be replicated from production to the test environment.
Also, ensure that integrated applications are configured the same in both environments and that they contain either a copy of the production data or very similar data.
- Identity Manager version and configuration
Use the same Identity Manager version and configuration in your test environment as in the production environment.
If real test resources do not exist, you can create simulated resources for the functional test. Take a complete extract of the production files and database. Then, copy this extract to your new test environment.
Additional recommendations include:
- Assuming that all of the users and resource configurations are different, remove all users.
- Reconfigure the resources to point to test systems, removing duplicates if needed.
- Load all users into the system, using the same method you used during the production rollout.
- Extract configuration objects only from the production environment and load them into your test environment.
Preparing to Upgrade Your Test EnvironmentBefore upgrading the Identity Manager installation in your test environment, perform the following tasks:
- Back up your current Identity Manager installation.
Note
You should always back up the Identity Manager database and file system before applying any Identity Manager service packs, hotfixes, or going through any major upgrades.
- Rename customized Identity Manager repository objects.
- Verify the environment.
Back Up Your Current Identity Manager Installation
Before updating, it is important to back up both the directory where Identity Manager is installed and the database that Identity Manager is using. You can use third-party back up software or a back up utility supplied with your system to back up the Identity Manager file system. To back up your database, refer to the database documentation for recommended back up procedures.
When you are ready to create your backups, you must first shutdown (or idle) Identity Manager. Then, use your backup utilities to back up your database and the file system where you installed Identity Manager.
Rename Customized Identity Manager Repository Objects
Identity Manager provides a set of database objects, such as user forms and workflow task definitions, that are usually customized for your environment. The upgrade process replaces some of these objects in the database after saving them in the file system.
If you are not currently using the System Configuration object, you should start using it before upgrading. The System Configuration object allows you to point to these customized objects instead of using standard product defaults.
With a System Configuration object, you can customize user forms and workflow task definition objects without having to customize the default objects provided by Identity Manager. Identity Manager references the customized objects listed in the System Configuration object instead of the default objects. Refer to Identity Manager Administration for details.
If you choose not to use the System Configuration object, you must import your customized objects after performing the upgrade.
Verify the Environment
Before upgrading Identity Manager in your test environment, verify the following:
Deploying the Upgrade in a Test EnvironmentThis section explains how to deploy an upgrade in a test environment. The information is organized as follows:
The procedures described in this section apply if you are upgrading from Lighthouse 4.x to Identity Manager 5.x, or upgrading from Identity Manager 5.x to Identity Manager 6.x.
Note
For some environments, you might prefer to use manual upgrade procedures. For example,
Instructions for performing a manual upgrade procedure are provided in Upgrading Manually.
Upgrade the Environment
This section describes two methods for upgrading your test environment:
The instructions in the following sections use commands that are specific to a Windows installation and a Tomcat application server. Depending on your environment and application server, you might use slightly different commands.
Note
Refer to the appropriate chapter in Sun Java™ System Identity Manager Installation for application server-specific instructions.
Using the Identity Manager Upgrade Program
To upgrade your test environment using Identity Manager’s installation and upgrade program:
- Shut down the application server.
- If you are upgrading to Identity Manager 6.0 or Identity Manager 7.0, you must upgrade the repository database schema, as follows:
- If you are running Sun Identity Manager Gateway on the Identity Manager server, use the following command to stop the Gateway service:
net stop “Sun Identity Manager Gateway“
- Use either of the following methods to start the installer:
- On the Welcome panel, click Next.
- On the Install or Upgrade? panel, select Upgrade, and then click Next.
- On the Select Installation Directory panel, select the directory where the earlier Identity Manager version is located and click Next.
The installer displays progress bars for the pre- and post-upgrade processes and then proceeds to Installation Summary panel.
- 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.
- If you are running Gateway on a remote system, upgrade it by using the following steps.
- Log in to the Windows system, and change to the directory where Gateway is installed.
- Stop the Gateway service by running the command:
gateway -k
- If using Windows 2000 or later, exit all instances of the Services MMC plug-in.
- Use the following command to 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 CD.
- Unpack the gateway.zip file into the directory where Gateway was installed.
- Run the following command to install the Gateway service:
gateway -i
- Run the following command to start the Gateway service:
gateway -s
Upgrading Manually
In some environments, you might want to perform the upgrade steps manually instead of using the Identity Manager installation and upgrade program.
On a Windows Platform
Use the following steps to upgrade Identity Manager manually on a supported Windows platform:
- Stop the application server and Sun Identity Manager Gateway.
- Update the Identity Manager database. (See Step 2 for detailed instructions.)
- 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- Run 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 software:
cd %WSHOME%
jar -xvf %ISPATH%\IDM.WAR- Run post-process:
java -classpath %CLASSPATH% -Dwaveset.home=%WSHOME%
com.waveset.install.UpgradePostProcess
- 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.
- If the upgrade process did not do so already, move any hotfix class files from the WEB-INF\classes directory to the $WSHOME\patches\HotfixName directory.
- Start the application server.
- Upgrade and then restart Sun Identity Manager Gateway. (See Step 10 for detailed instructions.)
On a Unix Platform
Use the following steps to upgrade Identity Manager manually on a supported Unix platform:
- Stop the application server and Sun Identity Manager Gateway.
- Update the Identity Manager database. (See Step 2 for instructions.)
- Enter the following commands to 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 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 software:
cd $WSHOME
jar -xvf $ISPATH/idm.war- Run post-process:
java -classpath $CLASSPATH -Dwaveset.home=$WSHOME
com.waveset.install.UpgradePostProcess
- Change directory to $WSHOME/bin/solaris or $WSHOME/bin/linux, and then 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.
- If the upgrade process did not do so already, move any hotfix class files from the WEB-INF/classes directory to the $WSHOME/patches/HotfixName directory.
- Start the application server.
- Upgrade and then restart Sun Identity Manager Gateway. (See Step 10 for instructions.)
Restore Customizations After Upgrade
After the test upgrade, restore any customized files and objects.
File Customizations
During upgrade, Identity Manager automatically copies all customized files (such as JSPs and HTML) into the following directory.
$WSHOME/patches/Sun_Java_System_Identity_Manager_Version_Date_/savedFiles
Table 3-1 describes the files in this directory:
The Identity Manager upgrade might add some files that were also installed with your original Identity Manager installation. Before Identity Manager overwrites the older files, it automatically saves them in the savedFiles directory. Review the savedFileList file for a list of these files.
Identity Manager automatically restores most of the files listed in changedFileList during the upgrade process, but does not restore all of them. When Identity Manager restores your customized files, it overwrites the newer version of those files (installed during upgrade).
You might have to restore some file customizations manually. Review the notRestoredFileList file for a list of the files that were not restored during upgrade. If you have to restore any customized files, edit the new file (installed during upgrade) to incorporate your customizations, and then save the newly edited file.
Object Customizations
If you set up your system configuration before performing the upgrade, you do not have to do anything to restore your object customizations unless you customized objects that are not listed in the system configuration. You must restore these objects by manually importing the XML for these objects.
As a safety measure, Identity Manager automatically saves many of the commonly customized objects to files when you import update.xml. You will find these files in the WEB-INF/savedObjects directory, in sub-directories whose names are a timestamp of the time at which the import was done. Importing update.xml can lead to the creation of up to three subdirectories in the savedObjects directory. You can manually import the object XML files to restore object customizations.
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 timestamp and the stage of the upgrade.
Testing the Upgrade Deployment PackageTesting is crucial before deploying the development upgrade image to your production environment.
Develop and Execute the Test Plan
Create and execute an effective test plan for the development package. A generic test plan includes:
Document All Changes
It is very important to document all changes that occurred during the test upgrade. When documenting the test upgrade process, consider the following:
- List the version control system you are using
- Verify that all existing customizations are tagged and stored in the version control system
- Check in all new customizations after completing the test upgrade cycle, including:
- Create an image that consists of all the changed objects Identity Manager stored in the test system during the test upgrade. You deploy this image into production after upgrading your production environment.