Running the IBM WebSphere Liberty monitoring extension

The MainView Middleware Monitor (MVMM ) IBM WebSphere Liberty monitoring extension uses Java Management Extension (JMX) interface to gather monitoring information from IBM WebSphere Liberty servers. The extension periodically (customizable interval) polls the JMX monitoring interface and retrieves configuration and statistical information from the monitored Liberty server.

The JMX configuration and monitoring capabilities of Liberty are documented on the IBM website.

As this information is gathered on a regular sample interval similar to every other MVMM  extension, all the features of the MVMM  product are available to Liberty users.

Related topics

Agent-and-Extension-Preferences

Viewing IBM WebSphere Liberty information

After you connect the extension to a Liberty server, information from the server appears under a WebSphere Liberty JMX Connection in the Monitor Console physical tree.

Discovered Servers and subordinate objects are displayed in the object repository.

Configuring the IBM WebSphere Liberty server for monitoring

The MVMM  IBM WebSphere Liberty extension uses  interface to gather monitoring information from the server.
To allow remote monitoring using the JMX REST connector, the Liberty server must have the following features enabled in the Liberty server.xml file:
   

restConnector-2.0
monitor-1.0

(Optional) Enabling this feature might provide additional monitoring information.

requestTiming-1.0

(Optional) Enabling this setting might provide additional monitoring information.
   

<monitor enableTraditionalPMI="true"/>

For monitoring configuration details, see IBM-WebSphere-Liberty-Policies.

You must configure security in the Liberty server for JMX access. The user requires administrator-role access to perform the security configuration. If the appSecurity-2.0 or appSecurity-3.0 features are configured, a user with reader-role access is sufficient for monitoring.

Only users with administrator-role access can monitor the state of Messaging Engines in the Liberty server. 

Configuring the IBM WebSphere Liberty monitoring extension on Windows and UNIX

This section describes how to configure the MVMM  IBM WebSphere Liberty monitoring extension to connect to a Liberty server.

To configure the IBM WebSphere Liberty monitoring extension on Windows

You must configure TLS to access the Liberty REST connector.

You can configure TLS by setting extension preferences or by setting properties in the extension configuration file. However, the settings provided in the configuration file is prioritized.

To configure TLS server authentication in the liberty_mon extension:

  1. Provide a Java KeyStore file configured with the trust materials for the Liberty server being monitored.

  2. Edit the liberty_mon.conf file and uncomment the following lines and set the TrustStore name and password appropriately. 

    # Set these additional parameters to configure TLS
    # The trust store should contain the certificate used by the Liberty REST connector
    wrapper.java.additional.3=-Djavax.net.ssl.trustStore=liberty.jks
    wrapper.java.additional.4=-Djavax.net.ssl.trustStorePassword=OBF:password

To configure TLS client authentication in the liberty_mon extension:

  1. Provide a Java KeyStore file configured with the key materials for the extension.

  2. Edit the liberty_mon.conf file and uncomment the following lines and set the KeyStore name and password appropriately. 

    # Set these additional parameters to configure TLS for client authentication
    # The key store should contain the client key and certificate, which should
    # be trusted by the Liberty REST connector
    wrapper.java.additional.6=-Djavax.net.ssl.keyStore=client.jks
    wrapper.java.additional.7=-Djavax.net.ssl.keyStorePassword= OBF:password
  3. Restart the extension for the changes to take effect.

To configure the IBM WebSphere Liberty monitoring extension on UNIX

You must configure TLS to access the Liberty REST connector.

You can also configure TLS by setting extension preferences or by setting properties in the extension configuration file. However, the settings provided in the configuration file is prioritized.

To configure TLS server authentication in the liberty_mon extension:

  1. Provide a Java KeyStore file configured with the trust materials for the Liberty server being monitored.

  2. Edit the liberty_mon.sh file and uncomment the following lines and set the TrustStore name and password appropriately.

    # Set these additional parameters to configure TLS
    # The trust store should contain the certificate used by the Liberty REST connector
    EXT_SSL_PARAMS="-Djavax.net.ssl.trustStore=liberty.jks $EXT_SSL_PARAMS"
    EXT_SSL_PARAMS="-Djavax.net.ssl.trustStorePassword=OBF:password $EXT_SSL_PARAMS"

