2 Patching Your Environment Using OPatchAuto

OPatchAuto, which is automatically installed with the OPatch utility as a part of your installation, provides several commands that you can use to automate the application and roll back of a patch for a single host or multi-host environment.

For more information about patching with OPatchAuto, see the following topics:

  • About Zero Downtime Patching with OPatchAuto
    If you are patching a multi-host topology, one of the first steps after downloading a patch is to identify whether the patch is suitable for Zero Downtime (ZDT) patching. If it is, you can use one of two methods to apply the patch with OPatchAuto.
  • Preparing to Use OPatchAuto
    To ensure successful patching, there are several prerequisites you should complete to prepare your environment for running OPatchAuto, such as obtaining the latest version of OPatch, obtaining required patches from My Oracle Support, and backing up the environment.
  • Using OPatchAuto to Patch Oracle Fusion Middleware
    You can use OPatchAuto to automate the necessary steps for applying or rolling back a patch on a single host or multi-host environment.
  • An Example of Creating A Topology File Using FMW Composer
    For multi-host patching, a prerequisite is to define the elements of your topology in a topology file. You’ll need to use FMW Composer to create this file and provide information about your environment to OPatchAuto. This allows OPatchAuto to automatically perform the patching steps without manual intervention.

2.1 About Zero Downtime Patching with OPatchAuto

If you are patching a multi-host topology, one of the first steps after downloading a patch is to identify whether the patch is suitable for Zero Downtime (ZDT) patching. If it is, you can use one of two methods to apply the patch with OPatchAuto.

  • What is a Zero Downtime Patch?
    Zero Downtime (ZDT) patching provides a process and mechanism for rolling out a patch across a domain while allowing applications to continue to service requests.
  • Identifying a Zero Downtime Patch
    You can identify a Zero Downtime (ZDT) patch by the value of the patch uptime option in the patch metadata.
  • About the Available Patch Plans
    After you identify whether a patch is suitable for ZDT patching, you need to identify and select a patch plan. As a result, it is important you review and understand the characteristics and limitations of the patch plans available for applying a patch.

2.1.1 What is a Zero Downtime Patch?

Zero Downtime (ZDT) patching provides a process and mechanism for rolling out a patch across a domain while allowing applications to continue to service requests.

You can apply a ZDT patch using OPatchAuto, which rolls out the change to one node at a time and allows a load balancer (typically, Oracle Traffic Director (OTD)) to redirect incoming traffic to the remaining nodes until the change is complete.

The recommended way to identify whether a patch is suitable for ZDT patching is to determine the value of the patch uptime option in the metadata of the patch. To identify a ZDT patch, see Identifying a Zero Downtime Patch.

2.1.2 Identifying a Zero Downtime Patch

You can identify a Zero Downtime (ZDT) patch by the value of the patch uptime option in the patch metadata.

After you download a patch, open up patchdeploy.xml in the PATCH_HOME/etc/config directory, where PATCH_HOME is the location of the patch directory that contains the patch.

If the value of patch-uptime-option is FMW_ROLLING_ORACLE_HOME, as shown in the following example:

<patch-uptime-option>FMW_ROLLING_ORACLE_HOME<patch-uptime-option>

OR the value is FMW_ROLLING_SESSION:

<patch-uptime-option>FMW_ROLLING_SESSION<patch-uptime-option>

Then, the patch is suitable for ZDT patching.

If FMW_ROLLING_ORACLE_HOME or FMW_ROLLING_SESSION does not appear in the patch metadata, then you know that the patch is not suitable for ZDT patching, and as a result, not compatible with a ZDT patch plan. The value of the patch uptime option will help you select the appropriate patch plan for applying the patch. For information on selecting a patch plan, see About the Available Patch Plans.

2.1.3 About the Available Patch Plans

After you identify whether a patch is suitable for ZDT patching, you need to identify and select a patch plan. As a result, it is important you review and understand the characteristics and limitations of the patch plans available for applying a patch.

A patch plan describes the sequence of steps to execute in order to deploy a patch. To execute a plan, you specify the plan name on the command line using the -plan option. For more information, see Patch Plans in Oracle OPatch User’s Guide for Windows and UNIX.

To discover the plans available in an Oracle home, use the opatchauto lsplans command. The following example shows sample output of this command, which lists and describes the available plans:

cd ORACLE_HOME/OPatch
./opatchauto lsplans

Oracle OPatchAuto Version 13.9.1.0.0
Copyright (c) 2016, Oracle Corporation.  All rights reserved.

  OPatchAuto available patch plan information:

    Product Name: OPatchAuto Core
      Patch Plan Name: rolling (Default)
        Description: Process patch targets on a per-home basis and tries to minimize downtime.
      Patch Plan Name: parallel
        Description: Process patch targets in parallel and does not attempt to minimize downtime.

    Product Name: Oracle Fusion Middleware
      Patch Plan Name: wls-zdt-rollout
        Description: Performs full WLS ZDT rollout.
      Patch Plan Name: wls-push-image
        Description: Performs only image push portion of WLS ZDT rollout.

