Skip Headers
Oracle® Business Transaction Management Installation Guide
12.1

E26543-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

10 Installing Observer Libraries on WebSphere

This chapter provides instructions for upgrading, installing, and uninstalling observer libraries for monitoring JavaEE running in WebSphere 6.1 application servers.

The Observer Distribution Files

The Business Transaction Management observers are distributed by way of ZIP files. Each ZIP file contains one type of observer that is suitable for installation into a particular application server. The ZIP files suitable for installing observers into WebSphere application servers are as follows:

Note:

In the actual ZIP files, the asterisk (*) is replaced with the observer version number.

Installing the Observer Libraries on WebSphere

  1. Locate the observer distribution ZIP file that is appropriate for your version of WebSphere.

    This ZIP file contains the observer for WebSphere 6.1.

  2. Unpack the observer ZIP file into your WebSphere installation root directory (WAS_INSTALL_ROOT).

    The default location of the WebSphere installation root directory on Windows systems is:

    C:\Program Files\IBM\WebSphere\AppServer
    

    On UNIX-like systems, the default location is:

    /opt/IBM/WebSphere/AppServer
    

    For the remainder of this procedure, replace WAS_INSTALL_ROOT with the actual path to the WebSphere installation root directory.

    Unpacking the ZIP file creates a directory named nanoagent that contains two subdirectories—config and lib.

    Note:

    By default, the observer looks in the lib directory for its libraries. For information on overwriting this default location, see Specifying the Observer Library Location.
  3. 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

  4. Move ap-nano-jaxrpc.jar from nanoagent/lib/bootstrap to WAS_INSTALL_ROOT/lib/ext.

  5. Restart WebSphere and log in to the WebSphere Administrative Console for your profile.

  6. In the WebSphere Administrative Console, navigate to Servers > Application servers > server1 > Server Infrastructure > Java and Process Management > Process Definition > Java Virtual Machine (you might have to substitute a different server name for server1).

    1. Add the observer libraries to your server's class path by adding the observer bootstrap file to the Classpath field as follows:

      For Windows systems, add this string:

      ${WAS_INSTALL_ROOT}\nanoagent\lib\bootstrap\ap-nano-bootstrap.jar
      

      For UNIX-like systems, add this string:

      ${WAS_INSTALL_ROOT}/nanoagent/lib/bootstrap/ap-nano-bootstrap.jar
      
    2. Add the following arguments to the Generic JVM arguments field:

      For Windows systems, add this string:

      -javaagent:${WAS_INSTALL_ROOT}\nanoagent\lib\bootstrap\aspectwerkz-jdk5-2.0.jar
      

      For UNIX-like systems, add this string:

      -javaagent:${WAS_INSTALL_ROOT}/nanoagent/lib/bootstrap/aspectwerkz-jdk5-2.0.jar (Linux/UNIX) 
      

      Note:

      This property configures the AspectWerkz module. You do not need to set it if you plan to monitor only JAX-RPC services.
  7. Add custom properties as follows:

    1. Click the Custom Properties link, and then for each property you are adding, click New, input the name, value, and description, and then click OK. The properties to add follow:

    2. Add a property that specifies the observer home directory:

      Name = AP_NANO_HOME

      Value = WAS_INSTALL_ROOT/nanoagent

      Note:

      Replace WAS_INSTALL_ROOT with the actual path to your WebSphere installation root directory. You must uses backslashes for Windows. Follow these examples:

      For Windows systems:

      Value = C:\Program Files\IBM\WebSphere\AppServer

      For UNIX-like systems:

      Value = /opt/IBM/WebSphere/AppServer

      Description = The observer home directory

    3. Add a property that associates the observer with a monitor:

      Name = AP_NANO_CONFIG_URL

      Value = http://Host:Port/btmmonitor/agent/agent/

      Notes:

      Replace Host:Port with the host name and port number at which the monitor is available.

      If you are using replicated monitors, you must set the host and port portion of the URL to the host and port of your load balancer's HTTP virtual server. For example, if the HTTP virtual server's IP address is 10.147.46.152, and its port number is 5072, then you would set the URL to:

      http://10.147.46.152:5072/btmmonitor/agent/agent/
      

      For more information about the load balancer's HTTP virtual server, see Configuring Your Load Balancer.

      Description = Associates the observer with the monitor whose URL you specify. At startup, the observer retrieves its configuration from the specified monitor and begins sending observations to the monitor.

    4. Add a property that configures the AspectWerkz module:

      Name = aspectwerkz.classloader.preprocessor

      Value = com.amberpoint.nanoagent.plugins.APAspectFilterPreProcessor

      Description = Business Transaction Management observer class preprocessor

      Note:

      You do not need to set this property if you plan to monitor only JAX-RPC services.
    5. Click Save to save your master configuration.

  8. Shutdown WebSphere and modify the Java policies as described in Java Policy Modifications.

    If Java 2 security is enabled for WebSphere, you must make all of the modifications described in the section. If Java 2 security is not enabled, you need modify only the server.policy file.

  9. Ensure that the user under which your WebSphere server is running has permission to write to the observer's error log directory.

    By default, the observer's error log directory is the WebSphere profile directory. For information about configuring error logging, see Chapter 14, "Logging Observer Errors and Debugging Information."

  10. Restart WebSphere.

  11. Ensure that the monitor to which your observer forwards messages has an Observer Communication policy applied to it.

    For information on applying an Observer Communication policy, see Applying an Observer Communication Policy.

