The primary purpose of the Oracle Identity Management (IDM) Patching Framework for Oracle Fusion Applications is to simplify and expedite the maintenance of the code and functionality shipped as part of Oracle Identity Management for the Oracle Fusion Applications suite of products.
IDM patching can be either manual or automated depending on a variety of factors.
The Oracle Identity Management patching framework coordinates the application of multiple patches to an Oracle Identity Management deployment and includes the following features:
Patches all products within the Oracle Identity Management domain, including dependencies
Runs across multiple machines
Uses shared or local storage
Runs during both initial provisioning and on an ongoing basis
Runs in a defined, tier-wise order, minimizing downtime based on the patches being applied
Stops and starts affected servers, as required and when appropriate
Includes the ability to execute post-patch artifact changes
Includes comprehensive state-sharing and reporting
Oracle Identity Manager includes patches for the following products that are installed in the Oracle Identity Management domain:
Oracle Internet Directory
Oracle Virtual Directory
Oracle Directory Services Manager
Oracle Identity Federation
Oracle Access Manager
Oracle Identity Manager
Oracle HTTP Server
Oracle HTTP Server WebGate
Oracle SOA Suite
Oracle WebLogic Server
The Oracle Identity Management Patching Framework is composed of the Oracle Identity Management Patch Manager and the Oracle Identity Management Patcher tools. These tools work to apply patches to the Oracle Identity Management environment, using complete information about the deployment topology and verifying what services are running on which hosts. Based on the topology and the patches available, a patch session is created that defines and executes a patch plan. The Oracle Identity Management Patch Manager is used to generate the patch plan.
The patch plan is then executed by the Oracle Identity Management Patcher by:
Stopping and starting servers
Applying patches, as required, in an optimal manner
The Oracle Identity Management Patch Manager is a tool that generates the patch plan and controls the patch session.
The Oracle Identity Management Patch Manager generates the patch plan as follows:
A PATCH_TOP directory containing patches, classified by each product subdirectory is provided to the tool.
The PATCH_TOP directory is scanned and initial validations are performed.
The deployment topology is read and analyzed.
The information obtained in Step 2 and Step 3 is combined, and a patch plan is generated using the OPlan utility. The patch plan is generated in HTML and plain-text formats, as well as binary format used for execution.
The topology data used by the tools is located in the topology store, which is an XML file located at $LCM_CONFIG/topology/topology.xml. This file contains most of the environment information used by the tools to apply patches. Additionally, the provisioning.plan file, located at $IDM_TOP/provisioning/plan, is also used for some tasks.
patchtop-contents.properties FileThe downloaded patches must be organized in the following directory structure:
A top-level PATCH_TOP directory containing different subdirectories for storing product-specific patches.
Mapping between the products and the relative paths of the subdirectories under the PATCH_TOP stored in patchtop-contents.properties.
The relative paths of the subdirectories should be populated correctly in the patchtop-contents.properties file under the $IDM_LCM_TOP/patch/config/ directory to ensure that the Oracle Identity Management Patching Framework can find the patches.
CONDITIONAL: There is a default structure already supported by the patchtop-content.properties file. If you do not want to follow the existing directory structure for storing the patches, then ensure that the patchtop-content.properties file is updated with the relative paths created under the PATCH_TOP so that the patching framework can find the product-specific patches correctly.
The following example provides details of the patchtop-contents.properties file:
#key: name of Fusion Middleware/Application patch component
#value: list of PATCH_TOP subdirectories containing the patches of the component separated by commas.
common=oracle_common/patch
dir=idm/patch/oid, idm/patch/ovd, pltsec/patch
oam=iamsuite/patch/oam, idm/patch
odsm=idm/patch/odsm
ohs=webtier/patch
ohswg=webgate/patch
oif=idm/patch/oif, oif/patch
soa=soa/patch
wls=smart_update/weblogic
The targets shown on the left side cannot be modified, but the values on the right side can be updated. These values are the relative paths from the PATCH_TOP. If these paths are deleted from the file, the Oracle Identity Management Patching Framework assumes the default path location.
env.properties FileThe env.properties file, located at $IDM_LCM_TOP/patch/config/env.properties, contains all environment variables required by the Oracle Identity Management Patching Framework. These properties are populated by the provisioning flow. Before running the Oracle Identity Management Patch Manager and Oracle Identity Management Patcher tools, ensure that the environment variables described in the following table are set:
Table 7-1 Environment Variables
| Name | Value | Mandatory | Description |
|---|---|---|---|
|
JAVA_HOME |
JDK absolute path |
Yes |
The path pointing to the JDK location. |
|
IDM_TOP |
IDM_TOP absolute path |
Yes |
The absolute path of the IDM_TOP where IDM products are installed and configurations are stored. |
|
LCM_CONFIG |
IDMLCM absolute path |
Yes |
Absolute path where the IDMLCM configuration is stored. |
|
ANT_HOME |
Ant Home |
No, but recommended |
Absolute path pointing to the root directory of an Apache Ant distribution. This is required only to apply artifact changes for some products. If this environment variable is not set, impacted artifact changes may not complete. |
|
RETURN_MESSAGE_BUFFER_SIZE |
This buffer size includes standard output and error messages stored in log files Default value is 8KB |
No |
The size of return message that is stored for each command executed. Affects the size of output printed to console and logs. Available units are as follows:
|
|
COMMAND_TIMEOUT |
A number and unit default value is 3600s (1 hour) |
No |
Timeout value followed by unit. If command execution takes longer, it is terminated. Permissible units are as follows:
|
The env.properties file is populated during the provisioning flow. However, in case of multiple IDM_TOPs are using a single Oracle Identity Management provisioning and patching tools install, then the values must be deleted of the IDM_TOP and LCM_CONFIG variables from the env.properties file and set the correct values.
There is also an option to set the environment variables through the command line using the commands listed. However, ensure that the existing values are deleted from the env.properties file before setting the values. In case of use a POSIX-compliant shell, use the following command:
export JAVA_HOME=<JDK absolute path>
The Oracle Identity Management Patching Framework consists of the Oracle Identity Management Patch Manager and Oracle Identity Management Patcher tools. The following sections describe how to create and apply the patch plan:
Perform the following steps to create the patch plan using Oracle Identity Management Patch Manager:
To run the Oracle Identity Management Patch Manager, use the command line utility, idmpatchmgr, located in the $IDM_LCM_TOP/patch/bin directory. Its shell script sets the environment and calls the utility. For UNIX, the shell script is idmpatchmgr.sh. idmpatchmgr and can be run with various commands and options. Oracle Identity Management Patch Manager maintains a stateful session to track the patch process coordination with the Oracle Identity Management Patcher tool.
MANDATORY: The Oracle Identity Management Patch Manager must be run on the primordial host to create the patch plan as described in the Create the Patch Plan section. A new patching session cannot be created until the existing session is completed or is aborted.
Oracle Identity Management Patch Manager maintains a session file in the $LCM_CONFIG/patch/session/ directory. The session file has the current state of the Oracle Identity Management Patch Manager patch session. At any given point in time there will be only one or zero active patch sessions existing on the primordial host.
The patch session displays one of the statuses as described in the following table. The status COMPLETE and INCOMPLETE are the terminal states; whereas FAILED and ABORTING are recoverable states.
Table 7-2 Patch Session Status
| State | Description |
|---|---|
|
|
In-progress state |
|
|
Halted state in response to a step failing execution |
|
|
Halted state in response to the administrator issuing an abort command |
|
|
Terminal state where all steps are executed |
|
|
Terminal state if a session is aborted, either in response to a step execution failure or otherwise |
Run the Oracle Identity Management Patch Manager, use the command line utility, idmpatchmgr, where instructions in brackets are optional . Example of the Oracle Identity Management Patch Manager command is a follows:
(UNIX) $IDM_LCM_TOP/patch/bin/idmpatchmgr.sh <command> [-options]
Where <command> is any IDM Patch Manager command, and the [options] are any options desired for the given command. The following table describes all the IDM Patch Manager commands:
Table 7-3 Oracle Identity Management Patch Manager Commands
| Command | Description |
|---|---|
|
apply |
Starts a patch session where selected patches will be deployed. |
|
rollback |
Starts a patch session where selected patches will be removed. |
|
abort |
Ends a patch session without completing all planned steps. |
|
progress |
Displays the status for an ongoing patch session. |
To view additional information for any idmpatchmgr command, use the following syntax:
(UNIX) $IDM_LCM_TOP/patch/bin/idmpatchmgr.sh command -help
To create a patch plan containing instructions for applying patches to an Oracle Identity Management environment, run the idmpatchmgr apply command. This plan can be executed by running the Oracle Identity Management Patcher tool.
MANDATORY: To create the patch plan, run the Oracle Identity Management Patch Manager on the primordial host.
Syntax
(UNIX) $IDM_LCM_TOP/patch/bin/idmpatchmgr.sh apply -patchtop patch_top
For more information about the way the patch plan is generated, see the Understand the Patch Plan section.
The patch plan is automatically generated by the Oracle Identity Management Patch Manager. To do so, Oracle Identity Management Patch Manager performs the following:
The apply command validates the given PATCH_TOP location and validates the existence of the patch session with ACTIVE or FAILED status.
If no patch session exists, the patch scanner is internally invoked to validate and generate a composite bundle patch from the provided PATCH_TOP. This bundle patch is internally used in the plan generation. The composite bundle patch is created in the location: $LCM_CONFIG/patch/patches.
A patch plan is generated with instructions for applying patches using the topology store information and composite bundle patch.
The apply command generates the patch plan in the following location in HTML and plain text formats:
$LCM_CONFIG/patch/status/current-sessionID/manager/log/PatchInstructions.html
$LCM_CONFIG/patch/status/current-sessionID/manager/log/PatchInstructions.text
The patch plan in HTML and plain text formats provides useful information regarding the Oracle Identity Management environment, commands executed by the Oracle Identity Management Patcher, total number of steps, steps that require downtime and so on. This enables you to better understand the Oracle Identity Management Patching Framework execution flow.
At the time of plan generation, a new patch session is created in ACTIVE status, with all steps with status PLANNED. The patch session is stored in the $LCM_CONFIG/patch/session/session file. The step information is stored in the $LCM_CONFIG/patch/session/step file.
The log files are generated in the following locations:
Before the session is created:
$LCM_CONFIG/patch/status/log/idmpatchmgr.log
After the session is created:
$LCM_CONFIG/patch/status/currentSessionID/manager/log/idmpatchmgr-session.log
The following table lists the option available for the apply command:
Table 7-4 apply Command Option
| Option | Description |
|---|---|
|
|
Displays the path to the location of the patches. |
The following section describe the concept of applying Oracle Identity Management Patcher is based on an understanding of the Oracle Identity Management Patches utility and consists of applying the patches and applying artifact changes. This section contains the following topics:
The Oracle Identity Management Patcher is the tool used to apply Oracle Identity Management (IDM) patches to an Oracle Fusion Applications environment.
To apply patches, use the run command. This command performs the following tasks:
Validates the existence of a patch session and the availability of one or more steps with status PLANNED for the host where the tool is running.
If there are one or more steps with status PLANNED for any other host prior to the above steps, then Oracle Identity Management Patcher reports that the execution is not possible until execution is complete for the other host.
Creates the following log file named status with the details:
$LCM_CONFIG/patch/status/currentSessionID/hosts/currentHostName/status
When Oracle Identity Management Patcher starts executing the patching steps, the status log file is updated with key = step-id and value = RUNNING. After setting the status, it extracts the command from the execution step and invokes the command using the step executor. On successful execution of the command, the status log file will be updated with key = step-id and value = COMPLETED. The execution continues to the next step from the execution plan for the current host.
If there are no steps to be executed for the current host, it halts the execution and updates the administrator on the next steps to be executed.
The run command also updates the session status. When reusing the run command, Oracle Identity Management Patch Manager displays the results.
On failure, the status log file is updated with key = step-id and value = FAILED and execution is stopped.
The run command generates log files in the following locations:
Before the session is created:
$LCM_CONFIG/patch/status/log/idmpatchmgr.log
$LCM_CONFIG/patch/status/log/idmpatch.log
After the session is created:
$LCM_CONFIG/patch/status/currentSessionID/manager/log/idmpatchmgr-session.log
$LCM_CONFIG/patch/status/currentSessionID/hosts/hostname/log/idmpatch-session.log
For information about how to use theOracle Identity Management Patcher run command, see the Apply the Patches section.
To run the Oracle Identity Management Patcher, use the command line utility, idmpatch, located in the $IDM_LCM_TOP/patch/bin directory. Its shell script sets the environment and calls the utility. The following command shows the basic syntax for the idmpatch utility:
(UNIX) $IDM_LCM_TOP/patch/bin/idmpatch.sh run
OPTIONAL: To run only the prerequisites, use the prereq option . This will not stop and start the services or apply and rollback patches. The syntax to run the idmpatch is as follows:
(UNIX)$IDM_LCM_TOP/patch/bin/idmpatch.sh run -prereq
Oracle Identity Management Patch Manager supports the application of post-patch artifact changes, such as adding an entry within a configuration properties file or invoking a product MBean. While most patches do not include them, Oracle Identity Management Patch Manager automatically executes the changes after all binary patch application for a single product is completed for those patches that do.
For example, if three patches [1, 2, 3] are applied to Oracle Access Manager within a patch session, and 1 contains an artifact change, the order of operations is [binary 1, binary 2, binary 3, artifact 1].