PageSequenceMonitor

The PageSequenceMonitor (PSM) lets OpenNMS monitor web applications. This monitor has several configuration options regarding IPv4, IPv6, and how to deal with name resolution. To add flexibility, the node label and IP address can be passed as variable into the monitor. This lets you run the monitor with node dependent configuration. Beyond testing a web application with a single URL, it can also test a path through a web application. A test path through an web application can look like this:

login to a certain web application
Execute an action while being logged in
Log off

The service is considered as up if all this is working ok. If there’s an error somewhere, your application will need attention and the service changes the state to down.

Monitor Facts

Class Name

org.opennms.netmgt.poller.monitors.PageSequenceMonitor

Remote Enabled

true

Configuration and Use

The configuration for this monitor consists of several parts. First is the overall configuration for retries and timeouts. These parameters are global for the whole path through the web application.

Figure 1. Configuration overview of the PSM

The overall layout of the monitor configuration is more complex. Additionally, it is possible to configure a page sequence containing a path through a web application.

Table 1. Monitor parameters for the PageSequenceMonitor
Parameter	Description	Required	Default value
`retry`	The number of retries per page.	optional	`0`
`strict-timeout`	Defines a timer to wait before a retry attempt is made. It is only used if at least one (1) retry is configured. If `retry >= 1` and `strict-timeout` is `true` the next attempt is delayed and the Poller Daemon waits `NOW - InitialAttempt ms + Timeout ms`. With `strict-timout = false` the next attempt is started right after a failure.	optional	`false`
`page-sequence`	Definition of the page-sequence to execute, see table with Page Sequence Parameter	required	`-`
`sequence-retry`	The retry parameter for the entire page sequence.	optional	`0`
`use-system-proxy`	Should the system wide proxy settings be used? The system proxy settings can be configured via system-properties/introduction.adoc#ga-opennms-system-properties[system properties	optional	`false`

This monitor implements the Common Configuration Parameters.

Table 2. Page Parameter
Parameter	Description	Required	Default
`name`	The name of the page-sequence.	optional	`-`
`method`	HTTP method (GET or POST)	optional	`-`
`http-version`	HTTP protocol version (0.9, 1.0 or 1.1)	optional	`HTTP/1.1`
`user-agent`	Set the user agent field in HTTP header to identify the OpenNMS monitor.	optional	`OpenNMS PageSequenceMonitor (Service name: "${SERVICE NAME}")`
`virtual-host`	Set the host field in HTTP header. Useful in cases where one server hosts multiple sites. In case of an HTTPS request, this is also the virtual domain to send as part of the TLS negotiation, known as server name indication (SNI) (See: RFC3546 section 3.1.)	optional	`-`
`path`	The relative URL to call in the request. Any query string content after a `?` should be part of the `query` parameter.	required	`-`
`scheme`	Define the URL scheme as `http` or `https`.	optional	`http`
`user-info`	Set user info field in the HTTP header. Colon-separated credentials such as `USERNAME:PASSWORD`.	optional	`-`
`host`	Set the IP or FQDN of destination host for the request.	optional	`IP interface address of the service`
`requireIPv6`	Communication requires a connection to an IPv6 address. (`true` or `false`)	optional	`-`
`requireIPv4`	Communication requires a connection to an IPv4 address. (`true` or `false`)	optional	`-`
`disable-ssl-verification`	Enable or disable SSL certificate verification for HTTPS tests. Please use this option carefully, for self-signed certificates import the CA certificate in the JVM and don’t just disable it.	optional	`false`
`port`	Host port number to use when connecting.	optional	`80`
`query`	Value to concatenate with a `?` after the path parameter.	optional	`-`
`failureMatch`	Text to look for in the response body. This is a Regular Expression matched against every line, and it will be considered a failure at the first match and sets the service with this monitor Down.	optional	`-`
`failureMessage`	The failure message is used to construct the reason code. `${\n}` values may be used to pull information from matching groups in the `failureMatch` regular expression.	optional	`-`
`successMatch`	Text to look for in the response body. This is a Regular Expression matched against every line, and it will be considered a success at the first match and sets the service with this monitor Up.	optional	`-`
`locationMatch`	The relative URL which must be loaded for the request to be considered successful.	optional	`-`
`response-range`	Range for allowed HTTP error codes from the response.	optional	`-`
`session-variable`	Assign the value of a regex match group to a session variable with a user-defined name. The match group is identified by number and must be zero or greater.	optional	`-`
`response-range`	A comma-separated list of acceptable HTTP response code ranges (`200-202,299`).	optional	`100-399`

