Installation and Configuration
This section explains how to install and configure a new Meridian instance.
Objectives
-
Install all required OpenNMS Meridian components, including PostgreSQL, on a single node.
-
Run Meridian core and PostgreSQL with the default configuration.
The default configuration is not optimized to run in production or monitor large networks. -
By default, your time series database is RRDtool, which persists RRD files on the local file system.
-
-
Log in to the web UI and change the
admin
account’s default 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. -
A SELinux policy that permits binding to the ICMP service (if you are using an operating system that includes SELinux).
Note that failure to include the appropriate SELinux policy may generate an ICMP permission error when starting OpenNMS (see SELinux and ICMP permissions).
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. |
SELinux and ICMP permissions
If you have SELinux enabled on your Meridian server, there must be a policy configured to allow Meridian to bind to the ICMP service.
The steps in this section apply specifically to CentOS 8. |
To verify that you have SELinux running and enabled, use the sestatus
console command.
If it is enabled, you should see the following:
SELinux status: enabled
SELinuxfs mount: /sys/fs/selinux
SELinux root directory: /etc/selinux
Loaded policy name: targeted
Current mode: enforcing
Mode from config file: enforcing
Policy MLS status: enabled
Policy deny_unknown status: allowed
Memory protection checking: actual (secure)
Max kernel policy version: 33
Use audit2allow -a
to check if Meridian violates SELinux policies.
If the audit2allow command is missing, run dnf install policycoreutils-devel to install the package.
|
Look for entries that prevent the binding of ICMP sockets:
#============= unconfined_service_t ==============
allow unconfined_service_t node_t:icmp_socket node_bind;
============= unconfined_service_t ==============
allow unconfined_service_t port_t:icmp_socket name_bind;
Create a type enforcement file (for example, JniPing.te
):
module JniPing 1.0;
require {
type unconfined_service_t;
type node_t;
type port_t;
class icmp_socket { name_bind node_bind };
}
#============= unconfined_service_t ==============
allow unconfined_service_t node_t:icmp_socket node_bind;
allow unconfined_service_t port_t:icmp_socket name_bind;
Create a SElinux module and compile it:
checkmodule -M -m -o JniPing.mod JniPing.te
semodule_package -o JniPing.pp -m JniPing.mod
Install the SELinux package and enforce it:
semodule -i JniPing.pp
getenforce
You can verify the package with the following command: semodule --list-modules | grep JniPing
.
Note that this command is based on the audit2allow
command on a CentOS 8 system.
Set up PostgreSQL
PostgreSQL 14 and 15 use 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.
|
sudo dnf install langpacks-en glibc-all-langpacks -y
sudo localectl set-locale LANG=en_US.UTF-8
sudo localectl
sudo dnf makecache
sudo dnf update -y
sudo reboot
sudo dnf info postgresql-server
These procedures use a specific PostgreSQL version. Make sure you reference your current PostgreSQL version. |
sudo dnf -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm
sudo dnf -y install postgresql14-server
sudo /usr/pgsql-14/bin/postgresql-14-setup initdb
sudo systemctl enable --now postgresql-14
sudo -i -u postgres createuser -P opennms
You must provide a secure password for the opennms database user account.
This guide uses YOUR-OPENNMS-PASSWORD as a placeholder.
|
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/14/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-14
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
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). |
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/2023/stable/rhel9 (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. |
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 ~390MB.
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 upgrading, 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 updates except when you plan to perform an upgrade. |
sudo dnf config-manager --disable meridian
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
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. |
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.
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. |
sudo dnf config-manager --disable meridian
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
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. |
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.
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. |
sudo yum -y install yum-utils
sudo yum-config-manager --disable meridian
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
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 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. |
sudo /opt/opennms/bin/runjava -s
sudo /opt/opennms/bin/install -dis
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.)
sudo systemctl enable --now opennms
sudo firewall-cmd --permanent --add-port=8980/tcp
sudo systemctl reload firewalld
Encrypt database credentials
It is possible to store the PostgreSQL credentials in the secure credentials vault.
To achieve this, use the scvcli
command line utility to add the credentials, and reference these credentials in opennms-datasources.xml
.
sudo -u opennms ${OPENNMS_HOME}/bin/scvcli set postgres opennms password (1)
sudo -u opennms ${OPENNMS_HOME}/bin/scvcli set postgres-admin postgres password
1 | Replace both password instances with the actual passwords for your opennms and postgres database accounts. |
<jdbc-data-source name="opennms"
database-name="opennms"
class-name="org.postgresql.Driver"
url="jdbc:postgresql://localhost:5432/opennms"
user-name="${scv:postgres:username}"
password="${scv:postgres:password}" />
<jdbc-data-source name="opennms-admin"
database-name="template1"
class-name="org.postgresql.Driver"
url="jdbc:postgresql://localhost:5432/template1"
user-name="${scv:postgres-admin:username}"
password="${scv:postgres-admin:password}" />
First-time login and data choices
After you start the Meridian core services, you can access the web application at http://core-instance-ip:8980/opennms
.
The default user login is admin
with the password admin
.
After you log in for the first time, immediately change the admin account’s password to a secure one.
|
The first time you log in, Meridian prompts for permission to allow the Data Choices module to collect and publish anonymous usage statistics to https://stats.opennms.org. The OpenNMS Group uses this anonymized information to help determine product use and to improve the Meridian software. We do not share it with third parties, and we will not use it for sales purposes.

Click Show Me What is Being Sent to see what information we collect. Statistics collection and publication happen only if an admin user opts in.
Admin users can enable or disable statistics collection at any time. |
-
On the top menu bar, click
. -
Type your current password and new password in the appropriate fields.
-
Confirm your new password, and click Submit.
We encourage you to use Meridian with individual user accounts instead of the admin
account.
If all users have individual accounts, you can see who is completing tasks like clearing or acknowledging alarms.
For information on how to create a personalized user account, see Create a new user in the Quick Start guide.
Receive SNMP traps/informs
Meridian core lets you receive and process SNMP traps and 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.
|
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
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, Meridian uses the public community string.
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.
-
Log in to the web UI.
-
Click
. -
Verify that you received a
uei.opennms.org/generic/traps/EnterpriseDefault
event from your test host.
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.
Next steps
See the Quick Start guide for more information on setting up and configuring your Meridian instance.