After identifying whether the patch is a ZDT patch (see Identifying a Zero Downtime Patch), consider the following information when choosing a plan:

  • If a patch is not a ZDT patch, you should use the parallel patch plan to apply the patch, as shown in Applying a non-ZDT Patch on Multiple Hosts Using the Apply Command.

  • If a patch is a ZDT patch, there are two available plans, rolling and wls-zdt-rollout.

    • Use the rolling option if the patch is a FMW_ROLLING_ORACLE_HOME patch. This option uses a pure OPatchAuto approach, where OPatchAuto is used to perform all patching operations. This is the recommended method for Fusion Middleware.

      With this approach, you can perform both image based and non-image based patching. You can also use this approach to perform what is known as configuration patching (or patching operations performed on a domain). However, this method has no session management features, such as migrating a session to another server when a server is shutdown.

      For information on how to apply a ZDT patch with the rolling plan, see Applying a ZDT Patch on Multiple Hosts Using the Apply Command.

    • Use the wls-zdt-rollout option if the patch is a FMW_ROLLING_SESSION patch. You also use OPatchAuto for this option, but certain lifecycle operations are delegated to WebLogic Server components, such as WLST or the WebLogic Server Administration Console. This is recommended for WebLogic Server only.

      This approach only supports image based patching and doesn’t support configuration patching. But, it does provide support for migrating a session when an instance is shutdown.

      This document does not cover the steps to apply a ZDT patch using this option. See Introduction to Zero Downtime Patching in Oracle Fusion Middleware Administering Zero Downtime Patching Workflows to learn more about this option.

2.2 Preparing to Use OPatchAuto

To ensure successful patching, there are several prerequisites you should complete to prepare your environment for running OPatchAuto, such as obtaining the latest version of OPatch, obtaining required patches from My Oracle Support, and backing up the environment.

For more information on preparing your environment, see the following topics:

2.2.1 Locating and Obtaining the Latest Version of OPatch and OPatchAuto

Before you run OPatchAuto, find the OPatchAuto utility in the Oracle home and verify that you have the latest version. If you have the latest version of OPatchAuto, you have the latest version of OPatch.

For more information, see the following topics:

2.2.1.1 Locating and Running OPatchAuto in the Oracle Fusion Middleware Oracle Home

You can find and run the OPatchAuto utility in the ORACLE_HOME/OPatch directory after you install any Oracle Fusion Middleware product.

To run OPatchAuto, simply run the opatchauto command in this directory.

For example, to view the list of commands available for OPatchAuto on a Unix system, enter the following:

./opatchauto -help

2.2.1.2 Identifying the Version of OPatchAuto Included with Oracle Fusion Middleware 12c

Oracle Fusion Middleware 12c (12.2.1.2) includes OPatchAuto version 13.9.1.0.0. Use the opatchauto version command to verify that you have this version.

In general, there is a version of OPatch and OPatchAuto available for each version of the Oracle Universal Installer software.

To identify the version of OPatchAuto:

  1. Change directory to the following directory: 
    cd ORACLE_HOME/OPatch/
  2. Run the following command: 
    ./opatchauto version

    For example:

    ./opatchauto version
Oracle OPatchAuto Version 13.9.1.0.0
Copyright (c) 2016, Oracle Corporation.  All rights reserved.

1. OPatchAuto version 13.9.1.0.0

If you have the latest version of OPatchAuto, you have the latest version of OPatch. If you don’t have the latest version, OPatch can be downloaded using patch 6880880. You should always use the latest download designated for your installation.  For Oracle Fusion Middleware 12c (12.2.1.2), select OUI NextGen 13.9.1 for the version and platform, and then click Download to download OUI NextGen OPatch 13.9.1.

2.2.2 Obtaining Patches Required For Your Installation

You can search for and download the latest patches for your installation from My Oracle Support.

You can check for the latest patches available for your Oracle Fusion Middleware product or component by registering and logging in to My Oracle Support at:

http://support.oracle.com

After you log in to My Oracle Support, click the Patches & Updates tab, which provides various tools that allow you to quickly locate the patches most important to your Oracle software installation.

Note:

It is important that you review the README file that is included with each patch. The README file includes important information about the requirements and procedures for applying the patch.

2.2.3 Directory Variables Used in the Examples

The examples in this guide show sample commands for running OPatchAuto. These example commands use variables to reference key directories.

The following directory variables are used in this guide:

  • ORACLE_HOME, which is used to reference the location of the Oracle home directory.

  • PATCH_HOME, which is used to reference the location of the patch directory that contains the patches to be applied to the Oracle home.

  • DOMAIN_HOME, which is used to reference the location of the domain home directory.

2.2.4 Creating a Topology File for Patching Multiple Hosts

To apply a patch on multiple hosts, you must create a topology file that defines the elements of your topology. To do this, you’ll need to open FMW (Fusion Middleware) Composer, which is located in ORACLE_HOME/oracle_common/bin, and then add and define each element of the topology one-by-one.

After you create your topology in Composer, you can save it to a XML or JSON file, which you can then provide to OPatchAuto to apply the patch.

To familiarize yourself with the Composer user interface, see An Example of Creating A Topology File Using FMW Composer. You should review this example to understand the basic steps for creating a topology file.

2.2.5 Creating a Wallet

To successfully run OPatchAuto, you must provide a wallet on the command line that contains the necessary password credentials, such as the SSH credentials for each host.

To create a wallet, you can use one of the following tools:

2.2.5.1 Creating a Wallet Using the patchingWallet Tool

You can use the patchingWallet.sh tool in the ORACLE_HOME/OPatch/auto/core/bin directory to create a wallet file.

When you create a wallet:

  • SSH credentials should be defined for each host using the format “user:hostname:ssh”

  • WebLogic administrator credentials should be defined using the format “adminuser:adminhost:wls”. The wls credential is required if you are using the wls-zdt-rollout option to apply a zero downtime (ZDT) patch.

For multi-host patching, you will need to create a topology file using FMW Composer. This requires the following additional credentials:

  • Node Manager credentials should be defined using the format “adminuser:domain_name/NM”

  • Domain administrator credentials should be defined using the format “adminuser:domain_name/ADMIN”

Note that domain_name/NM and domain_name/ADMIN are the default wallet aliases used by FMW Composer for the Node Manager and Administration Server, respectively. You can use different values. But, when you create a topology file using Composer, you need to make sure the credential values specified in the Credential fields in Composer match the aliases in the wallet.

The following shows an example of how to create a wallet and add the credentials to the wallet:

