1. Installation Overview

The OpenNMS platform can be installed in several ways.
This guide describes the installation of the platform on Red Hat Enterprise Linux (RHEL)-based, Debian-based and Microsoft Windows
operating systems. The following abbreviations will be used to refer to the following operating systems:

Please make sure your DNS settings for the OpenNMS server are correct.
In case there is an incorrect or missing A Resource Record for the server, OpenNMS might not start correctly.
The reason is that the Java security manager cannot be initialized and an RMI class loader disabled exception will be shown.

OpenJDK 8 can be used, but for production and critical environments Oracle Java SE Development Kit 8 is recommended.

${OPENNMS_HOME} will be used to refer to the path where OpenNMS is installed. It is different
depending on your platform:

RHEL: /opt/opennms

Debian: /usr/share/opennms

Microsoft Windows: C:\Program Files\opennms

With the opennms meta package all dependencies needed for the components mentioned above are maintained.
The following sections describe how to install OpenNMS on a single system.
Dependencies for Java and the PostgreSQL database are maintained with the opennms meta installation package.

2. Compatibility Matrix

OpenNMS

Java

PostgreSQL

Newts

Cassandra

Grafana

Elasticsearch

Kafka

Horizon 19

8

9.2+

Yes

1.2, 2.X, 3.0

3.X, 4.X

2.X, 5.X

0.10

Horizon 18

8

9.1+

Yes

1.2, 2.X, 3.0

3.X, 4.X

1.0

No

Meridian 2016

8

9.1+

Yes

1.2, 2.X, 3.0

3.X, 4.X

No

No

Horizon 17

8

9.1+

Yes

1.2, 2.X

3.X, 4.X

No

No

Horizon 16

8

9.0+

No

No

3.X, 4.X

No

No

Horizon 15

7

9.0+

No

No

No

No

No

Meridian 2015

7

9.0+

No

No

No

No

No

3. Yum/APT Package Repositories

Installation packages are available for different releases of OpenNMS.
You need to choose which release you would like to run and then configure your package repository to point to that release.
Configuring a package repository will enable you to install and update the software by using standard Linux software update tools like yum and apt.

4.1.2. Disable Automatic Updates (Optional)

We recommend you disable the OpenNMS Horizon Yum repository to avoid upgrades while it is running.

OpenNMS Horizon requires some manual steps upon upgrade to make sure the database and configuration are consistent in the new version, and on systems with many nodes or lots of events, this can take hours.
For this reason, it is recommended to exclude the OpenNMS Horizon packages from yum except when you are planning on performing an upgrade.

To do so, edit the /etc/yum.repos.d/opennms-*.repo file and change enabled=1 to enabled=0 in each section.

When you are ready to upgrade OpenNMS Horizon, call yum with the --enablerepo option to turn the 2 repositories defined in this file back on.
For example, if you installed the stable repository RPM on a CentOS or RHEL 7 system, you would run:

4.1.3. Prepare PostgreSQL

The CentOS package installs but doesn’t initialize the PostgreSQL database directory.
Additionally OpenNMS requires authentication to access the database and are described in this section.
Initialize the database directory with

Initialization of the PostgreSQL database

postgresql-setup initdb

System startup configuration for PostgreSQL

systemctl enable postgresql

Startup PostgreSQL database

systemctl start postgresql

The next step is setting the postgres super user password and creating an opennms database user with password.
Additionally it is required to configure the authentication method to allow authentication from the local network.

4.2.2. Disable Automatic Updates (Optional)

We recommend you disable automatic updating of the OpenNMS Horizon packages to avoid upgrades while it is running.

OpenNMS Horizon requires some manual steps upon upgrade to make sure the database and configuration are consistent in the new version, and on systems with many nodes or lots of events, this can take hours.
For this reason, it is recommended to exclude the OpenNMS Horizon packages from update except when you are planning on performing an upgrade.

4.3. Microsoft Windows

This guide does not apply to OpenNMS Meridian, which can be installed only on Red Hat Enterprise Linux or CentOS systems.

OpenNMS is mostly developed on Unix/Linux based systems, nevertheless it is possible to install the platform on Microsoft Windows operating systems.
To install the application a graphical installer is provided and can be used to install OpenNMS on Microsoft Windows.
This section describes how to install the OpenNMS platform on Microsoft Windows 2012 Server.

