Installation and configuration

Objectives

  • Install all required OpenNMS Horizon components including PostgreSQL on a single node

  • Run Horizon Core and PostgreSQL with the default configuration (which is not optimized to run in production and monitor large networks)

    • By default your time series storage is JRobin, which persists RRD files on the local file system

  • Log in to the web UI and change the default admin password

Requirements

  • Linux physical server or a virtual machine running a supported Linux operating system

  • Internet access to download the installation packages

  • DNS works and localhost and your server’s host name resolve properly

  • System user with administrative permissions (sudo) to perform installation

  • To run services in Docker you need Docker Compose for the service stacks from our examples

On Debian, you must install and configure sudo yourself. See the Debian Wiki for more information.

Set up PostgreSQL

  • CentOS/RHEL 8

  • CentOS/RHEL 7

  • Debian/Ubuntu

  • Docker

Install PostgreSQL client and server
sudo dnf -y install postgresql-server postgresql
Initialize the PostgreSQL database
sudo postgresql-setup --initdb --unit postgresql
Enable PostgreSQL on system boot and start immediately
sudo systemctl enable --now postgresql
Create an opennms database user and password
sudo -i -u postgres createuser -P opennms
You must provide a password for the opennms database user. This guide uses YOUR-OPENNMS-PASSWORD as a placeholder. Please set a secure password.
Create an empty database and set the owner to the opennms user
sudo -i -u postgres createdb -O opennms opennms
Set a password for PostgreSQL superuser
sudo -i -u postgres psql -c "ALTER USER postgres WITH PASSWORD 'YOUR-POSTGRES-PASSWORD';"
Change YOUR-POSTGRES-PASSWORD to a secure one. The superuser is required to be able to initialize and change the database schema for installation and updates.
Change the access policy for PostgreSQL
sudo vi /var/lib/pgsql/data/pg_hba.conf
Allow Horizon to access the database over the local network with an MD5 hashed password
host    all             all             127.0.0.1/32            md5(1)
host    all             all             ::1/128                 md5(1)
1 Change method from ident to md5 for IPv4 and IPv6 on localhost.
Apply configuration changes for PostgreSQL
sudo systemctl reload postgresql
Add PostgreSQL 12 package repository
sudo yum -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
Install PostgreSQL 12 client and server
sudo yum -y install postgresql12-server postgresql12
Initialize PostgreSQL database
sudo /usr/pgsql-12/bin/postgresql-12-setup initdb
Enable PostgreSQL on system boot and start immediately
sudo systemctl enable --now postgresql-12
Create an opennms database user and password
sudo -i -u postgres createuser -P opennms
You must provide a password for the opennms database user. This guide uses YOUR-OPENNMS-PASSWORD as a placeholder. Please set a secure password.
Create an empty database and set the owner to the opennms user
sudo -i -u postgres createdb -O opennms opennms
Set a password for PostgreSQL superuser
sudo -i -u postgres psql -c "ALTER USER postgres WITH PASSWORD 'YOUR-POSTGRES-PASSWORD';"
Change YOUR-POSTGRES-PASSWORD to a secure one. The superuser is required to initialize and change the database schema for installation and updates.
Change the access policy for PostgreSQL
sudo vi /var/lib/pgsql/12/data/pg_hba.conf
Allow Horizon to access the database over the local network with an MD5 hashed password
host    all             all             127.0.0.1/32            md5(1)
host    all             all             ::1/128                 md5(1)
1 Change method from ident to md5 for IPv4 and IPv6 on localhost.
Apply configuration changes for PostgreSQL
sudo systemctl reload postgresql-12
Install PostgreSQL client and server
sudo apt -y install postgresql
Create an opennms database user and password
sudo -u postgres createuser -P opennms
You must provide a password for the opennms database user. This guide uses YOUR-OPENNMS-PASSWORD as a placeholder. Please set a secure password.
Create an empty database and set the owner to the opennms user
sudo -u postgres createdb -O opennms opennms
Set a password for PostgreSQL superuser
sudo -u postgres psql -c "ALTER USER postgres WITH PASSWORD 'YOUR-POSTGRES-PASSWORD';"
Change YOUR-POSTGRES-PASSWORD to a secure one. The superuser is required to initialize and change the database schema for installation and updates.
Create a project directory for PostgreSQL and create a docker-compose.yml file
mkdir postgres
cd postgres
vi docker-compose.yml
Create the PostgreSQL service and publish the port on your local host
---
version: '3'

