
= Minion
:description: Learn about the OpenNMS Minion: benefits, how it works. Includes architecture diagram with three Minions.

A Minion is an instance of the Karaf OSGi runtime that enables {page-component-title} to monitor devices and services in locations that it otherwise cannot reach.
Minions communicate with these remote devices while {page-component-title} performs coordination and task delegation.
Minions can operate behind a firewall and network address translation (NAT), as long as they can communicate with {page-component-title} via an ActiveMQ or Apache Kafka message broker.

The `CAP_NET_RAW` and `CAP_NET_BIND_SERVICE` capabilities are assigned out of the box, letting you bind Minions to privileged ports (less than `1024`).

Minions provide the following benefits:

* No need to set up and maintain a large set of firewall rules for multiple management protocols.
* Avoid the difficulty of communicating with managed devices over unreliable networks, using UDP-based management protocols.
* Enable monitoring of nodes with overlapping IPv4 address ranges at different locations.
* Simplify network communication to the message broker.

== How it works

A Minion monitors all managed nodes and IP services in the same location (for example, "Pittsboro office, building-3").
The Minion communicates with the message broker, which in turn communicates with the core {page-component-title} instance.

.Example {page-component-title} instance with three Minions in different locations
image::deployment/minion/location.png["Network diagram displaying an example {page-component-title} instance with three Minions, each in a different location", 850]

By default, every node provisioned in {page-component-title} is created in the default location.
The {page-component-title} core instance handles all nodes and services in the default location.
To enable the Minion to handle all the nodes and services in a remote location, you define a location (for example, "Pittsboro office, building-3") in your core server, and configure the location property on the Minion to match.
The Minion registers itself to the {page-component-title} instance on start-up.

{page-component-title}'s xref:operation:deep-dive/provisioning/introduction.adoc#ga-provisioning-introduction[provisioning system] lets you associate nodes with any location.
{page-component-title} delegates monitoring requests for nodes in a specified location to the Minions that are configured for that location, using the Minion as a proxy.

.Minion communication with {page-component-title}
image::deployment/minion/communication.png["Network diagram displaying the communication channels between {page-component-title} and a Minion", 850]

By default, the {page-component-title} instance automatically provisions the Minion as a node and monitors it with the `Minion-Heartbeat` and `JMX-Minion` services.
The Minion sends heartbeat messages to show that it is functioning properly in the defined location, and provides metrics about its own performance.

The specific management protocol messages (for example, SNMP, ICMP) transit a message broker for execution by a Minion.
The Minion forwards the responses via the same message broker to the central {page-component-title} instance, which processes them accordingly.

A Minion proxy scenario supports the following monitoring capabilities:

* Receive Syslog messages and SNMP traps, and forward them through the message broker to a central {page-component-title} instance.
* Act as a proxy for performance data collection.
* Act as a proxy for service monitors to test availability and measure response times from applications.
* Receive streaming telemetry and flow export messages, and forward them through the message broker for persistence by a Sentinel instance.