./patchingWallet.sh -walletDir wallet_location –create "user:adminhost:ssh" "user:host1:ssh" "user:host2:ssh" 
"adminuser:domain_name/ADMIN"  "adminuser:domain_name/NM"

For example:

./patchingWallet.sh -walletDir /tmp/samplewallet –create "oracle:adminhost:ssh" "oracle:host1:ssh" 
"oracle:host2:ssh" "weblogic:zdtDomain/ADMIN" "weblogic:zdtDomain/NM"

The tool will prompt you to enter and confirm the password for each credential:

Enter Password for oracle:adminhost:ssh:
Confirm Password for oracle:adminhost:ssh:
Enter Password for oracle:host1:ssh:
Confirm Password for oracle:host1:ssh:
Enter Password for oracle:host2:ssh:
Confirm Password for oracle:host2:ssh:
Enter Password for weblogic:zdtDomain/ADMIN:
Confirm Password for weblogic:zdtDomain/ADMIN:
Enter Password for weblogic:zdtDomain/NM:
Confirm Password for weblogic:zdtDomain/NM:

2.2.5.2 Creating a Wallet Using FMW Composer

If you are patching a multi-host topology, you could also use FMW Composer in ORACLE_HOME/oracle_common/bin to create a wallet when you create the topology file.

This tool provides a graphical user interface to assign or edit an existing wallet or create one from scratch. Assigning or Creating a Wallet File provides an example of how to assign or create a wallet for a topology.

2.2.6 Configuring Node Manager to Support Start and Stop Operations

To ensure that OPatchAuto can properly stop and start your system during patching, you must configure the Node Manager(s) to support the start and stop operations.

To do this, set the QuitEnabled and CrashRecoveryEnabled properties in the nodemanager.properties file as follows:

QuitEnabled=true
CrashRecoveryEnabled=false

Note that the default value for CrashRecoveryEnabled is false.

By default, this file is created in the Node Manager home directory, where the Node Manager home is typically DOMAIN_HOME/nodemanager.

Note:

For Zero Downtime (ZDT) patching:

  • QuitEnabled=true is only required if you are using the rolling plan to apply a ZDT patch. This is not required if you are using the wls-zdt-rollout plan, which is described in Introduction to Zero Downtime Patching in Oracle Fusion Middleware Administering Zero Downtime Patching Workflows.

  • If you are using the wls-zdt-rollout plan, then you should set CrashRecoveryEnabled to true.

After updating these properties, restart the Node Manager(s).

For more information about the nodemanager.properties file, see Reviewing nodemanager.properties in Oracle Fusion Middleware Administering Node Manager for Oracle WebLogic Server.

2.2.7 Remote Host Patching on Windows

For patching on Windows machines, ensure that Cygwin SSH server is installed and set up. OPatchAuto doesn’t support other SSH servers at this time.

For more information, see Remote Host Execution Using SSH in the Oracle OPatch User’s Guide for Windows and UNIX.

2.2.8 Backup and Recovery Considerations for Patching

It is highly recommended that you back up the Oracle home before any patch operation. You can back up the Oracle home using your preferred method.

You can use any method such as zip, cp -r, tar, and cpio to compress the Oracle home.

If the Oracle home doesn’t appear when you execute the opatch lsinventory -detail command, the Oracle home might be missing from the Central Inventory, or the Central Inventory itself could be missing or corrupted.

If the Oracle home is listed when you execute the opatch lsinventory -detail command, but the products and components within the Oracle home are not listed, the inventory within the Oracle home (local inventory) might be missing or corrupted.

If the local inventory is corrupted or lost for some reason, you must restore the entire Oracle home if it was backed up. If a backup doesn’t exist, you may have to reinstall the software.

2.3 Using OPatchAuto to Patch Oracle Fusion Middleware

You can use OPatchAuto to automate the necessary steps for applying or rolling back a patch on a single host or multi-host environment.

The following topics describe how to use OPatchAuto to patch Oracle Fusion Middleware.

2.3.1 Summary of the Steps For Using OPatchAuto in a Fusion Middleware Environment

Applying a patch with OPatchAuto involves a series of steps that must be performed to ensure successful patching.

The following table summarizes the typical steps required to patch your existing Fusion Middleware environment using OPatchAuto.

Table 2-1 Using OPatchAuto with Oracle Fusion Middleware

Task Description Documentation

Acquire patches required for your installation

Log in, search for, and download the patches required for your specific installation.

You don’t need to worry about whether OPatchAuto supports a particular patch type. If OPatchAuto doesn’t support a particular patch type, you will be notified when you run the tool.

Obtaining Patches Required For Your Installation

Review the README.txt file for the patch.

Each patch archive includes a README file that contains important information and instructions that must be followed prior to applying your patch. It is important to review the README file because it provides any unique steps or other information specific to the patch.

The README.txt file that is packaged within the patch archive

For a multi-host environment, identify whether the patch is a Zero Downtime (ZDT) patch.

Determine the patch uptime option in patchdeploy.xml to identify whether the patch is a ZDT patch, and as a result, identify the patch plan to use to apply the patch.

Identifying a Zero Downtime Patch

About the Available Patch Plans

For a multi-host environment, define your topology (configuration) using FMW Composer.

To apply a patch on multiple hosts, you must create a topology file, which can be a XML or JSON file and should be created using FMW Composer. This file contains information about your configuration.

The topology file provides a way for OPatchAuto to obtain information from your environment so it can automate the application of the patch.

An Example of Creating A Topology File Using FMW Composer

Check for patch prerequisites.

The OPatchAuto apply -analyze command will identify that the prerequisites for the patch have been met.

If you are patching a single host environment, see Verifying the Prerequisites for Applying a Patch on a Single Host.

If you are patching a multi-host environment, see Verifying the Prerequisites for Applying a Patch on Multiple Hosts.