If you set requireIPv4 and requireIPv6 false, the host IP for connection will be resolved from system name resolver and the associated IP address from the IP interface is ignored.

Table 3. Variables which can be passed in the configuration
Variable	Description
`${nodelabel}`	Nodelabel of the node the monitor is associated to.

Session variables

It is possible to assign strings from a retrieved page to variables that can be used in page parameters later in the same sequence. First, specify one or more capturing groups in the successMatch expression (see Java Class Pattern for more information on regular expressions in Java). The captured values can then be assigned to variable names by using the session-variable parameter, and used in a later page load.

Per-page response times

It is possible to collect response times for individual pages in a sequence. To use this functionality, a ds-name attribute must be added to each page whose load time should be tracked. The response time for each page will be stored in the same RRD file specified for the service via the rrd-base-name parameter under the specified datasource name.

You will need to delete existing RRD files and let them be recreated with the new list of datasources when you add a ds-name attribute to a page in a sequence that is already storing response time data.

Examples

The following example shows how to monitor the OpenNMS web application using several mechanisms. It first does an HTTP GET of ${ipaddr}/opennms (following redirects as a browser would) and then checks to ensure that the resulting page has the phrase Password on it. Next, a login is attempted using HTTP POST to the relative URL for submitting form data (usually, the URL which the form action points to). The parameters (j_username and j_password) indicate the form’s data and values to be submitted. Furthermore a custom header (foo) is set for demonstration purposes. After getting the resulting page, first the expression specified in the page’s failureMatch attribute is verified, which when found anywhere on the page indicates that the page has failed. If the failureMatch expression is not found in the resulting page, then the expression specified in the page’s successMatch attribute is checked to ensure it matches the resulting page. If the successMatch expression is not found on the page, then the page fails. If the monitor was able to successfully login, then the next page is processed. In the example, the monitor navigates to the Event page, to ensure that the text Event Queries is found on the page. Finally, the monitor calls the URL of the logout page to close the session. By using the locationMatch parameter, it is verified that the logout was successful and a redirect was triggered.

Each page is checked to ensure its HTTP response code fits into the response-range, before the failureMatch, successMatch, and locationMatch expressions are evaluated.

Configuration to test the login to the OpenNMS Web application

<service name="OpenNMS-Web-Login" interval="30000" user-defined="true" status="on">
  <parameter key="retry" value="1"/>
  <parameter key="timeout" value="5000"/>
  <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response"/>
  <parameter key="ds-name" value="opennmslogin"/>
  <parameter key="page-sequence">
    <page-sequence>
      <page path="/opennms/login.jsp"
            port="8980"
            successMatch="Password" />
      <page path="/opennms/j_spring_security_check"
            port="8980"
            method="POST">
        <parameter key="j_username" value="admin"/>
        <parameter key="j_password" value="admin"/>
        <header name="foo" value="bar"/>
      </page>
      <page path="/opennms/index.jsp"
            port="8980"
            successMatch="Log Out" />
      <page path="/opennms/event/index"
            port="8980" successMatch="Event Queries" />
      <page path="/opennms/j_spring_security_logout"
            port="8980"
            method="POST"
            response-range="300-399"
            locationMatch="/opennms" />
    </page-sequence>
  </parameter>
</service>

<monitor service="OpenNMS-Web-Login" class-name="org.opennms.netmgt.poller.monitors.PageSequenceMonitor"/>

Test with mixing HTTP and HTTPS in a page sequence

