Installing the WebSphere Application Server monitoring extension

This section describes how to install the WebSphere Application Server monitoring extension on various platforms, and includes:

Installing the WebSphere Application Server monitoring extension on Windows or UNIX 

Before you begin

• See Supported middleware monitoring technologies for performance and availability to verify the intended monitored technology is supported and that all footnote prerequisites are satisfied.
• Ensure that the WebSphere Application Server Monitoring Extension distribution files are available on the agent machine.
• It is possible to monitor a WebSphere Application Server environment remotely from a dedicated agent machine. This requires a WAS Application Client installation on the dedicated agent machine that is the same version as the WAS server. The WAS Administrative Client JAR files must be copied from the WAS server to the agent machine (specifically into the WAS Application Client install on the agent machine). The required WAS Administrative Client JAR files are described in the qpwasmon.conf (Windows) or qpwasmon.sh (UNIX) file according to the WAS version being monitored. If a secure connection is required, you need to copy the truststore and keystore files from the WAS server to the agent machine. For assistance in monitoring WebSphere Application Server with the extension running as a thin client (that is, qpwasmon on a separate machine than WebSphere Application Server), contact BMC Support.

To install the WebSphere Application Server monitoring extension on Windows or UNIX 

1. Create a WAS_HOME system variable and set it to the location of the WebSphere Application Server installation. See the operating instructions for setting environment variables. The system might require a restart.

   If the WebSphere Application Server installation directory contains a space (for example, C:\Program Files\WebSphere\AppServer), then define WAS_HOME as C:\progra~1\WebSphere\AppServer.
2. At a command prompt, change to the directory where the TMTM Extensible Agent is installed. Unzip the contents of the distribution file to a subdirectory of the TMTM Extensible Agent directory:
   • For Windows, unzip pkg_windows_qpwasmon.zip
   • For UNIX, unzip pkg_unix_qpwasmon.zip
3. If you are reinstalling or upgrading agents, restore the backup copy of the eaa.xml file.
4. (UNIX only) Use chmod +x filename to make the following files executable:
   
   qpwasmon.sh
   Depending on the monitoring needs other files might need to be executable. The binary files and the *.ksh files for the operating system listed in TMTM Extensible Agent and extension files to distribute must be executable.
5. Edit the ComMQSoftwareWASMonitor.xml file as follows:
   • In the Connection stanza, ensure the value matches the type of the WebSphere Application Server server. Change it if needed. Possible values for this field are:
   1. • SOAP
      • RMI
   • Replace the host and port values with a host name and port of the WebSphere Application Server server. The default ports are:
   1. • WebSphere Application Server base version: SOAP-8880, RMI-2809
      • WebSphere Application Server Network Deployment: SOAP-8879, RMI-9809.
   • If you want to modify the default monitoring level of WebSphere Application Server, then add the SetStatisticSet level="all" setting in the Connection stanza. The available values are:
   1. • all
      • extended
      • basic
        
        See the WebSphere Application Server documentation for details about what is monitored at each level. The default is all.
         
6. If security is not enabled for WebSphere Application Server, skip to step h. Otherwise, uncomment the lines by removing the <!-- and --> symbols.
7. Replace the username and password with the user name and its password with proper access rights.
8. Ensure the paths for the trustStore and keyStore match the environment. Change them if needed. These values point to the keys used for the SSL interaction. The paths correspond to the system where the client is running and can point to the default keystores or you can specify your own.
9. Replace the trustStorePassword and keyStorePassword with the passwords for the trustStore and keyStore. The defaults are WebAS.
10. Save the ComMQSoftwareWASMonitor.xml file.

11. Execute setupCmdLine.bat (Windows) or setupCmdLine.sh (UNIX); note that you must run the script from the WAS instance you are connecting to.
    
    Windows example:
    cd %WAS_HOME%\profiles\profile name\bin
setupCmdLine.bat
    
    UNIX example:
    cd $WAS_HOME/profiles/profile name/bin
setupCmdLine.sh

    Note

    To monitor more than one WebSphere Application Server, duplicate the <Connection> stanza (see the list below) below the current <Connection> stanza and modify each copy to reflect element and attribute values for the added servers.

    Define different port, hostname, user, password and ssl* settings to match the connections settings of the new WAS instance, each connection must be unique.

    
    Connection stanza in ComMQSoftwareWASMonitor.xml
    <Connection class="com".mqsoftware.Extensions.qpwasmon.connection.websphere.WebSphereConnection>
