14 Performing an Oracle Identity Management Multimaster and Fan-Out Replication Upgrade

This appendix describes how to upgrade to Oracle Identity Management 11g Release 1 (11.1.1) in an Oracle Internet Directory replicated environment.

Refer to the following sections for more information:

14.1 Task 1: Review the Terminology, Prerequisites, and Key Concepts For Upgrading a Replication Environment

Review the following prerequisites and requirements before proceeding with the upgrade procedures in this chapter:

14.1.1 Terminology Conventions for This Chapter

In this chapter, the destination replica is the newly installed and upgraded 11g Release 1 (11.1.1) replica; the source replica is the 10g Release 2 (10.1.2) or 10g (10.1.4.0.1) replica you are upgrading.

14.1.2 Valid Starting Points When Upgrading a Replication Environment

The upgrade procedures in this chapter are designed for administrators who have installed and configured an Oracle Internet Directory 10g Release 2 (10.1.2) or 10g (10.1.4.0.1) multimaster or fan-out replication environment.

This chapter assumes that the Oracle Identity Management components in the replication environment are distributed. In other words, you have installed the Oracle Internet Directory (and optionally Oracle Directory Integration Platform) components in one or more Oracle homes, and you installed the Oracle Single Sign-On and Oracle Delegated Administration Services components in one or more additional Oracle homes.

Figure 14-1 shows a typical Oracle Identity Management 10g Release 2 (10.1.2) multimaster replication environment, which is described in detail in "Deploying Identity Management with Multimaster Replication," in the 10g Release 2 (10.1.2) Oracle Fusion Middleware High Availability Guide.

Figure 14-1 A Typical Oracle Identity Management 10g Release 2 (10.1.2) Multimaster Replication Environment

Description of Figure 14-1 follows
Description of "Figure 14-1 A Typical Oracle Identity Management 10g Release 2 (10.1.2) Multimaster Replication Environment"

Information about deploying Oracle Identity Management with fan-out replication can be found in the Oracle Application Server 10g (10.1.4.0.1) Oracle Identity Management Concepts and Deployment Planning Guide, which is available in the Oracle Application Server 10g Release 2 (10.1.2) documentation library.

14.1.3 Oracle Recommendations When Upgrading a Replication Environment

Oracle Corporation recommends the following during the upgrade procedure:

  • After you upgrade the destination replica, disable replication between the destination replica and the source replica. The destination replica can receive and process changes from source replica, but the source replica cannot process changes originated and received from destination replica.

  • The replication environment can be a Single Master (that is, only one replica is set to read and write, and all others are set to read only).

14.2 Task 2: Prepare for the Oracle Identity Management Multimaster or Fan-Out Replication Upgrade