To configure TLS client authentication in the liberty_mon extension:

  1. Provide a Java KeyStore file configured with the key materials for the extension.

  2. Edit the liberty_mon.sh file and uncomment the following lines and set the KeyStore name and password appropriately.

    # Set these additional parameters to configure TLS for client authentication
    # The key store should contain the client key and certificate, which should
    # be trusted by the Liberty REST connector
    EXT_SSL_PARAMS="-Djavax.net.ssl.keyStore=client.jks $EXT_SSL_PARAMS"
    EXT_SSL_PARAMS="-Djavax.net.ssl.keyStorePassword=OBF:password $EXT_SSL_PARAMS"
  3. The extension must be restarted to affect these changes.

Set extension preferences to monitor IBM WebSphere Liberty servers

Extension preferences are used to control the Liberty servers that are available for monitoring.  
A Liberty server has a URL that describes the hostname and port on which JMX monitoring information is available. For example, http://hostName:portNumber.
The Liberty server writes the hostname and port used to the file ${server.output.dir}/logs/state/com.ibm.ws.jmx.rest.address when the Rest connector feature is enabled.

When the URL is provided to the extension, a JMX connection is established, and the server and subordinate objects are discovered and made available for monitoring. The server objects can then be selected for monitoring either explicitly through the MVMM  object repository, or by applying an MVMM  Policy.

For example: Use agentpref to set a URL preference for the server to discover a server on host my-liberty-host, port portNumber.

agentpref --set “WebSphere Liberty Monitor” --pref_path ComBmcLibertyJMXConnection
myServerName URL http://hostName:portNumber JMXUser admin JMXPassword nnn

Important

The name (myServerName in the above example) is applicable only to MVMM , and need not map to any name in the Liberty configuration.

Important

Passwords are encoded by using an encoding process that the extension supports. However, you can provide an encoded value and this value is then re-encoded according to the supported encoding. Supported encodings are: OBF, Base64, Cryptor, and Cloaker.

The supported extension preferences are as follows:

Preference name

Description

Example

URL

(Required) URL for HTTPS endpoint enabled for JMX monitoring.

JMXUser

User ID used for JMX monitoring.
This is required unless certificate authentication is being used.

monitorUser

JMXPassoword

Password used for JMX monitoring.

This can be obfuscated or plaintext.

This is required unless certificate authentication is being used.

nnn

JMXRole

(Optional) Use Administrator or Reader.

Administrator is required to monitor Messaging Engine state.

The default value is Reader.

Administrator

DisableURLHostnameVerification

(Optional) Disables hostname verification for HTTPS URLs.

The default value is false.

false

UseCertificateAuthentication

(Optional) Enables client certification-based authentication.

The default value is false. If the value is set to true, JMXUser and JMXPassword are not required or used.

true

MaxServerWaitTime

(Optional) Milliseconds to wait for server timeouts.

The default value is 30000.

12000

ReadTimeout

(Optional) Milliseconds to wait for server read timeouts.

The default value is 60000.

12000

ServerStatusPollingInterval

(Optional) Milliseconds between polls for server status.

The default is 4000.

30000

WLMEndPoints

(Optional) Comma separated list of workload management endpoints to monitor.

The endpoint format is hostname:portnumber.

host1:1234,host2:4567

TLSProtocol

(Optional) TLS protocol version for HTTPS connections to the Liberty servers.

The default value is TLSv1.3.

TLSv1.3

TrustStore

Filename of Java truststore used to verify HTTPS certificates.
This is required for HTTPS monitoring. A truststore file is required.

The javax.net.ssl.trustStore setting in the extension configuration file takes precedence.

trustStore.pkcs12

TrustStorePassword

Password of Java truststore used to verify HTTPS certificates.
Required for HTTPS monitoring.
This can be obfuscated or used as plain text.

A truststore file is required.

The javax.net.ssl.trustStorePassword setting in the extension configuration file takes precedence.

