6 Patching Individual Applications, Domains, or Servers

Smart Update enables you to point a domain or server at a set of patches that are not necessarily intended for the entire installation by using a custom patch profile.

This section includes the following topics:

About Patching Domains or Servers

By default, when you download and apply patches, those patches are in effect for the entire target installation. Every domain and server that is configured to run from such an installation runs against the patches applied to it. Sometimes, however, individual servers or domains within a production environment need to run at different patch levels. To accommodate this need, Smart Update enables you to point individual domains, servers, or clusters at specific patches that are not necessarily in effect installation-wide.

For example, if you have (a) multiple products installed in a Middleware home directory, and (b) domains that exclusively use only one of those products, it is recommended that you point those domains at only those patches that have been applied to the specific product used by the domain.

At a high level, the work required to point an individual domain or server at one or more patches that are not intended to be in effect installation-wide can be summarized as a three-step procedure:

  1. Create a custom patch profile.

  2. In the appropriate start script for the corresponding domain or server, insert a pointer to the custom patch profile.

  3. Apply the desired patches to the custom patch profile.

Figure 6-1 provides a detailed version of this procedure.

Figure 6-1 How to Point an Individual Domain, Cluster, or Server at a Custom Patch Profile

Description of Figure 6-1 follows
Description of "Figure 6-1 How to Point an Individual Domain, Cluster, or Server at a Custom Patch Profile "

About Patching Applications, Domains, or Servers

Smart Update enables you to apply Shared Archive patches to specific applications. When you apply a shared archive patch to a default patch profile, it is installed automatically. However, when you apply an application-scoped patch to a custom patch profile, it should be explicitly deployed: see Shared Archive Patches.

How Custom Profiles Can Patch Individual Domains, Servers, and Applications

By default, all patches included in the default patch profile are in effect for all domains and servers in an entire installation. The patches in a custom patch profile, however, can be put into effect for any subset of domains or servers within an installation. As noted in Patches That Replace Resources For All Applications, Domains, and Servers, patches that replace system-wide resources cannot be selectively targeted by a subset of domains or servers. Such selective targeting is possible, however, for patches with classes or library files that are loaded through a start script and thereby supersede existing, same-named resources in the system.

The following sections provide background information about how custom patch profiles can be used to patch individual domains and servers:

How a Domain or Server Can Point to a Patch in a Custom Profile

When you create a domain using the Configuration Wizard, the Configuration Wizard creates the following scripts for the domain:

By default, the values of the PATCH_CLASSPATH, WEBLOGIC_EXTENSION_DIRS, PATCH_LIBPATH, and PATCH_PATH variables provided in the product installation script, commEnv, are used by all the server instances that run on that installation. If, however, you override these values for any of the variables in a domain-level script, the new values are used only by the WebLogic Server instances that are started by those scripts.

Note:

The definition of a given patch variable should reference no more than one patch manifest JAR. If multiple patch manifest JAR files are referenced, unpredictable behavior may occur at run time.

Modifying the definition of a patch path variable in a start script is a convenient way of pointing servers started by that script at the patches included in a custom patch profile. For example, if you want to point a server at the WebLogic system classes in a patch that has been applied to a custom patch profile, you simply add a definition of the PATCH_CLASSPATH variable to that server start script, setting the variable to the path of the patch manifest JAR file in the custom patch profile. Similarly, you can point a server or domain at a native library file in a custom patch profile by adding a reference to the directory in the custom patch profile that contains that native file. To add this reference, you add a definition of the PATCH_PATH or PATCH_LIBPATH variable to the start script for the appropriate server or domain.

Note:

When adding a definition of a patch path variable to a start script, ensure that the definition appears before any statement that invokes another start script. For example, if you add a patch path variable definition to the setDomainEnv script, add it before the statement that invokes the commEnv script. This placement ensures that the definition you add is not overridden by a definition appearing in any of the start scripts that are subsequently invoked.