<Property key=type value=SOAP/>
<Property key=host value=localhost/>
<Property key=port value=8880/>
<!--
<Property key=securityEnabled value=true/>
<Property key=username value=wasadmin/>
<Property key=password value=wasadmin/>
<Property key=javax.net.ssl.trustStore value=/WASInstallDir/AppServer/profiles/YourProfile/etc/DummyClientTrustFile.jks/>
<Property key=javax.net.ssl.keyStore value=/WASInstallDir/AppServer/profiles/YourProfile/etc/DummyClientKeyFile.jks/>
<Property key=javax.net.ssl.trustStorePassword value=WebAS/>
<Property key=javax.net.ssl.keyStorePassword value=WebAS/>
-->
<!-- Valid values for the level are all, extended, basic -->
<!-- The default is 'all' -->
<!-- NOTE: Setting this to anything other than all will -->
<!-- keep some values from showing up in the -->
<!-- Management Console -->
<SetStatisticSet level="all"/>
<QueryExp>
<ObjectName name=:type=Perf,/>
</QueryExp>
</Connection>



12. (UNIX only) Enter echo $WAS_HOME to verify that the WAS_HOME environment variable is set. If it is not, set it to the root directory of the WebSphere Application Server installation. See the operating instructions for setting environment variables. The system might require a restart.
13. If your installation monitors a large number of objects and attributes, your system might experience a significant increase in resource requirements. 
14. Edit file qpwasmon.conf (Windows) or qpwasmon.sh (UNIX) as directed in the files themselves.
15. Start the WebSphere Application Server.
16. To set the TMTM Topic Service host name and port, enter:
    • For Windows, enter qpwasmon --ts-host host --ts-port port
    • For UNIX, enter ./qpwasmon.sh --ts-host host --ts-port port
      
      where:
      host is either the host name or the IP address
      port is the port number, default 15001. Needed in the command only if the port is not the default.
17. At a command prompt, enter qpea --status to ensure that the agent is running. If it is not running, enter qpea --start.
18. (Windows only) Change to the directory where you extracted the WebSphere Application Server monitoring extension files and enter qpwasmon --install to install the WebSphere Application Server monitoring extension as a Windows service.
19. To start the WebSphere Application Server Monitoring Extension, you must be in the same directory as qpwasmon.bat (Windows) or qpwasmon.sh (UNIX) and:
    • For Windows, enter qpwasmon --start
    • For UNIX, enter ./qpwasmon.sh --start
20. (Optional) Set the sample interval by opening framework.props in a text editor and changing the line:
    
    com.bmc.mmpa.eaapi.framework.waitstate.SampleInterval=60
    This sets the sample interval to 60 seconds, the default.
21. (Optional) Set the logging level by opening and modifying the qplog.props file. The options are info, debug, and warn. Info and warn can be used every day, but debug contains a large amount of data and might not be useful for continual logging.

Where to go from here

• To control and configure the extension, see Running the WebSphere Application Server monitoring extension.

• To define an alternative JRE, see Defining alternative JREs for Java extensions.
• To view uninstall instructions, see Uninstalling the WebSphere Application Server monitoring extension.

Installing the WebSphere Application Server monitoring extension on i5/OS 

Before you begin

• See Supported middleware monitoring technologies for performance and availability to verify the intended monitored technology is supported and that all footnote prerequisites are satisfied.
• Ensure that the WebSphere Application Server Monitoring Extension distribution files are available on the agent machine.

To install the WebSphere Application Server monitoring extension on i5/OS 

1. Create a WAS_HOME system variable and set it to the location of the WebSphere Application Server installation. The WAS_HOME variable must be set to the directory where WebSphere Application Server is installed.

   If the WebSphere Application Server installation directory contains a space (for example, C:\Program Files\WebSphere\AppServer), then define WAS_HOME as C:\progra~1\WebSphere\AppServer.
2. Unzip pkg_os400_qpwasmon.zip to a library
3. If you are reinstalling or upgrading agents, restore the backup copy of the eaa.xml file.
4. Change to the directory where you extracted the WebSphere Application Server agent files.
5. Using a text editor, edit qpwasmon.sh edit JAVA_HOME variable so that it points to the Java installation.
   
   If the path contains multiple versions of Java, then the supported version must appear before any older, unsupported versions.
   JAVA_HOME=/QIBM/ProdData/Java400/jdk14/
