Skip Headers
Oracle® Access Manager Upgrade Guide
10g (

Part Number E12495-01
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Index
Go to Feedback page
Contact Us

Go to previous page
Go to next page
View PDF

G Troubleshooting the Upgrade Process

In addition to the guidelines and techniques presented throughout this guide, this chapter provides troubleshooting details that you can employ during or after the upgrade process. Topics include:

G.1 Accessing Log Files

During each component upgrade, one or more log files might be produced to inform you if any problem should arise. If a log file is created, a message during the upgrade process indicates the name and location of each log file created. In general, you can find upgrade log files in:

Log File Path:


where \Component_install_dir is the directory where the specific component is installed; identity|access represents the system to which the component belongs (Identity System or Access System, respectively); and toolname represents the name of the utility that produced the log. For example, the following log files might be generated:

General Log Files
obmigratenp.log (generated by the main tool obmigratep which calls the other
obmigratefiles.log (generated by the obmigratefiles tool that reads a given
map-file and copies files from source directory to target directory based
upon the mapping list)
obmigrateparamsg.log (generated by the obmigrateparamsg tool which
performs the parameter and message catalog upgrade)
obmigrateds.log (generated by the obmigrateds tool which performs the schema
and data upgrade)

Component-specific Log Files
obmigrateNetPointOIS.log (Identity Server)
obmigrateNetPointWP.log (Webpass)
obmigrateNetPointAM.log (Policy Manager)
obmigrateNetPointAAA.log (Access Server)
obmigrateNetPointWG.log (WebGate)

Zero Downtime Mkbranch Log File
makebranch.log (Identity Server and Policy Manager)

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.

In general, log files include the following information that you can use to troubleshoot specific problems:

For information about specific log files, their content, and the tools that generate them see Appendix C, "Upgrade Process and Utilities".

Additionally, the following files are created to log any ldap specific errors:

G.2 Accessing Data Issues

If you receive a "Cannot find <person> Object Class" error after upgrading the schema and data, the problem might be that the master Access Manger component used to upgrade the schema and data did not use the same transport security as the original component.

If the original Access Manager component is installed and configured using SSL-enabled communication with the directory server, then the master component that you add to upgrade the Access System schema and data must also use SSL-enabled communication with the directory server.

For more information, see "Adding an Earlier Access Manager to Use as a Master for the In-Place Method".

G.3 Access Server Not Processing Earlier WebGate Data Properly

If you have a newly installed Access Server that does not appear to process information from an earlier WebGate, there might be a backward compatibility problem.

Upgraded Access Servers are automatically enabled for backward compatibility with earlier WebGates. However, a new 10.1.4 Access Server does not provide backward compatibility. If you install a 10.1.4 Access Server in an environment that includes earlier WebGates, you must manually set the "IsBackwardCompatible" Value="true" in the newly installed Access Server globalparams.xml to enable communication with earlier plug-ins and interfaces, as well as earlier WebGates and custom AccessGates. See also "Access Server Backward Compatibility".

G.4 Auditing and Access Reporting Issues

If you had auditing and access reporting configured in your earlier environment, you need to perform specific steps to ensure you can continue using this function. Otherwise, you might notice that some language characters (for example, Chinese or Japanese) in audit records are not being inserted correctly.

The steps you need to take to accommodate globalization changes, even when you have an English only environment, depends on the type of database you are using.


Simply upgrading or altering existing database instances and tables is not supported and could result in permanent truncation and loss of existing data.

In addition, when upgrading the master Identity Server and the schema and data from any release earlier than 700 the audit file name is changed by prefixing the path to the master Identity Server. If your deployment includes multiple Identity Servers, the audit file name for each will be prefixed by the same Identity Server installation directory path as the Identity Server from which the data upgrade is performed. The result is that your original configuration is lost during the Identity Server upgrade.

The following task overview provides details that you need to correct audit and access reporting issues.

Task overview: Correcting auditing and access reporting issues

  1. If your environment includes an Oracle database instance for auditing, you can check to ensure that your database character set is AL32UTF8.

  2. Review and complete all steps in "Upgrading Auditing and Access Reporting for the Identity System".

  3. Review and complete all steps in "Renaming Audit Files After Upgrading the Schema and Data".


    If you are using the zero downtime upgrade method, see "Renaming Audit Files After Upgrading Identity System Clones".
  4. Review and complete all steps in "Upgrading Auditing and Reporting for the Access Server".

G.5 Authentication Failures

Users with non Latin-1 login IDs might not be able to log in successfully when using a custom form. This problem can occur when you have internationalized data in your custom login forms, but you have not updated the login HTML encoding to UTF-8.

As discussed in Chapter 4, "System Behavior and Backward Compatibility", in 10.1.4, form-based authentication supports non-ASCII login credentials (username/password). When you use form-based authentication with 10.1.4 WebGates, you must ensure that character set encoding for the login form is set to UTF-8.


Basic Authentication fails with non-ASCII login credentials. Use form-based authentication for non-ASCII login credentials. Use Basic Authentication with ASCII login credentials.

To correct problems with form-based authentication, see "Upgrading Forms-based Authentication".

G.6 Authorization Failure Re-direct Problems After Upgrading from 6.1.1

Problem: Authorization failure redirects might not work as expected after upgrading from release 6.1.1.

Cause: A new authorization inconclusive state was introduced in release 7.x (apart from authorization success and failure states).

Solution: In the Authorization Rule, be sure to specify an explicit Deny rule and change Allow takes precedence to Yes under the General panel. For more information, see "Assuring Proper Authorization Failure Re-directs After Upgrading from 6.1.1".

G.7 Challenge and Response Phrase Issues

Problem: If your earlier environment has the challenge phrase and response attributes on separate panels, then the response attribute will not be displayed in the Profile page.

Cause: In earlier releases, the challenge phrase and response attributes were allowed on different panels of the Profile page of the User Manager, Group Manager, and Organization Manager. In 10.1.4, however, both the challenge phrase and response attributes must be on the same panel.

Solution: You need to update your panel definitions to include the response attribute on the same panel as the challenge attribute. For more information, see "Combining Challenge and Response Attributes on a Panel".

G.8 Challenge Response Might Not Convert Properly

If you choose to manually migrate data during an upgrade (exporting user data from old instance into new instance which is not recommended), the Challenge Response for lost password management might not convert properly. As a result, some users will not be able to use the lost password feature. For example, when providing a correct response on the Lost Password Management page the user cannot reset the password. Also some users might not be able to set new responses, basically it will complain that the old response is not correct.

The Challenge Response value is encrypted with the shared secret in the CPResponseEncryptionKey node, using the RC6 encryption algorithm. The Challenge Response encryption key contains the attributes:


cn=CPResponseEncryptionKey,obcontainerId=encryptionKey,o=Oblix,<container>     Attribute: obSecretSize     Attribute: obSharedSecret

where Attribute: obSharedSecret is a binary attribute.


If the configuration tree moved or a different directory server is used in the upgraded environment, the shared secrets might not match.

To ensure the Challenge Phrase Response is properly converted

  1. Use caution with the shared secret, which cannot be copied and pasted.

  2. Manually document the shared secret in your original configuration tree and add it to the 10.1.4 configuration tree.

For more information, see "Encryption Schemes and the Shared Secret" and "Checking Compatibility with Previous Releases".

G.9 Compatibility of Earlier Plug-ins in the Upgraded Environment

If your earlier customized plug-ins are not operating as expected after the upgrade when working with internationalized data (that is, non latin-1 data), you need to redesign these to ensure they can process UTF-8 encoded data. To send or receive internationalized data, earlier custom plug-ins must be redesigned to use UTF-8 encoding.

Also, on Solaris and Linux, plug-ins earlier than release 7.x must be re-compiled using the GCC v3.3.2 C++ compiler, regardless of the compiler that might be provided with the Operating System.


Release 7.0 plug-ins as well as earlier plug-ins implemented as executables or those using a scripting language (such as perl) do not require recompiling after the upgrade. However, to send and receive internationalized data, earlier plug-ins should be redesigned to communicate using UTF-8 encoding.

To ensure compatibility of your earlier plug-ins in the upgraded environment, see:

G.10 Customized Styles, Images, and JavaScript

Broken images or the incorrect appearance of a customized Graphical User Interface (GUI) or JavaScript errors is an indication that earlier customizations have not been manually incorporated into the upgraded environment.

As discussed earlier, customized .XSL style files, images, and JavaScript files are not migrated during the upgrade. If your previous installation includes significant changes to earlier XSL stylesheets, or if you use a style other than the Oracle Access Manager default Classic Style, you need to manually include those changes in 10.1.4 stylesheets, images, and JavaScript files.


If you simply copy earlier stylesheets, you might receive stylesheet bug reports or experience unpredictable behavior when using new features designed to work with new stylesheets.

For details about migrating customized styles, images, and JavaScript (including message handling), see details in Chapter 12, "Upgrading Your Identity System Customizations".

G.11 Deleting the File

If previous installations and upgrades have left behind a file, you might have trouble when you specify the installation directory. This can occur if a component installation terminates (or is terminated by you) after component files were extracted to the designated installation directory and you simply remove the installation directory without running the Uninstaller. In this case, you are left with an inconsistent file.

Before starting an upgrade you need to remove this file.

To remove the file

  1. Locate the file. For example:

    • On Windows NT: file is located in c:\WINNT.

    • On UNIX: The file is located in the home directory of the user running the installer

  2. Delete it.

G.12 Ensuring Compatibility with Earlier Portal Inserts

After the upgrade if you notice that your portal inserts are not working as expected, you need to ensure that your portal insert URLs have been manually updated for UTF-8 encoding. Also, to use internationalized data in PresentationXML requests, these requests must indicate UTF-8 encoding.

Oracle Access Manager 10.1.4 cannot detect query string character encoding and assumes it to be UTF-8. The 10.1.4 Identity Server cannot process Latin-1 data from earlier Portal Inserts. After upgrading to 10.1.4), you must change the encoding of the query string in earlier Portal Inserts from Latin-1 to UTF-8.

To ensure compatibility with portal inserts in your environment, see "Ensuring Compatibility with Earlier Portal Inserts".

G.13 Failover and Load Balancing Issues in Upgraded Environments

You should not experience any problems in this area following an upgrade. Refer to following discussions for more information:

G.14 Identity Server Not Processing Data from Earlier Plug-ins

If you have a newly installed Identity Server that does not appear to process information from an plug-in, there might be a backward compatibility problem.

Upgraded Identity Servers are automatically enabled for backward compatibility with earlier plug-ins. However, if you install a new 10g ( Identity Server in an upgraded environment you must manually set the encoding flag in the Identity Server oblixpppcatalog.lst to enable communication with earlier plug-ins and interfaces. See also "Identity Server Backward Compatability".

G.15 IdentityXML Calls Fail After WebGate Install

IdentityXML calls require authentication credentials. If there is no WebGate protecting WebPass, then the basic credential mechanism is used. This takes the form of username and password embedded in the SOAP request itself. However, when a WebGate is installed later, then the IdentityXML calls must be changed to use an SSO token-based authentication.

The IdentityXML calls need to be changed to first obtain an OBSSOCookie, and then pass that token into all the subsequent calls. An example of how to do this is shown in the Oracle Access Manager Developer Guide. Look for details on code examples of deployed IdentityXML functions, and the ObSSOCookie Example.

G.16 Language Issues

Oracle Access Manager 10g ( supports only 10g ( Language Packs. A 10.1.4 environment includes at least the English language and perhaps one or more non-English Language Packs.

After upgrading to 10.1.4 using either method described in this book, you must remove 10g ( Language Packs before applying the 10g ( patch set. After applying the 10g ( patch set you can install 10g ( Language Packs.

For more information, see:

G.17 LDAP Add Errors in a Replicated Environment

If you are upgrading from Oracle Access Manager 5.2.x on Windows 2000 SP3, you might receive LDAP add errors during the upgrade. If you receive these errors, you might need to set the replication agreements for the computers.

To you receive LDAP add errors in your Windows environment

  1. Install the Support Tools from the Windows 2000 CD.

  2. Run the dcdiag program, optionally using the /v command-line option.

  3. Under the Replication test, check for failures.

  4. If failures are reported, use the next procedure to troubleshoot LDAP add errors.

To troubleshoot LDAP add errors in a forest

  1. Confirm that the clocks are synchronized for the domain controllers.

  2. On the command line for all domain controllers in the forest, enter the following:

    net time /setsntp:machine name

    Use the same computer name so there is minimal clock skew.

  3. Set the group policy for replication:

    1. Open the Users and Computers tool.

    2. Go to Domain Controllers, right click, and select Properties.

    3. Under the Group Policy tab, select Default Domain Controllers Policy, select Computer Configuration, then click Windows Settings.

    4. Select Security Settings, select Local policies, then click User Rights Assignment.

    5. From the right hand side, select Access this computer from the network.

    6. Add ENTERPRISE DOMAIN CONTROLLERS to the access list.

  4. Do a replication using the Sites and Services tool:

    1. Go to Sites, select Default-First-site-name, then select Servers.

    2. Select the server name.

    3. Select NTDS settings.

    4. Right click <automatically generated> on the right hand side, and select replicate now.

    5. Enter the dcdiag program again on the command line to see if the replication test is now working.

After performing these steps, the schema migration should work properly.

G.18 Manual Schema Upload Fails

If you attempt to upload and use the full schema installation files for any directory during the upgrade (instead of using release-specific delta files for an existing schema), the operation will fail. This is because the schema already exists and the files used to upgrade an existing schema provide only the difference between the existing schema and the next release.

For example, suppose you have an installation with ADAM as the directory. If you attempt to upload and install the complete (new installation) schema file (ADAM_oblix_schema_add.ldif andADAM_user_schema_add.ldif) rather than release-specific delta-content files (osd_650_to_700_schema_adam.ldif and policy_650_to_700_schema_adam.ldif) the process will fail. This is because the schema already exists.


G.19 Mime_types -related Customizations Not Retained

You might notice that your mime_types-related customizations are not reflected in the attribute configuration applet in the System Console.

When upgrading, multiple entries with the same ParamName in mime_types (.xml and .lst) files are not retained:



The .xml version of the file is used by the Identity Server. The .lst version of the file is used by the WebPass Java applet. Both versions of the file must match. Both versions of the file must reside in the IdentityServer_install_dir and in the WebPass_install_dir.

For example, if your original mime_types.xml file in IdentityServer_install_dir/identity/oblix/apps/admin/bin/mime_types.xml contains the following NameValPair ParamNames:

<NameValPair ParamName="application/postscript" Value="ai1"/>
<NameValPair ParamName="application/postscript" Value="eps1"/>
<NameValPair ParamName="application/postscript" Value="ps1"/>

the following entries will occur in the newly upgraded file:

<NameValPair ParamName="application/postscript" Value="ai1"/>                    (CORRECT)
<NameValPair ParamName="application/postscript" Value="eps"/>                   (INCORRECT)
<NameValPair ParamName="application/postscript" Value="ps"/>                     (INCORRECT)

For existing user entries, the MIME type is stored along with the user entry in the directory. As a result, there is no impact on existing user entries and Oracle Access Manager installations after the upgrade.


Both .lst and .xml versions of the file are needed. You might remove MIME types that are no longer needed or add new MIME types to be associated with the particular attribute for further use. Simply edit the mime_types.lst and .xml files for the Identity Server, then copy these into the WebPass_install_dir to replace the earlier version.

To ensure MIME type files are accurate and available in the upgraded environment

  1. Edit the Identity Server mime_types.lst file if needed to remove MIME types that are no longer needed or add new MIME types to be associated with the particular attribute for further use.

  2. Edit the Identity Server mime_types.xml file to match your edited mime_types.lst file.

  3. Copy both Identity Server mime_types files (.lst and .xml) in to the WebPass_install_dir to replace the earlier version.

G.20 NPTL Requirements and Post-Installation Tasks

Oracle Access Manager uses either Native POSIX Thread Library (NPTL) or LinuxThreads. The default mode is LinuxThreads.

LinuxThreads: To support the default, the start_ois_server and start_access_server will start in LinuxThreads mode. In this case, the variable LD_ASSUME_KERNEL is automatically set to 2.4.19. The message "Using Linux Threading Library." appears in the console and in the server's oblog file.

NPTL: If you start the server with the start_ois_server_nptl or start_access_server_nptl scripts, NPTL mode is used. You can also restart the server with restart_ois_server_nptl or restart_access_server_nptl scripts. In this case, the message "Using NPTL Threading Library." appears in the console and in the server's oblog file.


On Linux, Oracle Access Manager Web components for Oracle HTTP Server 11g use only NPTL; you cannot use the LinuxThreads library. In this case, do not set the environment variable LD_ASSUME_KERNEL to 2.4.19.

The NPTL-ready scripts include:


Standard stop scripts and the following standard setup scripts will operate successfully whether you use LinuxThreads or NPTL: start_setup_ois, start_setup_webpass, start_setup_access_manager, start_configureAAAServer, stop_snmp_agent, start_configureWebGate, and start_configureAccessGate.

The setup script for the SNMP agent, start_snmp_agent, includes an entry for LD_ASSUME_KERNEL. When using NPTL with Oracle Access Manager, you must remove or comment out the LD_ASSUME_KERNEL=2.4.19 environment variable from the following file:

SNMP Agent: start_snmp_agent


Oracle Access Manager servers can run using NPTL while Oracle Access Manager Web components use LinuxThreads (and vice versa). When installing Oracle Access Manager Web components or third-party connectors for use with NPTL, there is no need to set the environment variable LD_ASSUME_KERNEL to 2.4.19.

Use the following procedure as a guide when using or modifying scripts for NPTL and Oracle Access Manager.

To use NPTL with Oracle Access Manager

  1. Use NPTL versions of start scripts for the Identity Server and Access Server stored in:


  2. SNMP Agent: Perform the following steps to remove or comment out the LD_ASSUME_KERNEL=2.4.19 environment variable from the start_snmp_agent script.

    1. Locate the start_snmp_agent script in the following path:

    2. In a text editor, remove or comment out the following line:

      LD_ASSUME_KERNEL =2.4.19
    3. Save the file.

    4. Repeat for each SNMP Agent in your deployment.

  3. Use standard setup and stop scripts:

  4. Web Components or Third-party Connectors Using NPTL: Do not set the environment variable LD_ASSUME_KERNEL to 2.4.19 when using NPTL with Oracle Access Manager.

G.21 Page Not Found Error While Accessing the Access or Identity URL


A "Page not found." error occurs after upgrading an older WebGate to 10.1.4.


Occasionally, earlier Access Servers do not completely shutdown. Upgrading an older Access Server that has processes running results in issues when upgrading older WebGates to 10.1.4. To avoid issues before upgrading, see "Stopping Servers and Services".


Stop the associated Access Servers, terminate any still-running processes (for example, on Solaris platforms use the kill -9 command), then restart the Access Servers.

G.22 Searches Are Slow

If you do not upload the indexes for iPlanet and NDS directories, the product will work. However, searching will be inefficient and impact performance.

For details, see "Uploading Directory Server Index Files".

G.23 Simple Mode Password File Not Converted During Upgrade

If the earlier Access Server is in Simple mode before the upgrade, during the upgrade to 10.1.4 the password.lst file is not converted to password.xml. The result is that the Access Server cannot be started in the Services Window unless you use the command-line parameters to convey the passphrase on startup. Also, after upgrading a WebGate in Simple mode and starting the Web server, the following error might appear:

"Exception thrown during WebGate initialization" 
     Error^Oracle AccessGate API is not initialized.

The initial Access System page appears. However, clicking on any link results in a "Server error" in the browser (no error number) with the error echoed to the console. The system cannot be accessed.

The upgraded area does not have the updated password.xml file.


In releases before 10.1.4, the password file is named and formatted as password.lst. Starting with release 10g (, the password file is named and formatted as password.xml

The following information is a workaround for this problem when the same Simple mode password is being used in the Identity System. In this case, you can copy the password.xml file from the upgraded Identity Server to the upgraded Access Server and WebGate as described in the following procedure.: "Workaround when the same Simple mode password is used in the Identity System". You will be asked about the password immediately after selecting Simple mode.

However, if the password is not the same on the Identity Server as it is on the Access Server, skip to the following procedures. Again, you will be asked about the password immediately after selecting Simple mode:

Workaround when the same Simple mode password is used in the Identity System

  1. If the same Simple mode password is being used in the Identity System, copy the password.xml file as follows:

    From: <upgraded_IdentityServer_install_dir>/oblix/config/password.xml
    To: <upgraded_AccessServer_install_dir>/oblix/config /password.xml
    To: <upgraded_WebGate_install_dir>/oblix/config/password.xml
  2. Start the Access Server.

  3. Restart the WebGate Web server.

If the Access System Simple mode password is not the same as the Identity System Simple mode password, you must change the password using the following tools and procedures.


Workaround when the Simple mode password is different on the Identity System and Access Server

  1. Go to the folder where configureAAAserver is located. For example:

  2. Run the following executable:

    configureAAAServer chpasswd AccessServer_install_dir 
  3. Responds to prompts as directed on the screen.

  4. Restart the Access Server.

Workaround when the Simple mode password is different on the Identity System and WebGate

  1. Go to the directory:


    where WebGate_install_dir is the directory in which WebGate is installed.

  2. Run the following command:

    configureWebGate -i WebGate_install_dir -t WebGate -k

    The -k option results in only prompts for the password for Simple or Cert mode transport security.

  3. Respond to prompts on the screen.

  4. Restart the WebGate Web server.

For more information about the configureAAAServer and configureWebGate tools, see the Oracle Access Manager Access Administration Guide.

G.24 Troubleshooting Sun Web Server Upgrades

The release numbers in this discussion are for illustration only and related to the information in Appendix E, "Upgrading Sun Web Server Version 4 to Version 6 on Windows 2000". Specific details of the intermediate upgrade from earlier Oracle Access Manager releases to release 6.1.1 are outside the scope of this manual. Before you start upgrading from a release earlier than Oracle Access Manager 6.1.1, contact Oracle Support at

There are several potential issues that might occur after upgrading to Sun release 6.0 Web server and upgrading to the Oracle Access Manager 7.0 Identity System.

During the upgrade, the following entries are added to obj.conf:

NameTrans fn="pfx2dir" from="/identity/oblix" dir="G:/70/webpass/identity/oblix" 
……<Object name="idoblix">PathCheck file=".nsconfig" fn="load-config" descend="1"</Object>

However, in the Oracle Access Manager 5.2 Identity System installed on a version 4.1 Web server, the obj.conf does not contain the entries underlined earlier. Even when the version 4 Web server is migrated to release 6 and Oracle Access Manager is upgraded to release 7.0, these entries are not included in obj.conf.

This completes the process.

G.25 Users Cannot Log In

If you do not upload appropriate indexes for Oracle Internet Directory after the schema and data upgrade, users will not be able to login.

For details, see "Uploading Directory Server Index Files".

G.26 Users Who Do Not Satisfy a Large Group Dynamic Filter Are Part of the Group


A large group dynamic filter that is working in the original installation (6.5) is not working properly when imported "as is" into a 10.1.4 environment. The filter comes as part of the group and is defined with a long list queries. However, users who do not satisfy this filter might still become part of the group.

Solution When Dynamic Filter Size is Greater than 4k

After the Access Server upgrade, you must apply the latest patch and then add a new parameter, DynamicGroupFilterMaxSize,to the Access Server globalparams.xml. The value you set for this parameter must exceed the maximum filter length.

The default value is 4096. You can increase the value up to 4,294,967,295. Oracle Access Manager increases the filter size while evaluating dynamic groups. This evaluation occurs on the fly and will occur as soon as you add the parameter and value and restart the Access Server. For more information about this parameter, see the chapter on parameters in the Oracle Access Manager Customization Guide.

The following procedure walks you through the solution.

To increase the value of the dynamic filter size

  1. Upgrade the Access Server using either the in-place method or the zero downtime method.

  2. In-Place Method:

    • Apply Release 10.1.4 Patch Set 1 (, as described in Oracle Access Manager Patch Set Notes Release 10.1.4 Patchset 1 ( For All Supported Operating Systems, and then proceed as for

    • Apply Release 10.1.4 Patch Set 2 (, as described in Oracle Access Manager Patchset Notes Release 10.1.4 Patchset 2 ( For All Supported Operating Systems.

  3. Zero Downtime Method: Apply the Release 10.1.4 Patch Set 2 (, as described in Oracle Access Manager Patchset Notes Release 10.1.4 Patchset 2 ( For All Supported Operating Systems.

  4. Locate the globalparams.xml file in the following path:


  5. Add the DynamicGroupFilterMaxSize parameter to the file with a value that exceeds the maximum dynamic group filter size. For example:

      <NameValPair ParamName="DynamicGroupFilterMaxSize" Value="7900" /> 
  6. Save the file.

  7. Restart the Access Server.

  8. Repeat for all Access Servers.

G.27 WebSphere Application Server 6.1 Registrytester File is Missing

Before you enable the NetPointWASRegistry, you need to run the registryTester program to ensure that the NetPointWASRegistry is registered and can successfully connect to the Identity System. A file required to run the registrytester was available in the WAS_install_dir. Today, however, the file is not bundled with the Oracle Access Manager Connector for WebSphere. As a result, you cannot run the registrytester with the Oracle Access Manager Connector for WebSphere 6.1.

Workaround: Copy the sas.jar from an external source (WebSphere Application Server 6.0 installation directory, for example), then set the classpath accordingly. For example:

set CLASSPATH=.:${CLASSPATH}:${INSTALL_DIR}/oblix/lib/NetPointWASRegistry.jar 

G.28 Weblogic Connectors Simple Mode Password File is Not Migrated

For Weblogic and WebSphere connectors running in simple mode, when you upgrade Oracle COREid Release 7.0.4 connector for Weblogic that is running in Simple mode to 10.1.4, the password.xml file is not migrated. In this case, you are prompted for the NetPoint Transport Password in addition to a user name and password when starting the Weblogic (or WebSphere) server.

Workaround: Before starting the upgrade, you need to add the following to the asdk_base_files.lst file in the directory connector_ install_dir/NetPointSecuProvForWeblogic/oblix/tools/migration_tools. After receiving the message that migration completed successfully, copy the file and mbean.jar from the upgraded directory to the Weblogic Portal Domain.

  1. Before starting the upgrade, add the following to the asdk_base_files.lst file in the directory connector_ install_dir/NetPointSecuProvForWeblogic/oblix/tools/mig ration_tools

  2. Start upgrading from Oracle COREid Release 7.0.4 to 10.1.4 and also upgrade the Access Server SDK.

  3. After receiving the message that migration completed successfully, copy the file and mbean.jar from the upgraded directory to the Weblogic Portal Domain.

  4. Restart WebLogic.

For more information, see "Finishing the Integration Connector Upgrade".

G.29 WebSphere Application Server and Portal Server Upgrades

During installation of the integration connector for WebSphere Application Server and Portal Server, you are asked to provide the WebSphere classes directory path so the following files are added:

jobaccess.jar and NetPointWASRegistry.jar

However, during the upgrade of the integration connector for WebSphere Application Server and Portal Server, you are not asked for this directory. Instead, you need to manually copy the three files (listed in the following example) into the directory following the upgrade, then restart the Websphere Application Server and the Portal Server.


There is no NetPointCMR.jar in a release 6.5 installation.

For more information, see "Upgrading Third-Party Integration Connectors".

G.30 Zero Downtime Upgrade Issues

This section discusses issues that are specific only to performing an upgrade using the zero downtime method. If you did not use the zero downtime upgrade method, you can skip this section. Topics here include:

G.30.1 Creating a New Branch During Zero Downtime Upgrade when the a DN Contains a Space

If the old configuration or policy DN includes a space, you must apply Bundle Patch (or a later bundle patch) to avoid a potential problem when creating the new branch.

When Bundle Patch is applied to the 10g ( clone of the first installed Identity Server (and the 10g ( clone of the first installed Access Manager), the Mkbranch tool can replace the old configuration or policy DN with the new one even if the old one includes a space.

For more information, see "Creating and Populating a New oblix Branch".

G.30.2 Generating a New Registry Key To Use When Rolling Back an Original Instance Upgrade

This topic explains how to reinstate the Windows 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.

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. As a result, 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 the following procedure.

The following procedure describes how to use the alternative approach when you do not have a back up copy of the original registry entry. This procedure provides sample path names, including:

  • Original Instance (also the upgrade destination): np611\ois_01\identity

  • Source (renamed original): np611\ois_01\identity_source

To generate a Windows registry entry if you don't have a backup copy to import when rolling back to an original instance

  1. Confirm that the clone setup is running and providing service to your customers with original WebGates.

  2. Stop the original servers.

  3. Confirm that the source path that was created for the instance upgrade differs from the original path.

    Source: np611\ois_01\identity_source

  4. Remove (or rename) the destination file system that was created for the original instance (the 10g ( component libraries and files with Release 10.1.4 Patch Set 1 ( applied).

    Delete (or Rename) Destination: np611\ois_01\identity

  5. Start re-installing the original component release to create the registry entry as follows:

    1. Locate and launch the original component installer on the computer that is hosting the renamed source. For example: NetPoint6_EN_sparc-s2_COREid_Server.

    2. Specify the same installation path that the original instance had. For example: np611\ois_01.

    3. Proceed with Step 5 or Step 6 based on the type of component you are installing.

  6. COREid or Access Server:

    1. Provide the same transport security details as the original instance.

    2. Provide the same configuration details as the original instance (the original COREid or Access Server name, host name, and port) to create the registry entry.

    3. When you are informed that the service name exists, click Cancel to end the installation process.

    4. Proceed to Step 7.

  7. WebPass, Access Manager, or WebGate: After libraries and files are extracted, Cancel the installation. The registry entry and new directories are created.

  8. All Components: Proceed with caution as you replace the freshly installed file system with the renamed source:

    1. From the freshly installed file system, delete the fresh \identity (or \access) folder and all subdirectories. For example:

      Delete From Freshly Installed File System: \identity (or \access)

    2. From the renamed source, copy the \identity (or \access folder and all sub directories. For example:

      Copy From Renamed Source: \identity_source

    3. To the freshly installed file system, add the copied folder. For example:

      Add to Fresh File System: \identity_source

    4. In the freshly installed file system, rename the copied folder to match the original name, if needed. For example:

      Change in Fresh File System: \identity_source

      To: \identity

  9. Access Server: Proceed with caution as you copy the backup Access Server \config directory and add this to the freshly installed Access Server file system. For example:

    1. Locate and copy the backup Access Server \config directory that was made before the original instance was reconfigured. For example:

      Copy From: backup_aaa\config

    2. To the newly renamed Access Server file system, add the copied \config folder. For example:

      Add to Fresh File System: np611\access\oblix\config

  10. WebPass, Access Manager, or WebGate: Reinstate the original Web server configuration files using the back up copy that was made before the instance upgrade. For example:

    1. Remove (or rename) the upgraded Web server configuration file for original components.

    2. Reinstate the back up copy of the Web server configuration file that contains entries for the earlier Web component (made before you upgraded the original instance).

    3. Restart the Web server instance.

  11. COREid or Access Server: Restart the Service.

  12. When all original components are started, test the original setup to ensure that it is fully operational.

G.30.3 No Registry Key for Upgraded Web Component Clones with IIS v5

Issue: Windows Registry is not updated for upgraded cloned Web components

After upgrading a cloned COREid Server and successfully starting the service, the Windows Registry is updated with details for the upgraded clone. However, the Registry is not updated after upgrading a cloned WebPass (or Access Manager) when Microsoft IIS 5.0 is the Web server. Instead, the component is upgraded to release 10.1.4 and the earlier Registry key is removed but there is no new entry under a 10.1.4 key.


The transfilter for the 10g ( patched Web component was not registered when copying the component to create a clone. As a result, the location is not available in the Registry editor.

Workaround: Perform the following steps

  1. Stop the upgraded clone COREid Server service.

  2. Stop the IIS v5 Web server that is running with the upgraded Web component.

  3. Rename the original COREid Server directory. For example:

    From: np611\ois_01\identity

    To: orig_np611\ois_01\identity_1014

  4. Rename the original Web component directory.

    From: np611\webcomponent_01\identity

    To: orig_np611\webcomponent_01\identity_1014

  5. Install the 10g ( Identity Server and WebPass and apply the 10g ( patch set, as follows:

    • Use instructions in "About Destination Creation and Obtaining Tools for a Zero Downtime Upgrade" as a guide.

    • Specify the original COREid Server installation directory as the destination for the 10g ( Identity Server. For example:

      Destination: np611\ois_01\identity

    • Apply the 10g ( patch set to the 10g ( Identity Server as described in the Oracle Access Manager Patch Set Notes Release 10.1.4 Patchset 1 ( For All Supported Operating Systems

    • Specify the original (now renamed) WebPass installation directory as the destination for the WebPass.For example:

      Destination: np611\webcomponent_01\identity

    • Apply the 10g ( patch set to the 10g ( WebPass as described in the Oracle Access Manager Patch Set Notes Release 10.1.4 Patchset 1 ( For All Supported Operating Systems.

  6. Proceed with remaining zero downtime upgrade tasks for your environment, as described in Chapter 15.