2.1. Objectives

Installing OpenNMS Horizon components on a single node using the built-in JRobin as time series storage

Setup OpenNMS Horizon on recommended operating systems

Login the Web User Interface and change the default admin password

2.2. Before you begin

The following abbreviations will be used to refer to their respective entry through this documentation.

Table 1. Operating Systems

RHEL

Red Hat Enterprise Linux 7 or higher, CentOS 7 or higher

Debian

Debian 9 or higher, Ubuntu 16.04 LTS or higher

Windows

Microsoft Windows Server 2012, Windows 10

It is recommended to meet the following requirements:

Table 2. Installation Requirements

Minimal Hardware

2 CPU, 2 GB RAM, 20 GB disk

Operating System

RHEL or Debian in a current version is recommended.
Please be aware OpenNMS Horizon is developed and mostly operated on Linux systems.
Community support is limited when you run on Microsoft Windows platform.
On Microsoft Windows the R integration for statistical computation on time series data is not supported.

Internet

Access to {yum,debian}.opennms.org or SourceForge for Microsoft Windows via https.

DNS Setup

Please make sure your DNS settings for the OpenNMS server are correct and the localhost name can be resolved.
If there is an incorrect or missing A Resource Record for the server hostname, OpenNMS might not start correctly.
The Java security manager might not initialize and an RMI class loader disabled exception will be shown.

Depending on the installed operating system, the path for OpenNMS Horizon is different.
If the instruction refers to ${OPENNMS_HOME}, the path is resolved to the following directories:

Table 3. Directory Structure

RHEL

/opt/opennms

Debian

/usr/share/opennms

Windows

C:\Program Files\opennms

2.3. Installing on RHEL

The following steps will be described:

Installation of the opennms meta package which handles all dependencies

Initialize PostgreSQL database and configure access

Initialize OpenNMS Horizon database and start

Log in to the Web User Interface and change default admin password

All commands on the command line interface need to be executed with root permissions.

We recommend disabling the OpenNMS Horizon apt repository after installation to prevent 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.

We recommend disabling the OpenNMS Horizon apt repository after installation to prevent 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.

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.

Set as current password admin and set a new password and confirm your newly set password

Click "Submit"

Logout and login with your new password

Next Steps

Additional information can be found in these follow up documents:

Getting Started Guide

Learn the first steps to setup, configure, and maintain an OpenNMS Horizon.

Reference Guide

Find in-depth information on the detecters, monitors, collectors, and configuration files used by the OpenNMS Horizon platform.

3. Monitor isolated location with Minion

This section describes how to install the Minion to monitor devices and services in a location which can’t be reached from an OpenNMS Horizon instance.

3.1. Objectives

Install a Minion to monitor devices and services unreachable from an OpenNMS Horizon instance

Configure an authenticated unencrypted communication between Minion and OpenNMS Horizon using ActiveMQ and REST

3.2. Before you begin

Setting up a OpenNMS Horizon with Minions requires:

Instance of OpenNMS Horizon needs to be exact same version as Minion packages

Packages are available as RPMs for RHEL-based systems and DEBs for Debian-based systems

OpenNMS Horizon needs to be installed and communication to the REST (8980/tcp) and ActiveMQ (616161/tcp) endpoints is possible

Depending on the installed operating system, the path for Minion is different.
If the instruction refers to ${MINION_HOME}, the path is resolved to the following directories:

Table 4. Directory Structure

RHEL

/opt/minion

Debian

/usr/share/minion

3.3. Installing on RHEL

Setup OpenNMS Horizon to allow Minion communication

Installation of the opennms-minion meta package which handles all dependencies

Starting Minion and access the Karaf console over SSH

Configure Minion to communicate with OpenNMS Horizon

Verify the connectivity between Minion and OpenNMS Horizon

All commands on the command line interface need to be executed with root permissions.

Step 1: Setup OpenNMS Horizon to allow Minion communication

Communication between a Minion and OpenNMS Horizon uses REST API and a messaging system, by default ActiveMQ.
An authenticated user in OpenNMS Horizon is required for these communication channels.
The security role ROLE_MINION includes the minimal amount of permissions required for a Minion to operate.

As an example we use in this guide the user name minion with password minion.
Change the credentials accordingly.

Create a user minion in the OpenNMS Horizon web user interface

Login the web user interface with a user which has administrative permissions

3.4. Installing on Debian

Installation of the opennms-minion meta package which handles all dependencies

Starting Minion and access the Karaf console over SSH

Configure Minion to communicate with OpenNMS Horizon

Verify the connectivity between Minion and OpenNMS Horizon

All commands on the command line interface need to be executed with root permissions.

Step 1: Setup OpenNMS Horizon to allow Minion communication

Communication between a Minion and OpenNMS Horizon uses REST API and a messaging system, by default ActiveMQ.
An authenticated user in OpenNMS Horizon is required for these communication channels.
The security role ROLE_MINION includes the minimal amount of permissions required for a Minion to operate.

As an example we use in this guide the user name minion with password minion.
Change the credentials accordingly.

Create a user minion in the OpenNMS Horizon web user interface

Login the web user interface with a user which has administrative permissions

The health:check command is a newer and more flexibel version of the original minion:ping command.
Therefore on Sentinel there is no equivalent such as sentinel:ping.

5. Install other versions than stable

Installation packages are available for different releases of OpenNMS Horizon or Minion.
You will 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.

