This chapter describes the procedure for patching the components of the Oracle Identity and Access Management software using the Lifecycle Tools.
It contains the following topics:
Before patching your Oracle Identity and Access Management software using the Lifecycle Tools, ensure that you complete the following prerequisites:
Installing the Oracle Identity and Access Management Lifecycle Tools for Patching Supported Products
Obtain patching-related tools for patching an Oracle Identity and Access Management deployment by installing the Oracle Identity and Access Management Lifecycle Tools.
For information about installing the Oracle Identity and Access Management Lifecycle Tools, see Oracle Fusion Middleware Deployment Guide for Oracle Identity and Access Management.
When you deploy an Oracle Identity and Access Management environment using the Oracle Identity and Access Management Lifecycle Tools, patching-related directories IAM_LCM_TOP
and LCM_CONFIG
, are created.
IAM_LCM_TOP
contains configuration files, executable files, scripts, and property files containing various environment variables that control the patching process. Figure 4-1 shows the contents of the IAM_LCM_TOP
directory.
The LCM_CONFIG
directory contains files such as logs, patch plans, topology store, credential store, and so on, that are used for some patching tasks. Figure 4-2 shows the contents of the LCM_CONFIG
directory.
Table 4-1 describes the components of the IAM_LCM_TOP
and LCM_CONFIG directories
.
Figure 4-1 Directory Structure of IAM_LCM_TOP
Figure 4-2 Directory Structure of LCM_CONFIG
Table 4-1 Directory Structure of an Oracle Identity and Access Management Patching Deployment
Directory Structure | Description |
---|---|
|
|
|
Contains the configuration files and the executable files for patching the software. |
|
Contains the Oracle Identity and Access Management Patch Manager and Oracle Identity and Access Management Patcher tools that can be executed on UNIX and Windows systems ( |
|
Contains |
|
Contains |
|
Contains scripts and property files required by the Patcher to start or stop services and for applying artifacts. |
|
|
|
Contains status files, logs, patches, and patch plan generated by Patch Manager when a patch session is started. |
|
Contains set of patches read in from the provided patch top, and staged by the Patch Manager for use during the session. These patches are used by the Patch Manager to generate the patch plan. |
|
Contains the patch plan in a machine-readable format, and other information about the session in progress that Oracle Identity and Access Management Patcher uses to execute the patching steps. |
|
Contains host-based files tracking the execution state of each patch-plan step. Also contains all generated log files, and the patch plan in human-readable HTML and plain-text formats. |
|
Contains the topology store file |
Note:
Modify the values in the common.properties
file and the patchtop-contents.properties
file as required. Before modifying these files, ensure that you check the content of these files, and set correct values.
The patchtop-contents.properties
file is located in IAM_LCM_TOP
/patch/config/
. It declares the relative paths within the patch top you provide, under which you place patches for each product supported by the Lifecycle Tools.
Open the patchtop-contents.properties
file, and verify its content.
Example 4-1 shows the contents of the patchtop-contents.properties
file.
common=oracle_common/patch dir=oud/patch oam=iamsuite/patch/oam ohs=webtier/patch ohswg=webgate/patch oim=iamsuite/patch/oim soa=soa/patch wls=smart_update/weblogic
The patchtop-contents.properties
file includes a default directory structure for all product patches. If you do not want to use the default directory structure to organize your patches, edit the file to declare the correct relative paths for your patch top, so that the Patch Manager can correctly detect all patches provided. If any of the parameters are commented out or removed from the file, the Patch Manager does not attempt to search for patches of those products within the patch top.
The IAM_LCM_TOP
directory also contains the following properties files:
common.properties
patch.properties
The common.properties
file is located in IAM_LCM_TOP
/common/config/
. It contains the environment variables JAVA_HOME
, IAM_TOP
, and LCM_CONFIG
, required for patching Oracle Identity and Access Management.
Ensure that you set the environment variables listed in Table 4-2 before running the Oracle Identity and Access Management Patch Manager and Oracle Identity and Access Management Patcher.
Table 4-2 Variables Listed in common.properties File
Variable | Description |
---|---|
|
The path pointing to the JDK location. |
|
The absolute path of the |
|
Absolute path where the configuration of the Lifecycle Tools is stored. |
The patch.properties
file is located in IAM_LCM_TOP
/patch/config/
. It contains preferences about low-level patching details, that you can modify. You need not edit this file as the default values that are available in the file are sufficient for most environments.
Ensure that you set the environment variables listed in Table 4-3 before running the Oracle Identity and Access Management Patch Manager and Oracle Identity and Access Management Patcher tools.
Table 4-3 Variables Listed in patch.properties File
Variable | Description |
---|---|
|
The size of return message that is stored for each command executed. This buffer size includes standard output and error messages stored in log files. This variable affects the size of output printed to console and logs. Following are the available units: - B (byte) - KB (kilobyte) - MB (megabyte) - GB (gigabyte) Default value of the variable is 8KB. |
|
The value consists of a timeout value followed by the unit. If the command execution takes longer, then the execution is terminated. Following are the permissible units for this variable: - ms (milliseconds) - s (seconds) - m (minutes) - h (hours) - d (days) Default value of the variable is 3600s (1 hour). |
Note:
The common.properties
file and patch.properties
are populated during the deployment. However, if you are administering multiple IAM_TOP
using a single Oracle Identity and Access Management deployment and patching tools install, then you should delete the values of IAM_TOP
and LCM_CONFIG
variables from the files and set the correct values.
You also have the option of setting the environment variables through the command-line interface, using the commands listed. However, ensure that you delete any existing values from the files before setting them in the environment.
For example, if you are using a POSIX-compliant
shell, use the following command:
export JAVA_HOME=jdk_absolute_path
Before running the Patcher, generate a patch plan on the hosts that you want to patch. The patch plan creates a list of comprehensive steps to patch a deployment.
Using various commands and options, you can use the iampatchmgr
utility to generate a patch plan, rollback a patch session, abort or end a patch session, or monitor the progress of a session. See Section 2.3.
Note:
Run the Patch Manager against an IAM_TOP
environment.
A new patch session cannot be created until the existing session is completed or aborted.
This section describes how to create a patch plan.
It contains the following topics:
The Lifecycle Tools work with patches organized within a patch top directory. This directory contains patches that have been unzipped and then categorized by product. The Patch Manager scans the patch top directory to find patches, validates their contents, and prepares them for execution as part of the patch session.
To apply patches downloaded from My Oracle Support, you need to organize them into a patch top so that the Patch Manager can find, validate, and execute them. To do this, perform the following steps before invoking the Manager:
Create the root directory for the patch top. Any random name can be used. Oracle recommends that you provide a name that denotes the contents that this patch top will hold. For example, 1404-idm-r2ps2-bp
Create a set of subdirectories, one for each product for which you have patches. You need not create directories for all the products supported.
Note:
Open the patchtop-contents.properties
file (see Section 4.1.2), and verify that the directories created match one of the relative paths declared for each product, whether those were set by default, or if you have added or changed the paths for the deployment.
Unzip all patches, and copy the unzipped directory and its contents for each patch to the correct patch top directory for that product. For example, if the downloaded patch is for OAM and is named 12345.zip
, the unzipped 12345
directory should be copied to the location PATCH_TOP
/iamsuite/patch/oam/12345
. The zipped copies must not be placed in the patch top.
A patch plan contains instructions for applying patches to an Oracle Identity and Access Management environment. See Section 2.3.2.
The plan that is generated by running the Patch Manager can be executed by running the Oracle Identity and Access Management Patcher.
To create a patch plan, run the Oracle Identity and Access Management Patch Manager utility (iampatchmgr
) with the apply
command:
Note:
Run the Oracle Identity and Access Management Patch Manager on the primordial host.
For UNIX
IAM_LCM_TOP/patch/bin/iampatchmgr.sh apply -patchtop patch_top_location
For Windows
IAM_LCM_TOP\patch\bin\iampatchmgr.bat apply -patchtop patch_top_location
The apply
command performs the following tasks:
It validates the given patch top location and the existence of the patch session with ACTIVE
or FAILED
status. If one exists, instead of beginning a new session, the output of the current session is displayed.
If no patch session exists, the patch top is scanned for patches as directed by the patchtop-contents.properties
. The resulting set of patches is copied into the LCM_CONFIG
directory for use by the patch session.
Using the information in the staged patches and the topology store, a plan containing instructions for applying that set of patches to the deployment is generated.
A human-readable version of the plan is created in HTML and plain text formats, and saved to the following location:
LCM_CONFIG/patch/status/session_ID/manager/log/PatchInstructions.html LCM_CONFIG/patch/status/session_ID/manager/log/PatchInstructions.text
The patch plan begins with an overview of the Oracle Identity and Access Management deployment. See Section A.1.
The plan also provides information such as steps to be executed, total number of steps, steps that require downtime, and so on. See Section A.2, Section A.3, and Section A.4.
The Patch Manager writes log messages to the following locations:
While outside of a patch session
LCM_CONFIG/patch/status/log/iampatchmgr.log
While within a patch session
LCM_CONFIG/patch/status/session_ID/manager/log/iampatchmgr-session.log
Run the iampatchmgr
utility using the following syntax:
For UNIX
IAM_LCM_TOP/patch/bin/iampatchmgr.sh command [-option]
For Example:
iampatchmgr.sh abort IAM_LCM_TOP/patch/bin/iampatchmgr.sh progress -all
For Windows
IAM_LCM_TOP\patch\bin\iampatchmgr.bat command [-options]
For Example:
IAM_LCM_TOP\patch\bin\iampatchmgr.sh abort IAM_LCM_TOP\patch\bin\iampatchmgr.sh progress -all
See Table 4-4 for a description of the commands that you can use with the iampatchmgr
utility.
Table 4-4 Oracle Identity and Access Management Patch Manager Commands
Command | Description |
---|---|
|
Starts a patch session where selected patches will be deployed. You must provide the location of the patch top with this command. For example: For UNIX IAM_LCM_TOP/patch/bin/iampatchmgr.sh apply -patchtop patchtop_location For Windows IAM_LCM_TOP\patch\bin\iampatchmgr.sh apply -patchtop patchtop_location For more information, see Section 4.2.2. |
|
Starts a patch session where selected patches will be removed. You must provide the location of the patch top with this command. For example: For UNIX IAM_LCM_TOP/patch/bin/iampatchmgr.sh rollback -patchtop patchtop_location For Windows IAM_LCM_TOP\patch\bin\iampatchmgr.sh rollback -patchtop patchtop_location For more information, see Section 4.6.5. |
|
Stops executing a patch session without completing all planned steps. Changes the status of the patch session to For more information, see Section 4.6.3. |
|
Ends and removes the entire patch session entirely. See Section 4.6.4. |
|
Displays the status for an ongoing patch session. For more information, see Section 4.6.1. |
Note:
To view additional information about any iampatchmgr
command, use the following syntax:
For UNIX
IAM_LCM_TOP/patch/bin/iampatchmgr.sh command -help
For Windows
IAM_LCM_TOP\patch\bin\iampatchmgr.bat command -help
Table 4-5 describes the status that you see when you run the progress
command during a patch session.
Table 4-5 Status of Patch Session
Status | Description |
---|---|
|
Session in progress. |
|
Session halted due to failure in execution of a step. |
|
Session halted as a result of step aborted by the administrator. |
|
Session complete. |
|
Failure in step execution or otherwise. |
Note:
The status COMPLETE
and INCOMPLETE
are the terminal states; whereas, FAILED
and ABORTING
are recoverable states.
The Oracle Identity and Access Management Patcher is a utility that completes the steps for applying patches. It applies product patches to the hosts in a patch session, as listed in the patch plan.
Run the Patcher by executing the following command in the command-line utility:
Note:
In ongoing patching, the administrator runs the Patcher to apply patches to an existing deployment. These may be one-off patches related to certain bugs, or security issues, or staged patches for Oracle Identity and Access Management products.
For UNIX
IAM_LCM_TOP/patch/bin/iampatch.sh run
For Windows
IAM_LCM_TOP\patch\bin\iampatch.bat run
The Oracle Identity and Access Management Patcher run
command performs the following tasks:
The command validates the existence of a patch session and the availability of one or more steps with the status PLANNED
, for the host where the tool is running. If such steps exist, then the Patcher proceeds to execute each step as follows:
The session status is updated to show that this step is in the status RUNNING
.
The Patcher determines the command for the step, and invokes it.
If invocation is successful, the status for that step changes to COMPLETE
and the session is updated.
Step execution continues until the next step is to be executed on a different host, or execution of a step fails, or until there are no more steps in the plan.
The next time you run the Patch Manager progress
command, its output reflects the outcome of the steps executed.
You can also use the prereq
option with this syntax to execute only steps related to prerequisite validation. This does not stop or start services, or apply or rollback patches.
The Patcher writes log messages to the following locations:
While outside of a patch session
LCM_CONFIG/patch/status/log/iampatch.log
While within a patch session
LCM_CONFIG/patch/status/session_ID/manager/log/iampatch-session.log
The Oracle Identity and Access Management Lifecycle Tools support the application of post-patch artifact changes, such as adding an entry within a configuration file, invoking a product's MBean, and so on. Most patches do not require such changes. To determine if a particular patch requires changes, see the corresponding README.txt
file for that patch.
For patches that require changes, the Patcher automatically executes the changes after you run all the binary patch applications for a single product.
Prerequisites for Applying Artifact Changes
The post-patch artifact changes require additional Perl libraries to perform certain tasks such as connecting to the database and executing sql
queries.
Note:
Ensure that Perl 5 version 5.8.8 or later is present on the system PATH
.
Ensure that the DB.pm
module is present within a directory on the list Perl searches when loading modules, obtainable using the array @INC
.
For example, the contents of @INC
for a given host can be obtained using the following command:
perl -le 'print foreach @INC'
The output of the artifact installation is saved to the following log file:
LCM_CONFIG/patch/status/session_ID/hosts/host_name/log/patch_id-artifactlog
The Oracle Identity and Access Management Lifecycle Tools additionally support the following scenarios for applying patches:
Any product patches present within the deployment repository are automatically applied by the Oracle Identity and Access Management Deployment Tool, as the corresponding product is installed and configured.
Note:
The deployment repository must not be used for ongoing patching. A separate patchtop directory containing the downloaded patches that need to be applied must be assembled.
The Oracle Identity and Access Management deployment tool invokes the Patcher for installing the post-installation patches, using additional options. These are applicable only to patching during the deployment process. For example, patches are applied before any server instance is configured so that the Deployment Tool can bypass the steps to start or stop servers.
In this release, such options are not supported for ongoing patching.
You can deploy the Web and Directory tier hosts in network segments different from the network segments containing the primordial host. For example, commonly, the Web tier is deployed to a network DMZ. In this deployment configuration, the shared LCM_CONFIG
directory that contains information about a patch session might not be available from such hosts. In this case, complete the following steps to run the Oracle Identity and Access Management Patcher on such disconnected hosts:
Generate a patch plan using the Oracle Identity and Access Management Patch Manager apply
command.
Run the Patcher on non-disconnected hosts using the run
command.
When the next host on which the plan needs to be executed is disconnected, perform the following steps:
On the primordial host
Run the Patch Manager createhostbundle
command to generate a host bundle containing the latest session information required for executing the Patcher on that specific disconnected host:
./iampatchmgr.sh createhostbundle
On running the progress command, a host bundle is generated in the location LCM_CONFIG
/patch/status/
session_id
/hosts/
disconnected_host_name
/hostbundle-
disconnected_host_name
.
zip
.
The hostbundle-
disconnected_host_name
.
zip
file contains information about executing the Patcher on the disconnected host.
Copy the bundle hostbundle-
disconnected_host_name
.
zip
to the disconnected host.
On the disconnected host
Read the host bundle using the Patcher readhostbundle
command:
./iampatch.sh readhostbundle -file path_to_the_host_bundle
Run the Patcher using run
command.
After running the Patcher, use the Patcher createhoststatus
command to generate a host status file that contains the status information resulting from Patcher execution:
./iampatch.sh createhoststatus
The host status is generated in the location LCM_CONFIG
/patch/status/
session_id
/hosts/
disconnected_host_name
/hoststatus
-disconnected_host_name
.zip
.
Copy the generated status from the disconnected host to the primordial host.
On the primordial host
Read the status using the Patch Manager readhoststatus
command:
./iampatchmgr.sh readhoststatus -file path_to_the_host_status
Proceed to execute the Patcher on non-disconnected hosts using the run
command. If the Patcher prompts you that the next host from which to execute the Patcher is disconnected, repeat the steps listed in this section.
This section describes how to monitor patch sessions and troubleshoot issues that you might encounter while patching Oracle Identity and Access Management using the Patcher.
It contains the following topics:
Use the progress
command to track the state of a patch session. The command displays a configurable report about the patch session.
You can use the option -all
with the progress
command to view the complete list of hosts and their status in the patch session.
Run the following command:
On UNIX
IAM_LCM_TOP/patch/bin/iampatchmgr.sh progress -all
On Windows
IAM_LCM_TOP\patch\bin\iampatchmgr.bat progress -all
Section A.5 shows a sample report that is displayed when you run the progress
command.
The progress
command displays the status of the patch session. Table 4-6 describes the status of the patch steps, and Table 4-7 describes the status of the patch session that you will see when you run the progress
command.
Options that you can use
Use the verbose option with the progress
command to get a detailed list of each individual step within the current phase of the patch session. Each step contains the step number so that it can be correlated with the detailed information on each step within the Patch Plan.
Use the all
option with the progress
command to get a detailed list of every step within the patch session.
Table 4-6 Status of a Patch Step When the progress Command is Executed
Status | Description |
---|---|
|
Step has not been executed by the Oracle Identity and Access Management Patcher. |
|
Step is in the process of being executed by the Patcher. |
|
Step execution successful. |
|
Step execution failed. See "Restarting a Failed Step". |
Table 4-7 Status of a Patch Session When the progress Command is Executed.
Status | Description |
---|---|
|
Patching in progress. |
|
Patching halted due to failure of patch step. |
|
Patching halted due to abortion of patch step. |
|
Terminal state showing that all steps were executed. |
|
Terminal state due to an aborted session either in response to a step execution failure or otherwise. |
If the patch session shows the status FAILED
due to a failed execution step, you can attempt to resume session execution from that failed step by using the retry
command as shown below.
On UNIX
IAM_LCM_TOP/patch/bin/iampatch.sh retry
On Windows
IAM_LCM_TOP\patch/bin\iampatch.bat retry
The retry
command performs the following functions:
Validates the existence of the patch session with the status FAILED
or RUNNING
, identifies the step with the status FAILED
.
It also ensures that the failed step needs to be executed from the current host.
The status of the session is updated to show that this step is in RUNNING
status. The overall session status is changed from FAILED
to ACTIVE
.
The step that are retried and successful are executed as documented in "Applying Patches".
Use the prereq
option with the retry
command to run only the prerequisites. This does not stop or start services, or apply and rollback patches.
Run the following command with the prereq
option:
On UNIX
IAM_LCM_TOP/patch/bin/iampatch.sh retry -prereq
On Windows
IAM_LCM_TOP\patch\bin\iampatch.bat retry -prereq
The abort
command changes the status of the patch session to INCOMPLETE
, preventing the Patcher from further execution.
If the progress
command is executed after a session is aborted, details of the session and steps continue to be displayed. If the session that is aborted was in FAILED
status, and if it is required to restore some or all products to the status that existed before patching was attempted, the details of the session and steps can be used to assemble the correct patch top directory to be provided to the Patch Manager rollback
command.
To abort a patch session, run the following commands:
On UNIX
IAM_LCM_TOP/patch/bin/iampatchmgr.sh abort
On Windows
IAM_LCM_TOP\patch\bin\iampatchmgr.bat abort
You can end a patch session by running the end
command. This command removes the patch session entirely.
If the progress
command is executed after a session is ended, no report is produced as no session exists. All log files produced during the session are retained, and can be examined to obtain information about the session, if required. To end the session without concern to the current status of session execution, the administrator can use the end
command.
To end a patch session, run the following commands:
On UNIX
IAM_LCM_TOP/patch/bin/iampatchmgr.sh end
On Windows
IAM_LCM_TOP\patch\bin\iampatchmgr.bat end
You can create a session to roll back patches that you have applied to the tiers. To roll back patches in the current tier or for tiers to which you have already applied a patch, initiate a new rollback session.
To roll back patches, do the following:
Create a patch plan by running the rollback
command:
On UNIX
IAM_LCM_TOP/patch/bin/iampatchmgr.sh rollback -patchtop patchtop_location
On Windows
IAM_LCM_TOP\patch\bin\iampatchmgr.bat rollback -patchtop patchtop_location
Run the Patcher as described in Section 4.3.
The rollback
command performs the following tasks:
It validates the given patch top location and the existence of the patch session with ACTIVE
or FAILED
status. If a session exists, instead of beginning a new session, the output of the current session is displayed.
If a patch session does not exist, the patch scanner is internally invoked to validate and generate patches from the patch top location provided. This staged patch is internally used to generate the patch plan.
A patch plan is generated with instructions for rolling back patches, using the topology store information and staged patches.
The rollback
command generates an HTML and text format of the patch plan in the following location:
LCM_CONFIG/patch/status/session_ID/manager/log/PatchInstructions.html LCM_CONFIG/patch/status/session_ID/manager/log/PatchInstructions.text
After generating the patch plan, the Patch Manager starts a new patch session with the status ACTIVE
. It then adds the status PLANNED
to the step that is being executed on each host, as a subordinate to the patch session. The Patch Manager saves details of the patch session to the log files.
The rollback
command generates log files for reference.