volumes:
  data-postgres: {}(1)

services:
  database:(2)
    image: postgres:13(3)
    container_name: database
    environment:(4)
      TZ: 'America/New_York'
      POSTGRES_USER: 'postgres'
      POSTGRES_PASSWORD: 'my-postgres-password'
    volumes:(5)
      - 'data-postgres:/var/lib/postgresql/data'
    healthcheck:(6)
      test: [ "CMD-SHELL", "pg_isready -U postgres" ]
      interval: 10s
      timeout: 3s
      retries: 3
    ports:
      - '5432:5432/tcp'
1 Persist the PostgreSQL database in a local volume.
2 PostgreSQL service is named database with a friendly container_name.
3 Image reference using the official PostgreSQL image.
4 Set the time zone and the postgres credentials for administrative tasks (for example, creating and changing database schemas for upgrades).
5 Mount the volume for persisting the PostgreSQL database files.
6 Run an internal health check to see if the PostgreSQL instance is ready.
Start the service and run it in background
docker-compose up -d
Verify the PostgreSQL process is up and running
docker-compose ps
The state should be Up (healthy) and the TCP port should be available on all interfaces
  Name                Command                 State               Ports
--------------------------------------------------------------------------------
database   docker-entrypoint.sh postgres   Up (healthy)   0.0.0.0:5432->5432/tcp

Install the Core instance

  • CentOS/RHEL 8

  • CentOS/RHEL 7

  • Ubuntu

  • Debian

  • Docker

Add repository and import GPG key
sudo dnf -y install https://yum.opennms.org/repofiles/opennms-repo-stable-rhel8.noarch.rpm
sudo rpm --import https://yum.opennms.org/OPENNMS-GPG-KEY
Install Horizon with all built-in dependencies
sudo dnf -y install opennms

If you want time series trending and forecast functions you must install the R project packages. The additional download size for packages is ~390 MB.

Install R-core packages for time series trending and forecasting (optional)
sudo dnf -y install epel-release
sudo dnf -y install R-core
Disable the OpenNMS Horizon repository after installation to prevent unwanted upgrades when upgrading other packages on the server. After upgrade, Horizon requires manual steps to upgrade configuration files or migrate database schemas to a new version. We recommend that you exclude the Horizon packages from update except when you plan to perform an upgrade.
Disable auto updates for OpenNMS Horizon
sudo dnf config-manager --disable opennms-repo-stable-*
Verify directory structure with the tree command
sudo dnf -y install tree
tree /opt/opennms -L 1
Directory structure after successful installation
/opt/opennms
├── bin
├── contrib
├── data
├── deploy
├── etc
├── jetty-webapps
├── lib
├── logs -> /var/log/opennms
├── share -> /var/opennms
└── system
Add repository and import GPG key
sudo yum -y install https://yum.opennms.org/repofiles/opennms-repo-stable-rhel7.noarch.rpm
sudo rpm --import https://yum.opennms.org/OPENNMS-GPG-KEY
Install Horizon with all built-in dependencies
sudo yum -y install opennms

If you want time series trending and forecast functions you must install the R project packages. The additional download size for packages is ~390 MB.

Install R-core packages for time series trending and forecasting (optional)
sudo yum -y install epel-release
sudo yum -y install R-core
Disable the OpenNMS Horizon repository after installation to prevent unwanted upgrades when upgrading other packages on the server. After upgrade, Horizon requires manual steps to upgrade configuration files or migrate database schemas to a new version. We recommend that you exclude the Horizon packages from update except when you plan to perform an upgrade.
Disable auto updates for OpenNMS Horizon
sudo yum -y install yum-utils
sudo yum-config-manager --disable opennms-repo-stable-*
Verify directory structure with the tree command
sudo yum -y install tree
tree /opt/opennms -L 1
Directory structure after successful installation
/opt/opennms
├── bin
├── contrib
├── data
├── deploy
├── etc
├── jetty-webapps
├── lib
├── logs -> /var/log/opennms
├── share -> /var/opennms
└── system
Add OpenNMS repository GPG key
sudo apt-key adv --fetch-keys https://debian.opennms.org/OPENNMS-GPG-KEY
Add apt repository
sudo add-apt-repository -s 'deb https://debian.opennms.org stable main'
You can safely ignore the message about conflicting distributions (expected stable but got opennms-xx).
Install OpenNMS Horizon with built-in dependencies (optional)
sudo apt -y install opennms
Installing R package for trending and forcasting (optional)

