6 Upgrading the Oracle Unified Directory Software
You can upgrade an Oracle Unified Directory to the latest version without a service interruption. It also describes how to upgrade an individual directory server instance and Oracle Unified Directory Services Manager.
Topics:
6.1 About Starting Points for an Oracle Unified Directory Upgrade
In this release, Oracle Unified Directory 12c (12.2.1.4.0) can be upgraded to 14c (14.1.2.1.0) release. The upgrade procedures in this guide explain how to upgrade an existing Oracle Unified Directory 12c (12.2.1.4.0) to Oracle Unified Directory 14c (14.1.2.1.0).
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 14c (14.1.2.1.0) environment:
Note:
This applies only to collocated installations and does not apply to standalone OUD 14.1.2.1.0 installations.- Apply the ADF patch (search for Bug ID 37376076 at https://support.oracle.com) manually using OPatch to the OUD 14.1.2.1.0
ORACLE_HOME
before performing the reconfiguration step. - Apply the one-off EM patch (search for Bug ID 37476292 at https://support.oracle.com) manually using OPatch to the OUD 14.1.2.1.0
ORACLE_HOME
before performing the reconfiguration step.
-
Stop all the Directory Server instances and domains where Oracle Unified Directory Services Manager (OUDSM) is installed, depending upon the domain configuration.
Stop the Standalone Oracle Unified Directory Server
If you have 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 the Collocated Oracle Unified Directory Server
If you have 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
) resides 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 Upgrading a Directory Server Without Service Interruption
Upgrading a replicated Oracle Unified Directory topology involves upgrading the software for each server instance individually. The strategy for maintaining service during an upgrade depends on the specifics of your deployment, but usually, you can upgrade an entire topology without any interruption in service.
Because a particular directory server instance must be stopped during the upgrade process, maintaining service during an upgrade 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 upgrade 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 upgraded.
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 upgraded 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 upgrade 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.
- Upgrade directory server A, following the steps in Upgrading an Existing Oracle Unified Directory Server Instance.
- Restart directory server A.
- Test that your directory server 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.
- Upgrade 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 upgrade your client applications so that they point to an alternative directory server each time you take a directory server down for an upgrade.
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 upgrade 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 upgraded at the same time.
- Upgrade directory server A, following the steps in Upgrading an Existing Oracle Unified Directory Server Instance.
- Restart directory server A.
- Test that your directory server 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.
- Upgrade 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 14.1.2.1.0 OUD Instance
You can enable the SCIM and Data REST APIs for upgraded 14.1.2.1.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 14.1.2.1.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 14.1.2.1.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 upgraded.
To verify the version of the Oracle Unified Directory Server instance, run the
start-ds
command.
$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 14.1.2.1.0
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.
- OUDSM Version Requirements
- Stopping the Administration Server
- Creating a Complete Backup
- Uninstalling the 12c (12.2.1.4.0) Product Distributions
- Installing the 14c (14.1.2.1.0) Product Distributions
- Reconfiguring the 14c (14.1.2.1.0) Product Distributions
- Starting the Administration Server
- Verifying the OUDSM Upgrade
6.5.1 OUDSM Version Requirements
The version of Oracle Unified Directory Services Manager (OUDSM) described in this guide is 14c (14.1.2.1.0). When you upgrade the Oracle Unified Directory software to 14c (14.1.2.1.0), OUDSM is also upgraded to this release.
Note:
The 14c (14.1.2.1.0) OUDSM upgrade is supported only for expanded domains and not for compact domains. To determine if a domain is compact, check the following file:DOMAIN_HOME/init-info/config-groups.xml
.
Locate the following tag:
<config-groups topology-profile="Compact" xmlns="http://xmlns.oracle.com/weblogic/config-groups">
If the tag specifies Compact
as shown above, then you cannot upgrade the domain.
Several requirements for using OUDSM with Oracle Unified Directory include:
-
You can use OUDSM 14c (14.1.2.1.0) to manage only Oracle Unified Directory 14c (14.1.2.1.0).
-
You cannot use OUDSM 14c (14.1.2.1.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 upgrade Oracle Unified Directory, you might encounter problems while trying to access the upgraded 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 upgraded version of OUDSM, first clear your browser's cache and cookies.
6.5.1.1 Upgrading Multiple Instances of OUDSM
If you have multiple instances of OUDSM in your replication topology, consider the following requirements:
-
If you upgrade one OUDSM instance to 14c (14.1.2.1.0), you must upgrade all OUDSM and replicated instances.
-
If you upgrade OUDSM to 14c (14.1.2.1.0), Oracle Unified Directory must be the same version. An upgraded 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.4.0 WebLogic domain used for OUDSM)
To stop the Administration Server, run the stopWebLogic
script from the 12.2.1.4.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.4.0 OUDSM.
To create a backup copy of the domain directory:
6.5.4 Uninstalling the 12c (12.2.1.4.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.4.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 14c (14.1.2.1.0) Product Distributions
Install the collocated 14c (14.1.2.1.0) Oracle Unified Directory before upgrading your existing Oracle Unified Directory Services Manager 12c (12.2.1.4.0).
6.5.6 Reconfiguring the 14c (14.1.2.1.0) Product Distributions
You must reconfigure the OUDSM 12c (12.2.1.4.0) domain before starting the Administration Server.
6.5.7 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 14.1.2.1.0 Domain home:
-
UNIX
DOMAIN_HOME/bin/startWebLogic.sh
-
Windows
DOMAIN_HOME\bin\startWebLogic.cmd
6.5.8 Verifying the OUDSM Upgrade
You can verify the OUDSM upgrade by accessing the OUDSM interface and checking the version number.
To verify that the OUDSM upgrade was successful, perform the following steps:
-
Open a browser, and access OUDSM using the following URL format:
http://host:port/oudsm
where the host and port correspond to the Administration Server on which OUDSM is deployed. 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.