Installing Minion

Objectives

  • Install a Meridian Minion on one of the following operating systems

  • Secure access with encrypted passwords to the Karaf shell

  • Configure connection to message broker for communication with the Meridian core instance

  • Verify the setup

Requirements

  • The Meridian core instance is running and configured with a message broker

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

  • Internet access to download the installation packages

  • Java installed OpenJDK 8, OpenJDK 11

  • DNS is configured, localhost and your server’s host name is resolved properly

  • Meridian core instance runs on latest stable release

  • Minion server can access the Meridian core instance via REST (8980/tcp) and desired message broker nodes (e.g., ActiveMQ 61616/tcp, Apache Kafke 9092/tcp)

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

Installing the Minion package

  • CentOS/RHEL 8

  • CentOS/RHEL 7

Install OpenJDK 11 JRE runtime
sudo dnf -y install java-11-openjdk-headless
Add repository and import GPG key

Configure the repository by copying the Meridian repository file you received from OpenNMS Sales to the Minion server.

Install the Meridian Minion package
sudo dnf -y install meridian-minion
We recommend disabling the OpenNMS Meridian repository after installation to prevent unwanted upgrades while it is running. Meridian requires some manual steps upon upgrade configuration files or migrate database schemas to a new version. For this reason, it is recommended to exclude the Meridian packages from update except when you are planning on performing an upgrade.
Disable auto updates for Meridian Minion
sudo dnf config-manager --disable opennms-repo-stable-*
Verify directory structure with the tree command
sudo dnf -y install tree
tree /opt/minion -L 1
Directory structure after successful installation
/opt/minion
├── bin
├── COPYING
├── deploy
├── etc
├── lib
├── repositories
└── system
Enable Meridian Minion on system boot and start immediately
sudo systemctl enable --now minion
Install OpenJDK 11 JRE runtime
sudo yum -y install java-11-openjdk-headless
Add repository and import GPG key

Configure the repository by copying the Meridian repository file you received from OpenNMS Sales to the Minion server.

Install the Meridian Minion package
sudo yum -y install meridian-minion
We recommend disabling the OpenNMS Meridian repository after installation to prevent unwanted upgrades while it is running. Meridian requires some manual steps upon upgrade configuration files or migrate database schemas to a new version. For this reason, it is recommended to exclude the Meridian packages from update except when you are planning on performing an upgrade.
Disable auto updates for Meridian Minion
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/minion -L 1
Directory structure after successful installation
/opt/minion
├── bin
├── COPYING
├── deploy
├── etc
├── lib
├── repositories
└── system
Enable Meridian Minion on system boot and start immediately
sudo systemctl enable --now minion

Secure Access to Karaf Shell

Change the default user/password admin/admin for the Karaf shell and encrypt it.
  • CentOS/RHEL 7/8

Enable password encryption
sudo vi /opt/minion/etc/org.apache.karaf.jaas.cfg
#
# Boolean enabling / disabling encrypted passwords
#
encryption.enabled = true(1)
#...
encryption.algorithm = SHA-512(2)
1 Enable password encryption from false to true
2 Set a secure encryption algorithm like SHA-512

As soon the file is saved, Karaf will immediately encrypt the password in users.properties.

Set a secure admin password for Karaf
sudo vi /opt/minion/etc/users.properties
# All users, groups, and roles entered in this file are available after Karaf startup
# and modifiable via the JAAS command group. These users reside in a JAAS domain
# with the name "karaf".
#
# OPENNMS: Change the admin user from 'karaf' to 'admin'
admin = {CRYPT}C7AD...{CRYPT},_g_:admingroup(1)
1 Replace the whole string {CRYPT}C7AD…​{CRYPT} with your new password in plainttext. As soon you save the file the password will be SHA-512 encrypted.
Set restrictive file permissions
sudo chmod 600 /opt/minion/etc/users.properties
Changing the password or encryption algorithm get applied immediately. You do not need to restart the Minion.
By default, the Karaf Shell is restricted to 127.0.0.1. To enable remote access, set sshHost=0.0.0.0 in org.apache.karaf.shell.cfg. The change is applied immediately and a Minion restart is not required. If you have firewall running on your host, allow 8201/tcp to grant access to the Karaf Shell.

Configure Connectivity to the Core Instance

Configurations has to be made in the Meridian etc directory. We reference etc relative to the OpenNMS Meridian core home directory. Depending on your operating system the home directory is /usr/share/opennms for Debian/Ubuntu or /opt/opennms for CentOS/RHEL.
  • Kafka

  • ActiveMQ

  • gRPC

  • AWS SQS