For branches use repofiles/opennms-repo-branches-${branch-name}-rhel7.noarch.rpm.

The installation procedure is the same as with the stable version.

6. Setup Minion with a config 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 ${MINION_HOME}/bin/client command can be used which allows to execute Karaf commands through the Linux shell.

7. Running in non-root environments

This section provides information running OpenNMS Horizon and Minions processes in non-root environments.
Running with a system user have restricted possibilites.
This section describes how to configure your Linux system related to:

sending ICMP packages as an unprivileged user

receiving Syslog on ports < 1023, e.g. 514/udp

receiving SNMP Trap on ports < 1023,e.g. 162/udp

7.1. Send ICMP as non-root

By default, Linux does not allow regular users to perform ping operations from arbitrary programs (including Java).
To enable the Minion or OpenNMS Horizon to ping properly, you must set a sysctl option.

Enable User Ping (Running System)d

# run this command as root to allow ping by any user (does not survive reboots)
sysctl net.ipv4.ping_group_range='0 429496729'

If you wish to restrict the range further, use the GID for the user the Minion or OpenNMS Horizon will run as, rather than 429496729.

To enable this permanently, create a file in /etc/sysctl.d/ to set the range:

/etc/sysctl.d/99-zzz-non-root-icmp.conf

# we start this filename with "99-zzz-" to make sure it's last, after anything else that might have set it
net.ipv4.ping_group_range=0 429496729

7.2. Trap reception as non-root

If you wish your Minion or OpenNMS Horizon to listen to SNMP Traps, you will need to configure your firewall to port forward from the privileged trap port (162) to the Minion’s default trap listener on port 1162.

7.3. Syslog reception as non-root

If you wish your Minion or OpenNMS Horizon 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.

8. Use R for statistical computing

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

OpenNMS Horizon interfaces with R via stdin and stdout, and for this reason, R must be installed on the same host
as OpenNMS Horizon.
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. Install R on RHEL

Install the EPEL repositories

yum install epel-release

Install R

yum install R

8.2. Install R on Debian

Install R

apt -y install r-recommended

9. Using a different Time Series Storage

OpenNMS Horizon stores performance data in a time series storage which is by default JRobin.
For different scenarios it is useful to switch to a different time series storage.
The following implementations are supported:

Table 7. Supported Time Series Databasees

JRobin

JRobin is a clone of RRDTool written in Java, it does not fully cover the latest feature set of RRDTool and is the default when you install OpenNMS Horizon.
Data is stored on the local file system of the OpenNMS Horizon node.
Depending on I/O capabilities it works good for small to medium sized installations.

RRDTool

RRDTool is active maintained and the de-facto standard dealing with time series data.
Data is stored on the local file system of the OpenNMS Horizon node.
Depending on I/O capabilities it works good for small to medium sized installations.

Newts

Newts is a database schema for Cassandra.
The time series is stored on a dedicated Cassandra cluster which gives growth flexibility and allows to persist time series data in a large scale.

This section describes how to configure OpenNMS Horizon to use RRDTool and Newts.

The way how data is stored in the different time series databases makes it extremely hard to migrate from one technology to another.
Data loss can’t be prevented when you switch from one to another.

9.1. 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 Horizon 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 Horizon to use it.

9.1.1. Install RRDTool on RHEL

Following this guide does not cover data migration from JRobin to RRDTool.

To install jrrd2 enable the OpenNMS YUM repository ensure the repositories are enabled.
You can enable them with yum-config-manager --enable opennms-repo-stable-common,opennms-repo-stable-rhel7.

A more current version of RRDTool is in the OpenNMS YUM repository.
The provided versions can be shown with yum info rrdtool.
This guide uses the RRDTool provided in the OpenNMS repository.
When using the CentOS provided RRDTool package verify the path to the rrdtool binary file.

The visualization with the graph engine is optional.
You can still use the default graphing engine backshift by not setting the org.opennms.web.graphs.engine property and use the system default.

Step 3: Restart OpenNMS Horizon and verify setup

find /opt/opennms/share/rrd -iname "*.rrd"

With the first data collection, RRDTool files with extension .rrd will be created.
The JRobin files with extension .jrb are not used anymore and are not deleted automatically.

9.1.2. Reference

The following configuration files have references to the RRDTool binary and may be changed if you have a customized RRDTool setup.

Table 8. References to the RRDtool binary

Configuration file

Property

opennms.properties

rrd.binary=/usr/bin/rrdtool

response-adhoc-graph.properties

command.prefix=/usr/bin/rrdtool

response-graph.properties

command.prefix=/usr/bin/rrdtoolinfo.command=/usr/bin/rrdtool

snmp-adhoc-graph.properties

command.prefix=/usr/bin/rrdtool

snmp-graph.properties

command.prefix=/usr/bin/rrdtoolcommand=/usr/bin/rrdtool info

9.1.3. Install RRDTool on Debian

Following this guide does not cover data migration from JRobin to RRDTool.

A more current version of RRDTool is in the OpenNMS YUM repository.
The provided versions can be shown with apt show rrdtool.
This guide uses the RRDTool provided in the OpenNMS repository.
When using the Debian/Ubuntu provided RRDTool package verify the path to the rrdtool binary file.

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

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

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.

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.

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.

9.2.2. Configure OpenNMS Horizon

Once Cassandra is installed, OpenNMS Horizon can be configured to use Newts.