nnn

TrustStoreType

(Optional) The default is managed by the JRE used for monitoring.

Type of trust store used to verify HTTPS certificates.

The javax.net.ssl.trustStoreType setting in the extension configuration file takes precedence.

pkcs12

KeyStore

Filename of Java keystore used for client certificate authentication.

This is required if the UseCertificateAuthentication value is true.

The javax.net.ssl.keyStore setting in the extension configuration file takes precedence.

keyStore.pkcs12

KeyStorePassword

Password of Java keystore used for client certificate authentication.

This is required if the UseCertificateAuthentication value is true.

The javax.net.ssl.keyStorePassword setting in the extension configuration file takes precedence.

nnn

KeyStoreType

(Optional) Type of keystore used for client certificate authentication.

The default value is managed by the JRE used for monitoring.

The javax.net.ssl.keyStoreType setting in the extension configuration file takes precedence.

pkcs12

Selective Monitoring of IBM WebSphere Liberty servers

You can use the MVMM  object repository to select IBM WebSphere Liberty servers and subordinate objects for monitoring. Use the object repository tab in the Monitor Console to explore the server objects and monitoring options, or use the repomgr command line tool to control monitoring options.
You can use the MVMM  Monitoring Policies to automate the selection of servers and subordinate objects for monitoring. Review the IBM WebSphere Liberty technology sample policies provided in the Monitor Console for examples.
IBM WebSphere Liberty allows for selective registration of JMX MBeans in the server itself. This can be an effective way to exclude selected objects from JMX monitoring entirely.

Controlling the IBM WebSphere Liberty monitoring extension on Windows and UNIX

This section describes how to start, stop, and otherwise run the MVMM  IBM WebSphere Liberty monitoring extension.
Perform the following steps for each of the following procedures:

  1. Open a command prompt and change directories to the liberty directory that were created when the monitoring extension was installed.
  2. Enter the monitoring extension command followed by the required parameter.

To get usage information from the monitoring extension

  • For Windows, enter: liberty_mon.bat --help
  • For UNIX, enter: liberty_mon.sh -–help

To check if the monitoring extension is running

  • For Windows, enter: liberty_mon.bat --status
  • For UNIX, enter: liberty_mon.sh –-status

To start the monitoring extension

  • For Windows, enter: liberty_mon.bat --start
  • For UNIX, enter: liberty_mon.sh –-start

To stop the monitoring extension

  • For Windows, enter: liberty_mon.bat --stop
  • For UNIX, enter: liberty_mon.sh –-stop

To install the monitoring extension as a Windows service

  • For Windows, enter: liberty_mon.bat --install

To remove the monitoring extension as a Windows service

  • For Windows, enter: liberty_mon.bat --remove

To run the monitoring extension in console mode

  • For Windows, enter: liberty_mon.bat --console
  • For UNIX, enter: liberty_mon.sh --console

Troubleshooting the IBM WebSphere Liberty monitoring extension

This section describes the steps necessary to switch on monitoring extension logging for BMC Support.

To switch on logging for the IBM WebSphere Liberty monitoring extension

  1. Edit the qplog.props file, found in the following locations:
    • Windows: <AGENT INSTALL>\liberty
    • UNIX: <AGENT INSTALL>/liberty
  2. Change the following lines:

    • From

      To

      log4j.logger.com.bmc.mmpa.ext.framework.treedump.sample.send=info
      log4j.logger.com.bmc.mmpa.ext.framework.treedump.sample.send=debug
      log4j.logger.com.mqsoftware.Extensions.jmx.JMXFrameworkExtension=debug=info
      log4j.logger.com.mqsoftware.Extensions.jmx.JMXFrameworkExtension=debug=debug
      log4j.appender.R.MaxFileSize=5MB
      log4j.appender.R.MaxFileSize=50MB
  3. Restart the monitoring extension.
  4. Send in the log, which is found in the following locations to BMC Support:
    • Windows: <AGENT_INSTALL>\liberty\liberty_mon.log
    • UNIX: <AGENT_INSTALL/liberty\liberty_mon.log

 

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