Before you begin upgrading Oracle Internet Directory in a replicated environment, you must perform the following steps for all replicas other than Master Definition Site (MDS) Replica or Primary supplier replica:

  1. Locate the database registration entry of the database of replica to be upgraded.

    On Window systems:

    SOURCE_ORACLE_HOME\bin\ldapsearch 
         -h hostname_of_replica_being_upgraded 
         -p port 
         -D cn=orcladmin 
         -w superuser_password 
         -b "cn=oraclecontext" 
         -s one "(objectclass=orcldbserver)" dn
    

    On UNIX systems:

    SOURCE_ORACLE_HOME/bin/ldapsearch 
         -h hostname_of_replica_being_upgraded
         -p port 
         -D cn=orcladmin 
         -w superuser_password 
         -b "cn=oraclecontext" 
         -s one "(objectclass=orcldbserver)" dn
    

    This will return a list of Distinguished Names (DNs) corresponding to all the Databases registered in Oracle Internet Directory in the following form:

    cn=database_name,cn=oraclecontext
    

    From the returned list of entries, locate and make a note of the DN of the following entry, which corresponds to the replica upgraded:

    cn=dbname_of_replica_to_be_upgraded,cn=oraclecontext
    
  2. Identify the replica ID of the replica to be upgraded by issuing following command:

    On Windows systems:

    SOURCE_ORACLE_HOME\bin\ldapsearch 
         -h hostname_of_replica_being_upgraded 
         -p port 
         -D cn=orcladmin 
         -w superuser_password 
         -b "" -s base "(objectclass=*)" orclreplicaid
    

    On UNIX systems:

    SOURCE_ORACLE_HOME/bin/ldapsearch 
         -h hostname_of_replica_being_upgraded 
         -p port 
         -D cn=orcladmin 
         -w superuser_password 
         -b "" 
         -s base "(objectclass=*)" orclreplicaid
    
  3. Modify the seeAlso attribute of the replica subentry so that it points to the database you are about to upgrade.

    The seeAlso attribute is a standard Oracle Internet Directory attribute. For more information, refer to "seeAlso" in the Oracle Fusion Middleware User Reference for Oracle Identity Management.

    To modify the seeAlso attribute:

    1. Create a file, for example mod.ldif, with following contents:

      #File Name : mod.ldif
      dn: orclreplicaid=replicaid_from_step_2,cn=replication configuration
      changetype: modify
      replace: seeAlso
      #The DN used in seealso attribute is obtained in Step #1.
      seeAlso: cn=dbname_of_replica_being_upgraded,cn=oraclecontext
      
    2. Modify the replica subentry using ldapmodify command.

      On Windows systems:

      SOURCE_ORACLE_HOME\bin\ldapmodify 
         -h hostname_of_replica_being_upgraded 
         -p port 
         -D superuser_DN 
         -w superuser_password 
         -v 
         -f mod.ldif
      

      On UNIX systems:

      SOURCE_ORACLE_HOME/bin/ldapmodify 
         -h hostname_of_replica_being_upgraded 
         -p port 
         -D superuser_DN 
         -w superuser_password 
         -v 
         -f mod.ldif
      
  4. Navigate to the following directory and locate ias.properties file:

    On Windows systems:

    SOURCE_ORACLE_HOME\config
    

    On UNIX systems:

    SOURCE_ORACLE_HOME/config
    
  5. Open the ias.properties file and verify that the properties shown in Table 14-1 are correct and valid.

  6. Make sure the Oracle Internet Directory server is up and running.

    To verify that Oracle Internet Directory is running, enter one of the following commands.

    Note:

    You may have to temporarily set the ORACLE_HOME environment variable to the Oracle Internet Directory Oracle home before running the ldapbind command.

    After you verify that the Oracle Internet Directory is running, you must then make sure the ORACLE_HOME environment variable is not defined before you start the 11g Release 1 (11.1.1) installer to begin the upgrade procedure.

    If you are running Oracle Internet Directory on a non-secure port:

    SOURCE_ORACLE_HOME/bin/ldapbind -p Non-SSL_port
    

    If you are running Oracle Internet Directory on a secure port:

    SOURCE_ORACLE_HOME/bin/ldapbind -p SSL_port -U 1
    

    These commands should return a "bind successful" message.

  7. Stop the second LDAP server as shown below.

    This example assumes that the instance number used for the second instance was 2.

    SOURCE_ORACLE_HOME/bin/oidctl connect=connect_string_of_db server=oidldapd instance=2 stop
    

Table 14-1 Properties to Verify in ias.properties Before Replication Upgrade

Property Name Correct Value Before Replication Upgrade

OID.LaunchSuccess

True

OIDhost

host name of replica

OIDport

port of replica

OIDsslport

SSL port for replica


14.3 Task 3: Perform the Oracle Internet Directory Replica Upgrade

You can upgrade one replica at a time, or all of the replicas simultaneously. Refer to the following sections for more information:

14.3.1 Selecting a Replica Upgrade Method

Upgrading one computer at a time in a replicated environment ensures that Oracle Internet Directory is available during the upgrade for additions, modifications, and searching. When you use this method, only the replica you are upgrading is down. The other replicas continue to run and are available to your users.

Upgrading multiple replicas simultaneously ensures that the entire network is upgraded without a transient stage. The procedure is simpler than upgrading one replica at a time, but involves directory service downtime.

14.3.2 Upgrading One Replica at a Time