Apply the patch.

After you determine the Oracle home to which you need to apply the patch, and you have read the README file, then you should apply the patch with the opatchauto apply command.

If you are patching a single-host environment, see Applying a Patch on a Single Host Using the Apply Command.

If you are patching a multi-host environment, see one of the following, depending on whether the patch is suitable for ZDT patching:

Verify the patch was applied to the Oracle home successfully.

The OPatch lsinventory command will show what patches have been applied to the Oracle home. The listDomainPatchInventory.sh command will show the patches applied to the domain. Use these commands together to verify the application of the patch.

Using the OPatch lsinventory Command to Verify the Patches Applied to an Oracle Home

Using the listDomainPatchInventory.sh Command to Verify the Patches Applied to a Domain

Verify that your software runs properly after you apply the patch.

After the patching is complete and your servers are restarted, you should check your product software to verify that the issue has been resolved.

Verifying Your Installation After Applying a Patch

Troubleshoot the application of a patch.

If there are problems applying a patch, your first troubleshooting task is to review the log file for the OPatchAuto session.

Troubleshooting a Patch by Viewing the OPatchAuto Log File

Roll back the application of a patch.

If for some reason the result is not satisfactory, you can use the opatchauto rollback command to remove the patch from the Oracle home.

If additional assistance is required, go to My Oracle Support (formerly OracleMetaLink).

For a single host environment, see Rolling Back a Patch You Have Applied on a Single Host.

For a multi-host environment, see Rolling Back a Patch You Have Applied on Multiple Hosts.

2.3.2 Applying a Patch on a Single Host Using OPatchAuto

After you obtain the patches required for your installation, use the opatchauto apply —analyze command to verify prerequisites, and then use opatchauto apply to apply a patch on a single host. If needed, you can use opatchauto rollback to roll back a patch.

Patching a single host environment with OPatchAuto involves the following tasks:

  • Verifying the Prerequisites for Applying a Patch on a Single Host
    To verify that a patch can be applied on a single host, use the —analyze argument to the OPatchAuto apply command. For single host patching, you must also provide the domain location using the —instance argument.
  • Applying a Patch on a Single Host Using the Apply Command
    To apply a patch on a single host, use the opatchauto apply command. This is the same command as opatchauto apply —analyze, except you remove the —analyze argument when you are ready to apply the patch.
  • Rolling Back a Patch You Have Applied on a Single Host
    If you apply a patch and the results are not satisfactory, use the opatchauto rollback command to roll back the application of the patch. This is the same command as opatchauto rollback –analyze, except you remove the -analyze argument when you are ready to roll back the patch.

2.3.2.1 Verifying the Prerequisites for Applying a Patch on a Single Host

To verify that a patch can be applied on a single host, use the —analyze argument to the OPatchAuto apply command. For single host patching, you must also provide the domain location using the —instance argument.

The following command shows how to verify the prerequisites for applying a patch on a single host:

opatchauto apply PATCH_HOME -analyze -instance DOMAIN_HOME -wallet wallet_location -walletPassword password_ifneeded 
-wls-admin-host weblogic_adminserver_host:port

For example:

opatchauto apply /home/oracle/patches/15941858 -analyze -instance /home/oracle/config/domains/exampledomain -wallet /tmp/samplewallet 
-wls-admin-host examplehost.exampledomain.com:7001

If you want to apply multiple patches in one session, use the –phBaseDir option.

This command analyzes and displays the actions that will be taken by the patch, but does not actually apply the patch. As a result, it allows you to verify that the prerequisites for the patch have been met.

If any prerequisite checks fail, refer to the output and log file to fix the issues before continuing. For example, a common failure is the detection of patch conflicts. If any patch conflicts occur, follow the instructions in the log file for how to obtain a merge patch from Oracle Support.

2.3.2.2 Applying a Patch on a Single Host Using the Apply Command

To apply a patch on a single host, use the opatchauto apply command. This is the same command as opatchauto apply —analyze, except you remove the —analyze argument when you are ready to apply the patch.

The following example shows how to use the opatchauto apply command to apply a patch to an Oracle Fusion Middleware environment on a single host.

This example assumes that:

  • The patch you have downloaded has been saved to a directory that is named for the patch number in My Oracle Support. In this case, the patch number is 15941858.

  • The user runs the OPatchAuto command from the ORACLE_HOME/OPatch directory and includes the location of the patch (PATCH_HOME) as an argument to the command.

Note:

When you run the opatchauto apply command, make a note of the session id (for example, EKZR) in the command output. This will simplify the rollback process if you decide to roll back the patch later.

opatchauto apply PATCH_HOME -instance DOMAIN_HOME -wallet wallet_location -walletPassword password_ifneeded -wls-admin-host weblogic_adminserver_host:port

For example:

opatchauto apply /home/oracle/patches/15941858 -instance /home/oracle/config/domains/exampledomain -wallet /tmp/samplewallet 
-walletPassword password -wls-admin-host examplehost.exampledomain.com:7001

2.3.2.3 Rolling Back a Patch You Have Applied on a Single Host

If you apply a patch and the results are not satisfactory, use the opatchauto rollback command to roll back the application of the patch. This is the same command as opatchauto rollback –analyze, except you remove the -analyze argument when you are ready to roll back the patch.

The following example shows how to use the opatchauto rollback command to roll back a patch that was applied to an Oracle Fusion Middleware environment on a single host.

To do a roll back, you follow the same process for when you applied the patch. That is, you first do a test run of the opatchauto rollback command:

Note:

You can simplify the command if you provide the session id (for example, EKZR) that was used to apply the patch. Then, OPatchAuto can derive all the necessary command line parameters.

opatchauto rollback –session session_id -analyze –wallet wallet_location -walletPassword password_ifneeded -wls-admin-host weblogic_adminserver_host:port