The standalone installer for Microsoft Windows is only available for the most recent stable version of OpenNMS.

It is required to have Oracle JDK 8 installed.
The JRE is NOT sufficient.

To edit OpenNMS configuration files on Microsoft Windows the tool Notepad++ can deal with the formatting of .property and .xml files.

The setup process is described in the following steps:

Installation of PostgreSQL database service

Download and install the graphical OpenNMS installer

First start of the OpenNMS application

4.3.1. Install PostgreSQL

PostgreSQL is available for Microsoft Windows and latest version can be downloaded from Download PostgreSQL page.
Follow the on-screen instructions of the graphical installer.

The placeholder {PG-VERSION} represents the PostgreSQL version number.
A version of 9.1+ is required for OpenNMS.

Configure a discovery range for an initial node discovery.
If you don’t want any discovery set begin and end to the same unreachable address.

Choose secure passwords for all database users and don’t use the example passwords above in production.

There is currently an open issue in the installer NMS-7831.
Username and password are not written to the opennms-datasources.xml file and has to be changed manually.
The initialize of the database will fail with an authentication error.

Set the password for administrative changes of the OpenNMS database table

After setting the username and passwords in opennms-datasources.xml re-run the graphical installer and also initialize the database.
OpenNMS can be started and stopped with the start.bat and stop.bat script located in %OPENNMS_HOME%\bin directory.

5. Oracle Java SE Development Kit 8

Installing the Oracle Java SE Development Kit 8 (JDK8) requires installation packages provided by Oracle
or a 3rd-party maintainer for Debian-based Linux distributions.
The following tools should be installed to follow this installation manual:

Download files and tools with wget and curl

Extract archives with tar

Text manipulation with sed

Editing text, e.g. vi, nano or joe

Internet access

By downloading the Oracle Java SE Development Kit 8 RPM installer, you will accept the license agreement
from Oracle which can be found on the Java distribution web site.

Installing the Java Runtime Environment (JRE) is not sufficient.
The development kit is often named openjdk-devel or openjdk-jdk.
With a JRE installed, OpenNMS Horizon will not start and throws a java.lang.ClassNotFoundException: com.sun.tools.attach.AttachNotSupportedException.
For more details see NMS-9327.

5.1. RHEL

This section describes how to install Oracle Java SE Development Kit 8 on a RPM-based system like Red Hat Enterprise Linux 7 or CentOS 7.1.

Start the java8-installer.exe from the command line or with Windows Explorer from the Administrator’s Download folder.

The setup requires administrative privileges.

5.4. Java Environment

To locate the Java system files, applications typically use the $JAVA_HOME environment variable.
The environment can be set for a specific user or globally for the whole system on boot time.

Example path to Java on RHEL, Debian and Microsoft Windows systems

RHEL: /usr/java/jdk1.8.0_51

Debian: /usr/lib/jvm/java-8-oracle

Microsoft Windows: C:\Program Files\Java\jre1.8.0_51

5.4.1. Set JAVA_HOME on Linux

Option 1: Set the Java environment for the current user

vi ~/.bash_profile
export JAVA_HOME=/path/to/java

Option 2: Set the Java environment for all users on boot time

vi /etc/profile
export JAVA_HOME=/path/to/java

5.4.2. Set JAVA_HOME on Microsoft Windows

Option 1: Set JAVA_HOME as user specific system variable

setx "JAVA_HOME" "path\to\java"

Option 2: Set JAVA_HOME as a System variable

setx /M "JAVA_HOME" "path\to\java"

6. RRDtool

In most Open Source applications, RRDtool is often used and is the de-facto open standard for Time Series Data.
The basic installation of OpenNMS comes with JRobin but it is simple to switch the system to use RRDtool to persist Time Series Data.
This section describes how to install RRDtool, the jrrd2OpenNMS Java Interface and how to configure OpenNMS to use it.
RRDtool can be installed from the official package repositories provided by RHEL and Debian based Linux distributions.

6.1. RHEL

Installation on RHEL/CentOS

yum install rrdtool

6.2. Debian

Installation of RRDtool on Debian/Ubuntu

apt-get install rrdtool

6.3. Source

If you want the latest version of RRDtool, you may want to compile it from source. Instructions for doing so are at
rrdbuild.

