Specify an OpenNMS Instance and Profiles

An instance indicates how a Minion Appliance connects to your OpenNMS instance by specifying connectivity information (for example, message broker details) and configuration information (traps, syslog, telemtryd). You can specify an instance through the Quick Setup interface, or manually.

Note that you must create a connectivity profile when you create an instance. The connectivity profile specifies how the Minion communicates with OpenNMS.

Before you begin

  • Set up OpenNMS for Minion communication.

  • Collect the information required for your appliance to communicate with your OpenNMS instance and its broker:

    • The URL for your OpenNMS instance (for example, http://opennms.mycompany.com:8980/opennms or https://opennms.mycompany.com/opennms). Note that the URL must include /opennms as a suffix.

    • Minion user credentials (the username and password for the OpenNMS ROLE_MINION security role).

    • The broker type and settings:

      • ActiveMQ: the failover URL for your broker in the following format:

        failover:tcp://[hostname of OpenNMS server]:[port number]

        failover:ssl://[hostname of OpenNMS server]:[port number](for SSL connectivity).

        OR

      • Kafka: bootstrap server addresses in the following format:

        kafka:9092

        kafka1:9092,kafka2:9092

        Note that you do not need to list every server in the Kafka cluster, but you may want at least two listed for redundancy. See the official Kafka documentation and Communicate with multiple OpenNMS instances for more information.

  • If your OpenNMS instance uses secure communication and a self-signed certificate, upload your certificate.

Set up instance via Quick Setup

To specify your instance via the Quick Setup interface, follow these steps:

  1. Choose Quick Setup in the left menu.

  2. Select Instance, and click Get Started.

  3. Verify that you have the prerequisite information, and click Continue.

  4. Follow the setup instructions.

  5. After finalizing your configuration, choose Exit or Connect Appliance, as desired.

If you decide to connect an appliance using the Quick Setup, follow the instructions and enter any required information. When you are finished, review your configuration settings and confirm the setup.

Set up instance and connectivity profile

To set up an instance and create a connectivity profile, follow these steps:

  1. Choose OpenNMS Core Instances in the left menu and click Add Instance.

  2. Type an instance name and click Next.

  3. Type a profile name and click Next.

  4. On the HTTP Configuration page, enter the following information:

    • The URL for your OpenNMS instance.

    • The username and password for the OpenNMS ROLE_MINION security role.

    • The certificate (if required).

  5. (Optional) Select an online appliance and click Test to verify HTTP connection (see Test HTTP and broker configuration).

  6. Click Next.

  7. On the Broker Type page, specify your broker (Kafka or ActiveMQ).

    • For ActiveMQ, enter the following information:

      • The failover URL for your broker.

      • The username and password for your Minion user.

    • For Kafka, enter the following information:

      • The bootstrap servers, each separated by a comma.

      • (Optional) Click Add Advanced Settings to configure additional information (group ID, session timeout, retries, and so on).

  8. (Optional) Select an online appliance and click Test to verify broker connection (see Test HTTP and broker configuration).

  9. Click Next.

After you create an instance, you can edit, add, and remove connectivity profiles and feature profiles.

Making configuration changes to an instance (including changing its name and modifying its connectivity and feature profiles) respawns all Minions associated with that instance. This process triggers a brief service interruption.

Test HTTP and broker configuration

Follow these steps to test an instance’s HTTP and broker configuration settings:

  1. Choose OpenNMS Core Instances in the left menu and click Edit beside the instance that you want to test.

  2. On the Instance Profiles screen, click Edit beside the connectivity profile that you want to test.

  3. Click Next and select an appliance from the Select Online Appliance list.

    The appliance must be online for this test. If it isn’t online, it will not appear in the list.

  4. Click Test.

    The appliance attempts to connect to the HTTP server using the configured URL, credentials, and certificate (if applicable). If the test is successful, a "Successfully connected" message appears in the bottom-right corner of the screen. If the test fails, a "Connection failed" message appears at the top of the screen.

  5. To test broker connectivity, click Next and select an appliance from the Select Online Appliance list.

  6. Click Test.

    The appliance attempts to connect to the broker using the configured URL and credentials. If the test is successful, a "Successfully connected" message appears in the bottom-right corner of the screen. If the test fails, an error message appears at the top of the screen (for example, "Failed to connect to ActiveMQ broker").

    This test will time out after 10 seconds. If this happens, an "Exceeded timeout while trying to validate broker credentials" message appears at the top of the screen.

Reviewing configuration information (URLs, credentials, and certificates) is an important first step in troubleshooting when you encounter an error message on these tests. Make any necessary corrections and run the test again.

If configuration corrections don’t resolve the error, you may need to troubleshoot your network settings or contact our support team.

Feature profiles

A feature profile specifies Minion configuration information including Java agent support for out-of-band management, IPC parameters (RPC, Twin, and sink (Kafka)), SNMP trap, syslog, and network flows.

When you create an instance, the Appliance Service creates a default feature profile that you can edit later.

Edit a feature profile

Note that making configuration changes to an instance (including changing its name and modifying its connectivity and feature profiles) respawns all Minions associated with that instance. This process triggers a brief service interruption.

When configuration information includes a port number, the number should be above 1023, as ports below 1023 are privileged (ports that are restricted to the root user).

  1. Choose OpenNMS Core Instances in the left menu and click Edit beside the instance whose feature profile you want to edit.

  2. Expand the Feature Profiles section and click Edit beside the profile that you want to edit.

  3. In the left menu, expand the menu item for the feature that you want to configure, make your changes, and click Update.

    • In many cases, this information is key and value pairs associated with the selected item.

    • You can configure multiple features without exiting the screen by clicking among the features, setting parameters, and then clicking Update.

For information on the features and their associated parameters, see Configuring Minion via Confd in the main OpenNMS documentation.

Add a feature profile

An instance can have multiple feature profiles associated with it. This lets you specify the type of information the Minion receives, based on monitoring location. For example, you may have a location without NetFlow-capable devices, or locations from which you do not want to receive traps or syslog messages.

To add a feature profile to an instance, follow these steps:

  1. Choose OpenNMS Core Instances in the left menu.

  2. Click Edit beside the instance to which you want to add a feature profile.

  3. Click Add (+) beside the Feature Profiles section.

  4. Enter a name in the Feature Profile Name box.

  5. In the left menu, expand the menu item for the feature that you want to configure, add the appropriate information, and click Submit.

Sample feature profile configuration

This section provides examples for the most common features you might configure:

  • Telemetry single port listener

  • Telemetry multi-port listener

  • SNMP trap daemon

  • Syslog daemon

  • Multiple OpenNMS instances with a single Kafka cluster

  • General properties

Telemetry single port listener

If you are monitoring multiple flow protocols (for example, NetFlow5/9, IPFIX, and sFlow), you normally need to set up a flow listener for each one, each on its own UDP port. The single port listener feature lets you specify one port for all protocols. Based on the packet, the listener determines which protocol is being used and directs it to the right parser.

  1. In the feature profile, choose Telemetry > Flows > Single Port Listener.

  2. Click Enable Single Port Listener.

  3. Expand the Parameters section, and add a port and port number key/value pair.

See Protocol Reference in the main OpenNMS documentation for a list of protocol class names and parameters. For listener class names and parameters, see Listener Reference in the main OpenNMS documentation.

The following example configures the port number and maximum packet size, enables DNSLookup, and sets the maximum clock skew event rate:

Update Feature Profile page displaying sample configuration settings for a single port listener
Example single port listener configuration settings

Telemetry multi-port listener

The following example configures telemetry for IPFIX and NetFlow5. See the documentation links in Telemetry single port listener for information on protocol and listener parameters.

Update Feature Profile page displaying sample configuration settings for a flow listener
Example multi-port listener configuration settings

SNMP trap daemon

Configure the Minion Appliance to listen on a specific port for SNMP traps. See Configuring Minion via Confd in the main OpenNMS documentation for more information.

Update Feature Profile page displaying sample configuration settings for trapd
Example SNMP trapd configuration settings

Syslog daemon

Configure the Minion Appliance to listen on a specific port for syslog messages. You can use 0.0.0.0 to get any IP address on the server. If you have multiple network cards, you can set a specific IP address. See Configuring Minion via Confd in the main OpenNMS documentation for more information.

Update Feature Profile page displaying sample configuration settings for syslogd
Example syslogd configuration settings

Communicate with multiple OpenNMS instances

In some cases, you may choose to run several OpenNMS Horizon or Meridian instances for scalability or to have a test/staging environment where you can develop integrations and monitoring rules. Instead of running a second Kafka cluster for messaging, you can reuse the existing one with the other instance.

Use the OpenNMS system ID as a topic prefix to distinguish the message channels for these instances by setting the org.opennms.instance.id=<YourInstanceName> as a key-value pair in the feature profile:

Update Feature Profile page displaying sample system properties settings
Example system properties settings

General properties

Specify custom system properties that you or OpenNMS may have created. See System Properties in the main OpenNMS documentation for more information.

src="https://polyfill.io/v3/polyfill.min.js?features=es6">