Create a file to prevent installing ActiveMQ features on Minion startup
sudo vi etc/featuresBoot.d/disable-activemq.boot
Add the following lines to disable ActiveMQ features and save the file
!minion-jms
!opennms-core-ipc-rpc-jms
!opennms-core-ipc-sink-camel
Create a file to install Kafka features on Minion startup
sudo vi etc/featuresBoot.d/kafka.boot
Add the following lines to install the remote producer call (RPC) and sink feature for Kafka on Minion startup and save the file
opennms-core-ipc-rpc-kafka
opennms-core-ipc-sink-kafka
Configure the Kafka features and the Minion location via the Karaf Shell
ssh -p 8201 admin@localhost
Configure the Minion location and REST endpoint
config:edit org.opennms.minion.controller(1)
config:property-set location my-location(2)
config:property-set http-url http://core-instance-ip:8980/opennms(3)
config:update(4)
1 Edit the minion configuration
2 Replace my-location with a location name representing your remote location the Minion is running
3 Replace the example http-url with the URL of your Meridian Core instance
4 Save the configuration
By default the Minion generates a unique id. If you want to provide a human readable Minion identifier yourself with config:property-set id my-minion-name
Configure the credentials for the REST endpoint and exit Karaf shell
opennms:scv-set opennms.http my-minion-user my-minion-password(1)
1 Set the credentials for the REST endpoint created in your Meridian Core instance
The credentials are encrypted on disk in etc/scv.jce.
Configure the Kafka endpoints for RPC feature
config:edit org.opennms.core.ipc.rpc.kafka
config:property-set bootstrap.servers my-kafka-ip-1:9092,my-kafka-ip-2:9092(1)
config:update
1 Connect to the following Kafka nodes and adjust the IPs or FQDNs with the Kafka port (9092) accordingly.
Configure the Kafka endpoints for Sink feature
config:edit org.opennms.core.ipc.sink.kafka
config:property-set bootstrap.servers my-kafka-ip-1:9092,my-kafka-ip-2:9092(1)
config:update
1 Connect to the following Kafka nodes and adjust the IPs or FQDNs with the Kafka port (9092) accordingly.
If you set more than one Kafka node as bootstrap.servers the driver will attempt to connect to the first entry. If that is successful the whole broker topology will be discovered and will be known by the client. The other entries are only used if the connection to the first entry fails.
Ensure you use the FQDN or IP for your Kafka nodes as configured as advertised listener.

Exit the Karaf Shell with Ctrl+d

Restart the Minion to apply the configuration
sudo systemctl restart minion
Verify the configuration using the health check in the Karaf Shell
ssh -p 8201 admin@localhost
Run the health check command
opennms:health-check
Verify if all components are configured properly
Verifying the health of the container

Connecting to OpenNMS ReST API           [ Success  ]
Verifying installed bundles              [ Success  ]
Connecting to Kafka from RPC             [ Success  ]
Connecting to Kafka from Sink Producer   [ Success  ]

=> Everything is awesome
Connect to the Karaf shell with user admin and password admin
ssh -p 8201 admin@localhost
Configure REST endpoints, ActiveMQ and remote location name
config:edit org.opennms.minion.controller(1)
config:property-set location my-location(2)
config:property-set http-url http://core-instance-ip:8980/opennms(3)
config:property-set broker-url failover:tcp://core-instance-ip:61616(4)
config:update(5)
1 Edit the minion configuration
2 Replace my-location with a location name representing your remote location the Minion is running
3 Replace the REST endpoint URL which goes to your Meridian Core instance
4 Replace the Broker URL which goes to your Meridian Core instance. If you have ActiveMQ with SSL running replace tcp with ssl.
5 Save the configuration
By default the Minion generates a unique id. If you want to provide a human readable Minion identifier yourself with config:property-set id my-minion-name
Configure the credentials and exit Karaf shell
opennms:scv-set opennms.http my-minion-user my-minion-password(1)
opennms:scv-set opennms.broker my-minion-user my-minion-password(2)
1 Set the credentials for the REST endpoint created in your Meridian Core instance
2 Set the credentials for the ActiveMQ message broker
The credentials are encrypted on disk in etc/scv.jce.

Exit the Karaf Shell with Ctrl+d