Smart Update does not enforce or control how you modify start scripts. But if you use the start scripts that are created, by default, with standard tools such as the Configuration Wizard, and maintain them in the default locations determined by those tools, Smart Update can provide a structured and predictable method of locating the start scripts that need to be modified and suggesting the specific changes that must be made to those scripts.

Figure 6-2 shows two patch profiles used in an installation: the default patch profile and a custom patch profile. In this figure:

  • The default patch profile includes patches 1, 2, and 3. By default, all domains and servers running in the sample installation are pointing at it.

  • The custom patch profile includes patch 4. One server in the sample domain is pointing at it.

Figure 6-2 How to Point an Individual Domain, Cluster, or Server at a Custom Patch Profile

Description of Figure 6-2 follows
Description of "Figure 6-2 How to Point an Individual Domain, Cluster, or Server at a Custom Patch Profile "

Example Use of PATCH_CLASSPATH to Point a Server at Patch Classes

The following PATCH_CLASSPATH variable references the patch manifest JAR file weblogic_patch.jar, located in the custom profile ProductionServer1:

set PATCH_CLASSPATH=
%BEA_HOME%\patch_wls1001\profiles\ProductionServer1
\sys_manifest_classpath\weblogic_patch.jar

Note:

Starting from the Oracle Fusion Middleware 11gR1 release, MW_HOME is the new term for BEA_HOME.

When the preceding definition is added to the startWebLogic script for a given domain, server instances that are started in that domain by that script load the class files into the WebLogic server classpaths that are referenced by the weblogic_patch.jar file in the ProductionServer1 custom profile. This classpath loading occurs when the following line in the commEnv script is subsequently executed (PATCH_CLASSPATH is shown in bold):

set WEBLOGIC_CLASSPATH=%PATCH_CLASSPATH%;%JAVA_HOME%\lib\tools.jar;
%WL_HOME%\server\lib\weblogic_sp.jar;%WL_HOME%\server\lib\weblogic.jar;
%WL_HOMEE%\server\lib\webservices.jar

Note:

The weblogic_patch.jar in the ProductionServer1 profile may reference a set of patch JAR files that is entirely different from the set of patch JAR files referenced in the weblogic_patch.jar of the default patch profile.

If you want a server in a domain, or any domain in an installation, to continue to point to patches in the default patch profile, you do not need to change the start script for that server or domain if you use the default scripts for servers and domains provided by the Configuration Wizard. If, however, you want one or more servers or a domain to point at a custom patch profile, ensure that the start script you modify affects only the targeted servers or the domains.

For information about the sequence in which start scripts are executed, and how particular definitions of patch path variables affect servers started by scripts with patch path variable definitions, see Sequence in Which Start Scripts Are Executed.

Pointing to Custom Patch Profiles in OSGi-based Products

In a text editor, open the start script for the server (for example, in a WebLogic Event Server domain, startwlevs.cmd on Windows, startwlevs.sh on UNIX) and add the -DBEAPatchProfile property to this script as follows:

if "%1" == "-dgc" goto rundgc

"%JAVA_HOME%\bin\java" -Dwlevs.home="%USER_INSTALL_DIR%" -Dbea.home="%BEA_HOME%"
-Dcom.bea.core.security.username=wlevs -Dcom.bea.core.security.password=wlevs
–DBEAPatchProfile=custProfile
 -jar "%USER_INSTALL_DIR%\bin\wlevs_2.0.jar" %1 %2 %3 %4 %5 %6 

goto finish
:rundgc 

"%JAVA_HOME%\bin\java" %DGC_ARGS% -Dwlevs.home="%USER_INSTALL_DIR%"
-Dbea.home="%BEA_HOME%" -Dcom.bea.core.security.username=wlevs
-Dcom.bea.core.security.password=wlevs –DBEAPatchProfile=custProfile 
-jar "%USER_INSTALL_DIR%\bin\wlevs_2.0.jar" %2 %3 %4 %5 %6 
:finish

Note:

Starting from the Oracle Fusion Middleware 11gR1 release, MW_HOME is the new term for BEA_HOME.

