Remote Polling

From OpenNMS
Jump to navigation Jump to search


Remote polling allows you to poll devices from disparate locations, allowing you to get an aggregate of availability across sites. The remote polling architecture utilizes the same interfaces and services that OpenNMS's traditional centralized polling uses, but has it's own availability data tuned towards keeping track of multiple pollers originating from the same site, as well as combining that data with other site data for an overall view of your monitored devices. This data can be viewed either through a tabular report page, or a GUI map.


The OpenNMS remote polling facility uses a client-server model, with clients checking in at regular intervals with updated poll data and a heartbeat, and the server considering a remote poller down if that client doesn't "check in" in a certain amount of time.

The remote poller client is designed to be a standalone jar file which can be run from the command-line, a package (RPM, DEB, EXE) that can be installed on the system, or a Java WebStart package (JNLP) which can be launched directly from a web browser.

Getting Started

This May Not Do What You Think It Does

Before investing a ton of time and effort into configuring the remote poller, it's important to be aware of what the remote poller is and is not.

What the Remote Poller Is

  • Pure Java, so architecture-independent
  • Packaged as Java WebStart (JNLP) or as RPM/DEB/EXE packages
  • Capable of both GUI and headless operation

What the Remote Poller Is Not (yet)

  • A distributed poller or data collector
  • A mechanism for "scaling out" the work done by the central poller or for skirting firewalls or other inconvenient network topologies
  • SLA-deterministic

Server-Side (Your Central OpenNMS Server)

Before You Start

Make sure OpenNMS is working first! Before you work on trying to add remote pollers to the make, be sure that the central OpenNMS server is doing what you want. Able to poll, send notifications, get graphs, etc. You don't want to be debugging server issues while trying to figure out why a remote poller might not be reporting in.

Install the remoting webapp

Since Horizon 18 and Meridian 2016, server-side support for remote pollers is packaged separately from the rest of OpenNMS, and is not installed by default. You must install the opennms-webapp-remoting package using YUM or APT.


The first step is to decide what interfaces and services you wish to poll remotely. The default $OPENNMS_HOME/etc/poller-configuration.xml comes with an "example1" <package> section, which is used by the central OpenNMS server for polling. You will now want to add another package to define which services should be polled remotely.

Define a new <package>, giving it a unique name, and making sure that it contains the attribute remote="true". Then, include any services you wish to poll remotely. Note that some services (like SNMP, DHCP, BSF, SMB, and VMware monitoring) are not distributable because they rely on configuration outside of the <service> definition, or on native code.

Here is an example that matches all IP addresses, and enables polling HTTP remotely:

<package name="raleigh" remote="true">
  <filter>IPADDR IPLIKE *.*.*.*</filter>
  <include-range begin="" end=""/>
  <rrd step = "300">
  <service name="HTTP" interval="30000" user-defined="false" status="on">
    <parameter key="retry" value="1"/>
    <parameter key="timeout" value="3000"/>
    <parameter key="port" value="80"/>
    <parameter key="url" value="/"/>
    <parameter key="rrd-repository" value="/var/log/opennms/rrd/response"/>
    <parameter key="ds-name" value="http"/>
  <outage-calendar>zzz from poll-outages.xml zzz</outage-calendar>

  <!-- 30s, 0, 5m -->
  <downtime interval="30000" begin="0" end="300000"/>
  <!-- 5m, 5m, 12h -->
  <downtime interval="300000" begin="300000" end="43200000"/>
  <!-- 10m, 12h, 5d -->
  <downtime interval="600000" begin="43200000" end="432000000"/>
  <!-- anything after 5 days delete -->
  <downtime begin="432000000" delete="true"/>


The next step is to decide what locations your remote pollers will be able to check in from. These will generally be site-specific, and will have a GPS location associated with them (so they can be displayed on the maps).

