6 Patching Individual Applications, Domains, or Servers

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 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 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:

• setDomainEnv—Script used to set domain-level environment variables, including those used by all servers.

• startWebLogic—Start script used by any WebLogic Server instances in the domain that are not Managed Servers.

• startManagedWebLogic—Start script used by Managed Servers in the domain, including those in a cluster.

  Note:

  For details, see Default Script that Defines Class and Library Paths for All Domains and Servers.

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 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.

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:

• Initial Contents of a Custom Patch Profile

• Cloning a Patch Profile

• Adding Patches to a Custom Patch Profile

• Deleting a Custom Patch Profile

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.

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

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) below.

   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 (BEA_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 BEA_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: BEA_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: BEA_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%\BEA_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): BEA_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): BEA_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