When the modified start script is executed, only those patches applied to the patch profile specified in the script are referenced by the OSGi launcher.

Best Practices for Using Custom Patch Profiles

This section provides important information about the use of custom patch profiles:

Avoiding Proliferation of Custom Profiles

When you want to point a domain or server at a new set of patches you have downloaded, try to apply the patches to an existing patch profile, if possible. To change the set of patches at which a specific domain or server points, change the content of the custom patch profile that contains the patches. This approach is always preferable to creating a new custom patch profile and modifying start scripts so they point to it. Avoid creating a new profile for each patch that you download. By keeping the number of profiles you create to a minimum, you can more efficiently take advantage of the patch validation and dependency checking capabilities built into Smart Update and the My Oracle Support Repository.

In addition, when you minimize the number of custom profiles you use, you minimize the number of start script modifications that you must maintain. As a result, the likelihood of introducing errors in your scripts is reduced. In addition, the work required to remove patches is simplified: you simply update the appropriate patch profile; the need to update scripts is minimized.

Modifying Domain and Server Start Scripts

A great deal of flexibility is provided in the use of start scripts. The use of specific names and locations for start scripts is not enforced. However, by staying within the default directory structure that the Configuration Wizard creates for a domain, and by retaining the location and structure of the start scripts that are provided, you maximize your ability to rely on Smart Update to locate and generate suggested changes for start scripts that are required when custom profiles are used.

In general, when pointing a domain or server at a custom patch profile, keep in mind the following guidelines:

  • Before modifying a start script, make a backup copy.

  • Modify the start script at the most general level possible. For example, to point a domain at a custom patch profile, modify the setDomainEnv script, rather than each script that starts a server within the domain. When you implement this practice, you minimize the number of start scripts that you need to modify and maintain.

  • Never point a domain or server at more than one patch profile. Patch validation is performed within the boundaries of a single patch profile; it is never performed for multiple profiles simultaneously.

Removing Patches That Affect Installation-Wide Resources

Generally, there are no restrictions on the set of patches that can be added to a custom patch profile or removed from it. Patches that affect installation-wide resources, however, are automatically placed in all existing patch profiles for a target installation.

If you remove a patch that affects installation-wide resources from any single patch profile (regardless of whether that profile is the default profile or a custom profile), the patch is automatically removed from all patch profiles. If you have multiple profiles in a target installation, and you try to replace or remove a patch that affects installation-wide resources, Smart Update displays a warning.

Creating a Custom Patch Profile

To create a custom patch profile, complete the following steps:

  1. In the Target Installation panel, select a product installation.

  2. Choose Patches > Patch Profiles > New.

  3. In the New Patch Profile dialog box, choose the following:

    1. A name for the custom patch profile

    2. The initial contents of the profile

      Note:

      When you create a custom patch profile, Smart Update creates a directory for it, using the name you have chosen for the profile. Therefore, to ensure that custom patch profiles can be used with any combination of hardware and operating system supported by products software, only alphanumeric characters may be used in custom patch profile names.

  4. Click Create.

The following topics provide more information about custom profiles:

Related Topics

Initial Contents of a Custom Patch Profile

Custom patch profiles may contain the following types of patches:

  • Classes that can be loaded in the WebLogic system classpath

  • Classes that can be loaded in the extended classpath, for applications deployed on WebLogic Server

  • Native library files that can be added to the library path

By default, any installation-wide patches that have been applied to the target installation are automatically included whenever you create a new patch profile. Smart Update gives you the option, however, of creating a patch profile that initially contains no patches.

When you clone the contents of an existing patch profile to create a custom patch profile, only a subset of the patches from the existing patch profile are physically duplicated on disk:

  • Patch JAR files are not duplicated. A single patch JAR file is shared by all the patch profiles on your system that reference them.

    Replacement patches are not duplicated. When a patch replaces a system resource at the time it is first applied, the system resource is not replaced each time the patch is automatically duplicated in a custom patch profile, nor is a duplicate copy made of the patch container that is referenced by a duplicate entry for the patch in the custom patch profile.

  • Native library files from patches that are loaded into the system path at server start time are duplicated in the installation-level patch directory. If disk space is a concern, verify that the amount of space occupied by native library files that are duplicated by a custom patch profile is not causing a problem.

    Note:

    Patches that contain replacements for files or other artifacts are automatically applied to the entire installation.