<service name="OpenNMS-Web-Login" interval="30000" user-defined="true" status="on">
  <parameter key="retry" value="1"/>
  <parameter key="timeout" value="5000"/>
  <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response"/>
  <parameter key="ds-name" value="opennmslogin"/>
  <parameter key="page-sequence">
    <page-sequence>
      <page scheme="http"
            host="ecomm.example.com"
            port="80"
            path="/ecomm/jsp/Login.jsp"
            virtual-host="ecomm.example.com"
            successMatch="eComm Login"
            timeout="10000"
            http-version="1.1"/>
      <page scheme="https"
            method="POST"
            host="ecomm.example.com" port="443"
            path="/ecomm/controller"
            virtual-host="ecomm.example.com"
            successMatch="requesttab_select.gif"
            failureMessage="Login failed: ${1}"
            timeout="10000"
            http-version="1.1">
        <parameter key="action_name" value="XbtnLogin"/>
        <parameter key="session_timeout" value=""/>
        <parameter key="userid" value="EXAMPLE"/>
        <parameter key="password" value="econ"/>
      </page>
      <page scheme="http"
            host="ecomm.example.com" port="80"
            path="/econsult/controller"
            virtual-host="ecomm.example.com"
            successMatch="You have successfully logged out of eComm"
            timeout="10000" http-version="1.1">
        <parameter key="action_name" value="XbtnLogout"/>
      </page>
    </page-sequence>
  </parameter>
</service>

<monitor service="OpenNMS-Web-Login" class-name="org.opennms.netmgt.poller.monitors.PageSequenceMonitor"/>

Test login with dynamic credentials using session variables

<service name="OpenNMS-Web-Login" interval="30000" user-defined="true" status="on">
  <parameter key="retry" value="1"/>
  <parameter key="timeout" value="5000"/>
  <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response"/>
  <parameter key="ds-name" value="opennmslogin"/>
  <parameter key="page-sequence">
    <page-sequence name="opennms-login-seq-dynamic-credentials">
      <page path="/opennms"
            port="80"
            virtual-host="demo.opennms.org"
            successMatch="(?s)User:.*<strong>(.*?)</strong>.*?Password:.*?<strong>(.*?)</strong>">
        <session-variable name="username" match-group="1" />
        <session-variable name="password" match-group="2" />
      </page>
      <page path="/opennms/j_acegi_security_check"
            port="80"
            virtual-host="demo.opennms.org"
            method="POST"
            failureMatch="(?s)Your log-in attempt failed.*Reason: ([^<]*)"
            failureMessage="Login Failed: ${1}"
            successMatch="Log out">"
        <parameter key="j_username" value="$\{username\}" />
        <parameter key="j_password" value="${password}" />
      </page>
      <page path="/opennms/event/index.jsp"
            port="80"
            virtual-host="demo.opennms.org"
            successMatch="Event Queries" />
      <page path="/opennms/j_acegi_logout"
            port="80"
            virtual-host="demo.opennms.org"
            successMatch="logged off" />
    </page-sequence>
  </parameter>
</service>

<monitor service="OpenNMS-Web-Login" class-name="org.opennms.netmgt.poller.monitors.PageSequenceMonitor"/>

<service name="OpenNMS-Demo-Login" interval="300000" user-defined="true" status="on">
  <parameter key="page-sequence">
    <page-sequence>
      <page path="/opennms"
            port="80"
            virtual-host="demo.opennms.org"
            successMatch="(?s)User:.*<strong>(.*?)</strong>.*?Password:.*?<strong>(.*?)</strong>">
        <session-variable name="username" match-group="1" />
        <session-variable name="password" match-group="2" />
      </page>
      <page path="/opennms/j_acegi_security_check"
            port="80"
            virtual-host="demo.opennms.org"
            method="POST"
            successMatch="Log out">"
        <parameter key="j_username" value="$\{username\}" />
        <parameter key="j_password" value="${password}" />
      </page>
      <page path="/opennms/j_acegi_logout"
            port="80"
            virtual-host="demo.opennms.org"
            successMatch="logged off" />
    </page-sequence>
  </parameter>
</service>

<monitor service="OpenNMS-Demo-Login" class-name="org.opennms.netmgt.poller.monitors.PageSequenceMonitor"/>

Example with per-page response times

<service name="OpenNMS-Login" interval="300000" user-defined="false" status="on">
  <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response"/>
  <parameter key="rrd-base-name" value="opennmslogin"/>
  <parameter key="ds-name" value="overall"/>
  <parameter key="page-sequence">
    <page-sequence>
      <page path="/opennms/acegilogin.jsp"
            port="8980"
            ds-name="login-page"/>
      <page path="/opennms/event/index.jsp"
            port="8980"
            ds-name="event-page"/>
    </page-sequence>
  </parameter>
</service>

<monitor service="OpenNMS-Login" class-name="org.opennms.netmgt.poller.monitors.PageSequenceMonitor"/>