Java Policy Modifications

You must modify your WebSphere server's server.policy file as described in Modifications to the WebSphere server.policy file. If Java 2 security is enabled on your WebSphere server, you must also modify your app.policy files as described in Modifications to the app.policy files.

Modifications to the WebSphere server.policy file

Add the following policy definition to the WebSphere server.policy file and save it (the server.policy file is located at WAS_INSTALL_ROOT/profiles/Profile_Name/properties/server.policy):

grant codeBase "file:${was.install.root}/nanoagent/lib/-" {
  permission java.security.AllPermission;
};

Note:

You must use forward slashes in the path, even on Windows.

Modifications to the app.policy files

Add permissions to the app.policy file(s) as follows:

WebSphere has an app.policy file for each node. You must make the modification for each node that you want to monitor. The app.policy files are located in:

WAS_INSTALL_ROOT/profiles/profile_name/config/cells/cell_name/nodes/node_name

Add the following permissions to each policy definition in the app.policy file:

permission java.lang.RuntimePermission "getClassLoader";
permission java.lang.RuntimePermission "accessDeclaredMembers";
permission java.lang.RuntimePermission "modifyThreadGroup";
permission java.lang.RuntimePermission "modifyThread";
permission java.lang.RuntimePermission "shutdownHooks";
permission java.io.FilePermission "<<ALL FILES>>", "read,write,delete";
permission java.lang.RuntimePermission "accessClassInPackage.*";
permission java.util.logging.LoggingPermission "control";
permission java.lang.RuntimePermission "createClassLoader";
permission java.lang.RuntimePermission "reflectionFactoryAccess";
permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
permission com.ibm.websphere.security.WebSphereRuntimePermission "AdminPermission";

The following permissions are required in each policy definition in the app.policy file except the application policy definition (the first policy definition in the file). Your app.policy file probably has these permissions already declared. If not, add them.

permission java.net.SocketPermission "*", "connect";
permission java.util.PropertyPermission "*", "read";

Your app.policy file should look something like this when you have finished:

grant codeBase "file:${application}" {
  // The following are required by Java mail
  permission java.io.FilePermission "${was.install.root}${/}lib${/}mail-impl.jar",
"read";
  permission java.io.FilePermission "${was.install.root}${/}lib${/}activation-impl.jar",
"read";
  //Permissions Added for BTM observers 
  permission java.lang.RuntimePermission "getClassLoader";
  permission java.lang.RuntimePermission "accessDeclaredMembers";
  permission java.lang.RuntimePermission "modifyThreadGroup";
  permission java.lang.RuntimePermission "modifyThread";
  permission java.lang.RuntimePermission "shutdownHooks";
  permission java.io.FilePermission "<<ALL FILES>>", "read,write,delete";
  permission java.lang.RuntimePermission "accessClassInPackage.*";
  permission java.util.logging.LoggingPermission "control";
  permission java.lang.RuntimePermission "createClassLoader";
  permission java.lang.RuntimePermission "reflectionFactoryAccess";
  permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
  permission com.ibm.websphere.security.WebSphereRuntimePermission "AdminPermission";
};
grant codeBase "file:${jars}" {
  permission java.net.SocketPermission "*", "connect";
  permission java.util.PropertyPermission "*", "read";
  //Permissions Added for BTM observers
  permission java.lang.RuntimePermission "getClassLoader";
  permission java.lang.RuntimePermission "accessDeclaredMembers";
  permission java.lang.RuntimePermission "modifyThreadGroup";
  permission java.lang.RuntimePermission "modifyThread";
  permission java.lang.RuntimePermission "shutdownHooks";
  permission java.io.FilePermission "<<ALL FILES>>", "read,write,delete";
  permission java.lang.RuntimePermission "accessClassInPackage.*";
  permission java.util.logging.LoggingPermission "control";
  permission java.lang.RuntimePermission "createClassLoader";
  permission java.lang.RuntimePermission "reflectionFactoryAccess";
  permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
  permission com.ibm.websphere.security.WebSphereRuntimePermission "AdminPermission";
};
grant codeBase "file:${connectorComponent}" {
  permission java.net.SocketPermission "*", "connect";
  permission java.util.PropertyPermission "*", "read";
  //Permissions Added for BTM observers
  permission java.lang.RuntimePermission "getClassLoader";
  permission java.lang.RuntimePermission "accessDeclaredMembers";
  permission java.lang.RuntimePermission "modifyThreadGroup";
  permission java.lang.RuntimePermission "modifyThread";
  permission java.lang.RuntimePermission "shutdownHooks";
  permission java.io.FilePermission "<<ALL FILES>>", "read,write,delete";
  permission java.lang.RuntimePermission "accessClassInPackage.*";
  permission java.util.logging.LoggingPermission "control";
  permission java.lang.RuntimePermission "createClassLoader";
  permission java.lang.RuntimePermission "reflectionFactoryAccess";
  permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
  permission com.ibm.websphere.security.WebSphereRuntimePermission "AdminPermission";
};
grant codeBase "file:${webComponent}" {
  permission java.io.FilePermission "${was.module.path}${/}-", "read, write";
  permission java.lang.RuntimePermission "loadLibrary.*";
  permission java.lang.RuntimePermission "queuePrintJob";
  permission java.net.SocketPermission "*", "connect";
  permission java.util.PropertyPermission "*", "read";
  //Permissions Added for BTM observers
  permission java.lang.RuntimePermission "getClassLoader";
  permission java.lang.RuntimePermission "accessDeclaredMembers";
  permission java.lang.RuntimePermission "modifyThreadGroup";
  permission java.lang.RuntimePermission "modifyThread";
  permission java.lang.RuntimePermission "shutdownHooks";
  permission java.io.FilePermission "<<ALL FILES>>", "read,write,delete";
  permission java.lang.RuntimePermission "accessClassInPackage.*";
  permission java.util.logging.LoggingPermission "control";
  permission java.lang.RuntimePermission "createClassLoader";
  permission java.lang.RuntimePermission "reflectionFactoryAccess";
  permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
  permission com.ibm.websphere.security.WebSphereRuntimePermission "AdminPermission";
};
grant codeBase "file:${ejbComponent}" {
  permission java.lang.RuntimePermission "queuePrintJob";
  permission java.net.SocketPermission "*", "connect";
  permission java.util.PropertyPermission "*", "read";
  //Permissions Added for BTM observers
  permission java.lang.RuntimePermission "getClassLoader";
  permission java.lang.RuntimePermission "accessDeclaredMembers";
  permission java.lang.RuntimePermission "modifyThreadGroup";
  permission java.lang.RuntimePermission "modifyThread";
  permission java.lang.RuntimePermission "shutdownHooks";
  permission java.io.FilePermission "<<ALL FILES>>", "read,write,delete";
  permission java.lang.RuntimePermission "accessClassInPackage.*";
  permission java.util.logging.LoggingPermission "control";
  permission java.lang.RuntimePermission "createClassLoader";
  permission java.lang.RuntimePermission "reflectionFactoryAccess";
  permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
  permission com.ibm.websphere.security.WebSphereRuntimePermission "AdminPermission";
};

Uninstalling the Observer Libraries from WebSphere

  1. Log in to the WebSphere Administrative Console for your profile.

  2. Navigate to Servers > Application Servers > server1 > Server Infrastructure >Java and Process Management > Process Definition >Java Virtual Machine.

    You might have to substitute a different server name for server1.

  3. Remove the following line from the Classpath field:

    ${WAS_INSTALL_ROOT}/nanoagent/lib/bootstrap/ap-nano-bootstrap.jar
    
  4. Remove the following line from the Generic JVM arguments field:

    -javaagent:${WAS_INSTALL_ROOT}/nanoagent/lib/bootstrap/aspectwerkz-jdk5-2.0.jar
    
  5. Navigate to Servers > Application Servers > server1 > Server Infrastructure > Java and Process Management > Process Definition > Java Virtual Machine > Custom Properties.

  6. Remove any and all of the following custom properties (you might not have all of these properties set):

    • AP_NANO_CONFIG_URL

    • AP_NANO_HOME

    • aspectwerkz.classloader.preprocessor

  7. Click Save to save these changes to your master configuration.

  8. Stop the WebSphere server.

  9. Remove ap-nano-jaxrpc.jar from WAS_INSTALL_ROOT\lib\ext.

    The default location of the WebSphere installation root directory (WAS_INSTALL_ROOT) on Windows systems is:

    C:\Program Files\IBM\WebSphere\AppServer
    

    On UNIX-like systems, the default location is:

    /opt/IBM/WebSphere/AppServer
    
  10. Delete the nanoagent directory from WAS_INSTALL_ROOT, including all subdirectories and files.

  11. Restart WebSphere.