Cloning a Patch Profile

If you want to create a custom patch profile that includes the same patches in an existing patch profile, you can clone the existing profile and then customize it as needed, by adding or removing patches. This technique is convenient for creating custom patch profiles quickly.

Note:

Patches that affect installation-wide resources are included in all patch profiles created in a target installation. You cannot remove this type of patch from one profile without removing it from all patch profiles on the target installation. If you attempt to do so, Smart Update displays a warning message.

Adding Patches to a Custom Patch Profile

After you create a custom patch profile, you can add or remove patches to it, just as you added or removed patches from the default patch profile:

  1. From the Manage Patches tab, select the custom patch profile you have created.

  2. To add a patch to the profile, select the patch you want to add from the Downloaded Patches panel, and click Apply.

  3. To remove a patch from the profile, select that patch from the list displayed for the patch profile, and click Remove.

When you apply a patch to the target installation, the following events occur:

  1. The patch is validated against patches in the current patch profile.

  2. If there are no patch conflicts, the patch is applied.

    Note:

    Though the patch may be validated and applied to the target installation, any patch containing either classes to be loaded into a classpath or native library files to be loaded into a library path does not take effect until you complete the following procedure:

    1. Modify the appropriate domain or server start scripts, if necessary, to point to the patch.

    2. Restart the appropriate domains, servers, or applications. Shared archive patches should be explicitly referenced by the application, as described in Shared Archive Patches.

    If conflicts are detected, the Patch Installation Validation dialog box displays a summary of those conflicts. The patch cannot be applied until the conflicts are resolved. For more information, see Resolving Patch Conflicts.

  3. When the patch is applied, it is added to the current patch profile. The patch is no longer listed in the Downloaded Patches panel of the Manage Patches tab for this profile.

    Note:

    The listing for this patch in the Downloaded Patches panel of the Get Patches tab is retained.

Deleting a Custom Patch Profile

To delete a custom patch profile, complete the following steps:

  1. From the Manage Patches tab, select the custom patch profile you want to delete.

  2. Choose Patches > Patch Profiles > Delete.

    A confirmation dialog box is displayed, giving you the option of continuing or canceling the delete operation.

When deleting a custom patch profile, keep in mind the following:

  • Any start script for a domain or server may fail if it points to a custom patch profile that has been deleted. (Instructions for pointing a domain or server at a patch profile are provided in Pointing Domains and Servers at a Custom Patch Profile.)

  • When you delete a custom patch profile, the patches associated with it are not removed.

  • You cannot delete the default patch profile. If you try to do so, Smart Update displays an error message.

Pointing Domains and Servers at a Custom Patch Profile

To point a domain or server at a custom patch profile you have created, complete the following steps:

  1. Make a backup copy of each script you plan to modify.

  2. In the Target Installation panel within Smart Update, select a target installation.

  3. Choose the Patches > Start Script Editor menu option. The Start Script Editor dialog box is displayed.

  4. In the Start Script Editor dialog box:

    1. Choose the custom patch profile to which the domain or server will point.

    2. Open the start script you want to modify. For instructions, see Opening a Start Script

    3. Add the patch path variables that reference your new custom patch profile. Smart Update provides a code snippet containing suggested definitions for the PATCH_CLASSPATH, WEBLOGIC_EXTENSION_DIRS, PATCH_LIBPATH, and PATCH_PATH variables. These definitions reference patches that contain classes and files to be inserted into the system class and library path. However, depending on the content of the custom patch profile, and the specific patch path variables you need to reference, you might need to make different modifications.

    4. Save the start script.

      Note:

      When adding a definition of a patch path variable to a start script, ensure that the definition appears before any statement that invokes another start script. For example, if you add a patch path variable definition to the setDomainEnv script, add it before the statement that invokes the commEnv script. This placement ensures that the definition you add is not overridden by a definition appearing in any of the start scripts that are subsequently invoked.