For example:

opatchauto rollback –session EKZR -analyze –wallet /tmp/samplewallet -walletPassword password -wls-admin-host examplehost.exampledomain.com:7001

When the test run successfully passes, perform the actual roll back of the patch:

opatchauto rollback –session session_id –wallet wallet_location -walletPassword password_ifneeded -wls-admin-host weblogic_adminserver_host:port

For example:

opatchauto rollback –session EKZR –wallet /tmp/samplewallet -walletPassword password -wls-admin-host examplehost.exampledomain.com:7001

Alternatively, you can roll back the patch by pointing OPatchAuto to a copy of the unzipped patch as follows:

opatchauto rollback unzipped_patch_location -instance DOMAIN_HOME –wallet wallet_location -walletPassword password_ifneeded 
-wls-admin-host weblogic_adminserver_host:port

2.3.3 Applying a Patch on Multiple Hosts Using OPatchAuto

After you obtain the necessary patches, use the opatchauto apply —analyze command to verify prerequisites, and then use opatchauto apply to apply a patch on multiple hosts. If needed, you can use opatchauto rollback to roll back a patch.

Note:

Before applying a patch on multiple hosts, ensure that you have created a topology file using FMW Composer. You must supply this file, which can be either a XML or JSON file, on the command line using the -topology option when you run OPatchAuto. OPatchAuto uses this file to obtain information about the environment that you want to patch. For an example on how to create a topology file, see An Example of Creating A Topology File Using FMW Composer.

Patching a multi-host environment with OPatchAuto involves the following tasks:

2.3.3.1 Verifying the Prerequisites for Applying a Patch on Multiple Hosts

To ensure successful patching, use the opatchauto apply —analyze command to check for any prerequisites before applying a patch.

To verify that a patch can be applied to a specific Oracle home (ORACLE_HOME) and domain location (DOMAIN_HOME) on multiple hosts, use the —analyze argument to the OPatchAuto apply command.

opatchauto apply PATCH_HOME -analyze -plan patch_plan -topology path_to_topology_file -wallet wallet_location -walletPassword password_ifneeded

For example:

opatchauto apply /home/oracle/patches/15941858 -analyze -plan rolling -topology /home/oracle/topologies/topology-1.0.xml -wallet /tmp/samplewallet -walletPassword password

If you want to apply multiple patches in one session, use the –phBaseDir option.

Note that rolling is the default patch plan if no plan is specified on the command line. For information on identifying the available plans, see About the Available Patch Plans.

This command displays the actions that will be taken by the patch, but does not actually apply the patch. As a result, it allows you to verify that the prerequisites for the patch have been met.

If any prerequisite checks fail, refer to the command output and log file to fix any issues before continuing. For example, a common failure is the detection of patch conflicts. If any patch conflicts occur, follow the instructions in the log file for how to obtain a merge patch from Oracle Support.

2.3.3.2 Applying a non-ZDT Patch on Multiple Hosts Using the Apply Command

To apply a non-ZDT patch, use the opatchauto apply command with the parallel patch plan. This is the same command as opatchauto apply -analyze, except you remove the -analyze argument when you are ready to apply the patch.

The following example shows how to use the opatchauto apply command to apply a non-ZDT patch to an Oracle Fusion Middleware environment on multiple hosts.

This example assumes that:

  • The patch you have downloaded has been saved to a directory that is named for the patch number in My Oracle Support. In this case, the patch number is 15941858.

  • The user runs the OPatchAuto command from the ORACLE_HOME/OPatch directory and includes the location of the patch (PATCH_HOME) as an argument to the command.

Note:

When you run the opatchauto apply command, make a note of the session id (for example, EKZR) in the command output. This will simplify the rollback process if you decide to roll back the patch later.

opatchauto apply PATCH_HOME -plan parallel -topology path_to_topology_file -wallet wallet_location -walletPassword password_ifneeded

For example:

opatchauto apply /home/oracle/patches/15941858 -plan parallel -topology /home/oracle/topologies/topology-1.0.xml -wallet /tmp/samplewallet -walletPassword password

2.3.3.3 Applying a ZDT Patch on Multiple Hosts Using the Apply Command

To apply a Zero Downtime (ZDT) patch, use the opatchauto apply command with the rolling patch plan. This is the same command as opatchauto apply -analyze, except you remove the -analyze argument when you are ready to apply the patch.

The following example shows how to use the opatchauto apply command to apply a ZDT patch to an Oracle Fusion Middleware environment on multiple hosts.

This example assumes that:

  • The patch you have downloaded has been saved to a directory that is named for the patch number in My Oracle Support. In this case, the patch number is 15941858.

  • The user runs the OPatchAuto command from the ORACLE_HOME/OPatch directory and includes the location of the patch (PATCH_HOME) as an argument to the command.

Note:

  • When you run the opatchauto apply command, make a note of the session id (for example, EKZR) in the command output. This will simplify the rollback process if you decide to roll back the patch later.

  • rolling is the default patch plan if no plan is specified on the command line.

opatchauto apply PATCH_HOME -plan rolling -topology path_to_topology_file -wallet wallet_location -walletPassword password_ifneeded

For example:

opatchauto apply /home/oracle/patches/15941858 -plan rolling -topology /home/oracle/topologies/topology-1.0.xml -wallet /tmp/samplewallet -walletPassword password

2.3.3.4 Rolling Back a Patch You Have Applied on Multiple Hosts

If you apply a patch and the results are not satisfactory, use the opatchauto rollback command to roll back the application of a patch. This is the same command as opatchauto rollback –analyze, except you remove the -analyze argument when you are ready to roll back the patch.

The following example shows how to use the opatchauto rollback command to roll back a patch that was applied to an Oracle Fusion Middleware environment on multiple hosts.

