
[[poller-http-monitor]]
= HttpMonitor
:description: Learn about the HttpMonitor in OpenNMS {page-component-title} that tests the response of an HTTP server on a specific HTTP GET command.

The HTTP monitor tests the response of an HTTP server on a specific HTTP GET command.
During the poll, the monitor attempts to connect on the specified port(s).
The monitor can test web servers on multiple ports.
By default, it makes the test against ports 80, 8080, and 8888.
If the connection is successful, an HTTP GET request is sent to the interface.
The response is parsed and a return code extracted and verified.

== Monitor facts

[cols="1,7"]
|===
| Class Name
| `org.opennms.netmgt.poller.monitors.HttpMonitor`
|===

== Configuration and use

.Optional monitor-specific parameters for the HttpMonitor
[options="header"]
[cols="1,3,2"]
|===
| Parameter
| Description
| Default

| basic-authentication kbd:[{}]
| Authentication credentials to perform basic authentication. +
Credentials should comply to http://www.rfc-editor.org/rfc/rfc1945.txt[RFC1945], section
11.1, without the Base64 encoding part, and be a string made of the concatenation of: +
1- the user ID; +
2- a colon; +
3- the password. +
`basic-authentication` takes precedence over the user and password parameters.
|n/a

| header[0-9]+
| Additional headers to send with the request. +
Example of valid parameter names are +
`header0`, `header1`, and `header180`.
`header`is not a valid parameter name.
| n/a

| host-name
| Specify the `host` header value to include in the request.
| n/a

| nodelabel-host-name
| If the host-name parameter isn't set and the resolve-ip parameter is set to false, then {page-component-title} uses the node's label to set the `host` header value if this parameter is set to true.
Otherwise, {page-component-title} falls back using the node interface's IP address as `host` header value.
| false

| password kbd:[{}]
| Specifies the password to use.
Use this parameter with the user parameter to perform basic authentication.
The user and password parameters are ignored when the basic-authentication parameter is defined.
| empty string

| port
| A list of TCP ports to try to connect to.
| 80,8080,8888

| retry
| Number of attempts to get a valid HTTP response/response-text.
| 0

| resolve-ip
| If the host-name parameter is not set and this parameter is set to true, {page-component-title} uses DNS to resolve the node interface's IP address, and uses the result to set the Host header's value.
When set to false and the host-name parameter is not set, {page-component-title} tries to use the nodelabel-host-name parameter to set the Host header's value.
| false

| response
| A comma-separated list of acceptable HTTP response code ranges.
Example: 200-202,299
| If the url parameter is set to `/`, the default value for this parameter is 100-499; otherwise, it is 100-399.

| response-text
| Text to look for in the response body.
This will be matched against every line, and it will be considered a success at the first match.
If there is a `~` at the beginning of the parameter, the rest of the string is used as a regular expression pattern match; otherwise, the match will be a substring match.
The regular expression match is anchored at the beginning and end of the line, so you will likely need to put a `.*` on both sides of your pattern unless you are going to match on the entire line.
| n/a

| url kbd:[{}]
| URL to retrieve via the HTTP GET command.
| `/`

| user kbd:[{}]
| Specifies the user ID to use.
Use this parameter with the password parameter to perform basic authentication.
The user and password parameters are ignored when the basic-authentication parameter is defined.
| n/a

