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:

Task 1: Review the Terminology, Prerequisites, and Key Concepts For Upgrading a Replication Environment
Task 2: Prepare for the Oracle Identity Management Multimaster or Fan-Out Replication Upgrade
Task 3: Perform the Oracle Internet Directory Replica Upgrade
Task 4: Completing the Upgrade of Each Replica

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:

Terminology Conventions for This Chapter
Valid Starting Points When Upgrading a Replication Environment
Oracle Recommendations When Upgrading a Replication Environment

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 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:

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

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

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:

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

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

Navigate to the following directory and locate ias.properties file:

On Windows systems:
```
SOURCE_ORACLE_HOME\config
```
On UNIX systems:
```
SOURCE_ORACLE_HOME/config
```
Open the ias.properties file and verify that the properties shown in Table 14-1 are correct and valid.
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.
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:

Selecting a Replica Upgrade Method
Upgrading One Replica at a Time
Upgrading Oracle Internet Directory on Multiple Replicas Simultaneously

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:

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".
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.
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.
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.

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

14.3.3 Upgrading Oracle Internet Directory on Multiple Replicas Simultaneously

Use the following procedure to upgrade all the replicas simultaneously:

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".
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
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.
After you upgrade the replica, verify that the database on each upgraded replica is up and running.
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
```
For each upgraded replica, perform the steps in Section 14.4, "Task 4: Completing the Upgrade of Each Replica".
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:

Changing the Replication DN Password in the Oracle Internet Directory Wallet for Each Replica
Setting the orclreplicationid Attribute in the Upgraded 11g Directory

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:

Changing the Replication DN Password
Resetting the Replication DN Password

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".

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:

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

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

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:

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

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.
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