To do a roll back, you follow the same process for when you applied the patch. That is, you first do a test run of the opatchauto rollback command:

Note:

You can simplify the command if you provide the session id (for example, EKZR) that was used to apply the patch. Then, OPatchAuto can derive all the necessary command line parameters.

opatchauto rollback –session session_id -analyze -walletPassword password_ifneeded

For example:

opatchauto rollback –session EKZR -analyze -walletPassword password

When the test run successfully passes, perform the actual roll back of the patch:

opatchauto rollback –session session_id -walletPassword password_ifneeded

For example:

opatchauto rollback –session EKZR -walletPassword password

Alternatively, you can roll back the patch by pointing OPatchAuto to a copy of the unzipped patch as follows:

opatchauto rollback unzipped_patch_location -topology path_to_topology_file –wallet wallet_location -walletPassword password_ifneeded

Or, you can specify the patch id using the -id option without specifying the location of the patch directory, as shown in the following example:

opatchauto rollback -id 12345 -wallet /tmp/samplewallet -topology /home/oracle/topologies/topology-1.0.json

2.3.4 Troubleshooting a Patch by Viewing the OPatchAuto Log File

To understand how a patch is applied and to troubleshoot any problems with the application of a patch, you should review the log file for the OPatchAuto session.

The log file location is usually saved to the following directory or a subdirectory within this location:

ORACLE_HOME/cfgtoollogs/opatchauto/

The file name for each log file identifies the date and time it was executed. For example:

opatchauto2015-09-28_11-47-13AM.log

You can also locate the log file by viewing the output of the opatchauto command. The log file name and location is included in the output of the command. For example:

Session log file is /home/Oracle/products/fmw12c/cfgtoollogs/opatchauto/opatchauto2015-09-28_11-47-13AM.log

2.3.5 Using the OPatch lsinventory Command to Verify the Patches Applied to an Oracle Home

To verify what patches have been applied to an Oracle home, or to find out additional information about the Oracle home, use the opatch lsinventory command.

The following example shows sample output of the lsinventory command, which indicates that a specific interim patch has been applied.

Example 2-1 Running the opatch lsinventory Command to Obtain the Oracle Home Information

> opatch lsinventory
Oracle Interim Patch Installer version 13.9.1.0.0
Copyright (c) 2016, Oracle Corporation.  All rights reserved.

Oracle Home       : /opt/Oracle/products/fmw12c
Central Inventory : /opt/Oracle/oraInventory
   from           : /var/opt/Oracle/oraInst.loc
OPatch version    : 13.9.1.0.0
OUI version       : 13.9.1.0.0
Log file location : /opt/Oracle/products/fmw12c/cfgtoollogs/opatch/opatch2013-06-10_12-32-37PM_1.log

OPatch detects the Middleware Home as "/opt/Oracle/products/fmw12c"

Lsinventory Output file location :
/opt/Oracle/products/fmw12c/cfgtoollogs/opatch/lsinv/lsinventory2013-06-10_12-32-37PM.txt

--------------------------------------------------------------------------------
Local Machine Information::
Hostname:
ARU platform id: 226
ARU platform description:: Linux x86-64

Interim patches (1) :

Patch  15941858     : applied on Mon Jun 10 12:39:07 PDT 2013
Unique Patch ID:  150220
Patch description:  "TEST PATCH FOR WLS 12.2.1.2.0 - JAVA CLASSES PATCH"
   Created on 17 May 2013, 11:54:20 hrs PST8PDT
   Bugs fixed:
     783169, 15941850

--------------------------------------------------------------------------------

OPatch succeeded.

2.3.6 Using the listDomainPatchInventory.sh Command to Verify the Patches Applied to a Domain

To verify what patches have been applied to a domain, use the listDomainPatchInventory.sh command. Use this command with the OPatch lsinventory command to verify that the patch has been applied successfully.

For example:

cd ORACLE_HOME/OPatch/bin
./listDomainPatchInventory.sh DOMAIN_HOME

This command indicates that a specific interim patch has been applied.

You should see the same list of patches in both the domain inventory and in the inventory for each Oracle home. If not, re-apply the patch. When you re-apply the patch, only the missing steps will be executed. The tasks that have already been performed will be skipped.

2.3.7 Verifying Your Installation After Applying a Patch

After you apply one or more patches successfully, use the WebLogic Administration Console, Fusion Middleware Control, and your organization’s application testing to verify that your system is currently running successfully.

To verify your installations in an Oracle Fusion Middleware 12c environment:

  1. Ensure that all the servers in all the domains associated with the Oracle home you just patched are up and running.

    Note:

    If the servers were up and running before patching, it is not necessary to manually restart the servers. OPatchAuto restarts the servers for you once patching is complete.

  2. Open the WebLogic Server Administration Console for each domain to verify the Administration Server and to view the status of the components in the domain.

    • Also, in any Oracle Fusion Middleware domain (where the Oracle Fusion Middleware Infrastructure is installed), open the Oracle Enterprise Manager Fusion Middleware Control console to view the status of the components in the domain.

    From either console, you can verify that the servers and applications are up and running correctly. For more information, see the following topics in Oracle Fusion Middleware Administering Oracle Fusion Middleware:

If the software does not work as expected, follow the rollback instructions to roll back the application of the patch.

2.4 An Example of Creating A Topology File Using FMW Composer

For multi-host patching, a prerequisite is to define the elements of your topology in a topology file. You’ll need to use FMW Composer to create this file and provide information about your environment to OPatchAuto. This allows OPatchAuto to automatically perform the patching steps without manual intervention.

This guide uses an example to show you the typical steps to create a topology file for a multi-host topology. Specifically, this example provides step-by-step instructions to create a topology file for the sample topology shown in the following diagram. This topology represents a standard WebLogic Server domain that contains an Administration Server and a cluster containing two Managed Servers.