Follow these steps to upgrade one replica at a time:

  1. Make sure you have completed the procedure in Section 14.2, "Task 2: Prepare for the Oracle Identity Management Multimaster or Fan-Out Replication Upgrade".

  2. Identify the replication server on the replica to be upgraded.

    The replica can be an LDAP-based partial or fan-out replica, or it can be an Oracle Advanced Replication (ASR) based multimaster replica.

    See Also:

    "Directory Replication Concepts" in the Oracle Fusion Middleware Administrator's Guide for Oracle Internet Directory.
  3. Modify your load balancer to route traffic away from the replica you are about to upgrade; instead route all client traffic to the other replicas.

  4. Make sure the replica is up-to-date with changes from the other replica.

    This check is required to make sure that all the changes from the first replica are captured in the second replica before we turn off replication.

  5. Stop the replication server on the replica to be upgraded.

    On UNIX systems:

    SOURCE_ORACLE_HOME/oidctl
       connect=db_connect_string
       server=OIDREPLD
       instance=1
       flags="-p port_at_which_ldap_server_is_listening"
       stop
    

    On Windows systems:

    SOURCE_ORACLE_HOME\oidctl
       connect=db_connect_string
       server=OIDREPLD
       instance=1
       flags="-p port_at_which_ldap_server_is_listening"
       stop
    

    See Also:

    "Oracle Identity Management Server Administration Tools" in the Oracle Fusion Middleware User Reference for Oracle Identity Management for more information about the oidctl administration tool
  6. Make sure that the Oracle Internet Directory server, the Oracle Internet Directory database, and the database listener are up and running.

  7. If you are upgrading an ASR-based replica, then delete all ASR jobs on other replicas by issuing the oidrdjob.sql script.

    For example:

    export TWO_TASK=db_name_of_replica_being_upgraded
    ORACLE_HOME/bin/sqlplus repadmin/password@connect_string_of_db
           @ORACLE_HOME/ldap/admin/oidrdjob.sql
    

    All ASR jobs on other master sites that transfer changes to this replica are deleted. This has the effect of taking the replica currently being upgraded out of the replication environment, so that no changes come to it, while other replicas continue to operate and replicate changes.

  8. Depending on the configuration of the replica, refer to the following documentation resources to perform the upgrade of the replica:

    Note that upgrading the replica involves the following steps:

    • Installing Oracle WebLogic Server and creating the Middleware home

    • Installing and configuring Oracle Internet Directory.

    • Running the Upgrade Assistant to upgrade the configuration from the Oracle Internet Directory 10g instance to 11g

    • Performing any post-upgrade tasks for your environment.

  9. After you upgrade the replica, verify that the database in the upgraded replica Oracle home is up and running.

  10. Test the connectivity to the other replicas.

    The Net Services Upgrade assistant might have modified listener.ora and tnsnames.ora, breaking connectivity. If connectivity is broken, identify the entries that were modified in the files, and restore the entries from the corresponding files in the source Oracle home.

    For example, copy the original entries from the following files in the source Oracle home to the corresponding files in the destination Oracle home:

    SOURCE_ORACLE_HOME/network/admin/listener.ora
    SOURCE_ORACLE_HOME/network/admin/sqlnet.ora
    SOURCE_ORACLE_HOME/network/admin/tnsnames.ora
    
  11. If you are upgrading an Oracle Advanced Replication (ASR) based Replica, recreate the jobs on each replica, after it is upgraded, by issuing the following command:

    export LD_LIBRARY_PATH=DESTINATION_ORACLE_HOME/lib
    DESTINATION_ORACLE_HOME/ldap/bin/remtool –asrrectify
    

    The jobs that were deleted in previously are re-created. They will begin transferring the existing changes and new changes from other replicas to the upgraded replicas.

  12. Perform the procedures described in Section 14.4, "Task 4: Completing the Upgrade of Each Replica" for the newly upgraded replica.

  13. Stop the 10g replication servers.

    This is to avoid replicating the upgraded replica with those that have not been upgraded yet.

    Run the following command:

    export TWO_TASK=db_name_of_second_replica
    sqlplus repadmin/welcome1@db_connect_string 
            @$ORACLE_HOME/ldap/admin/oidrdjob.sql
    
  14. Redefine the following environment variables:

    For example:

    export INSTANCE_NAME=asinst_1
    export COMPONENT_NAME=oid1
    export ORACLE_HOME=11g_ORACLE_HOME_PATH
    export ORACLE_INSTANCE=11g_ORACLE_INSTANCE_PATH
    
  15. Start the replication server on the newly upgrade replica, if it is not already running:

    DESTINATION_ORACLE_HOME/oidctl
       connect=db_connect_string
       server=OIDREPLD
       instance=1
       flags="-p port_at_which_ldap_server_is_listening"
       start
    

    See Also:

    "Oracle Identity Management Server Administration Tools" in the Oracle Fusion Middleware User Reference for Oracle Identity Management for more information about the oidctl administration tool
  16. Modify the load balancer to route client traffic back to the newly upgraded replica.

  17. Upgrade the remaining replicas using the same procedures you used to upgrade the first replica.

