Install Minion
Objectives
-
Install a Meridian Minion on one of the supported operating systems.
-
Secure access to the Karaf shell with encrypted passwords.
-
Configure connection to message broker for communication with the Meridian core instance.
-
Verify the setup.
Requirements
-
A Meridian core instance running and configured with a message broker.
-
A Linux physical server or a virtual machine running a supported Linux operating system.
-
Internet access to download the installation packages.
-
Java installed OpenJDK 11 or 17.
-
DNS configured so that
localhost
and your server’s host name resolve properly. -
A Meridian core instance runs on latest stable release.
-
A Minion server can access desired message broker nodes (for example, ActiveMQ
61616/tcp
, Apache Kafka9092/tcp
). -
A system user with administrative permissions (sudo) to perform the installation tasks.
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. |
Install the Minion package
sudo dnf -y install java-11-openjdk-headless
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/2024/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 {package-prefix}-minion
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. For this reason, 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/minion -L 1
/opt/minion
├── bin
├── COPYING
├── deploy
├── etc
├── lib
├── repositories
└── system
sudo systemctl enable --now minion
sudo dnf -y install java-11-openjdk-headless
On some distributions, such as Oracle Linux 8, you may also need to manually install the tzdata-java package.
|
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/2024/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 {package-prefix}-minion
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. For this reason, 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/minion -L 1
/opt/minion
├── bin
├── COPYING
├── deploy
├── etc
├── lib
├── repositories
└── system
sudo systemctl enable --now minion
sudo yum -y install java-11-openjdk-headless
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/2024/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 {package-prefix}-minion
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. For this reason, 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/minion -L 1
/opt/minion
├── bin
├── COPYING
├── deploy
├── etc
├── lib
├── repositories
└── system
sudo systemctl enable --now minion
docker-compose.yml
file.mkdir minion
cd minion
vi docker-compose.yml
---
version: '3'
services:
minion:
image: opennms/meridian-minion:2024.1.5
container_name: minion(1)
environment:
TZ: 'America/New_York'(2)
JAVA_MIN_MEM: 512M(3)
JAVA_MAX_MEM: 2048M(4)
command: ["-c"]
volumes:
- ./minion-config.yaml:/opt/minion/minion-config.yaml(5)
#- ./keystore/scv.jce:/opt/minion/etc/scv.jce(6)
healthcheck:
test: "/health.sh"(7)
interval: 30s
timeout: 6s
retries: 3
ports:(8)
- '514:1514/udp'
- '162:1162/udp'
- '8201:8201/tcp'
1 | Friendly container name |
2 | Set the time zone and the Minion configuration via environment variables. To list all available time zones, use timedatectl list-timezones . |
3 | Optional. Use to control the minimal Java heap size. |
4 | Optional. Use to control the maximum Java heap size. |
5 | Configuration file for connectivity and features |
6 | Keystore file with encrypted credentials for authenticating broker endpoints. Initially this line should be commented out, and will need to be activated after the file has been created on the local system. |
7 | Run our health check to indicate the Minion is ready. It uses the opennms:health-check internally running in Karaf. |
8 | Publish ports for Syslog, SNMP trap listener, and the SSH access to the Karaf shell. |
The Minion process in the container runs as a non-root user and can’t open privileged ports < 1024. We open the listener for privileged (514/udp, 162/udp) and don’t have to give additional permissions to the Minion process in the container.
Some environments do not allow the use of ICMP (ping) for non-root users.
Meridian Minion runs as a non-privileged user in the container with userid=10001, groupid=10001 .
You can verify with sysctl -n net.ipv4.ping_group_range if the group id 10001 is in the allowed group range.
If not, add the following lines in your service definition in the docker-compose.yml file.
|
sysctls:
net.ipv4.ping_group_range: "10001 10001"
---
broker-url: 'failover:tcp://core-instance-ip:61616'(1)
id: 'my-minion'(2)
location: 'my-location'(3)
netmgt:
syslog:(4)
syslog.listen.interface: "0.0.0.0"
syslog.listen.port: 1514
traps:(5)
trapd.listen.interface: "0.0.0.0"
trapd.listen.port: 1162
1 | Replace the broker endpoint URL that goes to your Meridian Core instance. If you have ActiveMQ with SSL running, replace tcp with ssl . |
2 | Replace my-location with a location name that represents the remote location where the Minion is running. |
3 | Optional. You can set a unique human-readable Minion identifier; if not set, a unique identifier is generated. |
4 | Enable the Syslog listener on the Minion on port 1514/udp. |
5 | Enable the SNMP trap listener on the Minion on port 1162/udp. |
To run with Apache Kafka or configure flow listeners, see the Minion configuration reference. |
Next, we need to create the keystore file and add the credentials for connecting to the core Meridian server.
mkdir keystore
chown -R 10001:10001 keystore(1)
docker-compose run --rm -v $(pwd)/keystore:/keystore minion -s(2)
1 | Assign ownership so the container user account can write within the directory. |
2 | When prompted, enter the username and password for a ROLE_MINION user account on the Meridian server.
You may be prompted for the same username and password twice. |
docker-compose.yml
file to uncomment the keystore file- #- ./keystore/scv.jce:/opt/minion/etc/scv.jce
+ - ./keystore/scv.jce:/opt/minion/etc/scv.jce
docker-compose config -q
docker-compose up -d
docker-compose exec minion bin/client opennms:health-check
Verifying installed bundles [ Success ]
Connecting to JMS Broker [ Success ]
=> Everything is awesome
Secure access to Karaf shell
Change the default username and password (admin/admin) for the Karaf shell and encrypt it. |
ssh -p 8201 admin@localhost
config:edit org.apache.karaf.jaas
config:property-set encryption.enabled true
config:property-set encryption.algorithm SHA-512
config:property-set encryption.name jasypt
config:update
If you set the encryption.name option, you will need to reset any existing passwords that were created while encryption.enabled was set to true .
|
jaas:realm-manage --index 1 --realm karaf
jaas:user-add admin my-secure-password(1)
jaas:update
1 | Replace my-secure-password with a strong password. |
Log out and log back in to verify that your new password is set.
Changes to the password and encryption algorithm are 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 you do not need to restart the Minion.
If you have a firewall running on your host, allow 8201/tcp to grant access to the Karaf shell.
|
Configure connectivity to the core instance
Set configuration settings in the Minion etc
directory.
We reference etc
relative to the OpenNMS Minion home directory.
Depending on your operating system, the home directory is /usr/share/minion
for Debian and Ubuntu or /opt/minion
for CentOS and RHEL.
If you are deploying in a container, this step should have been completed as part of the container definition. |
sudo vi etc/featuresBoot.d/disable-activemq.boot
!minion-jms
!opennms-core-ipc-jms
sudo vi etc/featuresBoot.d/kafka.boot
opennms-core-ipc-kafka
ssh -p 8201 admin@localhost
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 that represents the remote location where the Minion is running. |
3 | Save the configuration. |
By default, the Minion generates a unique ID.
Provide a human-readable Minion identifier yourself with config:property-set id my-minion-name
.
config:edit org.opennms.core.ipc.kafka
config:property-set bootstrap.servers my-kafka-ip-1:9092,my-kafka-ip-2:9092(1)
config:update
1 | Adjust the IPs or FQDNs and the Kafka port (9092) to match your broker configuration. |
If you set more than one Kafka node as bootstrap.servers
the driver attempts 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 used only if the connection to the first entry fails.
You can use any valid Kafka configuration property. The following example uses SASL/SCRAM with TLS:
config:edit org.opennms.core.ipc.kafka
config:property-set bootstrap.servers my-kafka-ip-1:9096,my-kafka-ip-2:9096
config:property-set security.protocol=SASL_SSL
config:property-set sasl.mechanism SCRAM-SHA-512
config:property-set sasl.jaas.config 'org.apache.kafka.common.security.scram.ScramLoginModule required username="opennms-ipc" password="kafka";'
config:update
You can configure module-specific values for modules sink , rpc , and twin by replacing org.opennms.core.ipc.kafka in the config:edit command with org.opennms.core.ipc.sink.kafka , org.opennms.core.ipc.rpc.kafka , and org.opennms.core.ipc.twin.kafka , respectively.
Module-specific configuration values take precedence over common configuration values.
|
Exit the Karaf shell with Ctrl+d
By default, the Minion will use a topic prefix of OpenNMS
.
If you chose to use a different prefix in core (for example, to use a single Apache Kafka cluster with multiple Meridian instances), change the topic prefix by setting the org.opennms.instance.id
system property in $MINION_HOME/etc/custom.system.properties
:
org.opennms.instance.id=MyNMS(1)
1 | Change MyNMS to the prefix used by the Meridian instance that this Minion should connect to. |
sudo systemctl restart minion
ssh -p 8201 admin@localhost
opennms:health-check
Verifying the health of the container
Echo RPC (passive) [ Success ]
Verifying installed bundles [ Success ]
Connecting to Kafka from RPC [ Success ]
Connecting to Kafka from Sink Producer [ Success ]
Connecting to Kafka from Twin [ Success ]
=> Everything is awesome
admin
and password admin
ssh -p 8201 admin@localhost
config:edit org.opennms.minion.controller(1)
config:property-set location my-location(2)
config:property-set broker-url failover:tcp://core-instance-ip:61616(3)
config:update(4)
1 | Edit the Minion configuration. |
2 | Replace my-location with a location name that represents the remote location where the Minion is running. |
3 | Replace the broker URL that goes to your Meridian Core instance. If you have ActiveMQ with SSL running, replace tcp with ssl . |
4 | Save the configuration. |
By default, the Minion generates a unique ID.
Provide a human-readable Minion identifier yourself with config:property-set id my-minion-name
opennms:scv-set opennms.broker my-minion-user my-minion-password(2)
The credentials are encrypted on disk in ${MINION_HOME}/etc/scv.jce .
|
Exit the Karaf shell with Ctrl+d
sudo systemctl restart minion
ssh -p 8201 admin@localhost
opennms:health-check
Verifying installed bundles [ Success ]
Connecting to JMS Broker [ Success ]
=> Everything is awesome
sudo vi etc/featuresBoot.d/disable-activemq.boot
!minion-jms
!opennms-core-ipc-jms
sudo vi etc/featuresBoot.d/grpc.boot
opennms-core-ipc-grpc-client
ssh -p 8201 admin@localhost
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 that represents the remote location where the Minion is running. |
3 | Save the configuration. |
By default, the Minion generates a unique ID.
Provide a human-readable Minion identifier yourself with config:property-set id my-minion-name
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 instance. Replace the core-instance-ip accordingly. |
2 | Set the port of the gRPC server, which is 8990 by default. |
3 | Save the configuration. |
systemctl restart minion
ssh -p 8201 admin@localhost
opennms:health-check
admin@minion> opennms:health-check
Verifying the health of the container
Verifying installed bundles [ Success ]
Connecting to gRPC IPC Server [ Success ]
=> Everything is awesome
Optional. To enable TLS for gRPC you must provide certificate files and enable it. The commands for TLS appear below.
ssh -p 8201 admin@localhost
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 maximum size must be the same on the Meridian Core instance. The default message size is 10 MiB.
config:edit org.opennms.core.ipc.grpc.client
config:property-set max.message.size 10485760
config:update
sudo systemctl restart opennms
Receive Trap/Syslog Messages
By default, the Minion service only listens for traps and syslog messages on the localhost interface. If you would like to receive messages on the Minion, the interfaces and ports need to be configured.