
[[ga-pollerd-packages]]
= Poller Packages
:description: How to group service configurations into polling packages to define more complex monitoring configurations with {page-component-title}.

You can group service configurations into polling packages to define more complex monitoring configurations.
This allows you to assign different service configurations to nodes.
To assign a polling package to nodes, use the xref:reference:configuration/filters/filters.adoc[filter] syntax.

Each polling package can have its own xref:deep-dive/service-assurance/downtime-model.adoc[Downtime Model] configuration.
You can configure multiple packages, and an interface can exist in more than one package.
This provides great flexibility for determining service levels on a given device.

.Polling package assigned to nodes with rules and filters
[source, xml]
----
<package name="example1"> <1>
  <filter>IPADDR != '0.0.0.0'</filter> <2>
  <include-range begin="1.1.1.1" end="254.254.254.254" /> <3>
  <include-range begin="::1" end="ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff" /> <3>
----

<1> The polling package's unique name.
<2> Base filter on IP address, categories, or asset attributes of nodes based on xref:reference:configuration/filters/rule-formats.adoc[filter rules].
The filter is evaluated first and is required.
This package is used for all IP interfaces that do not have `0.0.0.0` as an assigned IP address and is required.
<3> Allows you to specify if the configuration of services is applied on a range of IP interfaces (IPv4 or IPv6).

Instead of using `include-range`, you can add one or more specific IP interfaces:

[source, xml]
<specific>192.168.1.59</specific>

You can also exclude IP interfaces:

[source, xml]
<exclude-range begin="192.168.0.100" end="192.168.0.104"/>

== Response time configuration

include::../retention.adoc[]

== Service status persistence

By default service monitors store their current service status in RRD files.
This lets you query the current status and the status history.
This feature is enabled by default.
To disable this feature for individual services, add a service parameter to the appropriate services in `poller-configuration.xml`:

[source, xml]
----
<service name="EXAMPLE" ...>
  <parameter key="rrd-status" value="false"/>
</service>
----

The value stored is an enum value based on the status of the polled service.
If the poller service is not able to run, such as due to an error in the monitor config, the stored value will be `NaN`.

[options="autowidth"]
|===
| Monitor Response | Stored Value

| Available
| 1

| Unavailable
| 0

| Unresponsive
| -1
|===

== Overlapping services

Because you can specify multiple polling packages, you can use the same service (like ICMP) multiple times.
The order that polling packages are defined in `poller-configuration.xml` is important when IP interfaces match multiple polling packages with the same service configuration.

The following shows which configuration is applied for a specific service:

[source, xml]
----
<package name="less-specific">
  <filter>IPADDR != '0.0.0.0'</filter>
  <include-range begin="1.1.1.1" end="254.254.254.254" />
  <include-range begin="::1" end="ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff" />
  <rrd step="300"> <1>
    <rra>RRA:AVERAGE:0.5:1:2016</rra>
    <rra>RRA:AVERAGE:0.5:12:1488</rra>
    <rra>RRA:AVERAGE:0.5:288:366</rra>
    <rra>RRA:MAX:0.5:288:366</rra>
    <rra>RRA:MIN:0.5:288:366</rra>
  </rrd>
  <service name="ICMP" interval="300000" user-defined="false" status="on"> <2>
    <parameter key="retry" value="5" /> <3>
    <parameter key="timeout" value="10000" /> <4>
    <parameter key="rrd-repository" value="/var/lib/opennms/rrd/response" />
    <parameter key="rrd-base-name" value="icmp" />
    <parameter key="ds-name" value="icmp" />
  </service>
  <downtime interval="30000" begin="0" end="300000" />
  <downtime interval="300000" begin="300000" end="43200000" />
  <downtime interval="600000" begin="43200000" end="432000000" />
</package>

<package name="more-specific">
  <filter>IPADDR != '0.0.0.0'</filter>
  <include-range begin="192.168.1.1" end="192.168.1.254" />
  <include-range begin="2600::1" end="2600:::ffff" />
  <rrd step="30"> <1>
    <rra>RRA:AVERAGE:0.5:1:20160</rra>
    <rra>RRA:AVERAGE:0.5:12:14880</rra>
    <rra>RRA:AVERAGE:0.5:288:3660</rra>
    <rra>RRA:MAX:0.5:288:3660</rra>
    <rra>RRA:MIN:0.5:288:3660</rra>
  </rrd>
  <service name="ICMP" interval="30000" user-defined="false" status="on"> <2>
    <parameter key="retry" value="2" /> <3>
    <parameter key="timeout" value="3000" /> <4>
    <parameter key="rrd-repository" value="/var/lib/opennms/rrd/response" />
    <parameter key="rrd-base-name" value="icmp" />
    <parameter key="ds-name" value="icmp" />
  </service>
  <downtime interval="10000" begin="0" end="300000" />
  <downtime interval="300000" begin="300000" end="43200000" />
  <downtime interval="600000" begin="43200000" end="432000000" />
</package>
----

<1> Polling interval for the packages is 300 seconds and 30 seconds.
<2> Custom polling interval for the ICMP service.
<3> Custom retry settings for the ICMP service.
<4> Custom timeout settings for the ICMP service.