If you want time series trending and forecast functions you have to install the R project packages. The additional download size for packages is ~152 MB.

sudo apt -y install r-recommended
Disable the OpenNMS Horizon repository after installation to prevent unwanted upgrades when upgrading other packages on the server. After upgrade, Horizon requires manual steps to upgrade configuration files or migrate database schemas to a new version. We recommend that you exclude the Horizon packages from update except when you are planning on performing an upgrade.
sudo apt-mark hold libopennms-java \
              libopennmsdeps-java \
              opennms-common \
              opennms-db
Verify directory structure with the tree command
sudo apt -y install tree
tree /usr/share/opennms -L 1
Directory structure after successful installation
/usr/share/opennms
├── bin
├── data
├── deploy
├── etc -> /etc/opennms
├── jetty-webapps
├── lib -> ../java/opennms
├── logs -> /var/log/opennms
├── share -> /var/lib/opennms
└── system
Install GnuPG and add OpenNMS repository GPG key
sudo apt -y install gnupg ca-certificates
sudo apt-key adv --fetch-keys https://debian.opennms.org/OPENNMS-GPG-KEY
Add Apt repository
sudo apt -y install software-properties-common
sudo add-apt-repository -s 'deb https://debian.opennms.org stable main'
sudo apt update
You can safely ignore the message about conflicting distributions (expected stable but got opennms-xx).
Install OpenNMS Horizon with built-in dependencies
sudo apt -y install opennms
Install R packages for trending and forcasting (optional)

If you want time series trending and forecast functions you must install the R project packages. The additional download size for packages is ~134 MB.

sudo apt -y install r-recommended
Disable the OpenNMS Horizon repository after installation to prevent unwanted upgrades when upgrading other packages on the server. After upgrade, Horizon requires manual steps to upgrade configuration files or migrate database schemas to a new version. We recommend that you exclude the Horizon packages from update except when you plan perform an upgrade.
sudo apt-mark hold libopennms-java \
              libopennmsdeps-java \
              opennms-common \
              opennms-db
Verify directory structure with the tree command
sudo apt -y install tree
tree /usr/share/opennms -L 1
Directory structure after successful installation
/usr/share/opennms
├── bin
├── data
├── deploy
├── etc -> /etc/opennms
├── jetty-webapps
├── lib -> ../java/opennms
├── logs -> /var/log/opennms
├── share -> /var/lib/opennms
└── system
Create a project directory for Horizon Core and create a docker-compose.yml file.
mkdir horizon
cd horizon
vi docker-compose.yml
---
version: '3'

volumes:
  data-opennms: {}(1)

services:
  horizon:(2)
    image: opennms/horizon:bleeding(3)
    container_name: horizon
    environment:(4)
      TZ: 'America/New_York'
      POSTGRES_HOST: 'my-database-host'(5)
      POSTGRES_PORT: 5432
      POSTGRES_USER: 'postgres'
      POSTGRES_PASSWORD: 'my-postgres-password'
      OPENNMS_DBNAME: 'opennms-core-db'
      OPENNMS_DBUSER: 'opennms'
      OPENNMS_DBPASS: 'my-opennms-db-password'
    volumes:(6)
      - data-opennms:/opennms-data
      - ./etc:/opt/opennms/etc(7)
    command: ["-s"]
    ports:(8)
      - '8980:8980/tcp'
      - '8101:8101/tcp'
    healthcheck:
      test: [ 'CMD', 'curl', '-f', '-I', 'http://localhost:8980/opennms/login.jsp' ](9)
      interval: 1m
      timeout: 5s
      retries: 3
1 Volume definitions to persist the Horizon Core data; for example, RRD files and PDF reports.
2 The Horizon Core instance service is named horizon with a friendly container_name.
3 Image reference using the Horizon container image with the Core services.
4 Set the time zone and the postgres credentials to initialize the database that the Horizon Core instance uses. To list all available time zones, use timedatectl list-timezones.
5 Set the host or IP address of the host that runs the PostgreSQL database.
6 Persist performance data PDF reports in a volume.
7 Mount the volumes for data persistence and bind mount the configuration in a local directory.
8 Publish ports to access the web UI and the Karaf shell.
9 Run an internal health check against the web UI to verify service health status.
Validate your Docker Compose file
docker-compose config -q

Set up the Core instance

  • CentOS/RHEL 7/8

  • Debian/Ubuntu

  • Docker

