Running the IBM DataPower monitoring extension

DataPower is an appliance designed to act as an Enterprise Service Bus (ESB) that takes in messages from various sources (HTTP, MQ, TIBCO EMS, WAS SIB). You can configure Policies to handle each message type. Each Policy has a Request Rule and can have a Response Rule. The Request Rule can Accept or Reject Messages, apply transformations (XSL stylesheets) to the data, and route them to one or more targets (HTTP, MQ, EMS, SIB, File, IMSConnect, Database). Each such Policy is deployed to a given DataPower Domain.

For information on installing this extension on the various supported platforms, see Installing-the-IBM-DataPower-monitoring-extension.

Note

DataPower is a group of appliances with different functions. Consult the supported platform tables for a list of the supported DataPower appliances.

This section includes:

Related topics

Running-performance-and-availability-monitoring-extensions

Running-application-transaction-tracing-transaction-monitoring-extensions

DataPower monitoring in TMTM

The TrueSight Middleware and Transaction Monitor DataPower extension uses the IBM XML Management Interface to gather monitoring information from XI50/52 DataPower devices. The extension periodically (customizable interval) sends SOAP formatted XML messages over HTTP to the XML Management Interface port of each configured DataPower device. This requires sending one query to gather the device properties and then an additional query for each domain. The response from DataPower is delivered in a similar SOAP formatted XML structure. This interface and the structure of the requests and responses are documented in the IBM DataPower InfoCenter.

As this information is gathered on a regular sample interval similar to every other TrueSight Middleware and Transaction Monitor extension, all the power of the TrueSight Middleware and Transaction Monitor product is immediately available to DataPower TrueSight Middleware and Transaction Monitor extension users.

Key capabilities for IBM DataPower include:

  • Web-accessible performance reports
  • Real-time dashboards displaying the state of DataPower hardware and performance
  • Integrated alerting and notification for DataPower properties and performance
  • Auto-discovery across domains, which eases the user implementation significantly

Viewing DataPower information

Once the agent is connected to the DataPower device any information from the DataPower device appears under the DataPower device node in the Monitor Console physical tree. 

Configuring the DataPower appliance for monitoring by the DataPower extension

The TrueSight Middleware and Transaction Monitor DataPower extension uses the IBM XML Management Interface to gather monitoring information from DataPower devices.