Description of GUID-9FD77E93-4BEC-41D4-AA0F-A11A40F67223-print.eps follows
Description of the illustration GUID-9FD77E93-4BEC-41D4-AA0F-A11A40F67223-print.eps

The following steps show how to create a topology file for this example topology:

  1. Starting FMW Composer
    Start FMW Composer from the ORACLE_HOME/oracle_common/bin directory.
  2. Creating a New Topology File
    After you start FMW Composer, open a new topology file. This is where you will add and define each element of your topology one-by-one.
  3. Assigning or Creating a Wallet File
    Use the FMW Composer Settings page to assign and edit an existing wallet file or create a new one for your topology.
  4. Adding the Hosts
    Next, add the hosts to the topology and then define the host information in the host panel on the right side of the screen.
  5. Adding the Oracle Home
    After you add the hosts, add the Oracle home to the hosts and provide information about the Oracle home on the right side of the screen.
  6. Adding the Domain
    Add the domain to the topology and provide information about the domain, such as the directory path of the domain home, the Administration Server credentials, and the Administration Server URL.
  7. Adding the Administration Server
    After adding the domain element to the topology, specify information about the domain’s Administration Server.
  8. Adding the Cluster
    Add the cluster to the domain and specify information about the cluster where the Managed Servers are running.
  9. Adding the Managed Servers
    Next, add the Managed Servers to the cluster in the domain.
  10. Adding the Node Managers
    Finally, if you have Node Managers being used in the environment, each Node Manager has to be defined in the topology file.
  11. Saving the Topology File
    After defining the elements of your topology, select File and then Save to save the topology to a topology file, which can be a XML or JSON file.

2.4.1 Starting FMW Composer

Start FMW Composer from the ORACLE_HOME/oracle_common/bin directory.

  1. Set the JAVA_HOME environment variable to the path of a certified JDK.

    For example:

    export JAVA_HOME=/home/Oracle/products/jdk1.8.0_101
  2. Change directory to the ORACLE_HOME/oracle_common/bin directory and start FMW Composer (fmw-composer.sh). 
    cd ORACLE_HOME/oracle_common/bin
./fmw-composer.sh

2.4.2 Creating a New Topology File

After you start FMW Composer, open a new topology file. This is where you will add and define each element of your topology one-by-one.

  1. Select File, New, and then Topology to open a new, blank topology file.
  2. Click anywhere inside the Model tab to display the Topology Properties panel on the right side of the screen.
  3. In the ID field, enter a name for the topology file. For example, sample-topology.
  4. In the Version field, enter 1.0 (default value).

    This property allows you to create different versions of a topology and distinguish them from one another.

  5. Select File and then Save As... to save the file as either a XML or JSON file.

    The file should be saved to a directory named topologies.

    The file name is automatically generated using the id-version.xml or id-version.json format. For example, sample-topology-1.0.xml.

2.4.3 Assigning or Creating a Wallet File

Use the FMW Composer Settings page to assign and edit an existing wallet file or create a new one for your topology.

  1. From the File menu, select Settings... to open the Composer Settings page.
  2. On the Settings page, click change next to Wallet.
  3. In the Change wallet dialog box, select one of the following options:

    • Select Select an existing wallet to assign an existing wallet to the topology.

    • Select Create a new wallet to create a wallet that does not require a password.

    • Select Create a new encrypted wallet to create a password-protected wallet.

    An additional dialog box appears that prompts you to identify the wallet location.
  4. Provide the wallet location and click Open.
  5. If the wallet requires a password, you will be prompted to enter a password for the wallet.
  6. After you create or identify a wallet, click edit to add the required credentials to the wallet.

    The wallet must contain the following credentials:

    • SSH credentials should be defined for each host using the alias format hostname:ssh

    • Administration Server credentials should be defined using the alias format domain_name/ADMIN

    • Node Manager credentials should be defined using the alias format domain_name/NM

  7. After the wallet is created and contains the required credentials, click OK to dismiss the Settings page.

2.4.4 Adding the Hosts

Next, add the hosts to the topology and then define the host information in the host panel on the right side of the screen.

  1. Inside the left pane of the Model tab, right-click and select Add New Host.
    A new host element (host1) appears on the left side of the screen.
  2. Select the host element, and then specify the following information in the fields on the right side of the screen.
    Field Description
    ID

    A unique name for the host. Keep the default value, host1.
    Address

    Enter the primary IP address for the host.
    Credential

    The credentials (username and password) from the wallet file that will be used to connect to the host.

    Click select to select the credential for the host from the wallet file. When you click select, a dialog box will appear with a list of credentials to choose from only if you have provided the path to a wallet on the Composer Settings page (located in the File menu).

    • If the credential already exists in the wallet, select the appropriate credential from the list and click OK

    • If the credential does not exist in the wallet, click New to add the host credential to the wallet.
  3. Repeat this process to add and define a second host (host2).

2.4.5 Adding the Oracle Home

After you add the hosts, add the Oracle home to the hosts and provide information about the Oracle home on the right side of the screen.

  1. Right-click the Host: host1 element and select Assign New Oracle Home to Host ‘host1’.
    An Oracle home element (home1) appears inside host1.
  2. Select the Oracle home: home1 element, and then specify the following information about the Oracle home in the fields on the right side of the screen.
    Field Description

    ID

    A unique name for the Oracle home. Keep the default value, home1.

    Type

    Select shared to indicate that the Oracle home is on shared storage. If your Oracle home is on local storage, select local.

    If there are copies of the Oracle home on multiple hosts, each Oracle home should be defined individually, and the Type attribute should be local for each one. Use shared if the Oracle home is on shared disk that is mounted on more than one host.

    Path

    Enter the full path to the Oracle home that is being patched.
  3. Right-click the Host: host2 element and select Assign Existing Oracle Homes to Host ‘host2’ to add home1 to Host: host2.