6. Edit the ComMQSoftwareWASMonitor.xml file as follows:
   1. In the Connection stanza, ensure the value matches the type of the WebSphere Application Server server. Change it if needed. The possible values for this field are:
      • SOAP
      • RMI
   2. Replace the host and port values with a host name and port of the WebSphere Application Server server. The default ports are:
      • WebSphere Application Server base version: SOAP-8880, RMI-2809
      • WebSphere Application Server Network Deployment: SOAP-8879, RMI-9809.
   3. If you want to modify the default monitoring level of WebSphere Application Server, then add the SetStatisticSet level="all" setting in the Connection stanza. The available values are:
      • all
      • extended
      • basic
        
        See the WebSphere Application Server documentation for details about what is monitored at each level. The default is all.
   4. If your installation monitors a large number of objects and attributes, your system might experience a significant increase in resource requirements. See Running the WebSphere Application Server monitoring extension.
   5. If security is not enabled for WebSphere Application Server, skip to step h. Otherwise, uncomment the lines in by removing the <!-- and --> symbols.
   6. Replace the username and password with the user name and its password with proper access rights.
   7. Ensure the paths for the trustStore and keyStore match the environment. Change them if needed. These values point to the keys used for the SSL interaction. The paths correspond to the system where the client is running and can point to the default keystores or you can specify your own.
   8. Replace the trustStorePassword and keyStorePassword with the passwords for the trustStore and keyStore. The defaults are WebAS.

   9. Save the ComMQSoftwareWASMonitor.xml file.

      Note

      To monitor more than one WebSphere Application Server, duplicate the <Connection> stanza (see the list below) below the current <Connection> stanza and modify each copy to reflect element and attribute values for the added servers. Do this for each WebSphere Application Server server you want to monitor.

      
      Connection stanza in ComMQSoftwareWASMonitor.xml
      <Connection class="com".mqsoftware.Extensions.qpwasmon.connection.websphere.WebSphereConnection>
<Property key=type value=SOAP/>
<Property key=host value=localhost/>
<Property key=port value=8880/>
<!--
<Property key=securityEnabled value=true/>
<Property key=username value=wasadmin/>
<Property key=password value=wasadmin/>
<Property key=javax.net.ssl.trustStore value=/WASInstallDir/AppServer/profiles/YourProfile/etc/DummyClientTrustFile.jks/>
<Property key=javax.net.ssl.keyStore value=/WASInstallDir/AppServer/profiles/YourProfile/etc/DummyClientKeyFile.jks/>
<Property key=javax.net.ssl.trustStorePassword value=WebAS/>
<Property key=javax.net.ssl.keyStorePassword value=WebAS/>
-->
<!-- Valid values for the level are all, extended, basic -->
<!-- The default is 'all' -->
<!-- NOTE: Setting this to anything other than all will -->
<!-- keep some values from showing up in the -->
<!-- Management Console -->
<SetStatisticSet level="all"/>
<QueryExp>
<ObjectName name=:type=Perf,/>
</QueryExp>
</Connection>



7. Edit file qpwasmon.sh as directed in the file itself.

8. Start the WebSphere Application Server.
9. To set the TMTM Topic Service host name and port, enter:
   • For Windows, enter qpwasmon --ts-host host
   • For UNIX, enter ./qpwasmon.sh --ts-host host
     
     where:
     host is either the host name or the IP address
     port is the port number, default 15001. Needed in the command only if the port is not the default.
10. Enter . WASInstallDir/bin/setupClient to configure your WebSphere Application Server environment. WASInstallDir is the location of your WebSphere Application Server installation.
11. Enter . WASInstallDir/bin/setupCmdLine to further configure your WebSphere Application Server environment. WASInstallDir is the location of your WebSphere Application Server installation.
12. At a command prompt, enter wrkactjob to ensure that the agent is running. If it is not running, start it; from a Qshell, enter qpwasmon.sh --start.

Where to go from here

• To control and configure the extension, see Running the WebSphere Application Server monitoring extension.

• To define an alternative JRE, see Defining alternative JREs for Java extensions.
• To view uninstall instructions, see Uninstalling the WebSphere Application Server monitoring extension.