This chapter explains how to perform an in-place upgrade of Business Transaction Management from any version of release 11 or 12 to the current release. Performing an in-place upgrade means that you upgrade components by simply replacing them with new components, and without editing configuration settings.
A complete upgrade of Business Transaction Management consists of upgrading these components:
all three central servers—these are, the Main server (btmMain.ear), the Performance server (btmPerformanceServer.ear), and the Transaction server (btmTransactionServer.ear)
all monitors (btmMonitor.ear)
all observers
If any of these components are older than release 11, do not attempt to perform an upgrade using the instructions in this chapter. Instead, enter a service request at My Oracle Support (http://support.oracle.com) for assistance in upgrading your installation.
If you choose to upgrade your system, you must upgrade all of the central servers and all of the monitors at the same time (a rolling upgrade is not supported between these components). However, you are not required to upgrade your observers, as long as the observers are at release 11 or higher. If you leave the observers at an older release version than the monitors, the monitors operate in compatibility mode in relation to the observers. Note, however, that if you do not upgrade the observers, you will not be able to take advantage of new functionality that depends on upgraded observers.
You must upgrade the Business Transaction Management central servers and monitors before upgrading the observers. Observers are permitted to be older than the central servers and monitors, but you must never install a version of the observer that is newer than the central servers and monitors.
Note:
In comparing version numbers between the observer and the central servers and monitors, you need be concerned only with the digits up to the second point. For example, in “11.2.0.1”, you need to consider only the “11” and the “2”. Digits after the second point refer to patches and are not important in determining compatibility between the observer and the central servers and monitors.To determine the version of your installed observer, open the observer's NanoAgent.log file and search for the line that displays the release number, for example:
INFO: Release 11.1.0.4: build 25237 of b21 (11.1.0.4/147754) on 2011-05-13
For information about locating the NanoAgent.log file, see Chapter 16, "Logging Observer Errors and Debugging Information."
To upgrade your Business Transaction Management installation:
Back up your Business Transaction Management databases and configuration data.
For information on how to perform this task, refer to the online help topics Backup and Restore Concepts and Backing up BTM. You can locate these topics by first choosing Help > Help in the Management console. After the online help opens, navigate to Administering BTM > Backup and Restore in the Contents pane.
Note:
The central servers must be running in order for you to access the online help.Back up the persistent storage directories for each of the central servers and monitors.
For information on the locations of the persistent storage directories, refer to the online help topic About Persistent Storage Directories. You can locate this topic by first choosing Help > Help in the Management console. After the online help opens, navigate to Administering BTM > Persistent Data in the Contents pane.
Locate the distribution archive that contains the Business Transaction Management central servers and monitor and unzip it into a directory (referred to as henceforth Install_Dir).
The distribution archive is named BTM_Servers_*.zip, where * is the Business Transaction Management version number.
Optional security step for UNIX-like operating systems – If you want to set permissions on the files that make up the distribution to the most restrictive level that still maintains functionality, complete this step:
Locate setPermissions.sh at the top level of Install_Dir.
This script contains commands for setting file permissions of all regular files to Owner – read/delete; all directories to Owner – read/execute/delete; and all scripts to Owner – read/execute/delete.
Note:
These permission levels are extremely restrictive, for example, only the owner can read the files.On a command line, at the top level of Install_Dir, run this command:
source setPermissions.sh
This command runs the commands in the script file and sets permissions for all files and directories in the expanded archive.
Shut down all of the central servers and monitors (btmMain.ear, btmPerformanceServer.ear, btmTransactionServer.ear, and btmMonitor.ear).
It is essential that you shut them all down.
For information about shutting down Business Transaction Management components, see Chapter 7, "Starting and Shutting Down Business Transaction Management."
Using your application server's deployment tools, redeploy each of the central servers and monitors using your new EAR files located in Install_Dir\archives.
Restart the central servers and monitors.
Restarting the central servers and monitors triggers the in-place upgrade of all Business Transaction Management data. During this process, the system might suffer from reduced performance and some of the data might be temporarily unavailable. This process should complete within 30 minutes.
For information about starting Business Transaction Management components, see Chapter 7, "Starting and Shutting Down Business Transaction Management."
Notify all Business Transaction Management users to flush their web browser caches.
The Management Console contains a number of Adobe Flash widgets. Web browsers normally cache these widgets and will continue to use the older cached widgets until you either flush the cache or restart your web browser.
After you are finished with upgrading the central servers and monitors, and the system has settled down, you can optionally upgrade your observers by following the instructions in the next section.
You should also read the online help topic named Post-Upgrade Configuration and Issues for information about further upgrade-related tasks you might have to perform and changes in behavior to expect, such as the default values of fields. You can locate this topic by first choosing Help > Help in the Management console. After the online help opens, navigate to Overview of BTM in the Contents pane.
You must upgrade the Business Transaction Management central servers and monitors, as described in the preceding section, before upgrading the observers.
The procedure for upgrading observers is specific to the application server and observer type. Refer to the following sections for detailed instructions on upgrading observers:
Note:
For detailed information about a specific observer's compatibility and functionality, refer to the README.txt file located in the observer's nanoagent directory after you expand the observer ZIP file.This section describes how to upgrade an observer installed into a WebLogic application server. Separate procedures are provided for three different upgrade paths. The procedure you use depends on the type of observer you are upgrading, your version of WebLogic server, and whether your server is Node-Manager configured or script-configured. These are the procedures to choose from:
Use this procedure to upgrade the following observers on WebLogic 10.3 Node Manager-configured servers:
observer for Oracle SOA Suite
observer for Oracle Service Bus 11gR1
release 11 or 12.1.0.1 observer for JavaEE (on WebLogic 10.3)
Locate the distribution ZIP file for the observer you want to install.
Open the WebLogic Administration Console (the default URL is http://machine_name:7001/console).
Remove WL_HOME/nanoagent/lib/bootstrap/ap-nano-bootstrap.jar from your managed server's classpath (this setting was required by the previous release of the observer but must be removed for the current release):
Using the Domain Structure pane (on the left), navigate to Environment > Servers.
In the Servers table, click your managed server.
Display the Configuration / Server Start tab.
Click Lock & Edit.
Note:
These instructions assume you are operating in a production environment and that your WebLogic server's Automatically Acquire Lock and Activate Changes setting is therefore disabled. However, if this setting is enabled as it might be in a development environment, you do not have to click Lock & Edit in order to make changes and you do not have to activate changes after saving them.Delete the entry from the Class Path field as follows:
For Windows systems, delete this string:
WL_HOME\nanoagent\lib\bootstrap\ap-nano-bootstrap.jar
For UNIX-like systems, delete this string:
WL_HOME/nanoagent/lib/bootstrap/ap-nano-bootstrap.jar
Keep this page open.
With the Configuration / Server Start tab still displayed, edit your WebLogic startup arguments as follows:
Remove JVM arguments from the Arguments field as follows (these settings were required by the previous release of the observer but must be removed for the current release):
For Windows systems, remove these arguments:
-Daspectwerkz.classloader.preprocessor=com.amberpoint.nanoagent.plugins.APAspectPreProcessor -javaagent:WL_HOME\nanoagent\lib\bootstrap\aspectwerkz-jdk5-2.0.jar
For UNIX-like systems, remove these arguments:
-Daspectwerkz.classloader.preprocessor=com.amberpoint.nanoagent.plugins.APAspectPreProcessor -javaagent:WL_HOME/nanoagent/lib/bootstrap/aspectwerkz-jdk5-2.0.jar
Configure the observer bootstrap module into your server by adding a JVM argument to the Arguments field as follows.
For Windows systems, add this argument:
-javaagent:WL_HOME\nanoagent\lib\bootstrap\ap-nano-bootstrap.jar
For UNIX-like systems, add this argument:
-javaagent:WL_HOME/nanoagent/lib/bootstrap/ap-nano-bootstrap.jar
Click Save and then click Activate Changes.
You should receive the following status:
"All changes have been activated. No restarts are necessary. Settings updated successfully."
Shut down the WebLogic managed server in which the observer is installed.
Delete the WL_HOME\nanoagent directory from your WebLogic managed server.
The string WL_HOME refers to the server's home directory, which is the wlserver_10.3 directory located in your server's installation directory. For the remainder of this procedure, replace the string WL_HOME with the actual path to the WebLogic home directory.
Unpack the observer distribution ZIP file into WL_HOME.
Unpacking the ZIP file creates a directory named nanoagent that contains three subdirectories bin, config, and lib.
Ensure that the user account running the WebLogic server has at least the following privileges:
read permission on the nanoagent/config and nanoagent/lib directories (on UNIX-like systems traverse permission is also required)
read permission on all JAR files in the lib directory
If you inserted <filter> and <filter-mapping> elements into the web.xml files of your web applications during your original installation of the observer, you must now remove those elements.
The elements to remove from the web.xml files are these:
<filter> <filter-name>ORACLE_BTM_WEB_APP_OBSERVER</filter-name> <filter-class> com.amberpoint.nanoagent.bootstrap.servlet.FilterHandlerBootstrap </filter-class> </filter> <filter-mapping> <filter-name>ORACLE_BTM_WEB_APP_OBSERVER</filter-name> <url-pattern>/*</url-pattern> </filter-mapping>
Restart your WebLogic server.
Use this procedure to upgrade the following observers on WebLogic 10.3 script-configured configured servers:
observer for Oracle SOA Suite
observer for Oracle Service Bus 11gR1
release 11 or 12.1.0.1 observer for JavaEE (on WebLogic 10.3)
Note:
When you originally installed the observer, you either installed it into all servers defined in the WebLogic installation or into servers of specific domains. The term global install refers to installing the observer into all servers, and the term domain install refers to installing the observer into a specific domain.In the following procedure, you will replace the nanoagent directory and its contents. If you installed the observer as a global install, the nanoagent directory is located inside your WebLogic server's home directory, which is the wlserver_10.3 directory located in your WebLogic installation directory.
If you installed the observer as a domain install, the nanoagent directory is located inside your domain directory. In this case, you need to repeat this procedure for each domain in which you installed the observer.
Shut down the WebLogic application server in which the observer is installed.
Make a backup copy of your observer script file.
The observer script file is the nanoEnvWeblogic.cmd or nanoEnvWeblogic.sh file located inside the nanoagent/bin directory.
Delete the nanoagent directory.
Unpack the observer distribution ZIP file into the directory from which you deleted the nanoagent directory.
Unpacking the ZIP file creates a directory named nanoagent that contains three subdirectories bin, config, and lib.
Ensure that the user account running WebLogic has at least the following privileges:
read permission on the nanoagent/config and nanoagent/lib directories (on UNIX-like systems traverse permission is also required)
read permission on all JAR files in the lib directory
Open your new observer script file for editing and open your backup copy so you can copy settings from it.
Ensure that the values of the NANOAGENT_HOME and NANOAGENT_CONFIGURATION_URL variables in your new observer configuration file match the values in your backup copy.
If you inserted <filter> and <filter-mapping> elements into the web.xml files of your web applications during your original installation of the observer, you must now remove those elements.
The elements to remove from the web.xml files are these:
<filter> <filter-name>ORACLE_BTM_WEB_APP_OBSERVER</filter-name> <filter-class> com.amberpoint.nanoagent.bootstrap.servlet.FilterHandlerBootstrap </filter-class> </filter> <filter-mapping> <filter-name>ORACLE_BTM_WEB_APP_OBSERVER</filter-name> <url-pattern>/*</url-pattern> </filter-mapping>
Restart your WebLogic server.
Use this procedure to upgrade the following observers on WebLogic servers:
release 12.1.0.2 observer for JavaEE
observer for JavaEE on WebLogic 9.2
observer for Oracle Service Bus 10gR3
Note:
Observers for some older platforms (such as WebLogic 9.2) are distributed with release 12.1.0.1 rather than release 12.1.0.2. Refer to Packaging for details.Shut down the WebLogic application server in which the observer is installed.
Make a backup copy of the WL_HOME\nanoagent directory.
The string WL_HOME refers to your WebLogic server's home directory, which is the weblogic92, wlserver_10.0, or wlserver_10.3 directory located in your WebLogic installation directory.
Delete the WL_HOME\nanoagent directory.
Unpack the observer distribution ZIP file into WL_HOME.
Unpacking the ZIP file creates a directory named nanoagent that contains three subdirectories bin, config, and lib.
Ensure that the user account running WebLogic has at least the following privileges:
read permission on the nanoagent/config and nanoagent/lib directories (on UNIX-like systems traverse permission is also required)
read permission on all JAR files in the lib directory
If you originally installed the observer by editing script files rather than by using the Node Manager, replace your new observer script file with the observer script file located in your backup copy of the nanoagent directory. If you use the Node Manager, you can skip this step.
On Windows systems, the observer script file is located at:
WL_HOME\nanoagent\bin\nanoEnvWeblogic.cmd
On UNIX-like systems, the observer script file is located at:
WL_HOME/nanoagent/bin/nanoEnvWeblogic.sh
Restart your WebLogic server.
This section explains how to upgrade an observer installed in a WebSphere application server.
Note:
The most recently released observer for this platform is distributed as part of release 12.1.0.1. It is not included with, but is compatible with, release 12.1.0.2.Shut down the WebSphere server in which the observer is installed.
Make a backup copy of the WAS_INSTALL_ROOT/nanoagent directory.
WAS_INSTALL_ROOT refers to your WebSphere installation root directory. The default location of this directory on Windows systems is:
C:\Program Files\IBM\WebSphere\AppServer
On UNIX-like systems, the default location is:
/opt/IBM/WebSphere/AppServer
Delete the WAS_INSTALL_ROOT/nanoagent directory.
Unpack the observer distribution ZIP file (BTMObserver_Was_6.1_JavaEE_*.zip) into WAS_INSTALL_ROOT.
Unpacking the ZIP file creates a directory named nanoagent that contains two subdirectories—config and lib.
Ensure that the user account running WebSphere has at least the following privileges:
read permission on the nanoagent/config and nanoagent/lib directories (on UNIX-like systems traverse permission is also required)
read permission on all JAR files in the lib directory
Restart your WebSphere server.
This section explains how to upgrade an observer installed in a JBossEAP application server.
Note:
The most recently released observer for this platform is distributed as part of release 12.1.0.1. It is not included with, but is compatible with, release 12.1.0.2.Shut down the JBoss server in which the observer is installed.
Make a backup copy of the JBOSS_HOME/nanoagent directory.
JBOSS_HOME refers to the value of your JBOSS_HOME environment variable.
C:\Program Files\IBM\WebSphere\AppServer
On UNIX-like systems, the default location is:
/opt/IBM/WebSphere/AppServer
Delete the JBOSS_HOME/nanoagent directory.
Unpack the observer distribution ZIP file (BTMObserver_Jboss_4.3_JavaEE_*.zip) into JBOSS_HOME.
Unpacking the ZIP file creates a directory named nanoagent that contains three subdirectories—config, jaxws, and lib.
Ensure that the user account running WebSphere has at least the following privileges:
read permission on the nanoagent/config and nanoagent/lib directories (on UNIX-like systems traverse permission is also required)
read permission on all JAR files in the lib directory
Restart your JBoss server.
This section explains how to upgrade an observer for WCF.
Unpack the observer distribution file (BTMObserver_Iis_6-7_Wcf35_*.zip) into a temporary directory (referred to henceforth as observer_temp).
Unpacking the ZIP file creates a nanoagent directory containing two subdirectories—config and lib. The lib directory contains the observer DLL files.
Make a note of the version number of the new DLLs.
To find the version number, open the Windows Properties dialog box for one of the DLL files and click the Version tab.
Use gacutil.exe or a Windows Explorer to copy all of the DLL files from observer_temp\nanoagent\lib to the global application cache (GAC; normally located at C:\WINDOWS\assembly).
Using a text editor, open the application configuration file that contains the observer configuration code that you added when you originally installed the observer.
The file is either the machine.config, or a web.config file.
In the application configuration file, locate the two occurrences of the Version attribute that refer to the version number of the observer DLLs.
The elements containing the Version attributes are inside a </behaviorExtensions> element and should look similar to this:
<add name="APEPInterceptor" type="AmberPoint.NanoAgent.DotNet.Wcf.APEPBehaviorExtnElem, AmberPoint.NanoAgentWCF, Version=64000.64000.25233.19024, Culture=neutral, PublicKeyToken=d8685c0afbb35893"/> <add name="APServiceInterceptor" type="AmberPoint.NanoAgent.DotNet.Wcf.APServiceBehaviorExtnElem, AmberPoint.NanoAgentWCF, Version=64000.64000.25233.19024, Culture=neutral, PublicKeyToken=d8685c0afbb35893"/>
Edit the setting of the Version attribute so that it matches the version number of the new observer DLLs, and then save and close the file.
Note:
If you configured the observer into multiple web.config files on the machine, edit the Version attributes in each file.Optional – Remove the old observer DLLs from the GAC (unless they are being used by another observer on the machine).
The name of each observer DLL begins with the string “AmberPoint”. To remove a DLL, right-click it and choose Uninstall.
Note:
The observer for ASP.NET uses many of the same DLLs as the observer for WCF. If you have the observer for ASP.NET installed on the machine, you must not remove the version of the DLLs that are being used by it.This section explains how to upgrade an observer for ASP.NET.
Unpack the observer distribution file (BTMObserver_Iis_6_Asp_*.zip) into a temporary directory (referred to henceforth as observer_temp).
Unpacking the ZIP file creates a nanoagent directory containing two subdirectories—config and lib. The lib directory contains the observer DLL files.
Make a note of the version number of the new DLLs.
To find the version number, open the Windows Properties dialog box for one of the DLL files and click the Version tab.
Use gacutil.exe or a Windows Explorer to copy all of the DLL files from observer_temp\nanoagent\lib to the global application cache (GAC; normally located at C:\WINDOWS\assembly).
Using a text editor, open the web.config file that contains the observer configuration code that you added when you originally installed the observer.
In the web.config file, locate the Version attribute that refers to the version number of the observer DLLs.
Here is an example of the XML code containing the version number:
<system.web>
<webServices>
<soapExtensionTypes>
<add type="AmberPoint.NanoAgent.DotNet.AspNet.Handlers.SoapExtensionHandler,
AmberPoint.NanoAgentAspNet, Version=64000.64000.25642.24032,
Culture=neutral, PublicKeyToken=d8685c0afbb35893" priority="1" group="0" />
</soapExtensionTypes>
</webServices>
</system.web>
Edit the setting of the Version attribute so that it matches the version number of the new observer DLLs, and then save and close the file.
Note:
If you configured the observer into multiple web.config files on the machine, edit the Version attributes in each file.Optional – Remove the old observer DLLs from the GAC (unless they are being used by another observer on the machine).
The name of each observer DLL begins with the string “AmberPoint”. To remove a DLL, right-click it and choose Uninstall.
Note:
The observer for WCF uses many of the same DLLs as the observer for ASP.NET. If you have the observer for WCF installed on the machine, you must not remove the version of the DLLs that are being used by it.