| user-agent kbd:[{}]
| Specifies the user-agent HTTP header.
(Also see http://www.rfc-editor.org/rfc/rfc2616.txt[RFC2616], section 14.43.)
| OpenNMS HttpMonitor

| verbose
| When set to true, full communication between client and the webserver will be logged (with a log level of `DEBUG`).
| n/a
|===

kbd:[{}] _indicates the parameter supports <<reference:service-assurance/introduction.adoc#ref-service-assurance-monitors-placeholder-substitution-parameters, placeholder substitution>>._

This monitor implements the <<reference:service-assurance/introduction.adoc#ref-service-assurance-monitors-common-parameters, Common Configuration Parameters>>.

== Examples

[source, xml]
----
<!-- Test HTTP service on port 80 only -->
<service name="HTTP" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="2"/> <1>
  <parameter key="timeout" value="3000"/> <2>
  <parameter key="port" value="80"/> <3>
  <parameter key="url" value="/"/> <4>
</service>

<!-- Test for virtual host opennms.com -->
<service name="OpenNMSdotCom" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="1"/> <1>
  <parameter key="timeout" value="3000"/> <2>
  <parameter key="port" value="80"/> <3>
  <parameter key="host-name" value="opennms.com"/> <5>
  <parameter key="url" value="/solutions"/> <4>
  <parameter key="response" value="200-202,299"/> <6>
  <parameter key="response-text" value="~.*[Cc]onsulting.*"/> <7>
</service>

<!-- Test for instance of OpenNMS running -->
<service name="OpenNMS-129" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="1"/> <1>
  <parameter key="timeout" value="3000"/> <2>
  <parameter key="port" value="8080"/> <3>
  <parameter key="url" value="/opennms/event/list"/> <4>
  <parameter key="basic-authentication" value="admin:admin"/> <8>
  <parameter key="response" value="200"/> <9>
</service>

<!-- Test for instance of OpenNMS with parameter substitution in basic-authentication parameter -->
<service name="OpenNMS-22" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="1"/> <1>
  <parameter key="timeout" value="3000"/> <2>
  <parameter key="port" value="8080"/> <3>
  <parameter key="url" value="/opennms/event/list"/> <4>
  <parameter key="basic-authentication" value="{username}:{password}"/> <8>
  <parameter key="response" value="200"/> <9>
</service>
<monitor service="HTTP" class-name="org.opennms.netmgt.poller.monitors.HttpMonitor" /> <10>
<monitor service="OpenNMSdotCom" class-name="org.opennms.netmgt.poller.monitors.HttpMonitor" /> <10>
<monitor service="OpenNMS-129" class-name="org.opennms.netmgt.poller.monitors.HttpMonitor" /> <10>
<monitor service="OpenNMS-22" class-name="org.opennms.netmgt.poller.monitors.HttpMonitor" /> <10>
----
<1> Number of attempts to test a service’s status.
<2> Timeout for the `isReachable` method, in milliseconds.
<3> A list of TCP ports to try to connect to.
<4> URL to retrieve via the HTTP *GET* command.
<5> Specifies the user ID to use.
<6> Specifies the password to use.
<7> Text to look for in the response body.
<8> Authentication credentials to perform basic authentication.
<9> A comma-separated list of acceptable HTTP response code ranges.
<10> Required *monitor* section for each service.

== Test filtering proxies with HttpMonitor

If a filtering proxy server is set up to allow retrieval of some URLs but deny others, the HttpMonitor can verify this behavior.

As an example, a proxy server runs on TCP port 3128 and serves http://www.opennms.org/ but never http://www.tiktok.com/.
To test this behavior, configure the HttpMonitor as follows:

[source, xml]
----
<service name="HTTP-Allow-opennms.org" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="1"/> <1>
  <parameter key="timeout" value="3000"/> <2>
  <parameter key="port" value="3128"/> <3>
  <parameter key="url" value="http://www.opennms.org/"/> <4>
  <parameter key="response" value="200-399"/> <5>
</service>

<service name="HTTP-Block-tiktok.com" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="1"/> <1>
  <parameter key="timeout" value="3000"/> <2>
  <parameter key="port" value="3128"/> <3>
  <parameter key="url" value="http://www.tiktok.com/"/> <4>
  <parameter key="response" value="400-599"/> <5>
</service>

<monitor service="HTTP-Allow-opennms.org" class-name="org.opennms.netmgt.poller.monitors.HttpMonitor"/> <6>
<monitor service="HTTP-Block-tiktok.com" class-name="org.opennms.netmgt.poller.monitors.HttpMonitor"/> <6>
----
<1> Number of attempts to test a service’s status.
<2> Timeout for the *isReachable* method, in milliseconds.
<3> A list of TCP ports to try to connect to.
<4> URL to retrieve via the HTTP *GET* command.
<5> A comma-separated list of acceptable HTTP response code ranges.
<6> Required *monitor* section for each service.