The latest version of RRDtool may not always be compatible with the version of OpenNMS that you want to run.
Please ask about RRDtool support on the discussion lists or chat rooms if you have any problems running a
new version of RRDtool.

If you want to install the latest RRDtool from source, make sure the rrdtool binary is in search path.
To make the setup easier, you can link the binary to /usr/bin/rrdtool which is the location where OpenNMS will expect
to find the executable binary.

6.4. Install jrrd2 Interface

To get access from the OpenNMS Java Virtual Machine you have to install jrrd2 as an interface.
You can install it from the OpenNMS package repository with:

Installation of jrrd2 on RHEL/CentOS

yum install jrrd2

Installation of jrrd2 on Debian/Ubuntu

apt-get install jrrd2

With OpenNMS 17.0.0 it is preferred to use jrrd2 instead of jrrd.
The jrrd2 module is improved for performance by adding multithreading capabilities.

6.5. Configure OpenNMS Horizon

To configure OpenNMS to use RRDtool instead of JRobin configure the following properties in rrd-configuration.properties.

7. Newts

It is currently not supported to initialize the Newts keyspace from Microsoft Windows Server operating system.
Microsoft Windows based Cassandra server can be part of the cluster, but keyspace initialization is only possible using a _Linux-_based system.

7.1. Setting up Cassandra

Cassandra is only required when using Newts.
If your OpenNMS Horizon system is not using Newts, you can skip this section.

It is recommended to install Cassandra on a dedicated server, but is also possible to run a node on the OpenNMS Horizon server itself.
This installation guide describes how to set up a single Cassandra instance on the same system as OpenNMS Horizon for the purpose of evaluating and testing Newts.
These steps are not suitable for a production Cassandra Cluster. If you already have a running cluster you can skip this section.

7.1.1. RHEL

This section describes how to install the latest Cassandra 3.0.x release on a RHEL based systems for Newts.
The first step is to add the DataStax community repository and install the required GPG Key to verify the integrity of the RPM packages.
After that install the package with yum and the Cassandra service is managed by Systemd.

Verify whether the Cassandra service is automatically started after rebooting the server.

7.1.2. Debian

This section describes how to install the latest Cassandra 3.0.x release on a Debian-based system for Newts.
The first step is to add the DataStax community repository and install the required GPG Key to verify the integrity of the DEB packages.
After that install the packages with apt and the Cassandra service is added to the runlevel configuration.

The Cassandra service is added to the runlevel configuration and is automatically started after installing the package.

Verify whether the Cassandra service is automatically started after rebooting the server.

7.1.3. Microsoft Windows

This section describes how to install the latest Cassandra 3.0.x release on a Microsoft Windows Server based systems for Newts.
The first step is to download the graphical installer and register Cassandra as a Windows Service so it can be manged through the Service Manager.

Run the Windows Installer file from PowerShell or through Windows Explorer and follow the setup wizard to install.
During the installation, accept the options to automatically start the services.
By default the DataStax Server, OpsCenter Server and the OpsCenter Agent will be automatically installed and started.

The DataStax OpsCenter Server is only required to be installed once per Cassandra Cluster.

If you install the DataStax OpsCenter make sure you have Chrome or Firefox installed.

7.2. Configure OpenNMS Horizon

Once Cassandra is installed, OpenNMS Horizon can be configured to use Newts.
To enable and configure Newts, set the following properties in ${OPENNMS_HOME}/etc/opennms.properties:

The org.opennms.newts.config.hostname property also accepts a comma separated list of hostnames and or IP addresses.

Once Newts has been enabled, you can initialize the Newts schema in Cassandra with the following:

Initialize Newts keyspace in Cassandra

${OPENNMS_HOME}/bin/newts init

Optionally, you can now connect to your Cassandra cluster and verify that the keyspace has been properly initialized:

Verify if the keyspace is initialized with cqlsh

cqlsh
use newts;
describe table terms;
describe table samples;

Restart OpenNMS Horizon to apply the changes.

8. R Statistics System

R is a free software environment for statistical computing and graphics.
OpenNMS can leverage the power of R for forecasting and advanced calculations on collected time series data.

OpenNMS interfaces with R via stdin and stdout, and for this reason, R must be installed on the same host
as OpenNMS.
Note that installing R is optional, and not required by any of the core components.