The $OPENNMS_HOME/etc/monitoring-locations.xml file defines the different locations from which remote poller monitoring instances will be running. Inside the <locations> tag, create one or more <location> entries with a set of attributes that uniquely identify it:

The short name of the location, used on the remote-poller startup command-line.
Used to group multiple locations together.
The package in poller-configuration.xml that the monitor will use to determine the services to poll.
(As of OpenNMS 1.7.11) The geographical location of the monitor. This should be a street address or similar. If none is specified or Google can't resolve the address to a latitude and longitude, the marker will be placed on the map at OpenNMS World HQ in Pittsboro, NC. :)
(As of OpenNMS 1.7.11) The geographical location of the monitor in the format "latitude,longitude".
(As of OpenNMS 1.7.11) The sort priority of this location for the UI (1 is lowest, 100 is highest).

It can also be optionally associated with 0 or more tags that identify a location. Generally these will be arbitrary metadata associated with that monitoring location.

For example, here's a monitoring-locations.xml that defines a location for The OpenNMS Group, Inc. headquarters in Pittsboro, NC:

<?xml version="1.0" encoding="UTF-8"?>
  xsi:schemaLocation=" ">
    <location-def location-name="RDU" 
        monitoring-area="raleigh" polling-package-name="raleigh"
        geolocation="The OpenNMS Group, Pittsboro, NC"
        coordinates="35.7174,-79.1619" priority="50">
        <tag name="store" />
        <tag name="production" />

users.xml and

By default, only administrators have the rights to send remote poller data to the central server, so you will want to create a user, or users, with remote polling rights to avoid using an admin username and password.

The easiest way to do so is to go to the OpenNMS admin UI, and add a new user there:

Once you've created the user, edit $OPENNMS_HOME/etc/ and add that user's ID to the role.remoting.users property.

Restart OpenNMS

Now that you've finished the server-side configuration, restart OpenNMS.

Client Side (The Remote Pollers)

UNIX-Like Systems

Installing the Remote Poller

If you are on an RPM or Debian-based install, you should be able to just install the "opennms-remote-poller" package through yum or apt.

If not, you can download the latest remote poller standalone distribution at the OpenNMS SourceForge project page.

These instructions will assume you are using one of the pre-packaged remote pollers, which provides the shell wrapper script in $OPENNMS_HOME/bin/

Running the Remote Poller

To run the remote poller and make sure everything's working, the easiest way to do so is just to start it on the command-line. No real configuration is necessary, but you will need to know the following information:

  • the location you wish to use (the "location-name" tag in monitoring-locations.xml)
  • how to reach your OpenNMS server from the remote poller system
  • the username and password you created above