Configure PostgreSQL database access
sudo vi /opt/opennms/etc/opennms-datasources.xml
Set credentials to access the PostgreSQL database
<jdbc-data-source name="opennms"
                    database-name="opennms"(1)
                    class-name="org.postgresql.Driver"
                    url="jdbc:postgresql://localhost:5432/opennms"
                    user-name="** YOUR-OPENNMS-USERNAME **"(2)
                    password="** YOUR-OPENNMS-PASSWORD **" />(3)

<jdbc-data-source name="opennms-admin"
                    database-name="template1"
                    class-name="org.postgresql.Driver"
                    url="jdbc:postgresql://localhost:5432/template1"
                    user-name="postgres"(4)
                    password="** YOUR-POSTGRES-PASSWORD **" />(5)
1 Set the database name Horizon should use.
2 Set the user name to access the opennms database table.
3 Set the password to access the opennms database table.
4 Set the postgres user for administrative access to PostgreSQL.
5 Set the password for administrative access to PostgreSQL.
Detect and assign Java environment and persist in /opt/opennms/etc/java.conf
sudo /opt/opennms/bin/runjava -s
Initialize the database and detect system libraries persisted in /opt/opennms/etc/libraries.properties
sudo /opt/opennms/bin/install -dis
Enable Horizon core instance on system boot and start immediately
sudo systemctl enable --now opennms
Allow connection to the web UI from your network
sudo firewall-cmd --permanent --add-port=8980/tcp
sudo systemctl reload firewalld
To receive SNMP Traps or Syslog messages you must allow incoming traffic on your host firewall as well. By default, the OpenNMS Horizon SNMP trap daemon listens on 162/udp and the Syslog daemon listens on 10514/udp. The SNMP Trap daemon is enabled by default, the OpenNMS Syslog daemon is disabled.
Configure PostgreSQL database access
sudo vi /usr/share/opennms/etc/opennms-datasources.xml
Set credentials to access the PostgreSQL database
<jdbc-data-source name="opennms"
                    database-name="opennms"(1)
                    class-name="org.postgresql.Driver"
                    url="jdbc:postgresql://localhost:5432/opennms"
                    user-name="** YOUR-OPENNMS-USERNAME **"(2)
                    password="** YOUR-OPENNMS-PASSWORD **" />(3)

<jdbc-data-source name="opennms-admin"
                    database-name="template1"
                    class-name="org.postgresql.Driver"
                    url="jdbc:postgresql://localhost:5432/template1"
                    user-name="postgres"(4)
                    password="** YOUR-POSTGRES-PASSWORD **" />(5)
1 Set the database name Horizon should use.
2 Set the user name to access the opennms database table.
3 Set the password to access the opennms database table.
4 Set the postgres user for administrative access to PostgreSQL.
5 Set the password for administrative access to PostgreSQL.
Detect Java environment and persist in /usr/share/opennms/etc/java.conf
sudo /usr/share/opennms/bin/runjava -s
Initialize the database and detect system libraries persisted in /opt/opennms/etc/libraries.properties
sudo /usr/share/opennms/bin/install -dis
Enable Horizon core instance on system boot and start immediately
sudo systemctl enable --now opennms
By default the OpenNMS SNMP Trap daemon listens on 162/udp and the Syslog daemon listens on 10514/udp. The SNMP Trap daemon is enabled by default, the OpenNMS Syslog daemon is disabled.
Prepare a local configuration directory to run as an unprivileged user
mkdir etc
chown 10001:10001 -R etc
Initialize the database and schema and a configuration directory
docker-compose run horizon -i
Start service in background
docker-compose up -d
You can also use this command when you run upgrades. You must delete the file etc/configured file first. It works as a guard to prevent unnecessary database migration runs on startup.

Show configuration changes from a pristine system with
docker-compose exec -w /opt/opennms/bin horizon ./config-diff.sh -d.

If you changed your configuration files manually you can run the configuration tester with
docker-compose exec horizon bin/config-tester -a

First login

After you start the Horizon Core services, access the web application at
http://core-instance-ip:8980/opennms. The default login and password is admin.

Immediately change the password to a secure one.
  1. Open http://core-instance-ip:8980/opennms in your web browser.

  2. Log in with with admin/admin.

  3. Click adminChange Password in the navigation bar.

  4. Use admin as the current password then type and confirm a new password in the appropriate boxes.

  5. Click Submit.

  6. Log out, then log in with your new password.