The R integration is not currently supported on Microsoft Windows systems.

8.1. RHEL

This section describes how to install R on a RHEL based system.

This description was built on RHEL 7 and CentOS 7.1.

Install the EPEL repositories

yum install epel-release

Install R

yum install R

8.2. Debian

This section describes how to install R on a Debian-based system.

This description was built on Debian 8 and Ubuntu 14.04 LTS.

Install R

sudo apt-get install r-recommended

9. Minion

Minion gives the ability to monitor devices and applications which are in isolated networks and hard to reach from a central OpenNMS Horizon instance.
Maintaining a large set of Firewall rules to allow a variety of management protocols is sometimes tedious and hard to set up.
Communicating with managed devices over unreliable networks and the use of UDP based management protocols can also be difficult to maintain.
Deploying a Minion can be used to address these issues.

A Minion can be used when a central OpenNMS Horizon can’t reach all devices and Management Agents for monitoring.
Furthermore it simplifies the network communication by using TCP-based ActiveMQ and ReST communication.

The network area where access to managed network devices and applications is allowed can be modeled in a Location.
Monitored Nodes and IP Services are associated to Locations and are defined during Provisioning.
Each Minion is configured with a Location and all Nodes and IP Services in the same Location are monitored through this Minion.

The Minion is currently not designed to be a replacement for the Remote Poller.
By using the Remote Poller a service can be tested from several remote sites, whereas a Minion extends network reachability for a central OpenNMS Horizon instance.

Every Node created in OpenNMS Horizon is by default created in the Location named Default.
All Nodes and Services in the Default Location are handled by the central OpenNMS Horizon instance itself.
For each branch office in an isolated network, a Location is defined.
The Minion has a configuration property for the Location and will register itself to the OpenNMS Horizon instance on startup.

The Provisioning System allows to associate Nodes to a Location.
OpenNMS Horizon will delegate monitoring requests for Nodes in the specified Locations to the registered Minions and uses them as a proxy.

Figure Minion communication gives a more detailed overview about the communication between an OpenNMS Horizon instance and a Minion.

Figure 2. Minion communication

The Minion needs a configuration which requires at minimum the following information:

An unique identifier (id) for this specific Minion

Monitoring Location name (location) this Minion is responsible

The communication endpoints (broker-url and http-url) for the central OpenNMS Horizon instance

The configuration resides in a property file in ${MINION_HOME}/etc/org.opennms.minion.controller.cfg.
When the minimal configuration is set up the Minion can be started and initially connects to the central OpenNMS Horizon instance and identifies itself with his unique ID.

The unique ID is generated when the packages get installed /usr/bin/uuidgen -t and is used if no ID is set manually.
On upgrade the ID is not updated.

By default the Minion will be automatically provisioned as a Node in the OpenNMS Horizon instance and get automatically monitored with the Minion-Heartbeat service.
The Minion sends heart beat messages to ensure it is running and functioning properly in this network area.

The specific management protocol messages, e.g. SNMP, ICMP, are piped through an ActiveMQ messaging communication channel and are executed by a Minion.
Responses are forwarded to the central OpenNMS Horizon instance and are processed accordingly.

Minions can be installed on every system that is able to communicate with these two endpoints:

The OpenNMS ReST Interface, by default TCP port 8980

The ActiveMQ broker used by OpenNMS Horizon, by default TCP port 61616

The following management protocols are currently supported in a Minion proxy scenario:

Receive Syslog messages and forward them through ActiveMQ to a central OpenNMS Horizon instance

Receive SNMP Traps and forward them through ActiveMQ to a central OpenNMS Horizon instance

Act as a proxy for SNMP performance data collections

Act as a proxy for Service Monitors to test availability and measure response times from applications

Packages are only available for RHEL-based systems (RPMS).

To avoid issues, make sure the Minion and the instance of OpenNMS Horizon have the same version.

9.1. Installing Minion

This section describes how to install the Minion and how to configure it to communicate with a central OpenNMS Horizon instance.

Installing a distributed OpenNMS Horizon requires:

Instance of OpenNMS Horizon needs to be same version as Minion Packages

Packages are available as RPMs for RHEL-based systems and DEBs for Debian-based systems (including Ubuntu)

OpenNMS Horizon needs to be installed and the communication to the ReST and ActiveMQ endpoints is possible

