This chapter explains how to perform an in-place upgrade of Business Transaction Management from any version of release 11 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. If you leave the observers at an older release version, 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 14, "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_MonitorServices_*.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 6, "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 6, "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 explains how to upgrade any type of observer installed in a WebLogic application server.
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, for example:
C:\oracle\Middleware\wlserver_10.3
Delete the WL_HOME\nanoagent directory.
Unpack the observer distribution ZIP file (for example, BTMObserver_Wls_10.3_JavaEE_11.2.0.1.zip) 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 the backup copy of the nanoagent directory you made in step 2. 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
If you are upgrading the observer for JavaEE on WebLogic 10.3, and you monitor only JAX-RPC services, and you use the Node Manager, you might not have configured the AspectWerkz module during your original installation of the observer. If this is the case, and you want to utilize the new Axis support provided in this upgrade, you must now configure the AspectWerkz module.
For information on how to configure the AspectWerkz module, see step 7c of Installation on Node Manager-Configured Servers.
If you are upgrading the observer for JavaEE on WebLogic 10.3, and 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.
This section explains how to upgrade an observer installed in a WebSphere application server.
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_7_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.
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 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.