In order to monitor DataPower using TrueSight Middleware and Transaction Monitor with a non-administrative user, the user ID used to access the DataPower Appliance with the TrueSight Middleware and Transaction Monitor DataPower monitoring extension must be a member of a DataPower group with the following permissions:

  • Login to the XML Management Interface for the default domain with read authority:

    deviceIP/default/login/xml-mgmt?Access=r
  • Read authority on all objects in the default domain:

    deviceIP/default/*?Access=r
  • Read authority to all objects on each domain that is to be monitored:

    deviceIP/DomainName/*?Access=r

To enable the DataPower XML Management Interface

  1. Log in to the DataPower WebGUI and go to: Network > Management > XML Management.
  2. Ensure that "Administrative State" is set to "enabled".
  3. Note the address and port that has been configured.
  4. Ensure that SOAP Management URI is selected.
  5. Turn on statistics collection (go to: Control Panel > View Status > Statistics collection).
  6. Click enabled.

Configuring the DataPower monitoring extension on Windows and UNIX

This section describes how to configure the TrueSight Middleware and Transaction Monitor DataPower monitoring extension to connect to the DataPower Appliance.

To configure the DataPower monitoring extension

  1. Edit the file com.bmc.mmpa.ext.datapower.extension.properties in a text editor. The file is located in the following location:
    • Windows: <AGENT INSTALL>\datapower\configuration\services
    • UNIX: <AGENT INSTALL>/datapower/configuration/services

  2. Add the following properties for each DataPower Appliance that you wish to monitor, incrementing the number for each DataPower Appliance you wish to monitor:

    com.bmc.datapower.hostname.1=<Your DataPower Appliance host name>
    com.bmc.datapower.port.1=<Your DataPower Appliance xml management port>
    com.bmc.datapower.username.1=<Your DataPower Appliance monitoring user id>
    com.bmc.datapower.password.1=<Your DataPower Appliance monitoring password> See the Note below.
    com.bmc.datapower.hostname.2=<Your DataPower Appliance host name>
    com.bmc.datapower.port.2=<Your DataPower Appliance xml management port>
    com.bmc.datapower.username.2=<Your DataPower Appliance monitoring user id>
    com.bmc.datapower.password.2=<Your DataPower Appliance monitoring password> See the Note below.

    Note

    The com.bmc.datapower.password property can be obfuscated by using a base64 encoded password and prepending the password with the "B64:" prefix. For example: com.bmc.datapower.password.1=B64:<base64 obfuscated password>

    To use a base64 encoded password, first the mqsusertool utilities on the TrueSight Middleware and Transaction Monitor server machine, then use the output from that utility as the password on agentpref command line.

    Example: Using mqsusertool
    $ mqsusertool --encode –t ActiveDirectory MyPassword

  3. Save the com.bmc.mmpa.ext.datapower.extension.properties file.

To configure the DataPower monitoring extension to use SSL/TLS client authentication

  1. Edit the file com.bmc.mmpa.ext.datapower.extension.properties in a text editor. The file is located in the following location:
    • Windows: <AGENT INSTALL>\datapower\configuration\services
    • UNIX: <AGENT INSTALL>/datapower/configuration/services

  2. Add the following properties for each DataPower Appliance that you wish to monitor, incrementing the number for each DataPower Appliance you wish to monitor:

    com.bmc.datapower.hostname.1=<Your DataPower Appliance host name>
    com.bmc.datapower.port.1=<Your DataPower Appliance xml management port>
    com.bmc.datapower.username.1=<Your DataPower Appliance monitoring user id>
    com.bmc.datapower.password.1=<Your DataPower Appliance monitoring password> (See the Note below)
    com.bmc.datapower.trustStore.1=The path (relative to the working directory of the extension or fully qualified) to a JKS (or JSSE supported) keystore file to be used as a trust store. This keystore should contain certificates that should be trusted by DataPower devices that present them to the extension.
    com.bmc.datapower.trustStorePassword.1 The password to be used to access the trust store. See the Note below.
    com.bmc.datapower.keyStore.1= The path (relative to the working directory of the extension or fully qualified) to a JKS (or JSSE supported) keystore file to be used as the key store. This should contain private key/certificate pairs that are presented to the DataPower server when requested during the SSL handshake.
    com.bmc.datapower.keyStorePassword.1=The password to be used to access the trust store. See the Note below.
    com.bmc.datapower.sslProtocol.1=TLS The protocol used for the secure connection to a DataPower device. This should be "TLS" and should not need to be changed.
    com.bmc.datapower.hostNameVerifier.1=all|browser|strict (The host name verifier to be used when the DataPower device presents its certificate to the extension. "all" indicates that no host name verification should be done, "strict" should be used to strictly verify that the host name matches the CN attribute of the certificate. The highest security is "strict" and your configuration must match accordingly. "browser" should not be used unless directed by BMC Support.)

    Note

    The com.bmc.datapower.trustStorePassword and com.bmc.datapower.keyStorePassword properties can be obfuscated by using a base64 encoded password and prepending the password with the "B64:" prefix. For example:
    com.bmc.datapower.trustStorePassword.1=B64:<base64 obfuscated trust store password>
    com.bmc.datapower.keyStorePassword.1=B64:<base64 obfuscated key store password>

    To use a base64 encoded password, first the mqsusertool utilities on the TrueSight Middleware and Transaction Monitor server machine, then use the output from that utility as the password on the agentpref command line.

    Example: Using mqsusertool
    $ mqsusertool --encode –t ActiveDirectory MyPassword

  3. Save the com.bmc.mmpa.ext.datapower.extension.properties file.

To configure the DataPower monitoring extension to support a new configuration entry

By adding the com.bmc.datapower.deviceVersion property to the configuration/services/com.bmc.mmpa.ext.datapower.extension.properties file, you can set a value to identify the version of the related DataPower device monitored. This entry is only required when monitoring a DataPower device of version 6.x (the lowest version officially supported). It is optional for later versions, i.e. 7.x onwards.

The property setting should be defined as follows for the device profile:

com.bmc.datapower.deviceVersion.1=<Your DataPower Appliance firmware version>

For example, to monitor a DataPower device with firmware version 6.0.2.0, you need to set the following:

com.bmc.datapower.deviceVersion.1=6.0.2.0

Controlling the DataPower monitoring extension on Windows and UNIX

This section describes how to start, stop, and otherwise run the TrueSight Middleware and Transaction Monitor DataPower monitoring extension.

For each of the following procedures, first open a command prompt and change directories to the 'datapower' directory created when installing the monitoring extension. Then enter the monitoring extension command followed by the required parameter.

To get usage information from the monitoring extension

  • In Windows, enter: bin\datapower --help
  • In UNIX, enter: ./bin/datapower -–help

To check if the monitoring extension is running

  • In Windows, enter: bin\datapower --status
  • In UNIX, enter: ./bin/datapower –-status

To start the monitoring extension

  • In Windows, enter: bin\datapower --start
  • In UNIX, enter: ./bin/datapower –-start

To stop the monitoring extension

  • In Windows, enter: bin\datapower --stop
  • In UNIX, enter: ./bin/datapower –-stop

To install the monitoring extension as a Windows service

  • In Windows, enter: bin\datapower --install

To remove the monitoring extension as a Windows service

  • In Windows, enter: bin\datapower --remove

To run the monitoring extension in console mode

  • In Windows, enter: bin\datapower --console
  • In UNIX, enter: bin/datapower --console

Note

When the extension is started in console mode, you are in the console of the Equinox OSGi runtime the extension is running in. This is indicated by the prompt osgi>. If you are familiar with OSGi you can use the OSGi command shell to determine whether all components of the extension have been started properly. To leave the OSGi runtime and to stop the extension enter close.

Troubleshooting the DataPower monitoring extension

This section details the steps necessary to switch on monitoring extension tracing for BMC Support.

To switch on tracing for the DataPower monitoring extension

  1. Edit the org.ops4j.pax.logging file, found in the following locations:
    • Windows: <AGENT INSTALL>\datapower\configuration\services
    • UNIX: <AGENT INSTALL>/datapower/configuration/services
  2. Uncomment this line:

    log4j.rootLogger=debug, R
  3. Comment out this line by placing a # character in front of it:

    log4j.rootLogger=info, R
  4. Restart the DataPower monitoring extension.
  5. Send in the log, which is found in the locations listed below, to BMC Customer Support:
    • Windows: <AGENT_INSTALL>\datapower\logs
    • UNIX: <AGENT_INSTALL/datapower/logs

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*