Deploy a Minion Virtual Appliance

Deployment of a Minion Virtual Appliance requires an appliance file that provides the connection string, and a VM image (OVA) that you download from the OpenNMS Portal. The Minion Virtual Appliance image is signed by OpenNMS for authenticity.

Before you begin, review the checklist of pre-installation tasks and complete those that apply to your network environment.

We strongly recommend using our OVA deployer script to automate the Minion Appliance creation process. This ensures that the configuration settings install and persist correctly.

Do not clone a virtual appliance. Doing so copies the serial number and other connectivity information; this information must remain unique. If you do clone a virtual appliance, both the original and the duplicate will "flap," because they will both try to connect with the same identity.

Download Minion Virtual Appliance files

Follow these steps to download the necessary files to deploy your Minion Virtual Appliance:

Sign in to the OpenNMS Portal.
Navigate to Appliances and locate the virtual appliance that you want to deploy.
Click the vertical ellipsis (⋮) and click Download Configuration.

The default appliance configuration file contains the connection string required for VM deployment. All other fields are empty. You can edit this file before deployment to update the empty values, or use the terminal user interface (TUI) to set this information on the VM.

The configuration file is used only on first boot of the VM. After first boot, the only way to change settings on a Minion Virtual Appliance is through the TUI.
In the Appliances menu, click Appliance VM Image.
Click Download and save the file.

Note that the Appliance VM Image page displays a checksum value that you can use to verify the integrity of the image.
- On Linux and MacOS, run md5sum with the image name as the argument.
- On Windows 10, use the CertUtil utility to run the following command: CertUtil -hashfile <path to image> MD5. For example:
  C:\Users\user>CertUtil -hashfile image_path MD5 MD5 hash of image: 8a798a3c976ec5656562271eb17f148a CertUtil: -hashfile command completed successfully.
  Pre-Windows 10 users must download a checksum utility to run this argument.

(Optional) Edit appliance configuration file

The default appliance configuration file contains the connection string that you require for VM deployment. All other fields are empty:

You may choose to edit this file and update these values so that they can be set on the VM as part of the deployment process. Note that the names of virtual appliances are automatically generated.

Consider the following limitations when editing the appliance configuration file:

Hostnames can contain only alphanumeric and '- .' characters.
If your network does not use DHCP, we recommend that you set static IP addresses.

For information on the HTTP/S proxy, see use an HTTP/S proxy.

Deploy Minion Virtual Appliance to VMware

We provide a shell script on GitHub to deploy the Minion Virtual Appliance to a VMware vCenter-based environment. Dependencies and instructions are included on the GitHub page.

Sign in to vCenter.
Download and use the shell script to deploy the appliance.
To sign in to the appliance, launch it from your hypervisor and use the following credentials:
- user name: admin
- password: opennms
  
  You are prompted to change your password.

When prompted, type a new secure password and log in to the appliance again.

If you need to set the configuration parameter manually, extract the connect string from the JSON configuration file (for example, jq -r '.cloudConnect' virtual-1.json). Shut down the VM, and in vCenter on the VM itself, go to Edit Settings > VM Options > Configuration Parameters and set the guestinfo.onms.cloudconnect string.

If required, use the terminal user interface (TUI) to set additional information:
- Static IP address and related information like the Default Gateway (if not using DHCP).
- System settings (hostname, NTP server, HTTP/S proxy).
- SNMP settings (location and contact).
Reboot if you are using an HTTP/S proxy.
Run a health check to verify your setup.
- We also recommend that you check that the appliance is connected to the Appliance Service.

The appliance takes approximately 2-5 minutes to reboot (about 2.5 minutes until you can SSH into it, and a bit longer before it appears in the OpenNMS Portal as online with a Minion).

To bulk create virtual appliances, copy the OVA into the data store and create a reference.

Open VM/VMware Tools

You cannot currently use OpenVM Tools or VMware Tools with the Minion Virtual Appliance. The appliance is based on Ubuntu Core, and thus allows the installation of only Snap packages that pass Canonical audits for security and system stability. No Snap packages currently exist for OpenVM Tools or VMware Tools.

Minion Virtual Appliance connection troubleshooting

If your Minion Virtual Appliance is not connected to the Appliance Service, try the following:

Make sure that you have an IP address.
Check that you implemented security and appliance firewall rules correctly.
Check that the connection string on the appliance is correct.

Next steps

After you deploy your Minion Virtual Appliance, you can configure it in the OpenNMS Portal. See the Getting Started section for information on adding new users, activating an appliance, and more.