14.3.3 Upgrading Oracle Internet Directory on Multiple Replicas Simultaneously

Use the following procedure to upgrade all the replicas simultaneously:

  1. In all replicas other than MDS replica or primary supplier replica, make sure you have completed the pre-upgrade steps provided in Section 14.2, "Task 2: Prepare for the Oracle Identity Management Multimaster or Fan-Out Replication Upgrade".

  2. Stop the replication server on all replicas in the Directory Replication Group (DRG):

    SOURCE_ORACLE_HOME/oidctl
       connect=db_connect_string
       server=OIDREPLD
       instance=1
       flags="-p port_at_which_ldap_server_is_listening"
       stop
    

    See Also:

    "Oracle Identity Management Server Administration Tools" in the Oracle Fusion Middleware User Reference for Oracle Identity Management for more information about the oidctl administration tool
  3. Use the instructions in Chapter 4, "Upgrading Your Oracle Internet Directory Environment" to upgrade the replica to Oracle Internet Directory 11g.

    Note that upgrading the replica involves the following steps, which are documented in Chapter 4:

    • Installing Oracle WebLogic Server and creating the Middleware home

    • Installing and configuring Oracle Internet Directory.

    • Running the Upgrade Assistant to upgrade the configuration from the Oracle Internet Directory 10g instance to 11g

    • Performing any post-upgrade tasks for your environment.

  4. After you upgrade the replica, verify that the database on each upgraded replica is up and running.

  5. Test the connectivity to the other replicas.

    The Net Services Upgrade assistant might have modified listener.ora and tnsnames.ora, breaking connectivity. If connectivity is broken, identify the entries that were modified in the files, and restore the entries from the corresponding files in the source Oracle home.

    For example, copy the original entries from the following files in the source Oracle home to the corresponding files in the destination Oracle home:

    SOURCE_ORACLE_HOME/network/admin/listener.ora
    SOURCE_ORACLE_HOME/network/admin/sqlnet.ora
    SOURCE_ORACLE_HOME/network/admin/tnsnames.ora
    
  6. For each upgraded replica, perform the steps in Section 14.4, "Task 4: Completing the Upgrade of Each Replica".

  7. Start the replication server on each of the upgraded replicas:

    DESTINATION_ORACLE_HOME/oidctl
       connect=db_connect_string
       server=OIDREPLD
       instance=1
       flags="-p port_at_which_ldap_server_is_listening"
       start
    

    See Also:

    "Oracle Identity Management Server Administration Tools" in the Oracle Fusion Middleware User Reference for Oracle Identity Management for more information about the oidctl administration tool

14.4 Task 4: Completing the Upgrade of Each Replica

The following sections describe tasks you must perform after you have completed the upgrade of a replica:

14.4.1 Changing the Replication DN Password in the Oracle Internet Directory Wallet for Each Replica

After you upgrade a replica, change the password for the replication distinguished name (DN). After you change or reset the password, you can then start oidmon, LDAP server, and replication server.

Refer to the following sections for more information:

14.4.1.1 Changing the Replication DN Password

After you upgrade each replica, you must change the replication distinguished name (DN) password, using the Replication Environment Management Tool (remtool), as follows:

DESTINATION_ORACLE_HOME/ldap/bin/remtool
    -pchgwalpwd -v -bind host:port/repl_dn_pwd