If you run it without options, it gives examples on what options are available:

 -d,--debug            write debug messages to the log
 -g,--gui              start a GUI (default: false)
 -h,--help             this help
 -l,--location <arg>   the location name of this remote poller
 -n,--name <arg>       the name of the user to connect as
 -p,--password <arg>   the password to use when connecting
 -u,--url <arg>        the URL for OpenNMS (default: http://server-name:8980/opennms-remoting)

If your OpenNMS server is reachable at, then you will want to use the following command:

 $OPENNMS_HOME/bin/ -l RDU -n remoteuser -p remotepass \

You should start to see data in the distributed status page within your polling interval (usually 5 minutes).

Windows Systems

You can install the Remote Poller on supported Windows systems (Windows Vista or later) by using JNLP or by installing the Remote Poller as a Windows Service. To do either, visit the remoting site on your local OpenNMS installation from the Windows host:


You can click on the JNLP links at the top ("Remote Poller with GUI" and "Remote Poller without GUI") to install and run the Remote Poller manually via JNLP. If you want to register the Remote Poller as a Windows Service, use the EXE installer at the bottom of the page. It will present a wizard that will collect all of the information needed to run the remote poller including:

  • Installation path (which is C:\Program Files\OpenNMS Remote Poller by default).
  • The IP address, port, and credentials for a user on your OpenNMS system.
  • The credentials for a user with administrator rights whose account will be used to run the Windows Service.

The installer will then launch JNLP to download the software from the OpenNMS system and wrap it in a Windows Service definition. The service will be configured to launch automatically on startup and can be controlled from the Services administrative tool or an optionally-installed tray icon.

Java Security

On Windows, Java's security controls may prevent you from installing the Remote Poller especially if you are trying to install a development version of the Remote Poller that you have built yourself that is not signed by the OpenNMS JAR certificate. In these cases, you will see the following dialog box:

Application blocked.png

In these cases, you should open the Java Control Panel and go to Security > Security Level and change the value from the default of High to Medium.

When the JNLP application downloads, it will also present you with a Security Warning dialog box confirming that you want to run the software. On this dialog box, you should select I accept the risk and want to run this application and you should also expand the options at the bottom and select Do not show this again for apps from the publisher and location above. This will put the certificate for the app into the trusted certificate list for Java on that machine.

Security warning2.png

If you wish to remove this certificate from the trusted certificate list at a later point, you can open the Java Control Panel and go to Security > Manage Certificates... and delete the certificate from the list of Trusted Certificates.

Advanced Topics

Configuring Applications

Applications allow you to create a collection of arbitrary services and treat them as a single unit with its own availability calculation. This is useful for creating an overall "service" that represents a number of different things.

For example, if you have a public-facing web application which uses tomcat, retrieves files from a SAN, and reads data from a database on another machine, you could create a single application which contains the HTTP service from the tomcat system and the SAN machine, and a JDBCStoredProcedureMonitor service from the database machine.

Applications can be configured in the applications UI:

Configuring Maps

As of OpenNMS 1.7.11, support for distributed maps was added, which lets you visualize locations and applications on a world map, based on the geolocation data in your monitoring-locations.xml.

All distributed map configuration is done in the $OPENNMS_HOME/etc/ file on the central server.

Configure Map Type

First, configure the type of map API you wish to use. If you have a Google Maps API key, or a MapQuest API key, you can choose "GoogleMaps" or "Mapquest" as the implementation, otherwise, OpenLayers uses OpenStreetMaps, an open-data project for providing map data in an open source manner, and should work for any user.

Configure Geocoding

Geocoding is what converts addresses into coordinates, and can be necessary to look up your addresses in monitoring-locations.xml if you did not provide exact coordinates. If you choose the Google or MapQuest geocoders, they will use the API key you configured earlier in If you choose the Nominatim geocoder, you will have to configure your email address by setting:<your-address>

It is a requirement from the OpenStreetMaps geocoder that you provide a contact address so they can contact you if you are making too many queries, since their server is run by a volunteer organization.

About Using OpenStreetMaps

As of 1.8.7, our default OpenStreetMaps implementation uses MapQuest's servers for data. MapQuest has contributed a large amount of resources to the OpenStreetMaps community, including servers which are free for all to use. If you see references to MapQuest relating to OpenLayers in our configuration, it is because we are using the open MapQuest resources, not the paid enterprise ones.

Accessing the Maps

Just click on the "Distributed Maps" link in the menu bar in your OpenNMS server's web UI.

Starting the Remote Poller

While the most common way to run the remote poller is as a console-only, command-line tool, it also provides a GUI version which you can start either from the command-line, or through Java webstart.

Command-Line GUI

To start the GUI from the command-line, add the "-g" option to your remote-poller command, like so:

 $OPENNMS_HOME/bin/ -g -l RDU \
   -n remoteuser -p remotepass \

HTTP Proxies

If you need to use an HTTP proxy to communicate with the OpenNMS server, add the http.proxyHost and http.proxyPort options to the java command-line:

 $OPENNMS_HOME/bin/ \  \
   -Dhttp.proxyPort=8080 -g -l RDU \

Design Overview

For a complete overview of the remote poller architecture, see the Remote Poller Design Overview page.