| Oracle® Access Manager Upgrade Guide 10g (10.1.4.2.0) Part Number B32416-01 |
|
|
View PDF |
| Oracle® Access Manager Upgrade Guide 10g (10.1.4.2.0) Part Number B32416-01 |
|
|
View PDF |
This chapter provides information about the utilities that are called into operation during the upgrade process.
Topics in this chapter include:
Note:
Running the tools manually is not recommended. Oracle strongly recommends that you perform a in-place upgrade as described in Part II and Part III or that you perform a zero downtime upgrade as described in Part VI.When you upgrade each component, the newest product release is installed over an earlier product release in the same location. This discussion introduces the program-driven processes that occur during component upgrades.
There will be a few differences when you perform an in-place upgrade versus an out-of-place zero downtime upgrade:
In-place upgrades are initiated using the corresponding Oracle Access Manager 10g (10.1.4.0.1) installer. The arguments needed by the underlying utilities are gathered by the installer. During each component upgrade, the program controls the sequence of events and messages automatically. The process requires very little input from you.
Out-of-place zero downtime upgrades are initiated using the 10.1.4.2.0 MigrateOAM script from a command-line. In this case, you must manually enter the mode for the operation, and other arguments and parameters, which are then passed to the underlying utilities.
In-place Upgrades: You initiate a component upgrade using the corresponding Oracle Access Manager 10g (10.1.4.0.1) installer. During each component upgrade, the program controls the sequence of events and messages automatically. The component upgrade process requires very little input from you.
After you start an upgrade and specify the same (target) installation directory where the earlier (source) component resides, you are asked if you want to upgrade the earlier version of the component.
If directory names include spaces, a program might not be invoked properly unless you include quotation marks around each path name in any command you use. For example:
obmigratenp.exe -c ois -f 650 -t 700 -s
"C:\Program Files\NetPoint\identity_20060519_134931"
-d "C:\Program Files\NetPoint\identity"
-i "C:\Program Files\NetPoint\identity"
WARNING:
If your directory names include spaces, be sure to include quotation marks around each path name in any command you use.
All Upgrades: Figure C-1 and the process overview that follows it describe a typical component upgrade, which is driven by each program (and the utilities that are called automatically during the process):
An in-place upgrade is depicted. After you start the installation program for the component, you see a Welcome message and you are asked to provide specific input (such as an installation path name). As automated processing continues, you are asked to accept an operational method (Automatic versus Confirmed), or simply acknowledge that you are ready to continue.
During a zero downtime upgrade, you manually enter a command line that includes arguments and specifications for the MigrateOAM script. The MigrateOAM script passes the arguments and specifications to other utilities that participate or control the upgrade. Starting with process 3 in Figure C-1, internal processing is similar whether you perform an in-place upgrade or a zero downtime upgrade. For more information about the zero downtime upgrade script and modes, see Chapter 15.
Figure C-1 Program-Driven Events During an In-place Upgrade
Process overview: When an earlier source is detected and you choose to upgrade
The source directory is renamed with a time stamp.
The target directory is created and 10g (10.1.4.0.1) files are extracted into it. The latest release must be extracted to the original target path, and languages for the previous installation are detected.
The English language is upgraded automatically. If 10g (10.1.4.0.1) Language Packs are available in the source directory you can upgrade earlier languages and add new languages.
Note:
If you upgrade a multi-language implementation without 10g (10.1.4.0.1) Language Packs, you will lose the multi-language functionality.For more information about multi-language implementations, see Chapter 4, "System Behavior and Backward Compatibility".The obmigratenp utility is called (which determines the release you are migrating from as well as the release you are migrating to) and it internally detects which features need to be upgraded for this particular component and which other utilities to use for those upgrades.
When your installation includes multiple languages, obmigratenp:
Migrates message catalogs in other selected languages when you have 10g (10.1.4.0.1) Language Packs in the component source directory.
Invokes general upgrades, as discussed in "Primary Utility: obmigratenp".
Note:
For details about each utility and the log file generated by each utility, see later discussions in this appendix.The obmigratefiles utility is called to upgrade program and library files.
Required files are extracted to the target directory.
Required configuration and SSL-related files are copied from the renamed source directory to the target directory, and 10g (10.1.4.0.1) is installed.
For more information, see "File Upgrade: obmigratefiles".
The obmigrateparamsg utility is called to upgrade message and parameter catalog files.
Required (.xml and .lst) files are identified in renamed source area.
Files are modified for the latest release and written to the target directory. With 10g (10.1.4.0.1), .LST files are converted to .XML files and customizations made to the originals are retained in the upgraded files.
For more information, see "Message and Parameter Upgrade: obmigrateparamsg".
Schema and Data Upgrades Only: Two utilities (obmigrateds and obmigratedata) are called automatically to initiate Oracle Access Manager schema and data upgrades.
Zero Downtime Upgrades: The schema and data are upgraded independently. For more information, see "Schema and Data Upgrades with the Zero Downtime Upgrade Method".
In-Place Upgrades: The schema and data are upgraded together with the master Identity Server (and master Policy Manager when your installation includes the Access System). During subsequent Identity Server (and Policy Manager) upgrades, the initial schema and data upgrade is detected and this portion of the process is skipped. Oracle recommends that you upgrade the Oracle Access Manager schema and data automatically, as described in Part II, "Upgrading the Schema and Data". These upgrades use LDIF files that are specific to your directory server. Each LDIF file includes only changes from one release of Oracle Access Manager to the next. As a result, the schema and data upgrade will repeat one time for each release from your starting release to 10g (10.1.4.0.1). For example, if you are upgrading from release 6.1.1, the schema and data upgrade occurs as follows:
From release 6.1.1. to release 6.5
From release 6.5 to release 7.0
From release 7.0 to 10g (10.1.4.0.1)
The obmigratews utility is called to perform a selective Web server configuration file and filter upgrade, if needed, to accommodate changes for newer versions of Policy Manager, WebPass, and WebGate.
Changes are added to the Web server configuration file.
For more information, see "Web Server Upgrade: obmigratews".
A component-specific utility is used to make changes to related registry entries for Windows, plug-ins, and other files.
For example:
Identity Server: obMigrateNetPointOis upgrades existing registry entry for the Identity Server to reflect the newer release; modifies PPP catalog if needed; modifies password from password.xml and .lst, if needed; re-creates proper uninstall_info.txt. For details, see "Identity Server: obMigrateNetPointOis".
Note:
The password written in the Oracle Access Manager 5.2, password.xml and password.lst files is not encrypted; however, later versions encrypt this. Encryption occurs automatically during an upgrade.WebPass: obMigrateNetPointWP upgrades existing registry entry for the WebPass to reflect the newer release; modifies password from password.xml and password.lst, if needed. For details, see "WebPass: obMigrateNetPointWP"
Policy Manager: obMigrateNetPointAM upgrades registry entry for Policy Manager; modifies password encryption from password.lst, if needed; copies your custom plug-ins to the target installation directory from your renamed source directory. For details, see "Policy Manager: obMigrateNetPointAM".
Access Server: obMigrateNetPointAAA upgrades registry entry for Access Server; modifies password encryption, if needed; copies your custom plug-ins from your renamed source directory to the target installation directory; upgrades the following failover files:
AppDB.lst—converted to .xml
ConfigDB.lst—converted to .xml
Group.lst—if present, converted to .xml
UserDB.lst—if present, converted to .xml
WebResrcDB.lst—converted to .xml
For more information, see "Upgraded Items".
WebGate: obMigrateNetPointWG upgrades registry entry for the WebGate; modifies password encryption, if needed. For details, see "WebGate: obMigrateNetPointWG".
SDK: obMigrateNetPointASDK is called by obmigratenp to accomplish an Access Manager SDK upgrade.
The SDK upgrade will be invoked automatically as the last step when upgrading components bundled with SDK (Identity Server and the Oracle Access Manager Connector for WebSphere).
Note:
If you decline the automatic SDK upgrade, current SDK configuration settings are not preserved and you must reconfigure SDK using the configureAccessGate tool, as described in the Oracle Access Manager Access Administration GuideFor details, see "Software Developer Kit (SDK): obMigrateNetPointASDK".
Finish as you would any installation.
For details about what must be handled manually, see "Items that You Must Manually Upgrade".
Note:
Upgrades occur incrementally. This means that the sequence of earlier processes begins and the earlier release is upgraded to the next-major release. Following the component-specific upgrade, the process might repeat automatically until all changes between your original release and the latest release are completed.If you cancel an upgrade after being informed that the component has been installed, you need to complete the following steps to restore your Oracle Access Manager configuration to the original state.
When you perform a zero downtime upgrade, you must use the MigrateOAM script that is available with Oracle Access Manager Release 10g (10.1.4.2.0). For details about the MigrateOAM script and processing, see "Zero Downtime Upgrade Tools and Processes".
Using the in-place ugprade method, the main utility driving a component upgrade is obmigratenp. If you are using the zero downtime upgrde method, the MigrateOAM script drives the process. The obmigrate utility orchestrates the upgrade process for a component from a given major release X to a given major release Y, as described in Table C-1.
Table C-1 The Upgrade Driver obmigratenp
obmigratefiles is called by the obmigratenp multiple times to carry out file and folder related upgrades.
File upgrades involve copying required files from the renamed source directory to the target installation directory. The obmigratenp tool calls the obmigratefiles tool, which works on a given map file that specifies:
The files to be copied
From which source
To which target
For more information, see the next process overview.
Process overview: obmigratenp calls obmigratefiles
obmigratefiles creates a folder of original files in the source directory in the two following circumstances, because the release 5.2.0 installer (and the 6.0.0 installer on Solaris) does not create a folder of original files:
When you are upgrading from Oracle Access Manager 5.2.0
When you are upgrading on Solaris from release 6.0.0
The map file that is used is component_Version_orig_files.lst. For example:
ois_520_orig_files.lst
or
ois_600_orig_files.lst
This folder is further used for the message and parameter upgrade.
obmigratefiles creates a folder of original files for the current release in the current installation directory using the map file
component_Version_orig_files.lst.
For example:
ois_600_orig_files.lst
The next time an upgrade occurs from this release to a newer release, the folder of original files for this release will be available to use during the message and parameter upgrade.
obmigratefiles copies config files, SSL setup-related files, and the like from the renamed source directory to the target installation directory.
In this case, obmigratefiles works on a given component_base_files. For example:
ois_base_files.lst
am_base_files.lst
and so on
Base files contain the list of configuration files required for the upgrade. Typically, configuration files do not change. Files and directories in the base file are copied during the upgrade, including failover-related files. Any file and directory clean up occurs as needed. For example, if a particular Oracle Access Manager release deletes a file or introduces additional files, these will be treated appropriately. Suppose a file added in Oracle Access Manager 6.0 is not required in 6.5. In this case, the file will be deleted from the later installation.
Upgrade all files listed in the base file.
For all source versions from the base file release to the current source release, upgrade files listed in component_source-version_files.lst files.
For example, consider upgrading from Oracle Access Manager 5.2. release-specific files exist for Oracle Access Manager 6.0, 6.5, and 7.0. In this case, step 2 copies files listed in ois_610_files.lst, ois_650_files.lst, and ois_700_files.lst. However, when upgrading from Oracle Access Manager 7.0 to 10g (10.1.4.0.1), the current source release is the base file release, therefore step 2 doesn't occur.
Note:
In case a deleted file exists in the base file, the deleted file will be removed from the base file list itself. Even if it existed in the earlier Oracle Access Manager release, it is no longer needed in the later release.Additionally, release-specific files contain changes specific to only a particular component_source-version_files.lst; information that needs to be copied if you are upgrading from that release and there are some deviations. For example, suppose a file is added in Oracle Access Manager 6.0 and 6.5. In this case, you need files for:
ois_600_files.lst
ois_650_files.lst
ois_700_files.lst
Note:
If Oracle Access Manager release 6.1 did not require any changes, ois_610_files.lst is not required.Table C-2 provides more information
Table C-2 File Upgrades with obmigratefiles
The obmigratenp utility calls the obmigrateparamsg utility with the required file for a specific component.
The Message Upgrade Process: Allows you to upgrade earlier messages with new messages and add new messages for the later release. A customized message will be retained. However, if the number of parameters in the message has changed, only the new message is retained. For example:
"Cannot copy file %1""Failed copy operation for file %1""Cannot copy file %1 from %2 to %3"
Note:
In the examples shown here, the new message is retained.The Parameter Upgrade Process: Parameter upgrades occur in parameter files. When you have modified parameters in your earlier release of Oracle Access Manager and the new release has modified the same parameter, the obmigrateparamsg utility overwrites the earlier changes. See the log file for changes.
Earlier Oracle Access Manager Versions: Include files named as component_Fromrelease_to_Torelease_msg|param.lst in the directory component_install_dir\identity|access\oblix\tools\migration_tools. For example:
ois_520_to_600_msg.lst
ois_520_to_600_param.lst
Use of obmigrateparamsg was an iterative process with upgrades occurring for each incremental release.
Note:
As mentioned previously, earlier during the upgrade from release 7.0 to 10g (10.1.4.0.1), .LST files are converted to .XML files and stored in the target directory. Customizations made in earlier .LST catalogs are preserved and appear in the .XML version of the file. No separate manual step is required to preserve customizations.Oracle Access Manager 10g (10.1.4.0.1): The migration of parameter and message catalogs is performed in a single process. 10g (10.1.4.0.1) includes files named component_release_param_files.lst and component_release_msg_files.lst. For example:
am_700_param_files.lst
am_700_msg_files.lst
Optional hidden parameters from the earlier release are copied into the target. Hidden parameters are those which Oracle Access Manager supports and which you might want to add.
With Oracle Access Manager 10g (10.1.4.0.1), a path within the _param|msg_files.lst file includes a language ID to handle the multi-language feature available as of Oracle Access Manager 6.5. This looks like the example here:
file:/oblix/lang/%lang%/frontpagemsg.xml
When you specify the -p option, the obmigrateparamsg tool upgrades only message catalogs of the specified languages. The installer detects the language/ language of earlier release according to the following decision and pass it to obmigratenp:
For 5.2, 6.0 & 6.1–Look into globalparams.xml file for the language tag. For example, language:En_US.
For 6.5 and Later–Look in obnls.xml for the list of languages.
Table C-3 provides additional information about obmigrateparamsg.
Table C-3 Message and Parameter Upgrades with obmigrateparamsg
As discussed in "Mime_types -related Customizations Not Retained", when upgrading from Oracle Access Manager 6.0, multiple entries with the same ParamName in mime_types (.xml and .lst) files are not upgraded:
Note:
Both versions of the file are needed. You can remove MIME types that are no longer needed or add new MIME types to be associated with the particular attribute for further use. Simply edit the mime_types.lst and .xml files for the Identity Server, then copy these into the WebPass_install_dir to replace the earlier version.Typically, the Oracle Access Manager schema is enhanced for each major Oracle Access Manager release. For example, when Identity Server functionality is enhanced it might refer to a greater number of schema attributes and object classes than previous versions.
During your upgrade, any differences between an earlier schema release and the next release are uploaded to your directory server using the required schema ldif file for your specific directory server. Every schema ldif file includes entries to modify the schema based on the difference between two versions. Schema ldif files use the following naming convention.
DataType_fromrelease_to_torelease_schema_DsType.ldif
For example:
osd_650_to_700_schema_ad.ldif
policy_650_to_700_schema_nds.ldif
and so on.
and reside in the directory with various upgrade map files:
Component_install_dir\identity|access\oblix\tools\migration_tools
During the upgrade, the obmigratenp utility reads the file obmigratenpparams.lst and calls obmigrateds to internally upload schema files when the kMigrateData kMigrateSchema flag is set to true in:
Component_install_dir\identity|access\oblix\tools\migration_tools
\obmigratenpparams.lst
Schema upgrades occur incrementally. This means that the earlier release is upgraded to the next-latest release, the resulting schema is upgraded to the next-latest release, and so on until all interim schema changes between your original release and the latest release are completed. Obsolete schema elements are deleted during the upgrade.
A schema upgrade can occur only with Oracle Access Manager components that interface with the directory server: Identity Server, Policy Manager, and Access Server. Table C-4 provides more information about obmigrateds.
Table C-4 Schema Upgrades with obmigrateds
| Description | Function |
|---|---|
|
obmigrateds.exe |
Note: Starting with release 6.0, and later, the upgrade includes user entries for the "ChallengeResponsePhrase" value with an RC6 encryption scheme. Earlier Oracle Access Manager versions used an RC4 encryption scheme for the same purpose. Note: Zero downtime schema upgrades do not include the data upgrade. For more information, see "About Schema Mode Processing". |
|
Path |
Component_install_dir\identity|access\oblix\tools\migration_tools\obmigrateds |
|
Command Line |
'Run obmigrateds.exe without any parameters. This command prints usage along with the meaning of all input parameters |
|
Other Files Used |
|
|
Output |
This utility carries out schema and data migration by invoking appropriate utilities. |
|
Log File |
Generates the log file: install_dir\identity|access\oblix\tools\migration_tools\obmigrateds.log |
When the newer release of Oracle Access Manager include a new Oracle Access Manager-specific data organization or values, data upgrades occur in much the same way as the schema upgrade. The delta between the old and new versions is determined and the appropriate data ldifs are provided so they can be uploaded to the directory server. An incremental upgrade is performed between each major release and the next major release until you have completed the upgrade. After the upgrade, Oracle Access Manager can identify and use the data present in the directory and run smoothly.
A data upgrade can occur only with Oracle Access Manager components that interface with the directory server: Identity Server, Policy Manager, and Access Server.
Files that contain both object-class and attribute mappings are provided. The object and attribute mapping files reside in:
install_dir\identity|access\oblix\tools\migration_tools\obmigratedata
The object-class mapping filename is oc_Fromrelease_to_Torelease_map.lst. For example:
oc_520_to_600_map.lst
oc_610_to_650_map.lst
oc_650_to_700_map.lst
Note:
There is no data migration from Oracle Access Manager 6.0.0 release 6.1.0. For this reason, there is no oc_600_to_610_map.lst file.The attribute mapping filenames are appear as:
at_Fromrelease_to_Torelease_map_DataType.lst. For example:
at_520_to_600_map_osd.lst—Oblix schema data
at_520_to_600_map_policy.lst—NetPoint policy data
at_520_to_600_map_user.lst—User data
at_520_to_600_map_wf.lst—Workflow data
as well as files for 600 to 650 and 650 to 700 and 700 to 10g (10.1.4.0.1). For example:
at_600_to_650_map_item.lst
at_650_to_700_map_item.lst
where item refers to osd, policy, user, or workflow attribute mapping files.
The obmigrateds utility invokes obmigratedata for data upgrading and passes a map file with initial information—OSD directory, bind DN, password, personoc, groupoc, and the like—to obmigratedata. This map file uses the naming convention:
data_Fromrelease_to_Torelease_osd.lst data_Fromrelease_to_Torelease_user.lst
For example:
data_520_to_600_osd.lst
data_520_to_600_psc.lst
data_610_to_650_osd.lst
data_610_to_650_psc.lst
data_650_to_700_osd.lst
data_650_to_700_psc.lst
data_700_to_1014_osd.lst
data_700_to_1014_psc.lst
This is because the upgrade is carried out in steps. For example, if you start from release 520, data is first upgraded from 520 to 600, then from 610 to 650, from 650 to 700, and finally from 700 to 10g (10.1.4.0.1).
Note:
There is no data upgrade between release 600 and 610. Starting from release 5.2, you upgrade first to release 6.1.1 using 6.1.1 installers; then you complete the upgrade from 6.1.1 using 10g (10.1.4.0.1).See Table C-5 for more information.
Table C-5 Data Upgrades with obmigratedata
Along with Policy Manager, WebPass, and WebGate enhancements might come the need for changes in the supporting Web server configuration file. During the upgrade process, you are asked about automatic Web server configuration file updates. Oracle recommends that you update the Web server configuration file automatically, though you can do this manually following the upgrade.
The obmigratenp utility calls obmigratews to complete the Web server configuration update by passing a map file and other parameters to obmigratews. The map file is named and located as follows:
Component_fromrelease_to_torelease_ws_WebserverType.lst install_dir\identity|access\oblix\tools\migration_tools
For example:
am_520_to_600_ws_nsapi.lst
Also, obmigratenp copies the file generated by obmigratews to the original Web server configuration file. Thus the Web server configuration file gets the required changes for the newer release of the component. See Table C-6 for more information.
Table C-6 Web Server Configuration Upgrades with obmigratews
Every component needs special treatment during the upgrade to accommodate specific registry changes, modifying specific files, and the like. As a result, obmigratenp.exe calls the appropriate utility depending upon the component selected for the upgrade. Typical actions taken during this sequence include:
Copy/modify specific files
Modify existing component specific registry entry
Copy specific plug-ins
Each component-specific utility is described as follows:
To accomplish a Identity Server upgrade, the obmigratenp tool calls the obMigrateNetPointOis tool. See Table C-7 for more information.
Table C-7 Identity Server Upgrade with obMigrateNetPointOis
To accomplish a WebPass upgrade, obmigratenp calls obMigrateNetPointWP. See Table C-8 for more information.
Table C-8 WebPass Upgrade with obMigrateNetPointWP
To accomplish an Policy Manager (formerly known as the Access Manager component) upgrade, obmigratenp calls obMigrateNetPointAM. See Table C-9 for more information.
Table C-9 Policy Manager Upgrade with obMigrateNetPointAM
To accomplish an Access Server upgrade, the obmigratenp utility calls the obMigrateNetPointAAA utility. See Table C-10 for more information.
Table C-10 Access Server Upgrade with obMigrateNetPointAAA
To accomplish an WebGate upgrade, obmigratenp calls obMigrateNetPointWG. See Table C-11 for more information
Table C-11 WebGate Upgrade with obMigrateNetPointWG
To accomplish a Software Developer Kit upgrade, obmigratenp calls obMigrateNetPointASDK. See Table C-12 for more information.
Table C-12 SDK Upgrade with obMigrateNetPointASDK
