Oracle® Access Manager Upgrade Guide 10g (10.1.4.2.0) Part Number B32416-01 |
|
|
View PDF |
Release 10.1.4 Patch Set 1 (10.1.4.2.0) includes new tools and updated utilities to support a zero downtime upgrade methodology for mission-critical deployments. Oracle recommends that you review all information about the zero downtime upgrade method to ensure that this approach is the right one for your enterprise. This chapter introduces the zero downtime upgrade methodology and includes the following topics:
Note:
If you are using the in-place upgrade method, skip this chapter.The zero downtime methodology is an alternative to the in-place upgrade methodology that is described in Part II and Part III of this book. The zero downtime upgrade methodology is also known as an out-of-place upgrade for reasons that are described in this chapter. Before you decided which method is appropriate for use when upgrading your deployment, Oracle recommends that you read all information about zero downtime upgrades as well as the in-place upgrade.
The zero downtime upgrade method is available as an option for those who want to upgrade with very little disruption to their original deployment and the services that are provided to internal and external customers. The zero downtime method provides the following features for mission-critical deployments:
Eliminates most Oracle Access Manager service downtime during the upgradeSeparates the Oracle Access Manager schema upgrade from Oracle Access Manager data upgrades Separates the upgrade of attributes and objectclassesEnables you to roll back changes and return to your starting position at any stage
Oracle Access Manager Release 10g (10.1.4.2.0) is a patch set release, as described in Chapter 1. Oracle Access Manager Release 10g (10.1.4.2.0) provides the tools that you need to perform a zero downtime upgrade. You can use the zero downtime upgrade method to upgrade directly to Oracle Access Manager release 10g (10.1.4.2.0) from releases as early as 6.1.1. For example, you can use this method to upgrade directly:
If your starting release is earlier than 6.1.1, you cannot upgrade directly. For more information, see "Indirect Upgrade Paths". For more information about upgrade paths, see Chapter 1.
Some situations are not appropriate for the zero downtime upgrade method. For example, do not use the zero downtime method:
If your starting release is Oracle Access Manager 10g (10.1.4.0.1), you can apply Release 10.1.4 Patch Set 1 (10.1.4.2.0) to each 10g (10.1.4.0.1) component instance. Do not use the zero downtime upgrade method. For more information, see the Oracle Access Manager Patch Set Notes Release 10.1.4 Patchset 1 (10.1.4.2.0) For All Supported Operating Systems.
If you are performing a switch from a Solaris platform to a Linux platform while upgrading from an earlier release, follow instructions in Appendix B. Afterward, you can apply Release 10.1.4 Patch Set 1 (10.1.4.2.0) to the 10g (10.1.4.0.1) components as described in the Oracle Access Manager Patch Set Notes Release 10.1.4 Patchset 1 (10.1.4.2.0) For All Supported Operating Systems. Do not use the zero downtime upgrade method in this case.
The following topics provide more information about the zero downtime upgrade method:
Original and Clone Environments for the Zero Downtime Upgrade Method
Schema and Data Upgrades with the Zero Downtime Upgrade Method
Customization Upgrades Using the Zero Downtime Upgrade Method
Note:
Oracle recommends that you review all information about the zero downtime method before you decide whether it is the right choice for your deployment and before you perform any upgrade tasks.A zero downtime upgrade can be performed with any deployment type or scenario. For example, you can perform a zero downtime upgrade on a development or test area or on a full production deployment. The deployment category can be either extranet or intranet. For more information about deployment scenarios and categories, see Chapter 1 and the Oracle Access Manager Deployment Guide.
Oracle recommends that you first use the zero downtime upgrade method in a small, isolated deployment. After performing the zero downtime upgrade and validating that this method produced the results that you expected in a small area, you can use the zero downtime method to upgrade a larger deployment. The tasks that you perform are the same regardless of the size or complexity of your deployment.
For more information about the duration of the zero downtime upgrade task and processing, see "Duration of Zero Downtime Tasks and Validation".
The zero downtime upgrade method is also known as an out-of-place upgrade method because you will be working with two complete environments:
This topic describes the original deployment and the role that it plays during a zero downtime upgrade. When you upgrade using the zero downtime method, your original Oracle Access Manager instances remain intact.
During a zero downtime upgrade, original instances typically remain on the same computer where they were installed. However, before upgrading a component you can change the hardware or the operating system or Web server. For more information, see "Hardware Requirements for Zero Downtime Upgrades".
Original instances use the original configuration and policy data. This data is stored in the original branch of the LDAP directory server that was specified when you installed the components. For more information, see "Schema and Data Upgrades with the Zero Downtime Upgrade Method".
Original instances provide a source for the copied instances (known as clones) that you will create and upgrade. Creating, upgrading and validating the clone system enables you to leave the original instances and data intact. For more information, see "The Clone Environment".
Original instances continue to serve all customers while you upgrade clones and validate the cloned system upgrade. You upgrade original component instances only when you are satisfied that the upgraded cloned environment is operating as expected.
Oracle recommends that you upgrade customizations early on in the upgrade process, so that you can test these thoroughly. When you use the zero downtime upgrade method, you can upgrade customizations and test these with the upgraded cloned environment. For more information, see "Customization Upgrades Using the Zero Downtime Upgrade Method".
At the center of the zero downtime upgrade method is a copy of each earlier Oracle Access Manager instance in your original deployment. The copy is referred to as a clone. You will also have a copy of the original oblix branch. This topic describes the clone setup and the role that it plays during a zero downtime upgrade.
Using the zero downtime upgrade method, you will create a clone of each component instance that resides in the original deployment (except WebGates).
The clone file system is a back up copy of the original file system. In later tasks, you will rename each clone subdirectory to create a source for the clone upgrade. The source becomes the back up copy of the component and remains intact while the destination that contains the 10.1.4.2.0 tools, libraries, and files, is upgraded. The original file system is untouched during clone upgrades.
You can install another instance of an earlier release Oracle Access Manager component to use as a clone. For example, if you have original instances operating with an IIS Web server on a Windows platform you need to place the clone on a different computer host. After you install the earlier instance on the new host you need to copy any customizations and configuration changes from the original instance to the newly installed clone. If the instance uses either Simple or Cert mode to communicate with existing components, you must copy the \config subdirectory from the original instance to the newly installed instance to ensure that all certificates are in order.
For example, suppose that you have a small distributed sandbox-type deployment with one instance each of the COREid Server (now named the Identity Server), WebPass, Access Manager (now named the Policy Manager), Access Server, and WebGate. Figure 15-1 shows both the original and clone instances in this sample environment.
Figure 15-1 Original and Clone Instances for a Zero Downtime Upgrade
As you can see in Figure 15-1, you will have a clone component instance for each original instance except WebGates. The clones can reside on the same computer host as the original; however, they can reside on a different computer host if you prefer. For more information, see "Hardware Requirements for Zero Downtime Upgrades".
WebGates: You do not clone WebGates because you can delay WebGate upgrades. Delaying WebGate upgrades is possible because an upgraded Access Server provides backward compatibility with earlier WebGates and earlier custom plug-ins. This backward compatibility is enabled automatically when you upgrade an earlier Access Server. As a result, you will configure original WebGates to work with cloned Access Servers and delay WebGate upgrades. For more information about backward compatibility, see Chapter 4.
Having only one WebGate will result in downtime when upgrading that WebGate (or when rolling back). Oracle recommends that you have more than one WebGate to avoid downtime. Alternatively, you can keep the older WebGate and not upgrade it because it will work with the upgraded Access Server.
Access Servers: Each WebGate upgrade requires that at least one Access Server configured for that WebGate is running. This is required to enable the migration of information from the WebGateStatic.lst file to the WebGate profile in the System Console.
SDK and Integration Connectors: In addition to delaying WebGate upgrades, you can delay upgrading the Software Developer Kit (SDK). Any item that must be handled manually can be upgraded at any time. For more information about manual tasks, see Chapter 3.
Separate Web Server for Clones: On computers that are hosting Web components, you need a separate Web server instance to serve the clone WebPass and Access Manager instances. For more information, see "Hardware Requirements for Zero Downtime Upgrades".
LDAP Directory Server: Also shown in Figure 15-1 is the LDAP directory. It contains the Oracle Access Manager schema that was installed when you installed the earlier original components, as well as the original branch where configuration and policy data are stored. The clone setup uses a copy of the data (there is no copy of the schema) from your original environment.
For the clone setup, you will create a new branch in the same LDAP directory server instance and populate the new branch with a copy of the original configuration and policy data. The original branch remains intact. After populating the new branch, you will reconfigure cloned components to use the new branch. After this reconfiguration, the clone component replicates the original. The original environment continues to use the original branch and the data in the original branch. For more information, see "Schema and Data Upgrades with the Zero Downtime Upgrade Method".
After upgrading the clones, you will validate the upgraded environment to ensure that it is operating as expected with the upgraded schema and data in the new branch. After validation, you can use the upgraded clones to serve in place of original components while you upgrade the originals. For an introduction to validation tasks, see "Validation During a Zero Downtime Upgrade".
Original instances reside on existing hardware. When you create a clone instance, Oracle recommends that clone resides on the computer that is hosting the original instance. However, you can create the clone on any computer that meets Oracle Access Manager 10g (10.1.4.2.0) requirements.
If you would like to upgrade hardware or change the operating system or Web server within your deployment, Oracle recommends that you do this before starting the zero downtime upgrade. Whether you use existing systems or choose to enhance these, you must ensure that the system is supported by Oracle Access Manager 10g (10.1.4.2.0). For more information, see "Bringing Host Computers to Oracle Access Manager 10g (10.1.4.0.1) Support Levels".
Note:
If you plan to add hardware to the existing deployment, you will need to install the earlier Oracle Access Manager instance on a supported platform before you start the upgrade.Clone component identifiers and service names will be different from those for the original instance. As a result, there is no need to place Identity Server or Access Server clones on a different computer host when you have an IIS Web server on the same computer as an original Identity Server or Access Server instance. For more information, see "Web Server Requirements for Zero Downtime Upgrades".
Currently supported Unix-based platforms include Linux and Solaris. Any Reference to Unix refers only to currently supported Unix-based platforms.
You can start the zero downtime upgrade when all systems are ready.
The cloned WebPass and Access Manager require a separate Web server instance. The Web server instance for the clone should be the same Web server type and release that is used with the original Web component instance. For example, if you are using an Oracle HTTP Server (OHS) based on Apache 2.0.5.2, you should use the same Web server for the clone. There are no cloned WebGates.
The following guidelines apply to Web server instances for cloned Web components:
If you have only one set of Web components on a single host computer, configured for a single Web server instance, you will need only one new Web server instance to service the clones.
If you have a more complex deployment, where Web components are distributed across multiple host computers, you will need one new Web server instance on each computer that is hosting cloned Web components.
If you have more than one Web server configured for more than one pair of WebPass or Access Manager components, you will need a similar pairing of Web server instances for the clone.
If you have other applications that are protected by Oracle Access Manager using the original Web server instance, you should also clone these applications to use the Web server instance that you create for the cloned Web components.
When cloning earlier IIS Web components on a Windows system, the Windows registry is not updated for the clone. This might cause issues because the IIS Web server requires the entries for Web components in the registry. For more information, see "Reinstating Original Windows Registry Entries During a Rollback Operation".
Oracle recommends that you do not have more than one instance of the IIS Web server on a host computer. If the original component uses an IIS Web server, Oracle recommends that you create the clone on a different host; the name of the host computer will differ for the clone.
You must perform Identity System set up for each upgraded COREid Server and WebPass association. You must set up each upgraded Access Manager. However, Web server instances cannot support Oracle Access Manager Web components that are at different release levels (6.1.1 and 10.1.4, for example). This is especially true on Unix-based systems.
There are implications for setting up the upgraded Identity System and Access Manager, whether it is a clone or an original system. All Web components that are serviced by a single Web server instance (WebPass, Access Manager, and WebGates), must be at the same release level before you restart the Web server. When you have a single Web server instance serving more than one Oracle Access Manager Web component, the Web server must remain stopped until all serviced Web components on the host computer are upgraded.
You cannot set up the upgraded Identity System or Access Manager (whether you are upgrading the clone setup or the original setup) until all Oracle Access Manager Web components that are serviced by the Web server instance have been upgraded to 10g (10.1.4.2.0).
The following conditions apply when you are ready to set up either the upgraded clone or upgraded original system:
Identity System Only:
A single Web Server instance cannot service multiple WebPass instances.
You can set up the Identity System after upgrading the only WebPass.
Joint Identity and Access System: You must delay setting up the Identity System and the Access Manager until you have upgraded all Web components that are serviced by a single Web server instance.
In the clone environment you upgrade COREid Servers, and serviced WebPass and Access Manager instances before setting up the Identity System and the Access System. There are no WebGate clones. In the original environment, you must upgrade all serviced WebPass, Access Manager, and WebGate instances.
When a WebPass and Access Manager both use the same Web server instance, delay Identity System setup until after the serviced Access Manager instances are upgraded.
When the same Web server instance is used by WebPass, Access Manager, and WebGate, delay Identity System setup until after you upgrade all serviced Web components.
If you have an Access Manager and WebGate installed in the same directory, you must postpone reconfiguring that Access Manager until the WebGate is upgraded.
You must upgrade components in the proper sequence on each host (COREid Server, WebPass, Access Manager, Access Server, and WebGate). Do not upgrade a WebGate before upgrading the Access Server on the same host.
You upgrade components on each host in a specific order. There is no need to wait for all the Web components throughout the environment to be upgraded before you set up the Identity System and Access Manager.
As you prepare your original environment for the zero downtime upgrade, you will be instructed to review the topics in the following list and perform any tasks that are applicable to in your environment. These topics are located in Chapter 5:
Strategies for Upgrading in a Replicated Environment
Your deployment might employ the use of replicas to increase system availability and improve performance. Oracle recommends that you disable replication until the upgrade is complete and all features have been validated to work correctly.
Configuring the Challenge/Response Phrase at the Object Class Level
Oracle recommends that before starting the upgrade you ensure that the Challenge and Response attributes are configured at the object class level. If Challenge and Response attributes are configured at the Employees tab level (rather than at the object class level), then the configuration data upgrade might not complete correctly.
Configuring Unique Namespaces for Directory Connection Information
Each directory server profile contains connection information for a directory that includes the profile name, a domain or namespace to which it applies, a directory type, and a set of operational requirements for Read, Write, Search, and so on. To ensure that namespaces are unique and do not overlap with other directory server profile namespaces, when earlier Oracle Access Manager installation with configuration data or policy data is stored in a different directory server than user data you need to configure unique namespaces before upgrading.
Preparing Your Directory Instances for the Schema and Data Upgrade
This task includes verifying that the directory server is supported, that specific considerations for your directory server type have been taken into account, and that you have verified that the value of the directory server's search size limit parameter is greater than the number of entries in your configuration tree.
When you installed and set up the first COREid Server instance and the first Access Manager instance in your original environment, the Oracle Access Manager schema and configuration and policy data were added to the LDAP directory server. This topic outlines the implications of the schema upgrade and data upgrades when you use the zero downtime method
You will create a new branch in the LDAP directory server and store a copy of your current configuration and policy data there for the clone system to use.
The schema is upgraded all at one time and is upgraded separately from configuration and policy data. For more information, see "About The Schema Upgrade".
Data in the new branch is upgraded when you upgrade the clone of the first installed COREid Server (and in some cases when you upgrade the clone of the first installed Access Manager). Data in the original branch is not upgraded and is available for use by the original system until that system is upgraded. For more information, see "About Configuration and Policy Data Upgrades".
Multiple values that are configured as challenge and response attributes for Lost Password Management are migrated during the user's first login after the upgrade. This migration is halted automatically until you upgrade original instances. For more information, see "User-Data Migration and Multiple Values in Challenge and Response Attributes for LPM".Lost password management functions are available for use in the upgraded cloned system. However, multiple challenge and responses for lost password management cannot be used without modifying the user data.
Parameter catalogs and message files are upgraded with each individual component (whether clone or original). For more information about processing during upgrades, see "Zero Downtime Upgrade Tools and Processes".
Both the schema upgrade and the data upgrade relies on Lightweight Directory Interchange Format (LDIF) files. An LDIF file is an ASCII format file that you can use to exchange and synchronize data between Lightweight Directory Access Protocol (LDAP) servers. There are LDIF files for each specific LDAP directory server.
Each LDIF file includes only the changes from one Oracle Access Manager release to the next. As a result, the data upgrade sequence will repeat one time for each release between your starting release and 10g (10.1.4.2.0). For example, if you are upgrading from release 6.1.1, the schema upgrade (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 10.1.4
This topic provides an introduction to the schema upgrade that you perform using the zero downtime upgrade method.
The Oracle Access Manager schema is usually 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 releases. The schema upgrade must be performed by someone who has directory server administrator privileges that includes write access to the LDAP directory server and files.
With the zero downtime upgrade method, the schema upgrade is separate from data upgrades. The schema upgrade occurs all at one time. You can ensure that the schema upgrade was successful before you upgrade any components (or the configuration and policy data).
Before upgrading the schema, Oracle recommends that you create a new branch within the same LDAP directory server instance that is used by the original instances. After creating the new branch, you populate it with a copy of the original configuration and policy data. The clone setup will use this new branch and will mirror the original environment without disrupting the original environment. For more information about how this is done for the zero downtime upgrade, see "About Mkbranch Mode Processing". The new branch in the directory server will not include a copy of the schema.
After populating the new branch and configuring cloned instances to use the new branch, you can upgrade the schema in the LDAP directory server. If you have only the Identity System deployed, or if you have a joint Identity and Access System with configuration and policy data stored together, you perform the task to upgrade the schema one time only: with the clone of the first installed COREid Server. When configuration and policy data are stored separately, you also need to upgrade the Access System schema. For more information about how this is done using the zero downtime upgrade, see "About Schema Mode Processing".
The upgraded schema offers backward compatibility with the earlier schema, as far back as release 6.1.1. However, Oracle Access Manager does not provide automated tools to roll back a schema upgrade. Some directory server vendors provide tools that you can use to back up the schema. If you did back up the schema before upgrading the schema, you should be able to reinstate the earlier schema if you decide to roll back to the original release. For more information, see "Backup and Recovery Strategies for Zero Downtime Upgrades".
Caution:
The zero downtime upgrade tools do not provide an automated way to roll back a schema upgrade.Both the original setup and the clone setup use the upgraded schema. After upgrading the schema, Oracle recommends that you perform validation tasks to ensure that everything is operating properly. For more information, see "Validating Successful Operations in Your Environment".
For details about upgrading the schema, see "Upgrading the Schema During a Zero Downtime Upgrade".
This topic introduces the configuration and policy data upgrade that occurs when you upgrade certain cloned components.
As discussed in Chapter 1, Identity System data includes:
In a joint Identity and Access System, the Access System data includes Oracle Access Manager access policy data.
Original instances use only the configuration and policy data that is stored in the original branch in the LDAP directory server. The original branch was set up when you installed the first COREid Server and first Access Manager in the original environment. Clone components use only the configuration and policy data that is stored in the new branch in the LDAP directory server. Configuration and policy data are upgraded in the new branch only. The original branch of the LDAP directory server remains untouched.
After you upgrade the schema, you can start upgrading clone instances and the configuration and policy data in the new branch. Data upgrades occur as follows:
If you have only the Identity System deployed, or if you have a joint Identity and Access System with configuration and policy data stored together, data is upgraded when you upgrade the clone of the first installed COREid Server.
If you have a joint Identity and Access System deployed with configuration and policy data stored in different directory servers, the access policy data is upgraded when you upgrade the clone of the first installed Access Manager.
During subsequent COREid Server (and Access Manager) clone upgrades, the initial data upgrade is detected and data upgrade activities are skipped. For more information about data upgrades for a zero downtime upgrade, see "About Clone Mode Processing".
No data is upgraded during original component upgrades with the zero downtime upgrade method. After upgrading original components, you will reconfigure these to use the new branch.
Any changes that are made to the original setup after creating and populating the new branch in the LDAP directory server will not be available in the clone setup. Similarly, any changes that are made to the clone setup will not be available in the original environment. Oracle recommends that you enforce a moratorium on changes to the original environment that affect configuration and policy data. Otherwise, you must repopulate the new branch of the LDAP directory server and upgrade clones a second time before you can upgrade original instances. For more information, see "About Retrieving Changes to the Original Branch Before Upgrading Original Instances".
Validation: Oracle recommends that you perform a number of validation activities to ensure that the clone and original environments are operating as expected following the schema upgrade (and the data upgrade). For more information about validation, see "Validation During a Zero Downtime Upgrade".
User data is not upgraded. The original searchbase is used by both the clone setup and the original setup.
Multiple values that are configured in challenge and response attributes for lost password management (LPM) are migrated with the first user login after the upgrade. No other user data attributes are migrated during a user's first login.
When you use the zero downtime upgrade method, you do not need to manually halt the migration of multiple values in challenge and response attributes for lost password management. Instead, this migration is automatically halted as a result of using the MigrateOAM script in Clone mode.
Even though the migration of multiple values in challenge and response attributes for LPM are suspended until you manually enable them, the lost password management functionality remains available for use.
Using the zero downtime upgrade method, you must manually restart user data migration after validating that your upgraded clone and original setup does not need to be rolled back to the earlier release.
You will only restart the migration of user data at first login at the end of the zero downtime task, after upgrading and validating your original setup. After upgrading and validating the upgraded cloned setup, you will not restart the migration of user data.
For more information about multiple values in challenge and response attributes for lost password management, see "Migrating User Data At First Login".
The following overview outlines the topics where you will find the preparation tasks that you must perform during a specific phase of the zero downtime upgrade. You do not need to perform these tasks now. The topics are provided as an introduction only and will be presented in the order in which they are to be used.
Topic overview: Preparation tasks for each phase are described in
Some of the preparation tasks that you will be instructed to perform are specific to zero downtime upgrades and are described in detail in the topics in the previous list. Other preparation tasks apply to both upgrade methods. In this later case, you will be directed to the actual details located in other chapters. For example, Chapter 5 provides steps to help you prepare for a schema and data upgrade when upgrading the clone of the first installed COREid Server and first installed Access Manager. Chapter 8 provides steps to help you prepare components.
Note:
If you do not perform all recommended preparation steps, you might not be able to recover from a problem or to roll back to the original release.About Preparing the Original Installation: Preparing the original installation includes adding profiles to the original System Console for cloned components. Regardless of the component or method, you need to prepare the host system and prepare earlier customizations. If you are upgrading a Web component, you will be instructed to back up the existing Web server configuration files. On Windows systems, you will be instructed to back up the Windows registry details for the component. When preparing a release 6.x environment or a multi-language installation there are other preparation activities.
About Preparing for Schema and Data Upgrades: When you upgrade the schema, you are instructed to back up the directory server instance and the schema. You will use vendor-supplied tools to perform these tasks as described in Chapter 5. Data upgrades occur when you upgrade the clone of the first installed COREid Server and Access Manager. The following list identifies the tasks that you will be directed to perform to prepare for data upgrades:
Clone of First Installed COREid Server: Perform the following backup activities as described in Chapter 5:
Clone of First Installed All Access Manager: Back up policy data, as described in Chapter 5.
About Preparing for Component Upgrades: Each Operating System provides a hierarchical tree structure where files are organized for storage and retrieval. After performing other preparation activities and before you upgrade each instance (whether clone or original), you will ensure that you have the 10g (10.1.4.2.0) MigrateOAM script in an appropriate location for that component. These activities are summarized as follows:
Source Creation: You must rename the subdirectory that contains the instance (whether the instance is a clone or an original instance) to create a source for the upgrade. In this guide, the source file system path will include "_source" as an identifier after the subdirectory is renamed. For example: np611\ois_01\identity_source
Each source provides all the configuration details for the corresponding instance. This information will be extracted during the instance upgrade. The source is not upgraded and can be used as a backup copy of the earlier instance.
Note:
You must create the source first because the destination will replace the clone or original location in the file system.Destination Creation: Extract 10g (10.1.4.0.1) Identity Server libraries and files and specify the same file system path that the clone (or the original instance if you are upgrading an original instance) had before you renamed it. In other words, the destination path must exactly match the path of the clone or original subdirectory before it was renamed to create the source. In this manual, the destination path is sometimes referred to as destination_dir.
The 10g (10.1.4.0.1) component libraries and files provide the foundation for the patch, and a destination for information that is extracted from the source during the upgrade. For more information, see "Destination Creation: Extracting 10g (10.1.4.0.1) Libraries and Files".
Obtaining the Tools: Apply Release 10.1.4 Patch Set 1 (10.1.4.2.0) to the 10g (10.1.4.0.1) instance to obtain the tools needed for the upgrade.
After the upgrade, this destination will include the instance that was upgraded to 10g (10.1.4.2.0) based on the source configuration details (and an updated Windows registry entry if it is on a Windows platform). For more information, see "Obtaining Tools: Applying Release 10.1.4 Patch Set 1 (10.1.4.2.0)".
For more information about original and clone environments, see the next topic.
Validation during a zero downtime upgrade is critical at several points. This topic introduces validation steps that you will use to ensure proper operations of cloned components and original components throughout the zero downtime upgrade process.
After upgrading the schema, you should confirm that both the clone environment and the original environment is operating without problem with the upgraded schema. Validation after the schema upgrade includes:
Confirming that the original environment is operating properly with the upgraded schema.
Confirming that the clone environment is operating properly with the upgraded schema.
After validating operations with the upgraded schema, you can begin upgrading cloned components. During certain clone upgrades, configuration data and policy data are upgraded:
When you have only the Identity System deployed, or if you have a joint Identity and Access System with configuration and policy data stored together, data is upgraded when you upgrade the clone of the first installed COREid Server.
When you have a joint Identity and Access System with configuration and policy data stored separately, access policy data is upgraded when you upgrade the clone of the first installed Access Manager.
Steps that you need to perform to validate that a particular task is successful are often embedded as steps within the procedure. You will see and perform these steps when you upgrade a clone instance and an original instance. Embedded steps help you determine that the procedure was successful. In addition, individual validation topics are provided at the conclusion of a sequence of procedures to help you validate results in the context of the overall system.
Task overviews like the one that follows provide an outline of the tasks that you must perform and provide a cross-reference link to the topic where you will find the information. In some cases, the description itself is a link to the information. If, as is the case in the following task overview, multiple items refer to the same topic, a general link is provided. For more information about the following task overview, see "Validating Successful Operations in Your Environment".
Task overview: Validation of clone and original instance upgrades
After upgrading and setting up the clone system, which includes upgrading all components, all customizations, and other manual upgrade tasks), you will proceed as outlined here:
Identity System Clones: Validating the Upgraded Cloned Identity System
Access System Clones: Validating the Upgraded Cloned Access System
After upgrading and setting up the original system, you will proceed as follows:
Original Identity System: Perform Identity System validation activities in Chapter 14
Original Access System: Perform Access System validation activities in Chapter 14
To help you with the more in-depth validation tasks, Oracle recommends that you develop deterministic test scripts to run both before and after your tasks to exercise a full end-to-end transaction. For more information, see "Customization Upgrades Using the Zero Downtime Upgrade Method".
If you plan a lengthy validation period, Oracle recommends that you completely isolate the clone and original setups. For more information, see the topic "About Isolating the Original and Cloned Environments", in the section "Duration of Zero Downtime Tasks and Validation".
Customized configurations that are built around your earlier Oracle Access Manager installation must be manually tested for compatibility before upgrading the original deployment. Oracle recommends that you upgrade your customizations and test these thoroughly with the upgraded clone system.
Customizations include those created for the front-end using IdentityXML, PresentationXML, and the Access Manager API (formerly known as the Access Server API or simply as the Access API). Also included are back-end customizations created with the Identity Event API, Authentication API, Authorization API (including AccessGates and plug-ins).
Testing and upgrading earlier customizations is primarily a manual process that can take some development time. It is important to plan ahead to ensure that your customizations can be redeployed into a shared environment quickly (for example, for QA, Integration, or Production).
Recommendation: Upgrading customizations and plug-ins
Start well in advance of other upgrades and review customization considerations here.
Note:
While not as critical when performing a zero downtime upgrade, you might find some information in "Planning Considerations for System Downtime During In-Place Upgrades" helpful.Develop deterministic test scripts to run both before and after the upgrade to exercise a full end-to-end transaction.
For example, the script could request a single page that requires authentication and authorization and a workflow request (all triggered by a single page request). Test scripts that verify the behavior of your earlier customizations help you ensure that these work as expected and produce the same result, both before and after the upgrade. Your test scripts will depend on the specific customization being exercised.
Compile and test the code, and the instructions you developed to explain how to configure the customization in a given environment.
In your original environment, test the earlier customization (styles, AccessGates, or plug-ins for example) to ensure that these are working properly.
To create a 10g (10.1.4.2.0) development deployment (ideally a sandbox-type setting) where the dependency on the overall Oracle Access Manager services is minimal:
Install 10g (10.1.4.0.1) in a small, isolated deployment. For installation details, see the Oracle Access Manager Installation Guide.
Use instructions in the Oracle Access Manager Patch Set Notes Release 10.1.4 Patchset 1 (10.1.4.2.0) For All Supported Operating Systems to apply Release 10.1.4 Patch Set 1 (10.1.4.2.0) to your 10g (10.1.4.0.1) component instance.
In the 10g (10.1.4.2.0) sandbox, test the earlier customization and perform any manual steps that are needed to upgrade the customization to operate with 10g (10.1.4.2.0) functionality. For information about specific customizations, see:
Perform a zero downtime upgrade to upgrade the schema, data, and clones as described in "Zero Downtime Upgrade Tasks and Sequencing".
After upgrading clones, integrate the upgraded custom components.
Validate the upgraded cloned environment as described in Chapter 14.
When you are satisfied that your upgraded customizations and upgraded cloned environment are working together without problem, finish the zero downtime upgrade by upgrading original components. For more information, see the following topics:
Finish by integrating upgraded customizations with the upgraded original environment and validate operations. For more information, see "Validating the Entire Upgraded Original Environment".
This section provides an overview of the tasks that must be performed when using the zero downtime upgrade methodology. Before undertaking any activity, Oracle recommends that you review all information about the zero downtime upgrade method and then decide if it is right for your environment.
When you use the zero downtime upgrade method, all tasks must be performed in the sequence that is illustrated in Figure 15-2. All tasks are required regardless of the size or type of deployment you are upgrading. For example, you might first use the zero downtime upgrade method in a small sandbox-type setting to get familiar with all procedures and tasks. You might then perform these same tasks in a larger deployment. The overview that follows Figure 15-2 provides additional information about each task and includes links to specific topics containing all the details.
Figure 15-2 Zero Downtime Upgrade Tasks and Sequence
Task overview: Upgrading using the zero downtime method and tools
Study every detail about the zero downtime upgrade method before you start any zero downtime upgrade activities.
Caution:
Before you perform any tasks using the zero downtime upgrade method, read through all information to gain a full understanding of what you must do.Develop your plan for a zero-downtime upgrade. For more information, see "Developing a Plan for a Zero Downtime Upgrade".
Prepare each host computer and earlier component instance for cloning. To perform this task you will:
Bring the host computer of each existing component up to a level that is supported by 10g (10.1.4.0.1). For more information, see Bringing Host Computers to Oracle Access Manager 10g (10.1.4.0.1) Support Levels .
Prepare directory server instances, as described in "Preparing Directory Server Instances and Data".
Add new hardware or earlier instances to expand, if desired, as explained in "Adding New Hardware or Earlier Instances to Your Deployment".
Add entries in the System Console for each clone instance that you will create (one clone for each original component and instance in the deployment). For more information about specific tasks, see the topics listed in Table 15-1.
Table 15-1 Summary of Profiles for Clone Instances for a Zero Downtime Upgrade
Topics that Describe How to Add Profiles for Clone Instances |
---|
Adding Profiles for Planned COREid Server Clones in the System Console |
Adding Profiles for Planned WebPass Clones in the System Console |
Associating WebPass Clone Profiles with COREid Server Clone Profiles |
Adding New Directory Server Profiles for Cloned COREid Servers |
There are no profiles for Access Manager clones, as described in "About Entries for Access Manager Clones" |
Adding a Profile for Access Server Clones |
Creating New Directory Server Profiles for Access System Clones |
Do not add entries for WebGate clones. Instead, perform activities in "Associating Original WebGates with Access Server Clones". |
Create a new Web server instance on each computer that is hosting cloned Web components and update the Web server configuration file by running server configuration update tools available with the original release.
Create a clone of each earlier component's installation directory in the file system (except WebGates). For more information, see "Cloning Earlier Components for a Zero Downtime Upgrade". You do not need to create WebGate clones because the upgraded Access Server provides backward compatibility with earlier WebGates. For more information, see "Access Server Backward Compatibility".
When instructed to do so, you must obtain the 10g (10.1.4.2.0) tools for zero downtime upgrade processing, as described in "About Destination Creation and Obtaining Tools for a Zero Downtime Upgrade".
For example, you will perform the following tasks as part of populating a new branch in the LDAP directory server, as part of upgrading the schema, as part of upgrading each cloned instance, and as part of upgrading each original instance:
Extract fresh 10g (10.1.4.0.1) component libraries and files for the instance to be upgraded: Identity Server, WebPass, Policy Manager, Access Server (and WebGate only when upgrading an original WebGate instance). Details are centralized in the topic, "Destination Creation: Extracting 10g (10.1.4.0.1) Libraries and Files".
Obtain and apply the Release 10.1.4 Patch Set 1 (10.1.4.2.0) to the 10g (10.1.4.0.1) libraries and files (also known as an instance) to obtain the MigrateOAM script that is required for zero downtime upgrade processing. Details are centralized in the topic, "Obtaining Tools: Applying Release 10.1.4 Patch Set 1 (10.1.4.2.0)".
For more information about zero downtime tools and processing, see "Zero Downtime Upgrade Tools and Processes".
Create a new branch in the same LDAP directory server that is used by the original environment, and then populate the new branch with a copy of the original configuration and data. You will use a function in the 10g (10.1.4.2.0) MigrateOAM script. For more information, see "Copying Configuration and Policy Data to a New Branch in the LDAP Directory Server".
Configure the clones to use the new branch in the LDAP directory server by using command-line tools in the cloned component directory. You will use a function in the 10g (10.1.4.2.0) MigrateOAM script. For more information, see "Configuring Cloned Components and Services".
Upgrade the schema in the LDAP directory server. You will use a function in the 10g (10.1.4.2.0) MigrateOAM script. For more information, see "Upgrading the Schema During a Zero Downtime Upgrade".
Validate your environments to ensure that both original and cloned components are working without problem with the upgraded schema. For more information, see "Validating Successful Operations in Your Environment".
Upgrade cloned components using a function in the 10g (10.1.4.2.0) MigrateOAM script and then validate the upgraded cloned environment:
Cloned Identity System: Upgrade and validate Identity System clones. For more information, see "Upgrading the Cloned Identity System". Configuration data in the new branch of the LDAP directory server is upgraded when you upgrade the clone of the first installed COREid Server. This activity includes tasks in "Renaming Audit Files After Upgrading Identity System Clones".
Cloned Access System: Upgrade and validate Access System clones. For more information, see "Upgrading the Cloned Access System". Policy data in the new branch of the LDAP directory server is upgraded when you upgrade the clone of the first installed Access Manager.
Perform any manual tasks to upgrade and integrate customizations so that you can test these with the upgraded cloned system:
Upgrade integration connectors and independently installed software developer kits (SDKs). For more information, see Chapter 11.
Upgrade Identity System customizations. For more information, see Chapter 12.
Upgrade Access System customizations. For more information, see Chapter 13.
Perform an in-depth validation of the entire upgraded cloned system to ensure that everything is operating without problem. For more information, see Chapter 14.
Changes to original data in the original branch: Repopulate a new branch with updated original data and then perform a new clone upgrade and validation tasks. Before you make your decision, see "About Retrieving Changes to the Original Branch Before Upgrading Original Instances". For steps, see "Retrieving Changes in the Original Branch Before Upgrading Originals".
Reconfigure network failover so that the clones substitute for original components while the originals are upgraded. For more information, see "Reconfiguring Domain Name Systems (DNS) to Use Upgraded Clones".
Upgrade original components, reconfigure originals to use the new branch in the LDAP directory server, and then confirm that the original upgraded components are operating without problem. You will use a function in the 10g (10.1.4.2.0) MigrateOAM script to:
Upgrade the Original Identity System: Upgrade, reconfigure, and validate the original Identity System. For more information, see "Upgrading Your Original Identity System".
Upgrade the Original Access System: Upgrade, reconfigure, and validate the original Access System. For more information, see "Upgrading Your Original Access System".
Upgrade and integrate original customizations. For more information, see "Validating the Entire Upgraded Original Environment".
Original Identity System Customizations: Upgrade, and then validate as described in "Upgrading SDKs and Identity System Customizations".
Original Access System Customizations: Upgrade, and then validate as described in"Upgrading SDKs, Integration Connectors, and Access System Customizations" .
After confirming that you will not roll back to either the earlier cloned or original deployment, start automatic user data migration. For more information, see "Starting On-the-fly User Data Migration".
Finish the upgrade as follows:
The actual length of time that is needed to upgrade and validate a deployment using the zero downtime method depends on the size and complexity of your original deployment. For example, when you have only one instance of each component in a joint Identity and Access System deployment with minimal plug-ins and customizations, it can take you a week to perform a zero downtime upgrade. This includes all tasks from planning through upgrading the schema and upgrading the data and the cloned environment.
Of course, validation must be performed to ensure that the upgrade was successful. You will want to perform validation tasks after upgrading the schema, after upgrading clones, after upgrading any customizations, and after upgrading the original instances. to ensure that the upgrade was successful. The deeper your validation is, the more time you need to perform it.
To help you with validation tasks, Oracle recommends that you develop deterministic test scripts to run both before and after your tasks to exercise a full end-to-end transaction. For more information, see "Customization Upgrades Using the Zero Downtime Upgrade Method".
Oracle recommends that you use the upgraded clone setup to explore release 10g (10.1.4.2.0) features. All functions will be available, including lost password management. However, the migration of multiple values in challenge and response attributes for lost password management will be suppressed. For more information, see "User-Data Migration and Multiple Values in Challenge and Response Attributes for LPM".
The more time that you spend getting acquainted with release 10g (10.1.4.2.0) features, the longer the period before you upgrade the original components. If you want to use the upgraded clone setup for a considerable amount of time (2 to 3 months, for example), Oracle recommends that you perform specific activities to completely uncouple the clone environment from the original environment. For more information, see "About Isolating the Original and Cloned Environments".
Oracle recommends that you do not change any data in the original deployment after you populate the new branch with original configuration and policy data. However, the decision to change data or not is strictly up to you. If any changes are made to the original setup during your validation of the cloned environment, you will need to take additional steps to copy the updated original data into the new branch and then upgrade the clones a second time. This will ensure that the data changes made in the original deployment are stored in the new branch of the directory before you set up network failover so that the clones replace the originals. Once the upgraded cloned environment replaces the original, it could take several weeks to upgrade the original environment.
Oracle recommends that you allow a time frame of about 3 months for upgrading and evaluation using the zero downtime method in a large scale, customized deployment.
This task is optional. If you plan to use the upgraded clone setup for a considerable amount of time (2 to 3 months, for example), Oracle recommends that you completely isolate the upgraded clone environment from the original environment.
The clone and original systems will operate independently and will use different branches of the LDAP directory server in any case. Isolating the two environments has no impact on the schema or data. Both the clone and original systems will use the upgraded schema.
You can perform these tasks either before upgrading the clone setup or after upgrading the clone setup and validating that it is fully operational, or not at all. There are implications if you choose to perform this optional task.
Before you decide if or when to perform this task, consider the following implications for a roll back and restart of the zero downtime upgrade:
Without original profiles in the clone System Console. In this case, there are no implications for roll back
Without clone profiles in the original System Console, you must re-enter these if you roll back and then restart the clone upgrade.
You must also re-enter clone profiles in the original System Console if you decide to create another new branch that includes changes made to original data during the clone system upgrade and validation period. For details about retrieving changes made to original data, see the next topic.
For steps to isolate environments, see "Isolating Environments".
You can use the upgraded clone system to perform validation tasks and to get acquainted with 10g (10.1.4.2.0) functions. For example, you can create new access policies and alter configuration data in the upgraded clone system.
Any changes that you make to the upgraded clone system are stored in the new branch of the LDAP directory server. These changes cannot be migrated to the original branch and cannot be used by original components.The new branch is not accessible by the original system until after you upgrade and reconfigure original components to use the new branch.
Lost password management functions are available for use in the upgraded clone system. However, multiple challenge and responses for lost password management cannot be used without modifying the user data. For more information, see "User-Data Migration and Multiple Values in Challenge and Response Attributes for LPM".
In the upgraded clone system, you can also customize stylesheets and files to test new customizations. You can retain new customizations in the upgraded clone environment. If you have customized files, you can transfer these to the upgraded original environment after you finish upgrading the originals.
If changes are made to the original branch in the LDAP directory server, after you create the new branch and before you upgrade the original, you can choose to retrieve it before you can upgrade original instances. This is an optional task that has implications for isolated environments. For details, see "Retrieving Changes in the Original Branch Before Upgrading Originals".
The zero downtime upgrade method uses the MigrateOAM script that is available only with Oracle Access Manager Release 10.1.4 Patch Set 1 (10.1.4.2.0). To obtain the tool, you will install one instance of each Oracle Access Manager 10g (10.1.4.0.1) component, and then apply Release 10.1.4 Patch Set 1 (10.1.4.2.0) to each 10g (10.1.4.0.1) component. For more information, see "About Destination Creation and Obtaining Tools for a Zero Downtime Upgrade".
The MigrateOAM script provides the following functional modes to help you perform specific tasks during the zero downtime upgrade:
Mkbranch: Populates the new branch that you create in the original LDAP directory server instance with a copy of the original configuration and policy data.
Schema: Upgrades the schema in the LDAP directory server, which will be used by both the original and the clone environment.
Clone: Upgrades clone components and upgrades configuration and policy data in the new branch.
Prod: Upgrades original components, which must be reconfigured to use the new branch.
Table 15-2 provides a general summary of the mode arguments and specifications that are required with the MigrateOAM script. Individual procedures for the zero downtime upgrade activities provide the exact arguments and specifications for that task.
Table 15-2 MigrateOAM Argument and Specifications Summary
MigrateOAM Arguments | Values and Specifications |
---|---|
File system path to the 10g (10.1.4.2.0) MigrateOAM script |
Change to the 10g (10.1.4.2.0) file system path where the MigrateOAM script resides for the instance and the task that you are performing. For example: Windows clone_np\identity\oblix\tools\migration_tools Unix /home/clone_np/identity/oblix/tools/migration_tools |
-script name |
Windows: MigrateOAM. bat Unix: MigrateOAM.sh |
-M Mode |
Specify the appropriate mode for the task that you are performing:
|
-C component |
Specify the appropriate component designation for the task:
|
-F nnn |
Specify the number that identifies your earlier release. For example:
|
-T 1014 |
Specify 1014 as the "to" release, the release to which this component will be upgraded. |
-S "source directory" |
Specify the full path (in quotation marks) to the renamed file system directorythat contains the earlier source information for the specified component (whether clone or original instance). For example:
Note: The source provides configuration details for the existing earlier component. This file system directory remains intact during any upgrade activities. |
-D "destination directory" |
Specify the full path (in quotation marks) to the file system directory that contains the 10g (10.1.4.2.0) MigrateOAM script for the component instance. For example:
Note: The destination contains 10g (10.1.4.2.0) information, which will be updated based upon details from the earlier source directory. |
-I "installation directory" |
The installation directory should always match the destination. For example:
Note: This file system directory is referenced by the script and underlying tools. It contains the 10g (10.1.4.2.0) script and tools. |
As with other command line tools, you must enter all arguments and specifications as a single line. In this manual, and on your screen, the line will wrap and might look something like the following example:
cd \1014\identity\oblix\tools\migration_tools>MigrateOAM.bat -M Mkbranch -C OIS -F 610 -T 1014 -S "C:\clone_np\ois_01\identity" -D "C:\1014\identity" -I "C:\1014\identity"
Processing begins when you press the Enter key. Messages and prompts keep you informed about what is occurring. The same sequence of messages and prompts will appear for each operational sequence from your starting release (6.1.1 for example) to the latest release, 10g (10.1.4.2.0) which might be referred to as simply 10.1.4. This means that you might see a sequence of messages and prompts more than once.
Oracle recommends that you accept and conduct operations using the Automatic operational mode when asked and that you do not skip any processes. The Confirmed operational mode requires more interaction from you and could result in a skipped operation that could lead to an unsuccessful outcome.
During each component upgrade, one or more log files are produced. These files are created if any problem occurred. If a log file is created, a message during the upgrade process indicates the name and location of the file.
For some operations, the MigrateOAM script calls utilities that are used during an in-place upgrade. Each log file contains information about a particular activity that occurs during the component upgrade. For example, a separate log file might be generated for file upgrades, or message and parameter upgrades, or the Oracle Access Manager schema upgrade, to name a few. For information about specific log files and their content, see Appendix C.
The MigrateOAM script produces a single log file when you use Mkbranch mode. The Mkbranch log file is stored in the destination file system path. For example:
where \destination_dir is the file system directory for the specific component libraries and files that were extracted and patched; identity|access represents the system to which the component belongs (Identity System or Access System, respectively); and makebranch.log is the name of the file.
In addition, the following log files are created to inform you of any LDAP-specific errors:
During Identity Server data migration, error_output_fromversion_to_toversion_osd.ldif file is created in the destination file system path for the specific component. For example, IdentityServer_destination_dir\identity\oblix\tools \migration_tools\obmigratedata directory in the file system.
During Policy Manager data migration, error_output_fromversion_to_toversion_psc.ldif file is created in the destination file system path. For example: PolicyManager_destination_dir\access\oblix\tools\migration_tools\obmigratedata directory in the file system
For details about using log files, see Appendix G.
For more information about the processes and utilities that are called for each mode, see the following topics:
This topic introduces the MigrateOAM script Mkbranch mode, which is used to populate a new branch in the LDAP directory server with a copy of the original configuration and policy data.
Before you use this mode, you must manually create the new branch node as a child node of original configuration base (also known as the configuration DN) and policy base (also known as the policy DN). For example:
o=company,c=us
o=Newbranch,o=company,c=us
o=Policy_base,o=company,c=us
o=NewPolicyBase,o=Policy_base,o=company,c=us
The new branch must be in the same LDAP directory server instance as the original branch. The original branch will not be altered. You can define the new config DN as follows:
o=Newbranch,<OldConfigDN>
and o=NewPolicyBase,<oldPolicyBase>
o=Newbranch,o=company,c=us
where o=company,c=us
is the old config DN
o=Newbranch,dc=us,dc=company,dc=com
where dc=us,dc=company,dc=com
is the old config DN
During Mkbranch mode processing, a copy of the data is modified for the new configuration DN or policy DN and then imported into an ldif file. The imported data is then exported from the new ldif file into the new branch.
The tools that are called and the processes that are automatically performed during the Mkbranch operation are shown in Figure 15-3.
When you have only the Identity System, there is no policy data. In this case, you use the Mkbranch mode with only the clone of the first installed COREid Server. The original configuration data is copied into the new branch.
When you have a joint Identity and Access System and configuration and policy data are stored together in the same LDAP directory server node, data is copied together when you use the Mkbranch mode with the clone of the first installed COREid Server. However, if policy data is stored in a different branch or on a different directory instance, you must repeat the Mkbranch operation with the clone of the first installed Access Manager to copy policy data into the new branch.
Figure 15-3 Overview of MigrateOAM MkBranch Function and Processes
Process overview: Populating the new branch with MigrateOAM
After you enter the Mkbranch command and specifications, the earlier source directory is detected in the file system.
The directory connection is established and the new configuration DN is requested:
Data in the original branch is read and copied.
The copy is massaged for the new configuration DN (and policy DN if both are stored together), and exported to an LDIF file. A success or failure message appears.
The copied data is imported from the LDIF file to the new branch.
A success or failure message appears.
This sequence repeats when you have configuration and policy data stored separately and you use Mkbranch mode with the clone of the first Access Manager component that was installed and set up.
This topic introduces the schema upgrade processing that occurs when you execute the MigrateOAM script in Schema mode.
With the zero downtime upgrade method, a schema upgrade is performed only with cloned components that interface with the directory server: Identity Server and Policy Manager. The number of times that you must perform a schema upgrade depends on the way in which data is stored. For more information, see "Upgrading the Schema During a Zero Downtime Upgrade".
During the schema 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 upgrades (like all other 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.
After the upgrade, you can review the following log files for more information about the processing:
destination_dir\identity|access\oblix\tools\migration_tools\obmigratenp.log
destination_dir\identity|access\oblix\tools\migration_tools\obmigrateschema.log
When you execute the MigrateOAM script in Schema mode, processes to upgrade the schema in the LDAP directory server are launched, as shown in Figure 15-4.
Figure 15-4 Overview of MigrateOAM Schema Mode and Process
Process overview: During the schema upgrade with MigrateOAM
After you launch MigrateOAM and specify the Schema mode and specifications, the source directory is detected in the file system:
You are asked to choose either Automatic operational mode or Confirmed operational mode. Oracle recommends that you choose Automatic.
The utility obmigratenp is called to determine which other utilities should be called and to manage language migrations.
The utility obmigrateds is called, which:
Reads configuration files, assesses schema data (OSD), and determines the directory server with which Oracle Access Manager is communicating.
Gathers the information required to connect and bind to the directory server.
Locates the schema file for the specific directory type, and the from and to versions, then uploads the appropriate ldif file to the directory server using the ds_conf_update.exe utility.
Using information read from the OSD (for example, 'o=oblix, ..'node) and configuration files, obmigrateds creates an input map file to be passed to obmigratedata.exe.
For example, for osd, policy, and workflow upgrades:
data_fromrelease_to_torelease_osd.lst
For example, for user data upgrade:
data_fromrelease_to_torelease_user.lst
The upgrade sequence for the schema begins, based on the component and data storage in your LDAP directory server:
First Installed COREid Server, the Identity System schema is upgraded starting from the earliest release to the next later release (from 6.1.1 to 6.5, for example).
First Installed Access Manager: The Access System schema is upgraded starting from the earliest release to the next later release (from 6.1.1 to 6.5, for example). For more information, see "Upgrading the Schema During a Zero Downtime Upgrade".
Step 4 repeats as needed, to continue the upgrade from the point where it concluded to the next later release (from 6.5 to 7.x, for example); this continues until release 10.1.4 is reached.
You are asked to confirm and conclude.
This topic introduces the processing that occurs when you use MigrateOAM Clone mode to upgrade clone components. Configuration and policy data in the new branch of the LDAP directory server are also upgraded, as follows:
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 and Policy Manager.
Files that contain both object-class and attribute mappings are provided for this purpose. The object and attribute mapping files reside in the obmigratedata file system directory. For example:
IdentityServer_install_dir\identity|access\oblix\tools\migration_tools\
obmigratedata
The MigrateOAM script processing that occurs when you use the Clone mode is shown in Figure 15-5. The copied configuration data in the new branch of the LDAP directory server is upgraded only when you upgrade the clone of the first installed COREid Server. Copied policy data in the new branch of the LDAP directory server is upgraded only when you upgrade the clone of the first installed Access Manager. Data in the original branch of the LDAP directory server remains intact and untouched.
Figure 15-5 Overview of MigrateOAM Clone Function and Process
Process overview: During a clone component upgrade with MigrateOAM
After you launch MigrateOAM and specify the Clone mode and details for this clone instance, the file system source is detected.
Note:
If you upgrade an existing multi-language implementation without 10g (10.1.4.0.1) Language Packs, you will lose multi-language functionality.A utility (obmigratenp) is called to detect which features need to be upgraded for this particular component based on the release you are upgrading from and the release you are upgrading to.
obmigratenp calls other utilities as needed. When your installation includes multiple languages, obmigratenp migrates message catalogs. Also, obmigratenp oversees data and file migration.
Note:
Installed languages are upgraded when you include appropriate 10g (10.1.4.0.1) Language Packs for each installed language in the same directory in the file system as the 10g (10.1.4.0.1) component installer.The obmigratefiles is called to upgrade earlier program and library files. For more information about obmigratefiles, see "File Upgrade: obmigratefiles".
obmigrateparamsg is called to upgrade earlier message and parameter catalog files. For more information about obmigrateparamsg, see "Message and Parameter Upgrade: obmigrateparamsg".
Data Upgrades: obmigrateds is called in NoSchema mode for a data only (not schema) upgrade. The data upgrade occurs in a sequence that brings the data from the earlier release to the next latest release until the data is upgraded for 10.1.4.
obmigrateds is called only with the clone of the first COREid Server that you installed and set up (and the clone of the first Access Manager that you installed and set up). During subsequent clone upgrades, the data upgrade is detected and skipped.
No data in the original branch of the LDAP directory server is upgraded. For more information about data upgrades, see "About Configuration and Policy Data Upgrades". For more information about obmigrateds, see "Schema Upgrade: obmigrateds".
A component-specific utility is selected and run to make changes to related registry entries for Windows, plug-ins, and other files. The component's configuration files are updated in a sequence that repeats from your earlier release to the next latest release, and so on until 10.1.4 is reached. This might be interspersed with data upgrades when you are upgrading the clone of the first installed COREid Server (or Access Manager). A single tool is called for the corresponding component upgrade, as follows:
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, 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, 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 about the items that are upgraded and converted, see "Upgraded Items". For details about the obmigratenp utility, see "Access Server: obMigrateNetPointAAA".
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).For more information about "Software Developer Kit (SDK): obMigrateNetPointASDK".
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 Guide.Web Server Configuration Updates: A utility (obmigratews) is called to perform a selective Web server configuration file and filter upgrade, to accommodate changes for newer releases of WebPass, Access Manager, and WebGate. For more information, see "Web Server Upgrade: obmigratews".
Process concludes with final remarks.
This topic discusses the differences between upgrading with MigrateOAM in Prod mode (production or original instance mode) versus Clone mode.
The processing that occurs when you upgrade original components using the MigrateOAM script in Prod mode is nearly the same as when you upgrade clone components using MigrateOAM script in Clone mode.
In Prod mode, the following exception applies: obmigrateds is not called; no schema or data upgrades occur when upgrading the first COREid Server or Access Manager that was installed.
After upgrading original components, you must reconfigure the upgraded originals to use upgraded data in the new branch of the LDAP directory server. This is explained in detail in Chapter 17.
Many of the same back up and recovery strategies that are discussed for in-place upgrades also apply to a zero downtime upgrade. Rather than repeat the same information with zero downtime procedures, you will be instructed to find the information in the original location in this manual. Table 15-3 lists the information that you will be instructed to back up and the location of that information in this manual.
Table 15-3 Back Up Strategies Before a Zero Downtime Upgrade
Back Up the Following | As Described In |
---|---|
Oracle Access Manager Schema |
Chapter 5: Backing up the Earlier Oracle Access Manager Schema |
Oracle Access Manager Configuration and Policy Data |
Chapter 5: Backing up Oracle Access Manager Configuration and Policy Data |
Oracle Access Manager User and Group Data |
|
Oracle Access Manager Workflow Data |
|
Processed Workflows |
|
Existing Directory Instances |
|
Web Server Configuration Files |
Chapter 8: Backing Up the Existing Web Server Configuration File |
Windows Registry |
The following details will give you an idea of what to expect during a zero downtime upgrade. Do not perform these tasks now.
The Zero Downtime Schema Upgrade: The upgraded schema offers backward compatibility with the earlier schema, as far back as release 6.1.1. However, you cannot roll back a schema upgrade using any Oracle-provided tools. If you backed up the earlier schema using external tools before upgrading, you should be able to reinstate the backup copy if you decide to roll back to the original release. Look for details in Chapter 5.
The Zero Downtime Data Upgrade: Data in the original branch of the directory server is not modified during a zero downtime upgrade. However, it is a good idea to perform the data backup tasks in Table 15-3 before you create and populate the new branch in the LDAP directory server during the zero downtime upgrade.
Oracle Access Manager Instance Upgrades: With the zero downtime upgrade method you do not need to back up the original instance file system directory. The source that you will create remains intact during an upgrade and becomes a back up copy. For more information, see "Preparation Tasks for the Zero Downtime Method". Source creation does not take care of Web server configuration details or Windows registry details for an instance. For details about backing these up before each instance upgrade, see Chapter 8.
Backing Up After Upgrading: Most tasks finish with specific steps that help you quickly assess whether the procedure was successful or not successful. Oracle recommends that you finish upgrading the Identity System (whether clone or original) and validate that it is fully operational before you back up upgraded Identity System information. If you have a joint Identity and Access System, upgrade and validate the Access System (whether clone or original) before you back up the upgraded Access System.
The information that you back up is similar whether you have upgraded a clone or the original instance. For instance, you will back the upgraded component file system directory and customization directories, as well as Web server configuration file and the Windows registry entry if needed.
Table 15-4 lists the topics that discuss backing up after zero downtime upgrade tasks.
Table 15-4 Back Up Strategies After a Zero Downtime Upgrade
Back Up the Following | As Described In |
---|---|
Upgraded Cloned Identity System |
|
Upgraded Cloned Access System |
|
Upgraded Original Identity System |
Chapter 17: Backing Up the Upgraded Original Identity System |
Upgraded Original Access System |
When something does not operate as expected after a zero downtime upgrade task (whether the instance is a clone or an original), you can pursue one of the following courses of action:
Recovery is a process where you can perform steps to restore the earlier instance (either cloned or original), and then try the upgrade again.
Caution:
Recovery strategies can be successful only when you have performed appropriate backup tasks when instructed to do so.Chapter 2 provides general information about recovery procedures that you can follow. For more information, see Table 2-3, "Upgrade Recovery Strategies". In addition:
Each zero downtime upgrade task includes one or more steps to help you assess if there is any problem with the specific instance at the end of the task. Rrecovery steps that you can perform immediately are generally included.
Specific recovery topics are provided for the zero downtime upgrade method. For details, see Table 15-5.
Table 15-5 RecoveryTopics for a Zero Downtime Upgrade
Task | See Topic in |
---|---|
Create Clone Profiles |
Chapter 16: Recovering From Issues With Information Entered in the System Console |
Creating and Populating a New Branch in the Directory Server |
Chapter 16: Recovering from Problems With Populating the New Branch |
Identity System Clone Upgrade |
Chapter 16: Recovering From a Cloned Identity System Upgrade Failure |
Access System Clone Upgrade |
Chapter 16: Recovering from a Failed Cloned Access System Component Upgrade |
Original Identity System Upgrade |
Chapter 17: Recovering From an Original Identity System Upgrade Failure |
Original Access System Upgrade |
Chapter 17: Recovering From an Original Access System Upgrade Failure |
Rolling back is a process where you undo everything that you have done and return to the original setup and the starting point of the zero downtime upgrade. You will have only your original installation and the original release level after rolling back.
Having only one WebGate will result in downtime when rolling back. Oracle recommends that you have more than one WebGate to avoid downtime. Alternatively, you can keep the older WebGate and not upgrade it because it will work with the upgraded Access Server.
Table 15-6 Rolling Back During a Zero Downtime Upgrade
Task | See Topics In |
---|---|
Clone Profiles in the System Conslle |
Chapter 16: Rolling Back to the Starting Point After Entering Clone Details |
Cloning Instances |
|
Creating and Populating a New Branch in the Directory Server |
Chapter 16: Rolling Back Changes Made for the New |
Reconfiguring Clones To Use the New Branch |
|
Schema Upgrades |
|
Data Upgrade or Identity System Clone Upgrades |
Chapter 16: Rolling Back After Upgrading Identity System Clones |
Data Upgrade or Access System Clone Upgrades |
Chapter 16: Rolling Back After Upgrading Access System Clones |
Original Identity System Upgrades |
Chapter 17: Rolling Back After Upgrading the Original Identity System |
Original Access System Upgrades |
Chapter 17: Rolling Back After Upgrading the Original Access System |
For information about Windows registry entries during a rollback operation, see "Reinstating Original Windows Registry Entries During a Rollback Operation".
This topic explains how to reinstate the registry entry when you are rolling back after upgrading original component instances that are installed on a Windows platform. This topic is not relevant for other platforms.
During Oracle Access Manager component installation on a Windows platform, a Windows registry entry is created for the instance. The Windows registry entry always points to the installed location and the product release (Oracle Access Manager release 6.1.1 for example). The registry entry is created after specific installation phases based on the type of Oracle Access Manager component you are installing:
When you install an Identity Server or Access Server, the Windows registry entry is created after you specify the service name for the instance.
When you install Web components (WebPass, Policy Manager, and WebGate), there is no service name. In this case, the Windows registry entry is created after the libraries and files are extracted into the specified installation path.
Windows registry details are not transferable. As a result, you cannot copy libraries and files from one installed location to another and then use the services in the new location. However, when you upgrade a component, the original registry is deleted and a new entry is created for the latest release. This means:
After upgrading, the Windows registry will contain only the entry for the upgraded instance in the destination file system path.
After upgrading, you cannot roll back and use the original instance unless you can reinstate the original registry entry. Otherwise, the Oracle Access Manager service will fail.
To help ensure and streamline the roll back procedure, Oracle recommends that you back up the Windows registry entry for each original instance immediately before you start upgrade activities for the instance. This means that before you rename the original file system path to create a source for the zero downtime upgrade, you must back up the original Windows registry entry. In fact, Step 1 of each upgrade procedure directs you to perform specific preparation tasks that are described in detail in Chapter 8. Backing up file system directories, Web server configuration files, and Windows registry details are among those tasks.
The following approaches are available to reinstate the original registry entry when you roll back:
Recommended: Back up the original registry entry before you rename the original instance file system path to create an upgrade source.
Oracle recommends that you export registry details for the instance (whether clone or original) before starting upgrade activities for each instance. This enables you to import the registry entry if you decide to roll back to the original release.
Alternative: Reinstall the original instance during the rollback task.
If you do not have a backup registry entry to import during a rollback, there is no automated way to reinstate the entry. In this case, you must start the original component installation anew. After the registry entry is created, you will end the installation process and then copy original configuration details from the source that was renamed before the upgrade. For details, see "Generating a New Registry Key To Use When Rolling Back an Original Instance Upgrade" in the appendix on troubleshooting.
Before you start any zero downtime upgrade activities, it is important to read through this entire chapter. For downtime assessment planning for in-place upgrades, see "Duration of Zero Downtime Tasks and Validation".
Whether you perform an in-place upgrade or you use the zero downtime upgrade method, you need to develop a solid plan for prerequisite and upgrade tasks. Your planning deliverables will include an inventory of details that you have gathered for all existing component instances in your deployment.
You need to collect and record specific details about each component and instance in your original deployment. Planning and tracking summaries are provided in Appendix F.
When developing a plan for a zero downtime upgrade, you perform the following tasks. After your planning is complete, you are ready to start upgrading as described in Chapter 16.
Figure 15-6 Developing a Zero Downtime Upgrade Plan
Task overview: Developing a plan for a zero downtime upgrade
Review all information about the zero downtime upgrade in this chapter, and in Chapter 16 and Chapter 17.
Take all zero downtime upgrade considerations into account as you begin to develop your plan For example:
Identify original components to be upgraded immediately, and record details in your planning documents. For more information, see the sumamries in Appendix F.
Identify components that can be upgraded later (dormant Access Servers, WebGates, and the Software Developer Kit (SDK)).
Develop a plan to manually migrate items that are not upgraded automatically, as described in "Items that You Must Manually Upgrade".
Take the following general planning considerations into account:
Deployment Scenarios: The upgrade task should be performed in a sequential order in relation to the deployment approach adopted in your organization: Identity System only versus Joint Identity and Access System; intranet versus extranet; number and type of installed environments.
For example, if you have an earlier Identity System-only release deployed for intranet-only use with three different LDAP environments (one for Development, another for Test/Demonstration, and one Production deployment), the upgrade process should be performed and fine tuned in the smaller environments before ultimately being performed in your production environment. For more information about deployment types, see .
Stability: Each deployment that you upgrade should currently be running a stable and appropriately installed release. In other words, each earlier Oracle Access Manager configuration must be confirmed to be stable and complete before you start upgrading.
A good approach to validate that the original environment is stable is to develop a deterministic test script and run it both before and after the upgrade. For example, the script could exercise a full end-to-end transaction by requesting a single page that requires authentication and authorization and a workflow request (all triggered by a single page request). This script can also help you validate that a task was successful and that the system is still operating without problem after upgrading clones or original components.
Administrative Access: Schema upgrade operations (as well as other upgrade operations) require administrative access with write permissions to the LDAP directory server and Oracle Access Manager files.
Schema and Data Upgrades: These are performed independently when you use the zero downtime upgrade method. For more information, see "Schema and Data Upgrades with the Zero Downtime Upgrade Method".
Customization Upgrades: This is primarily a manual process. Oracle recommends that you complete any testing and alterations in a development environment before redeploying these in a shared or production environment. For more information, see "Customization Upgrades Using the Zero Downtime Upgrade Method".
Take Inventory of the Earlier Deployment: If you have not already recorded the exact details of the earlier Oracle Access Manager installation, be sure to include details for Identity and Access components, LDAP directory servers, Web servers, and applications as indicated in Table 15-7 (repeated from Chapter 1). Planning summaries that you can either use as a reference or duplicate and fill in are provided in Appendix F.
Table 15-7 Inventory of Earlier Deployment Details
Detail Types | Description |
---|---|
Transport security mode; Simple, Cert, or Open Root CA details if certificate mode is used Any host definition type entries relevant to NetPoint (for example, /etc/host) |
|
Identity Server Inventory |
Workflows, search bases and ACLs Object definition details for all objects managed through NetPoint, if possible Auditing configuration details Password policy configuration |
Access Server Inventory |
Policy domains, authentication schemes, resource definitions, host identifiers Auditing configuration Directory profile information |
Application Tier details that will be impacted during the upgrade |
Any WebGate protected integration that uses Cookies or header variables (the impact on these should be minimal) Any custom AccessGate integration created using the API, which can have a more noticeable impact. Applications exposing Oracle Access Manager Identity Portal Inserts (such as portals). Look carefully at these to ensure that "service temporary unavailable" pages can be displayed during the upgrade process when access to workflows is unavailable. Applications relying on IdentityXML are significantly impacted because the IdentityXML service might be unavailable altogether (it could be complicated to separate read-only calls from write calls and might be best to disable the entire application during the upgrade process.) |
Administration and Presentation tier details for each WebGate, WebPass, and Web server |
Web server type, version, operating system, WebPass or WebGate identifier and exact patch version of the binary (for example, 6.1.1.19 or 7.0.4.2) Exact Oracle Access Manager patch version (for example, 6.1.1.19 or 7.0.4.2) WebPass or WebGate installation directory in the file system Connection information between the component and corresponding Oracle Access Manager Server, including primary or secondary status and number of connections |
Details for each and every AccessGate, WebGate, Policy Manager, application server integration Note: Policy Manager was formerly known as the Access Manager component |
HTTP Cookie domain, preferred host name, cache timeout and size, failover threshold Inventory any IdentityXML client that has been custom developed Inventory any virtual IP and DNS aliases used to reference the WebPass or Web server farm protected with WebGate, such that it would be feasible to alter their definition in cases where staged upgrade of the Web server components (WebPass and WebGate be planned/required) |
Oracle Access Manager Server Tier (for each Identity and Access Server) |
Exact patch level (6.1.1.19 or 7.0.4.2, for example) Installation directory for the Identity or Access Server Installation directory for the associated WebPass or WebGate TCP port number for the service for example, port 6021) Host name (DNS) and Identity (formerly COREid) Server identifier For the Access Server, note the status of the Access Management flag (on or off) Inventory any customizations performed Identify any Identity Event plug-ins For the Access Server, note any customized authentication or authorization plug-ins Record any file-based changes such as changes in globalparams.xml or .lst files Record any PresentationXML and XSL stylesheet customizations Are the Identity Server (and Access Server) configured to audit to files or a database For Unix systems, record the user name and group membership for the Identity Server (formerly known as the COREid Server) |
LDAP Directory Server Tier |
Exact LDAP directory server version and patch level for example, Sun ONE v5.2 SP2) LDAP directory server DNS name and Port Transport security mode: LDAP, LDAPS, ADSI Binding credentials used by Oracle Access Manager DIT and schema objects used in Oracle Access Manager Master/replica configuration details For more information, see "Schema and Data Upgrades with the Zero Downtime Upgrade Method". |
Customization Assessment and Planning |
Ensure that any custom developed plug-ins, Access Manager API clients, IdentityXML clients, PresentationXML customizations, Portal Inserts, and customized styles are compatible with Oracle Access Manager 10g (10.1.4.0.1). This is primarily a manual process. For more information, see: |