The default start script for the WebLogic Server product home directory is WL_HOME\common\bin\commEnv. It contains default values for the following variables used for inserting patch files into a classpath or library path:

  • PATCH_CLASSPATH

  • WEBLOGIC_EXTENSION_DIRS

  • PATCH_LIBPATH

  • PATCH_PATH

For details, see Default Patch Path Environment Variables.

If you add definitions for these variables to a server or domain start script, your new definitions override the default definitions, in the commEnv script, for the corresponding servers or domain. Therefore, whenever you define these variables in a server or domain script, ensure that your new definitions apply to the appropriate server instances.

Also, note the order in which start scripts are executed: after the definition of one of these variables has been set in a script, it is not overridden by any definition in a script that is executed subsequently. For more information, see Sequence in Which Start Scripts Are Executed.

Important Note if You Use Custom Scripts

If you use custom scripts in your environment that do not invoke the WL_HOME\common\bin\commEnv script, you must change the statements in your scripts that set the class and library paths for your environment so that the environment variables you have defined are properly inserted into statements such as Set WEBLOGIC_CLASSPATH and Set PATH.

For example, to set the WebLogic system classpath so that patch JARs in a custom patch profile supersede same-named classes appearing later in the classpath, add the PATCH_CLASSPATH variable as follows, shown in bold:

set WEBLOGIC_CLASSPATH=%PATCH_CLASSPATH%;%JAVA_HOME%\lib\tools.jar;
%WL_HOME%\server\lib\weblogic_sp.jar;%WL_HOME%\server\lib\weblogic.jar;
%WL_HOME%\server\lib\webservices.jar

For more information about pointing custom scripts at patch profiles, see Pointing All Domains and Servers at Patches Through Custom Scripts.

Related Topics

Managing Custom Patch Profiles in a Node Manager Environment

If you use the Node Manager in your domain, and all the patches used in your domain are applied to the default patch profile, the servers started by the Node Manager run against those patches automatically. If, however, you use custom patch profiles in a domain that is configured to use the Node Manager, you must complete the additional procedure provided in this section.

