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.
|
Time synchronization is a critical part of operating a monitoring system. Ensure you have a functional time synchronization process running with your operating system. If you are not familiar with this topic, the knowledgebase article Ensure time synchronization for your OpenNMS components is a good starting point. |
Set up PostgreSQL
sudo dnf -y install postgresql-server postgresql
sudo postgresql-setup --initdb --unit postgresql
sudo systemctl enable --now postgresql
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.
|
sudo -i -u postgres createdb -O opennms opennms
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.
|
sudo vi /var/lib/pgsql/data/pg_hba.conf
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. |
sudo systemctl reload postgresql
sudo yum -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
sudo yum -y install postgresql12-server postgresql12
sudo /usr/pgsql-12/bin/postgresql-12-setup initdb
sudo systemctl enable --now postgresql-12
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.
|
sudo -i -u postgres createdb -O opennms opennms
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.
|
sudo vi /var/lib/pgsql/12/data/pg_hba.conf
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. |
sudo systemctl reload postgresql-12
sudo apt -y install postgresql
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.
|
sudo -u postgres createdb -O opennms opennms
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.
|
docker-compose.yml
filemkdir postgres
cd postgres
vi docker-compose.yml
---
version: '3'
volumes:
data-postgres: {}(1)
services:
database:(2)
image: postgres:14(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. |
docker-compose up -d
docker-compose ps
Name Command State Ports
--------------------------------------------------------------------------------
database docker-entrypoint.sh postgres Up (healthy) 0.0.0.0:5432->5432/tcp
Install the Core instance
For security reasons, Horizon is designed to run within an organization’s protected intranet. Do not expose the web console and login pages directly to the Internet without appropriate isolation controls (for example, a VPN with multi-factor authentication). |
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
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.
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. |
sudo dnf config-manager --disable opennms-repo-stable-*
sudo dnf -y install tree
tree /opt/opennms -L 1
/opt/opennms
├── bin
├── contrib
├── data
├── deploy
├── etc
├── jetty-webapps
├── lib
├── logs -> /var/log/opennms
├── share -> /var/opennms
└── system
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
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.
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. |
sudo yum -y install yum-utils
sudo yum-config-manager --disable opennms-repo-stable-*
sudo yum -y install tree
tree /opt/opennms -L 1
/opt/opennms
├── bin
├── contrib
├── data
├── deploy
├── etc
├── jetty-webapps
├── lib
├── logs -> /var/log/opennms
├── share -> /var/opennms
└── system
sudo apt-key adv --fetch-keys https://debian.opennms.org/OPENNMS-GPG-KEY
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). |
sudo apt -y install opennms
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
sudo apt -y install tree
tree /usr/share/opennms -L 1
/usr/share/opennms
├── bin
├── data
├── deploy
├── etc -> /etc/opennms
├── jetty-webapps
├── lib -> ../java/opennms
├── logs -> /var/log/opennms
├── share -> /var/lib/opennms
└── system
sudo apt -y install gnupg ca-certificates
sudo apt-key adv --fetch-keys https://debian.opennms.org/OPENNMS-GPG-KEY
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). |
sudo apt -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 ~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
sudo apt -y install tree
tree /usr/share/opennms -L 1
/usr/share/opennms
├── bin
├── data
├── deploy
├── etc -> /etc/opennms
├── jetty-webapps
├── lib -> ../java/opennms
├── logs -> /var/log/opennms
├── share -> /var/lib/opennms
└── system
docker-compose.yml
file.mkdir horizon
cd horizon
vi docker-compose.yml
---
version: '3'
volumes:(1)
data-opennms: {}
data-config: {}
services:
horizon:(2)
image: opennms/horizon:29(3)
container_name: horizon
environment:
TZ: 'America/New_York'(4)
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
- data-config:/opt/opennms/etc
command: ["-s"]
ports:(7)
- '8980:8980/tcp'
- '8101:8101/tcp'
healthcheck:
test: [ 'CMD', 'curl', '-f', '-I', 'http://localhost:8980/opennms/login.jsp' ](8)
interval: 1m
timeout: 5s
retries: 3
1 | Volume definitions to persist the Horizon Core data and configuration files. |
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 | Mount directories to store RRD files, PDF reports, and configuration files in a persistent volume. |
7 | Publish ports to access the web UI and the Karaf shell. |
8 | Run an internal health check against the web UI to verify service health status. |
The process inside the container runs as a non-privileged user with user id 10001 .
If you want the configuration files in a bind mount on your local host system, make sure you set permissions and ownership accordingly with chown 10001:10001 ./path/to/my/config-dir .
|
To run a release candidate or a different version, use the public image tags from our repository on DockerHub. |
docker-compose config -q
Set up the Core instance
sudo -u opennms vi /opt/opennms/etc/opennms-datasources.xml
<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. |
sudo /opt/opennms/bin/runjava -s
sudo /opt/opennms/bin/install -dis
The core service user must be able to send ICMP echo requests.
During setup, the permissions for net.ipv4.ping_group_range
are set permanently on boot via /etc/sysctl.d/99-opennms-non-root-icmp.conf
.
Some system kernels do not honor this setting, and in those cases, additional configuration is required to allow binding to privileged ports.
We recommend creating a systemd overlay to add the necessary settings to the service configuration.
Run systemctl edit --full opennms.service
and add the following line to the [Service]
section:
AmbientCapabilities=CAP_NET_RAW CAP_NET_BIND_SERVICE
Reload the systemd unit with systemctl daemon-reload
and restart the service with systemctl restart opennms
.
(For more background on this issue, see H29+ won’t start with permission error to open ICMP socket on Discourse.)
sudo systemctl enable --now opennms
sudo firewall-cmd --permanent --add-port=8980/tcp
sudo systemctl reload firewalld
sudo -u opennms vi /usr/share/opennms/etc/opennms-datasources.xml
<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. |
sudo /usr/share/opennms/bin/runjava -s
sudo /usr/share/opennms/bin/install -dis
The core service user must be able to send ICMP echo requests.
During setup, the permissions for net.ipv4.ping_group_range
are set permanently on boot via /etc/sysctl.d/99-opennms-non-root-icmp.conf
.
Some system kernels do not honor this setting, and in those cases, additional configuration is required to allow binding to privileged ports.
We recommend creating a systemd overlay to add the necessary settings to the service configuration.
Run systemctl edit --full opennms.service
and add the following line to the [Service]
section:
AmbientCapabilities=CAP_NET_RAW CAP_NET_BIND_SERVICE
Reload the systemd unit with systemctl daemon-reload
and restart the service with systemctl restart opennms
.
(For more background on this issue, see H29+ won’t start with permission error to open ICMP socket on Discourse.)
If you are using Uncomplicated Firewall (UFW) as your host firewall, you can allow access to the web user interface with the command:
sudo ufw allow 8980/tcp
mkdir etc
chown 10001:10001 -R etc
docker-compose run horizon -i
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
|
Receive SNMP Traps/Informs
OpenNMS Horizon core lets you receive and process SNMP Traps/Informs out of the box. The OpenNMS Horizon core services run as an unprivileged user and can’t bind on port numbers < 1024 without escalated privileges. For this reason, the default port for the SNMP Trap/Inform listener is set to port number 10162/udp instead of the IANA registered port number 162/udp. The following example shows how to configure the local firewall daemon to forward port 162/udp to 10162/udp.
If you need SNMP Trap listener on port 162/udp directly, see the "Binding to privileged ports" steps in Set up the Core Instance. |
sudo firewall-cmd --permanent --add-masquerade
sudo firewall-cmd --permanent --add-port=162/udp
sudo firewall-cmd --permanent --add-port=10162/udp
sudo firewall-cmd --permanent --add-forward-port=port=162:proto=udp:toport=10162
sudo systemctl reload firewalld
sudo vi /etc/ufw/before.rules
*filter
section*nat
:PREROUTING ACCEPT [0:0]
-A PREROUTING -p udp --dport 162 -j REDIRECT --to-port 10162
COMMIT
sudo ufw allow in 162/udp
sudo ufw allow in 10162/udp
sudo ufw reload
You can verify your firewall and port forwarding configuration by sending an SNMP trap from a remote system to your OpenNMS Horizon core instance with the following command:
snmptrap -v 2c -c public opennms-core-host '' 1.3.6.1.4.1.2021.991.17 .1.3.6.1.2.1.1.6.0 s "Milky Way"(1)(2)
1 | By default, OpenNMS uses the community string public .
If you changed the community string in OpenNMS, use that name here. |
2 | Replace opennms-core-host with the IP or FQDN of your OpenNMS Horizon core instance. |
On RHEL/CentOS the snmptrap
command line tool is part of the net-snmp-utils
.
When you run on Debian/Ubuntu, you have to install the snmp-utils
package.
Your configuration works as expected when you see an SNMP trap event in the web UI.
-
Log in to the web UI.
-
Click
. -
Verify you received a
uei.opennms.org/generic/traps/EnterpriseDefault
event from your test host.
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. |
-
Open
http://core-instance-ip:8980/opennms
in your web browser. -
Log in with with admin/admin.
-
Click admin → Change Password in the navigation bar.
-
Use admin as the current password then type and confirm a new password in the appropriate boxes.
-
Click Submit.
-
Log out, then log in with your new password.
First monitored node
The default configuration will discover a single node with an interface 127.0.0.1 and detect services exposed on the loopback interface, including the OpenNMS-JVM service. Nodes with this service have JMX-based data collection performed on Java JVM statistics such as heap memory and open file handles.