# 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:

1. login to a certain web application

2. Execute an action while being logged in

3. 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 Sequence Parameter
Parameter Description Required Default

`name`

The name of the page-sequence. (Is this relevant/used?)

optional

`-`

`method`

HTTP method for example GET or POST

`-`

`-`

`http-version`

HTTP protocol version number, 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 virtual host field in HTTP header. 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) `-` `-` `path` The relative URL to call in the request. required `-` `scheme` Define the URL scheme as `http` or `https` optional `http` `user-info` Set user info field in the HTTP header `-` `-` `host` Set host field in HTTP header optional `IP interface address of the service` `requireIPv6` Communication requires a connection to an IPv6 address. (`true` or `false`) `-` `-` `requireIPv4` Communication requires a connection to an IPv4 address. (`true` or `false`) `-` `-` `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` Port of the web server connecting to optional `80` `query` ?? `-` `-` `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. `-` `-` `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.

`-`

`-`

`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.

`-`

`-`

`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.

`-`

`-`

`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="page-sequence">
<page-sequence>
port="8980"
<page path="/opennms/j_spring_security_check"
port="8980"
method="POST">
</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>

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="page-sequence">
<page-sequence>
<page scheme="http"
host="ecomm.example.com"
port="80"
virtual-host="ecomm.example.com"
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>

``````<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"
</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>

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="ds-name" value="overall"/>
<parameter key="page-sequence">
<page-sequence>