To ensure that all the Managed Servers in a domain cluster point to patches in the custom patch profile at startup time, complete the following steps:

  1. Ensure that each Node Manager instance is the Java-based version that runs within a Java Virtual Machine (JVM) process. To ensure that Node Manager is restarted automatically whenever the system is restarted, it is recommended that you run every Node Manager instance as follows:

    • On Windows platforms: as a Windows service

    • On UNIX platforms: as an operating service

    Use of the script-based version of the Node Manager is not supported for the procedures presented in this section.

  2. If the custom patch profile that must be referenced by the Managed Servers at start time contains patch JAR files for the WebLogic system classpath, but it does not contain native library files that need to be inserted into the system path, you can set the classpath for the affected Managed Servers through the WebLogic Server Administration Console, as follows:

    1. Start the Administration Server.

    2. Access the WebLogic Server Administration Console by entering the following URL:

      http://hostname:port/console

      Here hostname represents the DNS name or IP address of the Administration Server, and port represents the number of the port on which the Administration Server is listening for requests (port 7001 by default).

    3. In the Change Center of the Administration Console, click Lock & Edit.

    4. In the left pane of the Console, expand Environment and select Servers.

    5. In the Servers table, click the name of each Managed Server you want to configure. For each Managed Server, complete steps (f) and (g).

    6. Choose the Configuration > Server Start menu option.

    7. Add the PATCH_CLASSPATH environment variable to the beginning of the Classpath field.

    8. Click Save.

    9. To activate these changes, in the Change Center of the Administration Console, click Activate Changes.

  3. If the custom patch profile that must be referenced by the Managed Servers at start time contains native library files that need to be inserted into the system path, regardless of whether the custom patch profile also contains patch JAR files, you need to edit the Node Manager nodemanager.properties file on each system that hosts a Managed Server in the cluster. Open each such nodemanager.properties file and make the following changes:

    1. Set the StartScriptEnabled property to true, as in the following example:

      StartScriptEnabled=true

    2. Ensure that the StartScriptName property is set to the WebLogic Server start script used for all server instances in the domain. The default start scripts are operating system-specific:

      Windows:

      startWebLogic.cmd

      UNIX:

      startWebLogic.sh

      For information about modifying the nodemanager.properties file, see "Node Manager Configuration and Log Files" in Node Manager Administrator's Guide for Oracle WebLogic Server.

    3. In a text editor, open the setDomainEnv script for the domain (setDomainEnv.cmd on Windows, setDomainEnv.sh on UNIX) and define one or more of the patch path environment variables described in Table 6-1.

    For each file or directory identified in Table 6-1 that is included in the installation-level patch directory (MW_HOME\patch_wls1000), add a definition to the setDomainEnv script for the corresponding patch path variable so that the variable points to that file or directory. In Table 6-1, custom-profile represents the name of the custom patch profile created in the installation-level patch directory.

    For example, if your system hosts a JAR file called MW_HOME\patch_wls1000\profiles\custom-profile\sys_manifest_classpath\weblogic_patch.jar, add a definition of the PATCH_CLASSPATH variable to the setDomainEnv script that points to that file.

    Note:

    Starting from the Oracle Fusion Middleware 11gR1 release, MW_HOME is the new term for BEA_HOME.

    Table 6-1 Patch Variables to Define in setDomainEnv for Node Manager Environments

    Define the following variable If the following is present in the custom profile directory

    PATCH_CLASSPATH

    File:

    MW_HOME\patch_wls1001\profiles\custom-profile\
sys_manifest_classpath\weblogic_patch.jar

    Purpose of variable:

    The PATCH_CLASSPATH variable points to classes in patch JAR files that are to be inserted into the WebLogic system classpath used by each Managed Server that is started by the Node Manager in your domain.

    Example:

    PATCH_CLASSPATH= "%BEA_HOME%\patch_wls1001\profiles\
myCustomProfile\sys_manifest_classpath \weblogic_patch.jar"

    Note: The majority of patches issued by My Oracle Support are referenced by this patch manifest JAR file.

    WEBLOGIC_EXTENSION_DIRS

    File:

    MW_HOME\patch_wls1001\profiles\custom-profile\
sysext_manifest_classpath\weblogic_ext_patch.jar

    Purpose of variable:

    The WEBLOGIC_EXTENSION_DIRS variable points to classes in patch JAR files that are to be inserted into the classpath of an application that is deployed on WebLogic Server and required by a product.

    Example:

    WEBLOGIC_EXTENSION_DIRS="%BEA_HOME%\MW_HOME\
patch_wls1001\profiles\myCustomProfile\
sysext_manifest_classpath\weblogic_patch.jar"

    Note: Patch manifest JAR files that reference application-level classes are not supported by WebLogic Server 9.1.

    PATCH_LIBPATH

    Directory (UNIX only):

    MW_HOME/patch_wls1001/profiles/custom-profile/native

    Purpose of variable:

    The PATCH_LIBPATH variable points to native library files to be inserted into the system path through the LIBPATH environment variable.

    Example:

    PATCH_LIBPATH="${BEA_HOME}/patch_wls1001/
profiles/myCustomProfile/native"

    PATCH_PATH

    Directory (Windows only):

    MW_HOME\patch_wls1001\profiles\custom-profile\native

    Purpose of variable:

    The PATCH_PATH variable points to native library files to be inserted into the system path through the PATH environment variable.

    Example:

    set PATCH_PATH=%BEA_HOME%\patch_wls1001\
profiles\myCustomProfile\native

  4. Restart the each Managed Server instance. Until you do so, your updates to the Node Manager configuration files and patch path variable definitions do not become effective