Deploy a Minion Virtual Appliance

Minion Virtual Appliance deployment requires an appliance file (provides the connect string) and VM image (OVA) that you download from the OpenNMS Portal. Use these files to launch the appliance in your virtualization environment.

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 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. The duplicate appliances will "flap," as they will both try to connect with the same identity.

Download Minion Appliance files

  1. Sign in to the OpenNMS Portal.

  2. Navigate to Appliances and locate the virtual appliance you want to deploy.

  3. Click the vertical ellipsis (⋮) to view the drop-down menu and click Download Configuration.

    The default appliance configuration file contains the connect string that you require for VM deployment. All other fields are empty. You can edit this file before VM 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.

  4. In the Appliances menu, click Appliance VM Image.

  5. Click Download and save the file.

    Note that the Appliance VM Image screen displays a checksum value that you can use to verify the integrity of the image.

    1. On Linux/MacOS, run md5sum with the image name as the argument.

    2. 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:
      CertUtil: -hashfile command completed successfully.

    Pre-Windows 10 users must download a checksum utility to run this argument.

Edit appliance configuration file (optional)

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

null values

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. (The names of virtual appliances are auto-generated.)

  • Hostnames can contain only alphanumeric and '- .' characters.

  • Set static IP addresses if your network does not use DHCP.

  • For information on the HTTPS proxy, see about the HTTP(S) proxy.

Deploy Minion Appliance to VMware

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

  1. Sign in to vCenter.

  2. Download and use the following shell script to deploy:

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

  4. Pick a secure password and log back in to the appliance with the new password.

    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). Shutdown the VM, and in vCenter on the VM itself, go to Edit Settings → VM Options → Configuration Parameters and set the guestinfo.onms.cloudconnect string.
  5. If required, use the terminal user interface (TUI) to set additional information:

    1. Static IP address and related information (if not using DHCP)

    2. HTTP(S) proxy

    3. Other network information (NTP server, Gateway IP addresses, DNS server, DNS search names)

  6. Reboot the appliance if you are using an HTTP(S) proxy.

  7. Use the TUI to run a health check to verify your setup.

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. Based on Ubuntu Core, the Minion Appliance allows the installation only of Snap packages that pass Canonical audits for security and system stability. Currently, no Snap package exists for Open VM Tools or VMware Tools.