The last polling package on the service will be applied.
You can use this to define a less specific catch-all filter as the default configuration.
Use a more specific polling package to overwrite the default settings.
In the previous example, all IP interfaces in `192.168.1/24` or `2600:/64` will be monitored with ICMP using custom polling, retry, and timeout settings.

The IP interface and service pages show which polling package and service configuration are applied for this specific service, and associated statistics.

.Polling package settings applied to IP interface and service
image::service-assurance/03_polling-package.png["Screen displaying interface and service configuration and statistics for a polling package", 800]

[[ga-pollerd-packages-patterns]]
== Service patterns

Usually, the poller that monitors a service is found by matching its name with the service name.
There is an option for you to match a poller if you specify an additional `pattern` element.
If so, the poller is used for all services matching the regex pattern.

The regex pattern lets you specify named capture groups.
There can be multiple capture groups inside a pattern, but each must have a unique name.
Note that the regex must be escaped or wrapped in a CDATA tag inside the configuration XML to make it a valid property.

If a poller is matched using its pattern, the parts of the service name that match the capture groups of the pattern are available as parameters to the <<deep-dive/service-assurance/configuration.adoc#ga-pollerd-configuration-meta-data, Metadata DSL>> using the context `pattern` and the capture group name as key.

=== Examples

* `<pattern><![CDATA[^HTTP-(?<vhost>.*)$]]></pattern>`: matches all services with names starting with `HTTP-` followed by a host name.
If the service is called `HTTP-www.example.com`, the Metadata DSL expression `${pattern:vhost}` will resolve to `www.example.com`.
* `<pattern><![CDATA[^HTTP-(?<vhost>.*?):(?<port>[0-9]+)$]]></pattern>`: matches all services with names starting with `HTTP-` followed by a hostname and a port.
There will be two variables (`${pattern:vhost}` and `${pattern:port}`), which you can use in the poller parameters.

Use the service pattern mechanism whenever there are multiple instances of a service on the same interface.
You can make services identifiable by specifying a distinct service name for each instance, but there is no need to add a poller definition for each service.
Common use cases for such services are HTTP virtual hosts where multiple web applications run on the same web server, or BGP session monitoring where each router has multiple neighbors.

== Manually test services

You can run a test via the Karaf shell to test the {page-component-title} polling services:

[source, console]
ssh -p 8101 admin@localhost

NOTE: In the shell, you can use `opennms:poll --help` to view the command's help information.

The following example runs the ICMP monitor on a specific IP interface:

[source, console]
opennms> opennms:poll -S ICMP -P example1 10.23.42.1

The output is verbose, which lets you debug monitor configurations.
Important output lines include the following:

[source, console]
----
Package: example1 <1>
Service: ICMP <2>
Monitor: org.opennms.netmgt.poller.monitors.IcmpMonitor <3>
Parameter ds-name: icmp <4>
Parameter retry: 2 <5>
Parameter rrd-base-name: icmp <4>
Parameter rrd-repository: /opt/opennms/share/rrd/response <4>
Parameter timeout: 3000 <5>

Service is Up on 192.168.31.100 using org.opennms.netmgt.poller.monitors.IcmpMonitor: <6>
	response-time: 407,0000 <7>
----

<1> Service and package of this test.
<2> Applied service configuration from polling package for this test.
<3> Service monitor used for this test.
<4> RRD configuration for response time measurement.
<5> Retry and timeout settings for this test.
<6> Polling result for the service polled against the IP address.
<7> Response time.

== Manually test filters

Filters are ubiquitous in the {page-component-title} configurations that implement `<filter>` syntax.
You can use the Karaf shell to verify filters.
For more information, see xref:reference:configuration/filters/filters.adoc[].

.SSH to localhost
[source, console]
ssh -p 8101 admin@localhost

NOTE: In the shell, you can use `opennms:filter --help` to view the command's help information.

For example, you can run a filter rule that matches a location:

[source, console]
opennms:filter  "location='MINION'"

The output displays as follows:

[source, console]
----
nodeId=2 nodeLabel=00000000-0000-0000-0000-000000ddba11 location=MINION
	IpAddresses:
		127.0.0.1
----

You can also run a filter that matches a node location within a given IP address range:

[source, console]
opennms:filter "location='Default' & (IPADDR IPLIKE 172.*.*.*)"

The output displays as follows:

[source, console]
----
nodeId=3 nodeLabel=label1 location=Default
	IpAddresses:
		172.10.154.1
		172.20.12.12
		172.20.2.14
		172.01.134.1
		172.20.11.15
		172.40.12.18

nodeId=5 nodeLabel=label2 location=Default
	IpAddresses:
		172.17.0.111

nodeId=6 nodeLabel=label3 location=Default
	IpAddresses:
		172.20.12.22
		172.17.0.123
----

NOTE: Displayed node information includes the `nodeId`, `nodeLabel`, `location`, and optional fields like `foreignId`, `foreignSource`, and `categories` (when they exist).

== Monitor Microsoft AD services

To monitor Microsoft AD services, you must edit `$\{OPENNMS_HOME}/etc/poller-configuration.xml`.
See the https://opennms.discourse.group/t/monitor-microsoft-ad-services/1051[Monitor Microsoft AD Services] article on Discourse for more information.