Note that you must provide the existing password on the remtool command line. If you do not know the replication DN password, see Section 14.4.1.2, "Resetting the Replication DN Password".

See Also:

"remtool" in the Oracle Fusion Middleware User Reference for Oracle Identity Management for details about the arguments you can use with the remtool command, including the -pchgwalpwd and -presetpwd arguments

14.4.1.2 Resetting the Replication DN Password

If you do not know replication DN password, reset the replication DN password using the following command:

DESTINATION_ORACLE_HOME/ldap/bin/remtool -presetpwd -v -bind host:port

If you are upgrading a fan-out replica, you must also reset the password of the replication DN at its supplier. To reset the password of replication DN at its supplier:

  1. Identify the replica ID of the replica to be upgraded by issuing following command:

    Note:

    Before running the command, ensure that you set the ORACLE_INSTANCE environment variable.

    On Windows systems:

    SOURCE_ORACLE_HOME\bin\ldapsearch 
         -h hostname_of_replica_being_upgraded 
         -p port 
         -D cn=orcladmin 
         -w superuser_password 
         -b "" -s base "(objectclass=*)" orclreplicaid
    

    On UNIX systems:

    SOURCE_ORACLE_HOME/bin/ldapsearch 
         -h hostname_of_replica_being_upgraded 
         -p port 
         -D cn=orcladmin 
         -w superuser_password 
         -b "" 
         -s base "(objectclass=*)" orclreplicaid
    
  2. Create an LDIF file (for example, modpwd.ldif), with following contents:

    dn: cn=replication dn,orclreplicad=consumer_replicaid,cn=replication configuration
    changetype: modify
    replace: userpassword
    userpassword: new_password
    
  3. Apply the change at supplier using ldapmodify tool as shown below:

    ldapmodify  -h supplier_hostname
                -p supplier_port_number> 
                -D cn=orcladmin
                -w super_user_password_of_supplier
                -f modpwd.ldif
    

14.4.2 Setting the orclreplicationid Attribute in the Upgraded 11g Directory

If you are upgrading a 10g Release 2 (10.1.2) replica in an environment with fan-out replication, you must set the orclreplicationid in the Oracle Internet Directory attribute to a valid value.

This procedure is not necessary if you are upgrading from 10g (10.1.4.0.1), because this is a new attribute that was introduced in Oracle Identity Management 10g (10.1.4.0.1).

Oracle recommends that you set the value of this attribute so it matches the value of the existing orclagreementID attribute. To perform this task:

  1. Identify the replica ID of the replica to be upgraded by issuing following command:

    On Windows systems:

    SOURCE_ORACLE_HOME\bin\ldapsearch 
         -h hostname_of_replica_being_upgraded 
         -p port 
         -D cn=orcladmin 
         -w superuser_password 
         -b "" -s base "(objectclass=*)" orclreplicaid
    

    On UNIX systems:

    SOURCE_ORACLE_HOME/bin/ldapsearch 
         -h hostname_of_replica_being_upgraded 
         -p port 
         -D cn=orcladmin 
         -w superuser_password 
         -b "" 
         -s base "(objectclass=*)" orclreplicaid
    
  2. Create an LDIF file called id.ldif with the following content:

    dn: orclagreementid=000002,orclreplicaid=replicaid,cn=replication configuration
    changetype: modify
    replace: orclreplicationid
    orclreplicationid: 2 
    

    Note that in the above example, the first two lines should appear all in one line in the LDIF file.

  3. Apply the LDIF file by using the following ldapmodify command:

    ldapmodify -p port 
               -h host 
               -D DN 
               -w password 
               -f id.ldif
    

    In this example, replace port, host, DN, and password with the appropriate values for your environment.

    See Also:

    "The Replication Agreement Entry" in the chapter, "Oracle Internet Directory Replication Concepts" in the Oracle Fusion Middleware Administrator's Guide for Oracle Internet Directory for information about the orclreplicationid attribute

    "Oracle Internet Directory Data Management Tools" in the Oracle Fusion Middleware User Reference for Oracle Identity Management for more information about using the ldapmodify command