Restart the Minion to apply the configuration
sudo systemctl restart minion
Verify the configuration using the health check in the Karaf Shell
ssh -p 8201 admin@localhost
Run the health check to verify connectivity
opennms:health-check
The result should show Success for each component
Connecting to OpenNMS ReST API   [ Success  ]
Verifying installed bundles      [ Success  ]
Connecting to JMS Broker         [ Success  ]
=> Everything is awesome
Create a file to prevent installing ActiveMQ features on Minion startup
sudo vi etc/featuresBoot.d/disable-activemq.boot
Add the following lines to disable ActiveMQ features and save the file
!minion-jms
!opennms-core-ipc-rpc-jms
!opennms-core-ipc-sink-camel
Create a file to install gRPC features on startup
sudo vi etc/featuresBoot.d/grpc.boot
Add the gRPC client features
opennms-core-ipc-grpc-client
Configure the gRPC client and the Minion location via the Karaf Shell
ssh -p 8201 admin@localhost
Configure the Minion location and REST endpoint
config:edit org.opennms.minion.controller(1)
config:property-set location my-location(2)
config:update(3)
1 Edit the minion configuration
2 Replace my-location with a location name representing your remote location the Minion is running
3 Save the configuration
By default the Minion generates a unique id. If you want to provide a human readable Minion identifier yourself with config:property-set id my-minion-name
Configure the gRPC endpoint
config:edit org.opennms.core.ipc.grpc.client
config:property-set host core-instance-ip(1)
config:property-set port 8990(2)
config:update(3)
1 Set the host to connect to the gRPC server running on the Meridian Core server, replace the core-instance-ip accordingly
2 Set the port of the gRPC server which is by default 8990
3 Save the configuration
Restart the Minion to apply the changes
systemctl restart minion
Verify the configuration using the health check in the Karaf Shell
ssh -p 8201 admin@localhost
Run the health check command
opennms:health-check
Verify if all components are configured properly
admin@minion> opennms:health-check
Verifying the health of the container

Connecting to OpenNMS ReST API   [ Success  ]
Verifying installed bundles      [ Success  ]
Connecting to gRPC IPC Server    [ Success  ]

=> Everything is awesome
This optional, if you want to enable TLS for gRPC you have to provide certificate files and enable it. The commands for TLS are described below.
Connect to the Karaf Shell
ssh -p 8201 admin@localhost
Configure TLS and certificate parameters
config:edit org.opennms.core.ipc.grpc.client
config:property-set tls.enabled true(1)
config:property-set trust.cert.filepath /custom-path/ca.crt(2)
config:property-set client.cert.filepath /custom-path/client.crt(3)
config:property-set client.private.key.filepath /custom-path/client.pem(4)
config:update(5)
1 Enable TLS for the gRPC server
2 Set the path to your CA certificate file
3 Set the path to your client certificate file
4 Set the path client certificate key file
5 Save and update the configuration
This is optional and you can set a maximum message size for gRPC. The maxium size has to be the same on the Meridian Core server instance as well. If you don’t set a maximum message size the default is 10 MiB.
Configure maximum message size for gRPC in the Karaf Shell
config:edit org.opennms.core.ipc.grpc.client
config:property-set max.message.size 10485760
config:update
Apply the changes with restarting Meridian Core instance
sudo systemctl restart opennms
Create a file to install AWS SQS features on Minion startup
sudo vi etc/featuresBoot.d/aws-sqs.boot
Add the following lines to disable ActiveMQ and load AWS SQS
!minion-jms
!opennms-core-ipc-rpc-jms
!opennms-core-ipc-sink-camel
opennms-core-ipc-rpc-aws-sqs
opennms-core-ipc-sink-aws-sqs
Configure the AWS SQS via the Karaf Shell
ssh -p 8201 admin@localhost
config:edit org.opennms.core.ipc.aws.sqs(1)
config:property-set aws_region us-east-1(2)
config:property-set aws_access_key_id my-access-key(3)
config:property-set aws_secret_access_key my-secret-access-key(4)
config:property-set sink.FifoQueue false(5)
config:update(6)
1 Configure the AWS SQS feature
2 Set AWS SQS region
3 The AWS SQS access key
4 The AWS SQS secret for the access key
5 If consistent ordering of incoming messages is required, FIFO queues can be used, the default is false and must match with the Core server setting
6 Save and update the configuration
Restart the Minion to apply the configuration
sudo systemctl restart minion
Verify the configuration using the health check in the Karaf Shell
ssh -p 8201 admin@localhost
Run the health check command
opennms:health-check
Verify if all components are configured properly
Verifying the health of the container

Connecting to OpenNMS ReST API           [ Success  ]
Verifying installed bundles              [ Success  ]
Connecting to AWS-SQS from RPC           [ Success  ]
Connecting to AWS-SQS from Sink Producer [ Success  ]

=> Everything is awesome
You can find available configuration parameters in the Amazon Simple Queueing Services reference section.

Check Minion in the Core web UI

  1. Log in to the web UI as an administrative user.

  2. Click the gears icon and choose Manage Minions in the Distributed Monitoring area.

After a few minutes your Minion should be provisioned automatically and the status should be up.