Configuring Startup

The Minion’s startup configuration can be changed by editing the /etc/sysconfig/minion file. It allows you to override many of the defaults used at startup including the location of your JDK, how much memory to use, and what user to run as.

Starting the Minion

After successful installation a minion service can be started and enabled using systemd commands.

System startup configuration for Minion

systemctl enable minion

Startup Minion

systemctl start minion

After starting Minion the shell can be accessed locally on ssh://localhost:8201.
The default login user is admin and the password is initialized to admin.

Additionally, symbolic links are set up pointing to /etc/minion and /var/log/minion to match Debian’s expected filesystem layout.

Configuring Startup

The Minion’s startup configuration can be changed by editing the /etc/default/minion file. It allows you to override many of the defaults used at startup including the location of your JDK, how much memory to use, and what user to run as.

Starting the Minion

After successful installation a minion service can be started and enabled using standard Debian commands.

System startup configuration for Minion

update-rc.d minion enable

Startup Minion

service minion start

After starting Minion the shell can be accessed locally on ssh://localhost:8201.
The default login user is admin and the password is initialized to admin.

[root@localhost /root]# $ ssh -p 8201 admin@localhost

9.2. Configuring OpenNMS

Minions communicate with OpenNMS Horizon via ReST endpoints and via an ActiveMQ broker.
Some configuration is required to setup and secure these communication channels.

9.2.1. Authentication and Authorization

The minion role includes the minimal amount of permissions required for a Minion to operate.

This guide will assume you have created a user called minion, with a password of minion that has been associated to the ROLE_MINION role.

9.2.2. Configure ActiveMQ

OpenNMS Horizon embeds an ActiveMQ broker which, by default, cannot be accessed remotely via the network.
In order to make the ActiveMQ broker accessible remotely, you must edit $OPENNMS_HOME/etc/opennms-activemq.xml and
uncomment the transportConnector with the tcp://0.0.0.0:61616 URI.

<!-- Uncomment this line to allow external TCP connections -->
<!--
WARNING: Access to port 61616 should be firewalled to prevent unauthorized injection
of data into OpenNMS when this port is open.
-->
<transportConnector name="openwire" uri="tcp://0.0.0.0:61616?useJmx=false&amp;maximumConnections=1000&amp;wireformat.maxFrameSize=104857600"/>

If you wish to restrict ActiveMQ connections to only one particular external IP address, you can change 0.0.0.0 to the prefered IP address.

9.3. Configuring Minion

This section describes how to configure Minion once it has been installed and started.

Once the Minion service is started and the Karaf shell is accessible, you can configure the Minion to point it at your OpenNMS Horizon instance.

By default the Minion is configured to communicate with OpenNMS Horizon via localhost.

Configure the Minion’s location and endpoint URLs for communication with OpenNMS

9.4.3. Configure Minion to Receive Syslog Messages

If you wish your Minion to listen to syslog messages, you will need to configure your firewall to port forward from the privileged Syslog port (514) to the Minion’s default syslog listener on port 1514.

9.4.4. Minion Configuration File

Beside manually configuring a Minion instance via the Karaf CLI it is possibleto modify and deploy its configuration file through configuration management tools.
The configuration file is located in ${MINION_HOME}/etc/org.opennms.minion.controller.cfg.
All configurations set in Karaf CLI will be persisted in this configuration file which can also be populated through configuration management tools.

The Minion needs to be restarted when this configuration file is changed.

In case the credentials needs to be set through the CLI with configuration management tools or scripts, the /opt/minion/bin/client command can be used which allows to execute Karaf commands through the Linux shell.

9.5. Troubleshooting

This section gives some hints how to troubleshoot Minion deployments.
The OpenNMS Horizon comes with a few useful built-in commands to verify configurations and debug access to Management Agents through Minion.

9.5.1. Verifying Connectivity

Once the URLs and credentials for communicating with the OpenNMS Horizon instance are configured, you can verify connectivity using:

9.5.3. Run a monitor through a Minion

The Time To Live (TTL) is only related to messages in the ActiveMQ communication.
In case a poll is triggered manually through Karaf CLI the message TTL in ActiveMQ should be at least the number of retries x timeout in ms, e.g. 3 x 2000ms = 6000ms.
By default the configured polling interval is used, which is by default 5 minutes (300000 ms).