6 Updating the Oracle Unified Directory Software
You can update an Oracle Unified Directory directory service to the latest version without a service interruption. It also describes how to update an individual directory server instance and Oracle Unified Directory Services Manager.
Topics:
6.1 About Starting Points for an Oracle Unified Directory Update
In this release Oracle Unified Directory 12c (12.2.1.3.0) can be upgraded to 12c (12.2.1.4.0) release. The upgrade procedures in this guide explain how to upgrade an existing Oracle Unified Directory 12c (12.2.1.3.0) to Oracle Unified Directory 12c (12.2.1.4.0).
In the previous release(s), to upgrade from Oracle Unified Directory 11g (11.1.2.3.0) to 12c (12.2.1.4.0) it was only possible to first upgrade Oracle Unified Directory 11g (11.1.2.3.0) to 12c (12.2.1.3.0) and then upgrade from Oracle Unified Directory 12c (12.2.1.3.0) to 12c (12.2.1.4.0).
In this release it is now possible to perform an in-place upgrade directly from Oracle Unified Directory 11g (11.1.2.3.0) to 12c (12.2.1.4.0). The 12c (12.2.1.4.0) can be installed on a different directory and then change the install path of Oracle Unified Directory 11g (11.1.2.3.0) instance.
6.2 Prerequisites for Oracle Unified Directory Upgrade
Before you begin to upgrade Oracle Unified Directory 12c (12.2.1.4.0), you must stop the servers and back up your current environment.
You must complete the following prerequisites for upgrading to the Oracle Unified Directory 12c (12.2.1.4.0) environment:
-
Stop all the Directory Server instances and domains where Oracle Unified Directory Services Manager (OUDSM) is installed, depending upon the domain configuration.
Stop Standalone Oracle Unified Directory Server
If you installed Oracle Unified Directory in a Standalone Oracle Unified Directory Server (Managed independently of WebLogic server) mode, stop all the Directory Server instances using the
stop-ds
command.UnixORACLE_HOME/INSTANCE_NAME/OUD/bin/stop-ds
Windows
ORACLE_HOME\INSTANCE_NAME\OUD\bat\stop-ds.bat
Stop Collocated Oracle Unified Directory Server
If you installed Oracle Unified Directory in a Collocated Oracle Unified Directory Server (Managed through WebLogic server) mode, complete the following steps:
- Stop the OUD instance by running the following command from
command line interface.
Unix
DOMAIN_HOME/bin/stopComponent.sh INSTANCE_NAME
Windows
DOMAIN_HOME\bin\stopComponent.bat INSTANCE_NAME
- Stop the node manager.
Unix
DOMAIN_HOME/bin/stopNodeManager.sh
Windows
DOMAIN_HOME\bin\stopNodeManager.cmd
- Stop the Oracle WebLogic Administration Server.
Unix
DOMAIN_HOME/bin/stopWebLogic.sh
Windows
DOMAIN_HOME\bin\stopWebLogic.cmd
- Stop the OUD instance by running the following command from
command line interface.
-
Create a complete backup of your pre-upgrade environment before you begin an upgrade.
Note:
Oracle recommends that you create a complete backup of your pre-upgrade environment before you begin an upgrade. Upgrades cannot be reversed. In most cases, if an error occurs, you must stop the upgrade and restore the entire environment from backup and begin the upgrade process from the beginning.-
Back up the Oracle home (
ORACLE_HOME
). For example:Unix
tar -cf oracle_home_backup_06052017.tar ORACLE_HOME/*
Windows
jar cMf oracle_home_backup_06052017.jar ORACLE_HOME\*
-
if your Oracle Unified Directory instance (
OUD_INSTANCE
) reside outside the Oracle home (ORACLE_HOME
), then you must back up the instance directory. For example:Unix
tar -cf oud_instance_backup_06052017.tar oud_instance/*
Windows
jar cMf oracle_home_backup_06052017.jar ORACLE_HOME\*
-
If your Java Development Kit (JDK) resides inside the Oracle home (
ORACLE_HOME
), then you must move it to another location before you perform an upgrade.
-
6.3 Updating a Directory Service Without Service Interruption
Updating a replicated Oracle Unified Directory topology involves updating the software for each server instance individually. The strategy for maintaining service during an update depends on the specifics of your deployment, but usually, you can update an entire topology without any interruption in service.
Because a particular directory server instance must be stopped during the update process, maintaining service during an update requires alternative servers that can handle client requests while a particular server is down.
If your deployment includes one or more proxy server instances that route client requests to the back-end servers, you can safely take down one directory server at a time and update that server instance. The proxy server will reroute client requests to ensure uninterrupted service. Upgrading the proxy server instance requires more than one proxy server instance with the same configuration.
If your deployment does not include a proxy server, you must configure your client applications to send requests to an alternative server while a specific directory server instance is being updated.
The following sections outline the steps to follow for each of these topologies:
6.3.1 Upgrading a Topology That Includes a Proxy Server
Review these topics for the various topologies with the directory servers and replication servers either installed on the same host or different hosts.
Various topologies are possible as explained in the following topics:
-
About Topology with the Replication Servers and Directory Servers on the Same Host.
-
Upgrading a Topology with the Replication Servers and Directory Servers on the Same Host
-
About Topology with Replication Servers and Directory Servers on Different Hosts.
-
Upgrading a Topology wIth Replication Servers and Directory Servers on Different Hosts
6.3.1.1 About Topology with the Replication Servers and Directory Servers on the Same Host
In this topology, the directory servers and replication servers are installed on the same host.
If a single host contains both a replication server and a directory server, and those servers are associated with the same ORACLE_HOME
directory, the servers are stopped and updated at the same time.
In the following figure, Group 1 and Group 2 refer to configured replication groups. For more information about replication groups, see About Replication Groups in Administering Oracle Unified Directory.
Figure 6-1 Replicated Topology With Proxy Servers - RS and DS on the Same Host

6.3.1.2 Upgrading a Topology with the Replication Servers and Directory Servers on the Same Host
To update a topology with the directory servers and replication servers installed on the same host:
- Change the configuration of proxy server A so that client requests are not routed to directory server A.
- Stop directory server A. The replication server running on this host is stopped at the same time.
- Update directory server A, following the steps in Upgrading an Existing Oracle Unified Directory Server Instance.
- Restart directory server A.
- Test that your directory service is working properly before upgrading successive servers.
- Repeat steps 1-5 for each directory server in that replication group.
- Follow steps 1-6 for each replication group in the topology.
- Stop proxy server A.
- Update proxy server A, following the steps in Upgrading an Existing Oracle Unified Directory Server Instance.
- Restart proxy server A.
- Repeat steps 8-10 for the remaining proxy servers in the topology.
6.3.1.3 About Topology with Replication Servers and Directory Servers on Different Hosts
In this topology, the directory servers and replication servers are installed on different hosts. In the following figure, Group 1 and Group 2 refer to configured replication groups. For more information about replication groups, see About Replication Groups in Administering Oracle Unified Directory.
Figure 6-2 Replicated Topology With Proxy Servers - RS and DS on Different Hosts

6.3.2 Upgrading a Topology That Does Not Include a Proxy Server
In a topology that does not include any proxy server instances, you must update your client applications so that they point to an alternative directory server each time you take a directory server down for an update.
The following diagram shows a replicated topology that does not include a proxy server. This topology assumes that the directory servers and replication servers are installed on the same ORACLE_HOME
directory.
In this diagram, Group 1 and Group 2 refer to configured replication groups. See About Replication Groups in Administering Oracle Unified Directory.
Figure 6-3 Replicated Oracle Unified Directory Topology Without Proxy Servers

To update a topology that does not include a proxy server:
- Change your client application configuration so that applications do not access directory server A directly.
- Stop directory server A. The replication server on this host is stopped and updated at the same time.
- Update directory server A, following the steps in Upgrading an Existing Oracle Unified Directory Server Instance.
- Restart directory server A.
- Test that your directory service is working properly before upgrading successive servers.
- Change your client application configuration so that applications do not access directory server B directly.
- Stop directory server B.
- Update directory server B, following the steps in Upgrading an Existing Oracle Unified Directory Server Instance.
- Follow steps 1-8 for each replication group in the topology.
6.4 Upgrading an Existing Oracle Unified Directory Server Instance
You can upgrade all Oracle Unified Directory server instances that are associated with a specific ORACLE_HOME
directory.
Note:
-
If your Instance Home or Domain Home contains both OUD and OUDSM, you must review both Upgrading an Existing Oracle Unified Directory Server Instance and Upgrading Oracle Unified Directory Services Manager.
-
It is mandatory that you create your Oracle Unified Directory instance and Oracle Unified Directory Services Manager domain outside of the Oracle home directory.
To upgrade an existing Oracle Unified Directory server instance:
6.4.1 Enabling SCIM and Data REST APIs for an Upgraded 12.2.1.4.0 OUD Instance
You can enable the SCIM and Data REST APIs for upgraded 12.2.1.4.0 OUD instances to perform the REST API operations.
OUD exposes SCIM/Data REST interface through the HTTP and HTTPS connection handlers. You can enable these handlers either during an OUD instance set up or through dsconfig
for an existing instance.
However, if during the OUD instance set up the LDAPS port is not configured, then you would not be able to set up the HTTPS port. In this scenario, you need to ensure that the configurations for cn=JKS,cn=Key Manager Providers,cn=config
and cn=JKS,cn=Trust Manager Providers,cn=config
are enabled, which in turn requires you to create keystore and truststore.
Enabling SCIM/Data REST for an Upgraded 12.2.1.4.0 OUD Instance with LDAPS Not Configured
While setting up the OUD instance if you have not configured the LDAPS port, then perform the following steps to enable support for SCIM/ Data REST API:
- Create keystore to configure
cn=JKS,cn=Key Manager Providers,cn=config
. See Using JKS Key Manager Provider in Administering Oracle Unified Directory. - Create truststore to configure
cn=JKS,cn=Trust Manager Providers,cn=config
. See Using the JKS Trust Manager Provider in Administering Oracle Unified Directory. - Run the following
dsconfig
commands to enablecn=JKS,cn=Key Manager Providers,cn=config
andcn=JKS,cn=Trust Manager Providers,cn=config
configurations:dsconfig set-key-manager-provider-prop \ --provider-name "JKS" \ --set enabled:true \ --set "key-store-type:JKS" \ --set "key-store-file:config/jks-keystore" \ --set "key-store-pin-file:config/jks-keystore.pin” \ --hostname localhost \ --port 1444 \ --portProtocol LDAP \ --bindDN "cn=Directory Manager" \ --bindPasswordFile /home/oracle/pwd.txt \ --no-prompt
dsconfig set-trust-manager-provider-prop \ --provider-name "JKS" \ --set enabled:true \ --set "trust-store-type:JKS" \ --set "trust-store-file:config/jks-truststore" \ --hostname localhost \ --port 1444 \ --portProtocol LDAP \ --bindDN "cn=Directory Manager" \ --bindPasswordFile /home/oracle/pwd.txt \ --no-prompt
- Run the
dsconfig
command-line utility withcreate-connection-handler
subcommand as follows to create the connection handlers:Setting Up HTTP Port:
dsconfig create-connection-handler \ --handler-name "HTTP Connection Handler" \ --type http \ --set enabled:true \ --set listen-port:1080 \ --hostname localhost \ --port 1444 \ --portProtocol LDAP \ --bindDN "cn=Directory Manager" \ --bindPasswordFile /home/oracle/pwd.txt \ --no-prompt
Setting Up HTTPS Port:
dsconfig create-connection-handler \ --handler-name "HTTPS Connection Handler" \ --type http \ --set enabled:true \ --set listen-port:1081 \ --set use-ssl:true \ --set trust-manager-provider:JKS \ --set key-manager-provider:JKS \ --hostname localhost \ --port 1444 \ --portProtocol LDAP \ --bindDN "cn=Directory Manager" \ --bindPasswordFile /home/oracle/pwd.txt \ --no-prompt
- Configure the REST endpoints as follows:
- Enable the
Token Generator
endpoint.dsconfig set-end-point-prop \ --point-name 'Token Generator' \ --set enabled:true \ --hostname localhost \ --port 1444 \ --portProtocol LDAP \ --trustAll \ --bindDN "cn=Directory Manager" \ --bindPasswordFile /home/oracle/pwd.txt \ --no-prompt
- Enable the
REST Server
extension.dsconfig set-extension-prop \ --Extension-name 'REST Server' \ --set enabled:true \ --hostname localhost \ --port 1444 \ --portProtocol LDAP \ --trustAll \ --bindDN "cn=Directory Manager" \ --bindPasswordFile /home/oracle/pwd.txt \ --no-prompt
- Enable the directory endpoint.
dsconfig set-directory-end-point-prop \ --set enabled:true \ --hostname localhost \ --port 1444 \ --portProtocol LDAP \ --trustAll \ --bindDN "cn=Directory Manager" \ --bindPasswordFile /home/oracle/pwd.txt \ --no-prompt
- Enable the
- Restart the OUD instance.
Enabling SCIM/Data REST for an Upgraded 12.2.1.4.0 OUD Instance with LDAPS Configured
While setting up the OUD instance if you have configured the LDAPS port, then run the dsconfig
command-line utility to configure the connection handlers to expose the SCIM/Data REST interface.
- Run the
dsconfig
command-line utility withcreate-connection-handler
subcommand as follows to create the connection handlers:Setting Up HTTP Port:
dsconfig create-connection-handler \ --handler-name "HTTP Connection Handler" \ --type http \ --set enabled:true \ --set listen-port:1080 \ --hostname localhost \ --port 1444 \ --portProtocol LDAP \ --bindDN "cn=Directory Manager" \ --bindPasswordFile /home/oracle/pwd.txt \ --no-prompt
Setting Up HTTPS Port:
dsconfig create-connection-handler \ --handler-name "HTTPS Connection Handler" \ --type http \ --set enabled:true \ --set listen-port:1081 \ --set use-ssl:true \ --set trust-manager-provider:JKS \ --set key-manager-provider:JKS \ --hostname localhost \ --port 1444 \ --portProtocol LDAP \ --bindDN "cn=Directory Manager" \ --bindPasswordFile /home/oracle/pwd.txt \ --no-prompt
- Configure the REST endpoints as follows:
- Enable the
Token Generator
endpoint.dsconfig set-end-point-prop \ --point-name 'Token Generator' \ --set enabled:true \ --hostname localhost \ --port 1444 \ --portProtocol LDAP \ --trustAll \ --bindDN "cn=Directory Manager" \ --bindPasswordFile /home/oracle/pwd.txt \ --no-prompt
- Enable the
REST Server
extension.dsconfig set-extension-prop \ --Extension-name 'REST Server' \ --set enabled:true \ --hostname localhost \ --port 1444 \ --portProtocol LDAP \ --trustAll \ --bindDN "cn=Directory Manager" \ --bindPasswordFile /home/oracle/pwd.txt \ --no-prompt
- Enable the directory endpoint.
dsconfig set-directory-end-point-prop \ --set enabled:true \ --hostname localhost \ --port 1444 \ --portProtocol LDAP \ --trustAll \ --bindDN "cn=Directory Manager" \ --bindPasswordFile /home/oracle/pwd.txt \ --no-prompt
- Enable the
- Restart the OUD instance.
6.4.2 Verifying the Oracle Unified Directory Server Instance Upgrade
After completing all the upgrade steps, verify that the upgrade was successful by checking that the Oracle Unified Directory Server version has been properly updated.
To verify the version of the Oracle Unified Directory Server instance, run the
start-ds
command.
cd $OUD_INSTANCE_HOME/OUD/bin/start-ds -s | grep 'Oracle Unified Directory'
The following shows an example of the result after running the command:
Oracle Unified Directory 12.2.1.4.0
Build ID: 20170727163142Z
JAVA Version: 1.8.0_251
JAVA Vendor: Oracle Corporation
JVM Version: 25.251-b08
JVM Vendor: Oracle Corporation
JAVA Home: /u01/oracle/products/dir12c/jdk/jre
Class Path: /u02/private/oracle/config/instances/oud1/OUD/classes:/u01/oracle/products/dir12c/oud/winlib/classpath.jar:/u02/private/oracle/config/instances/oud1/OUD/lib/*.jar
JE Version: 7.0.7
Current Directory: /u01/app//imupg_files/oud12cPS3
Installation Directory: /u01/app/fmw/ORACLE_HOME/dir12c/oud
Instance Directory: /u01/app/fmw/ORACLE_HOME/config/instances/oud1/OUD
Operating System: Linux 2.6.39-400.306.1.el6uek.x86_64 amd64
JVM Architecture: 64-bit
System Name: ldaphost1
Available Processors: 4
Max Available Memory: 5569642496
Currently Used Memory: 5569642496
Currently Free Memory: 5518099608
Verify that the upgraded version matches the latest version number for that Oracle Unified Directory Server.
6.5 Upgrading Oracle Unified Directory Services Manager
Consider these topics if you run Oracle Unified Directory Services Manager on Oracle WebLogic Server to manage Oracle Unified Directory.
Note:
If your Instance Home or Domain Home contains both OUD and OUDSM, you must review both Upgrading an Existing Oracle Unified Directory Server Instance and Upgrading Oracle Unified Directory Services Manager.
6.5.1 OUDSM Version Requirements
The version of Oracle Unified Directory Services Manager (OUDSM) described in this guide is 12c (12.2.1.4.0). When you update the Oracle Unified Directory software to 12c (12.2.1.4.0), OUDSM is also updated to this same release.
Note:
OUDSM update to OUDSM 12c (12.2.1.4.0) is supported from Oracle Unified Directory 12c (12.2.1.3.0).
Several requirements for using OUDSM with Oracle Unified Directory include:
-
You can use OUDSM 12c (12.2.1.4.0) to manage only Oracle Unified Directory 12c (12.2.1.4.0).
-
You cannot use OUDSM 12c (12.2.1.4.0) to manage previous versions of Oracle Unified Directory, Oracle Internet Directory, or Oracle Virtual Directory. Similarly, you cannot use versions of OUDSM shipped with Oracle Internet Directory or Oracle Virtual Directory to manage any versions of Oracle Unified Directory.
Note:
After you update Oracle Unified Directory, you might encounter problems while trying to access the updated version of OUDSM on your browser. This problem usually occurs if you used your browser to access an earlier version of OUDSM.
Therefore, to access the updated version of OUDSM, first clear your browser's cache and cookies.
6.5.1.1 Updating Multiple Instances of OUDSM
If you have multiple instances of OUDSM in your replication topology, consider the following requirements:
-
If you update one OUDSM instance to 12c (12.2.1.4.0), you must update all OUDSM and replicated instances.
-
If you update OUDSM to 12c (12.2.1.4.0), Oracle Unified Directory must be the same version. An updated OUDSM version is not supported with earlier versions of Oracle Unified Directory.
6.5.2 Stopping the Administration Server
You must stop the Administration Server (the 12.2.1.3.0 WebLogic domain used for OUDSM)
To stop the Administration Server, run the stopWebLogic
script from
the 12.2.1.3.0 DOMAIN_HOME
:
-
UNIX
DOMAIN_HOME/bin/stopWebLogic.sh
-
Windows
DOMAIN_HOME\bin\stopWebLogic.cmd
6.5.3 Creating a Complete Backup
Before you start an upgrade, back up the Oracle home
(ORACLE_HOME
) and the domain directory (DOMAIN_HOME
) that
includes the WebLogic domain used for 12.2.1.3.0 OUDSM.
To create a backup copy of the domain directory:
6.5.4 Uninstalling the 12c (12.2.1.3.0) Product Distributions
Uninstall the Oracle Unified Directory and Oracle Fusion Middleware Infrastructure before upgrading your existing Oracle Unified Directory Services Manager 12c (12.2.1.3.0)
- Uninstall Oracle Unified Directory, as described in Removing the Oracle Unified Directory Software.
- Uninstall Oracle Fusion Middleware Infrastructure, as described in Uninstalling Oracle Fusion Middleware Infrastructure.
This is the start of your topic.
6.5.5 Installing the 12c (12.2.1.4.0) Product Distributions
Install the collocated 12c (12.2.1.4.0) Oracle Unified Directory before upgrading your existing Oracle Unified Directory Services Manager 12c (12.2.1.3.0).
6.5.6 Starting the Administration Server
After a successful upgrade, restart all processes and servers, including the Administration Server and any Managed Servers.
To start the Administration Server, use the startWebLogic
script
from the 12.2.1.4.0 Domain home:
-
UNIX
DOMAIN_HOME/bin/startWebLogic.sh
-
Windows
DOMAIN_HOME\bin\startWebLogic.cmd
6.5.7 Verifying the OUDSM Upgrade
You can verify the ODSM upgrade by accessing the OUDSM interface and checking the version number.
To verify that the ODSM upgrade was successful, perform the following steps:
-
Open a browser, and access OUDSM using the following URL format:
http://host:port/oudsm
where host is the name of the managed server on which OUDSM is running and port is the Managed Server port number of the Administration Server. The default admin port is
7001
. -
When the login page appears, navigate to the bottom right pane and click About.
The About Oracle Unified Directory Services Manager page is displayed.
-
Verify that the version number of the upgraded OUDSM version matches the latest version number.
6.6 What to Do If the Upgrade Process Fails
If any step in the upgrade process fails, then terminate the upgrade process and restore the environment to its original state using the backup files you created in Prerequisites for Oracle Unified Directory Upgrade.