2.4.6 Adding the Domain

Add the domain to the topology and provide information about the domain, such as the directory path of the domain home, the Administration Server credentials, and the Administration Server URL.

  1. Inside Host: host1, right-click the Oracle home: home1 element and select Add New Domain To Host ‘host1’ (home1).
    A domain element (domain1) appears inside the Host: host1 element.
  2. Select the Domain: domain1 element, and then specify the following information about the domain in the fields on the right side of the screen.
    Field Description
    ID

    A unique name for the domain. Keep the default value, domain1.
    Name

    Enter the name of the domain. This should match the name provided during domain configuration.
    Type

    Select shared to indicate that the domain is on shared storage. If your domain is on local storage, select local.
    Path

    Enter the full path to the Domain home.
    Admin Credential

    The administrative credentials from the wallet file that will be used to connect to the domain’s Administration Server.

    Click select to select the credential for the Administration Server from the wallet file. When you click select, a dialog box will appear with a list of credentials to choose from only if you have provided the path to a wallet on the Composer Settings page (located in the File menu).

    • If the credential already exists in the wallet, select the appropriate credential from the list and click OK.

    • If the credential does not exist in the wallet, click New to add the Administration Server credential to the wallet.
    Admin Server Url

    Enter the URL that is used to connect to the WebLogic Administration Server. For example, http://adminserver_host:adminserver_port.
  3. Inside Host: host2, right-click the Oracle home: home1 element and select Assign Existing Domains to Host ‘host2’ (home1) to add the domain (domain1) to host2.

2.4.7 Adding the Administration Server

After adding the domain element to the topology, specify information about the domain’s Administration Server.

  1. Inside Host: host1, right-click the Domain: domain1 element and select Add New Server for Domain ‘domain1’ to Host ‘host1’ (home1) to add a server (server1) to host1.
    A new server (server1) appears inside the domain on host1.
  2. Select the Server: server1 element, and then specify the following information about the Administration Server in the fields on the right side of the screen.
    Field Description

    ID

    A unique name for the server in the domain. Keep the default value, server1.

    Is Admin Server

    Select the Is Admin Server check box to identify this server as the Administration Server.

    Name

    Enter a name for the Administration Server. For example, AdminServer.

    Listen Address

    Enter the listen address of the Administration Server.

    Listen Port

    Enter the listen port of the Administration Server. For example, 7001.

2.4.8 Adding the Cluster

Add the cluster to the domain and specify information about the cluster where the Managed Servers are running.

  1. Inside Host: host1, right-click the Domain: domain1 element and select Add New Cluster to Domain ‘domain1’ to add a cluster to the domain.
    A new cluster (cluster1) appears in the domain.
  2. Select the Cluster: cluster1 element, and then specify the following information about the cluster in the fields on the right side of the screen.
    Field Description

    ID

    A unique name for the cluster in the domain. Keep the default value, cluster1.

    Name

    Enter the name of the cluster.

2.4.9 Adding the Managed Servers

Next, add the Managed Servers to the cluster in the domain.

  1. Inside Host: host1, right-click the Cluster: cluster1 element and select Add New Server to Cluster ‘cluster1’ to add a new server (server2) to the cluster on host1.
    A new server (server2) appears in the cluster on host1.
  2. Select the Server: server2 element, and then specify the following information about the Managed Server in the fields on the right side of the screen.
    Field Description

    ID

    A unique name for the server in this domain. Keep the default value, server2.

    Name

    Enter a name for the Managed Server. For example, managed_server_1.

    Listen Address

    Enter the listen address of the Managed Server.

    Listen Port

    Enter the listen port of the Managed Server.
  3. Repeat this process to add a second Managed Server, server3, to the cluster on host2.

2.4.10 Adding the Node Managers

Finally, if you have Node Managers being used in the environment, each Node Manager has to be defined in the topology file.

  1. Inside Host: host1, right-click the Domain: domain1 element and select Assign New Node Manager to Domain ‘domain1’.
    A Node Manager (nm1) appears in the domain on host1.
  2. Select the Node Manager: nm1 element, and then specify the following information about the Node Manager in the fields on the right side of the screen.
    Field Description
    ID

    A unique name for the Node Manager. Keep the default value, nm1.
    Name

    Enter the name of the Node Manager. This should match the name provided during domain configuration.
    Credential

    The credentials from the wallet file that will be used to connect to the Node Manager.

    Click select to select the credential for the Node Manager from the wallet file. When you click select, a dialog box will appear with a list of credentials to choose from only if you have provided the path to a wallet on the Composer Settings page (located in the File menu).

    • If the credential already exists in the wallet, select the appropriate credential from the list and click OK.

    • If the credential does not exist in the wallet, click New to add the credential to the wallet.
    NmAddress

    Under Tuning Parameter Settings, click Add New Item icon to add a value for the Node Manager listen address parameter (NmAddress).

    When you click this icon, a dialog box appears. For Name, select NmAddress from the drop-down menu, and then enter the Node Manager listen address in the Value field.
    NmPort

    Under Tuning Parameter Settings, click Add New Item icon to add a value for the Node Manager listen port parameter (NmPort).

    When you click this icon, a dialog box appears. For Name, select NmPort from the drop-down menu, and then enter the Node Manager listen port in the Value field (for example, 5556).
  3. Repeat this process to add a Node Manager, nm2, to host2.

2.4.11 Saving the Topology File

After defining the elements of your topology, select File and then Save to save the topology to a topology file, which can be a XML or JSON file.

The following image shows what the example topology looks like in Composer when it’s finished:

Description of GUID-48ED4183-B423-47A5-B190-014939A8B686-default.png follows
Description of the illustration GUID-48ED4183-B423-47A5-B190-014939A8B686-default.png