Installation and Configuration (2024)

This section explains how to install and configure a new Meridian instance, including the following tasks:

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 a production environment or monitor large networks.
- By default, your time series database is RRDtool, which persists RRD files on the local file system.
Sign in to the web UI and change the admin account’s default password.

DNS considerations

If you are planning a large deployment, you may need to review your DNS configuration to ensure name lookups can be processed quickly.DNS lookups may be preformed by different processes, including while provisioning new nodes and when receiving syslog messages.It is vital that DNS lookups can be performed quickly to prevent them from becoming a bottleneck, which can happen if your deployment covers thousands of nodes.One way to mitigate DNS performance is to setup your Meridian as a secondary DNS server so that it is able to self-host DNS records for your network.

Requirements

The following components and settings are required to set up a new Meridian instance:

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 necessary.
If you do not include the appropriate SELinux policy, Meridian may generate an ICMP permissions error when starting up (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.

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

Pool size and maximum database connections

You must configure the PostgreSQL max_connections setting to at least twice the maximum pool size in Meridian.

The default maximum pool size value in Meridian is 50, but it applies to each connect in opennms-datasources.xml: opennms (the main connection used at runtime) and opennms-admin (the connection used during administrative operations, including installation).Therefore, your max_connections setting should be at least 100.

If you change the default pool size, make sure you also update the max_connections.You typically set this in PG_HOME/data/postgresql.conf, but you may also use the ALTER SYSTEM syntax.You must restart the PostgreSQL server for the changes to take effect.

You may find PGTune useful to calculate configuration parameters for PostgreSQL.As with all third-party tools, we do not endorse or guarantee it.Use it at your own discretion.

CentOS/RHEL 9
CentOS/RHEL 8
CentOS/RHEL 7

Install language packs and set language

sudo dnf install langpacks-en glibc-all-langpacks -ysudo localectl set-locale LANG=en_US.UTF-8sudo localectlsudo dnf makecachesudo dnf update -ysudo rebootsudo dnf info postgresql-server

These procedures use a specific PostgreSQL version.Make sure you reference your current PostgreSQL version.

Install PostgreSQL client and server

sudo dnf -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpmsudo dnf -y install postgresql14-server

Initialize the PostgreSQL database

sudo /usr/pgsql-14/bin/postgresql-14-setup initdb

Enable PostgreSQL on system boot and start immediately

sudo systemctl enable --now postgresql-14

Create an opennms database user and password

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.

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/14/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-14

Install the core instance

For security reasons, Meridian is designed to run within an organization’s protected intranet.Do not expose the web console or sign in pages directly to the Internet without appropriate isolation controls (for example, a VPN with multi-factor authentication).

CentOS/RHEL 9
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 CentOSbaseurl=https://REPO_USER:REPO_PASS@meridian.opennms.com/packages/2024/stable/rhel9(1)gpgcheck=1gpgkey=http://yum.opennms.org/OPENNMS-GPG-KEYEOFsudo 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 {package-prefix}

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

Note that R-core packages require that you have a PowerTools repository enabled.

(Optional) Install R-core packages for time series trending and forecasting

sudo dnf config-manager --set-enabled powertoolssudo dnf -y install epel-releasesudo 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.

Disable auto updates for OpenNMS Meridian

sudo dnf config-manager --disable meridian

Verify directory structure with the tree command

sudo dnf -y install treetree /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/9

Configure PostgreSQL database access

You can store your PostgreSQL credentials in the secure credentials vault.To do this, use the scvcli command line utility to add the credentials, and reference these credentials in opennms-datasources.xml:

Create encrypted credentials for the PostgreSQL database connections:
```
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.

Edit opennms-datasources.xml with vi:

sudo -u opennms vi /opt/opennms/etc/opennms-datasources.xml

Set encrypted 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" (2) user-name="${scv:postgres:username}" (3) password="${scv:postgres:password}" /> (4)<jdbc-data-source name="opennms-admin" database-name="template1" class-name="org.postgresql.Driver" url="jdbc:postgresql://localhost:5432/template1" (5) user-name="${scv:postgres-admin:username}" (6) password="${scv:postgres-admin:password}" /> (7)...<jdbc-data-source name="opennms-monitor" database-name="postgres" class-name="org.postgresql.Driver" url="jdbc:postgresql://localhost:5432/postgres" (8) user-name="${scv:postgres-admin:username}" (9) password="${scv:postgres-admin:password}" /> (10)...

1	Set the database name that Meridian should use.
2	Set the JDBC connection string to your Postregres server for the instance database.
3	Set the user name to access the opennms database table.
4	Set the password to access the opennms database table.
5	Set the JDBC connection string to your Postregres server for the schema database
6	Set the postgres user for administrative access to PostgreSQL.
7	Set the password for administrative access to PostgreSQL.
8	Set the JDBC connection string to your Postregres server for the system database.
9	Set the postgres user for administrative access to PostgreSQL.
10	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 you cannot upgrade your OS, you need to assign CAP_NET_RAW capabilities:

Run systemctl edit opennms.service and add the following code 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/tcpsudo systemctl reload firewalld

First-time sign in

After you start the Meridian core services, you can access the web application at http://core-instance-ip:8980/opennms.The default user credentials are as follows:

Username: admin
Password: admin

When you try to sign in with these credentials, Meridian prompts you to change your password.Although you also have the option to skip this action and sign in with default the credentials, we strongly recommend that you change the admin account’s password to a secure one.

Type your current password.
Type your new password and confirm it.
Click Change Password.

Change password after first sign in

To change your account’s password after the first time you sign in, follow these steps:

On the top menu bar, click Admin Change Password.
Type your current password and new password in the appropriate fields.
Confirm your new password, and click Submit.

The password is updated.

We encourage you to use Meridian with individual user accounts instead of using only the admin account.If all users have individual accounts, you can see who is completing tasks (for example, clearing or acknowledging alarms).For information on how to create personalized user accounts, see Create a new user in the Quick Start guide.

Usage statistics

The first time you sign in, Meridian notifies you that it collects anonymized usage statistics and publishes them to https://stats.opennms.com.Consent to share collected usage statistics is assumed by default.

The OpenNMS Group uses this 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 Learn More to view the information that we collect and share.This also hides the notification.

Click Dismiss to simply hide the notification.You can view the usage statistics at any time on the admin page.

Admin users can opt out of sharing the statistics at any time.

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.

Startup Configuration
SELinux and ICMP permissions
Receive SNMP traps/informs
Install JDBC Driver on Meridian Core

Next steps

See the Quick Start guide for more information on setting up and configuring your Meridian instance.