Installation and Configuration

Objectives

  • Install all required OpenNMS Meridian components, including PostgreSQL, on a single node.

  • Run Meridian 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 RRDtool, which persists RRD files on the local file system.

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

Requirements

  • Credentials to access the Meridian repositories.

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

  • Internet access to download the installation packages.

  • A working DNS server, and a localhost and server name that resolve properly.

  • A system user with administrative permissions (sudo) to perform installation.

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

PostgreSQL 14 uses the scram-sha-256 password authentication method by default. If you use older versions of PostgreSQL, you should change the method in postgresql.conf and in pg_hba.conf before continuing with the core instance installation.

  • CentOS/RHEL 8

  • CentOS/RHEL 7

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 Meridian 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 Meridian 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 the core instance

For security reasons, Meridian 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).

  • CentOS/RHEL 8

  • CentOS/RHEL 7

Add repository and import GPG key
cat << EOF | sudo tee /etc/yum.repos.d/opennms-meridian.repo
[meridian]
name=Meridian for Red Hat Enterprise Linux and CentOS
baseurl=https://REPO_USER:REPO_PASS@meridian.opennms.com/packages/2021/stable/rhel8(1)
gpgcheck=1
gpgkey=http://yum.opennms.org/OPENNMS-GPG-KEY
EOF

sudo rpm --import https://yum.opennms.org/OPENNMS-GPG-KEY
1 Replace the REPO_USER and REPO_PASS with your Meridian subscription credentials.
Install Meridian with all built-in dependencies
sudo dnf -y install meridian

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 Meridian repository after installation to prevent unwanted upgrades when upgrading other packages on the server. After upgrade, Meridian requires manual steps to upgrade configuration files or migrate database schemas to a new version. We recommend that you exclude the Meridian packages from update except when you plan to perform an upgrade.
Disable auto updates for OpenNMS Meridian
sudo dnf config-manager --disable meridian
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
cat << EOF | sudo tee /etc/yum.repos.d/opennms-meridian.repo
[meridian]
name=Meridian for Red Hat Enterprise Linux and CentOS
baseurl=https://REPO_USER:REPO_PASS@meridian.opennms.com/packages/2021/stable/rhel7(1)
gpgcheck=1
gpgkey=http://yum.opennms.org/OPENNMS-GPG-KEY
EOF

sudo rpm --import https://yum.opennms.org/OPENNMS-GPG-KEY
1 Replace the REPO_USER and REPO_PASS with your Meridian subscription credentials.
Install Meridian with all built-in dependencies
sudo yum -y install meridian

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 Meridian repository after installation to prevent unwanted upgrades when upgrading other packages on the server. After upgrade, Meridian requires manual steps to upgrade configuration files or migrate database schemas to a new version. We recommend that you exclude the Meridian packages from update except when you plan to perform an upgrade.
Disable auto updates for OpenNMS Meridian
sudo yum -y install yum-utils
sudo yum-config-manager --disable meridian
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

Set up the core instance

  • CentOS/RHEL 7/8

Configure PostgreSQL database access
sudo -u opennms 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 Meridian 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
Assign CAP_NET_RAW capabilities

Meridian runs as a non-root user, which requires having a Linux kernel greater than 3.10. If you run on an older kernel, and are unable to upgrade your OS, you need to assign CAP_NET_RAW capabilities:

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

Enable Meridian 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

Receive SNMP traps/informs

Meridian core lets you receive and process SNMP traps/informs out of the box. Meridian services run as an unprivileged user and can’t bind on port numbers below 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 the SNMP trap listener on port 162/udp directly, see the "Binding to privileged ports" steps in Set up the core instance.

  • CentOS/RHEL 7/8

Enable Masquerade to allow port forwarding
sudo firewall-cmd --permanent --add-masquerade
Forward SNMP Trap UDP port 162 to 10162
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

You can verify your firewall and port forwarding configuration by sending an SNMP trap from a remote system to your Meridian core instance:

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 Meridian, use that name here.

  2. Replace opennms-core-host with the IP or FQDN of your Meridian core instance.

On RHEL and CentOS, the snmptrap command line tool is part of the net-snmp-utils. If you run on Debian or Ubuntu, the tool is part of the snmp-utils package.

Your configuration works as expected when you see an SNMP trap event in the web UI.

  1. Log in to the web UI.

  2. Click Status → Events → All events.

  3. Verify you received a uei.opennms.org/generic/traps/EnterpriseDefault event from your test host.

First login

After you start the Meridian 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 the default user name and password.

  3. Click admin → Change Password in the navigation bar.

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

  5. Click Submit.

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