
[[install-minion]]
= Install Minion
:description: How to install OpenNMS Minion on CentOS/RHEL 7-9, Debian/Ubuntu, Docker, and configure with message brokers: Kafka, ActiveMQ, Embedded ActiveMQ, gRPC.

[[objectives]]
== Objectives

* Install a {page-component-title} Minion on one of the supported <<minion/system-requirements.adoc#operating-systems-Core, operating systems>>.
* Secure access to the xref:reference:karaf-shell/karaf-shell.adoc[Karaf shell] with encrypted passwords.
* Configure connection to message broker for communication with the {page-component-title} core instance.
* Verify the setup.

== Requirements

* A {page-component-title} core instance running and configured with a <<core/setup-message-broker.adoc#setup-message-broker,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 {compatible-javajdk}.
* DNS configured so that `localhost` and your server's host name resolve properly.
* A {page-component-title} core instance runs on latest stable release.
* A Minion server can access desired message broker nodes (for example, ActiveMQ `61616/tcp`, Apache Kafka `9092/tcp`).
* A system user with administrative permissions (sudo) to perform the installation tasks.
ifeval::["{page-component-title}" == "Horizon"]
* If you are running the services in link:https://docs.docker.com/[Docker], you also need link:https://docs.docker.com/compose/install[Docker Compose] for the service stacks from our examples.

NOTE: If you run Debian, you must install and configure `sudo` yourself (see the link:https://wiki.debian.org/sudo/[Debian Wiki]).
endif::[]

include::../time-sync.adoc[]

== Install the Minion package

[{tabs}]
====
CentOS/RHEL 9::
+
--
include::centos-rhel9/install-minion.adoc[]
--

Docker::
+
--
include::docker/minion.adoc[]
--

ifeval::["{page-component-title}" == "Horizon"]
Ubuntu::
+
--
include::ubuntu/install-minion.adoc[]
--

Debian::
+
--
include::debian/install-minion.adoc[]
--

endif::[]
====

== SELinux

Minion does not currently support running with `SELinux` in enforcing mode by default.
However, if `SELinux` is required, the following policy is sufficient to allow Minion to start successfully:

.`minion.te`
[source]
----
module minion 1.0;

require {
        type init_t;
        type unlabeled_t;
        type usr_t;
        type port_t;
        type initrc_t;
        class file { execute execute_no_trans unlink };
        class icmp_socket name_bind;
}

#============= init_t ==============
allow init_t unlabeled_t:file execute_no_trans;
allow init_t unlabeled_t:file execute;
allow init_t usr_t:file unlink;
allow initrc_t port_t:icmp_socket name_bind;
----

This can be saved as `minion.te`, compiled, and installed as below:
[source,shell]
----
checkmodule -M -m -o minion.mod minion.te <1>
semodule_package -o minion.pp -m minion.mod <2>
semodule -i minion.pp <3>
----
<1> From the `checkpolicy` package; Checks and compiles a `SELinux` security policy module into a binary representation.
<2> From the `policycoreutils` package; Creates a `SELinux` policy module package from a binary policy module.
<3> From the `policycoreutils` package; Manages `SELinux` policy modules, including installing, upgrading, listing and removing modules.

== Secure access to Karaf shell

IMPORTANT: Change the default username and password (_admin/admin_) for the Karaf shell and encrypt it.

[{tabs}]
====
Linux::
+
--
include::secure-karaf.adoc[]
--

ifeval::["{page-component-title}" == "Horizon"]
Docker::
+
--
include::docker/secure-karaf.adoc[]
--
endif::[]
====

Changes to the password and encryption algorithm are applied immediately.
You do not need to restart the Minion.

TIP: 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 `/opt/minion`.

NOTE: If you are deploying in a container, this step should have been completed as part of the container definition.

[{tabs}]
====
Kafka::
+
--
include::message-broker/kafka.adoc[]
--

ActiveMQ::
+
--
include::message-broker/activemq.adoc[]
--

gRPC::
+
--
include::message-broker/grpc.adoc[]
--
====

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

=== Syslog messages

.`$\{MINION_HOME}/etc/org.opennms.netmgt.syslog.cfg`
[source, properties]
----
syslog.listen.interface=0.0.0.0
syslog.listen.port=514
----

=== SNMP traps

.`$\{MINION_HOME}/etc/org.opennms.netmgt.trapd.cfg`
[source, properties]
----
trapd.listen.interface=0.0.0.0
trapd.listen.port=162
----

== Check Minion in the core web UI

. Log in to the web UI as an administrative user.
. Click menu:Administration[Configure OpenNMS] in the side menu, then click menu:Distributed Monitoring[Manage Minions].

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