Minion Management

A Minion is a lightweight, secure collector that monitors and communicates with the devices on your network, shares collected data, and connects your network with OpenNMS Cloud/Lōkahi.

With OpenNMS Cloud, you install your first Minion as part of the onboarding process.

Each Minion is associated with a monitoring location. The monitoring location defines a network area where you installed your Minion (for example, "Boston" or "Building 3"). The Minion installed as part of onboarding belongs to the "default" location. The Minion’s security certificate is closely tied to the location.

This section describes management tasks for installed Minions, and how to deploy a Minion from the UI.

Create a location

A location defines the network area where you installed your Minion.

  1. Click Locations in the left navigation menu.

  2. Click the + Location button.

  3. Type the location name in the field.

    Note that you cannot edit the location name after you save the location.

  4. (Optional) In the Physical Address field, type the street address for the location or the latitude and longitude to display nodes associated with the location on the geographical map page.

  5. Click Save.

The new location is saved.

If you want to deploy a Minion, you can download the Minion software bundle, following the instructions in Deploy a Minion.

From the Locations list, you can edit the location (to add a Minion or specify a physical address) or delete it.

Deploy a Minion

To deploy a Minion, you need to download the software bundle and install it locally. The bundle includes the following:

  • Encrypted Minion certificate with a decryption password

  • Docker Compose file with a Minion container

Deployment can take up to 10 minutes.


Make sure your system meets the following requirements:

  • CPU: 3GHz quad core x86_64 and above

  • RAM: 8GB (physical) and above

  • Storage (disk space): 100GB with SSD and above

  • Docker environment with Docker Compose (installation instructions: Mac, Linux, Windows)

  • Access to a terminal window or command line interface

  • Synchronized system time (via NTP or Windows time service)

We recommend using Linux for production environments. Mac and Windows work as test environments for the Minion, but sending traps to the Minion does not work correctly. Traps will not be associated with the correct node, and passive discovery will not be able to find the node that is sending traps.

To deploy a Minion, follow these steps:

  1. Click Locations in the left navigation menu.

  2. In the Locations list, click the vertical ellipsis () next to the location where you want to deploy the Minion.

  3. Click Edit.

    You can also deploy a Minion when you create a location.
  4. Click Download Bundle.

  5. Create a permanent directory for the Minion on the device where you want to run it.

  6. Copy the downloaded bundle to the permanent directory and unzip it.

    You can ignore the Unlock File Password field, as it is no longer required.
  7. Open a terminal window, navigate to the bundle location, and type the following command: docker compose up -d.

Refresh the browser to view your Minion. It will appear in the Locations screen once it is running and OpenNMS detects it.

Regenerate a Minion certificate

If at any point you are concerned your Minion might have been compromised, you may want to revoke the Minion’s current security certificate and create a new one for it.

To regenerate a Minion certificate, follow these steps:

  1. Click Locations in the left navigation menu.

  2. In the Locations list, click the vertical ellipsis () next to the location with the Minion whose certificate you want to revoke and recreate.

  3. Click Edit.

  4. Click the Regenerate button.

  5. When prompted, click Continue.

View Minion details

You can view details about the Minion including latency and status on the Inventory page (select Inventory from the left navigation menu).

Delete a location

To delete a location, follow these steps:

  1. Click Locations in the left navigation menu.

  2. Find the location that you want to remove and select the vertical ellipsis beside its name.

  3. Choose Delete and confirm deletion.

Delete a Minion

If you delete your only Minion, you will no longer receive network monitoring data.

Follow these steps to delete a Minion:

  1. Click Locations in the left navigation menu.

  2. In the locations list, click the location with the Minion you want to delete.

  3. Click the vertical ellipsis beside the Minion name and click Delete.

    You are prompted to confirm deletion.

  4. Click Delete.