Device Sync integrationOpenNMS

Lab tested

OpenNMS Device Sync

From V8.4.2, rConfig can import nodes from OpenNMS Horizon and Meridian through the OpenNMS REST API. Each OpenNMS node becomes an rConfig device with the right template, credentials and category, and stays in step with OpenNMS on a schedule. The setup follows the same model as the Statseeker V2 setup; only the Setup tab fields, the filters and the way devices get their profile are different.

Lab tested: customer field testing required

The OpenNMS driver was tested against OpenNMS Horizon 35.0.5 in the rConfig lab. It has not yet run in a customer environment or against Meridian. If you use it in production, please share what you find with rConfig support so the status can be promoted.

Platform	rConfig V8 Support	Auth supported	V2 Status
OpenNMS	V8.4.2+ (Pro only)	Username and password (HTTP basic)	Lab tested

Mental Model: End Goal First

The point of setting up a V2 integration is to land in a steady state where rConfig’s device inventory is continuously reconciled against OpenNMS on a schedule, with no operator in the loop. That end state looks like this:

A Scheduled Task of type Integration V2 Job runs the OpenNMS instance in Apply mode on a cron, for example nightly. It runs the same six-stage pipeline you’ll run interactively in this guide, writes any create and update decisions to rConfig, leaves any conflicts or ambiguous matches in Problem Devices for review, and notifies you on completion.

To get there, you walk a one-time setup and a sanity-check loop:

1. Create the integration instance: OpenNMS connectivity and login in the Setup tab. Validate with Test Connection.
2. Set up the Device Profiles the synced devices will inherit from, under Inventory → Device Profiles.
3. Add surveillance categories in OpenNMS named rconfig::device_profile::<slug>, so each node knows which profile to use.
4. Run an Extract Preview to confirm the filters return the right OpenNMS nodes.
5. Run a Sync Preview to walk the full pipeline (canonicalize → reconcile → decide) without writing.
6. Run a Full Sync (Apply) once the preview’s decisions look right.
7. Schedule the integration to run on a cron from the rConfig scheduler.

%%{init: {'themeVariables': {'fontSize': '60px'}}}%%
flowchart LR
    A[Create instance<br/>Setup tab] --> B[Test Connection]
    B --> C[Device Profiles<br/>Inventory]
    C --> D[Extract Preview]
    D --> E[Sync Preview]
    E --> F[Full Sync · Apply]
    F --> G[Scheduled Task<br/>recurring sync]

  classDef step font-size:60px,stroke-width:2px;
  class A,B,C,D,E,F,G step;

Prerequisites

OpenNMS:

• OpenNMS Horizon or Meridian with the REST API, which every current release has. The driver uses /rest/info, /api/v2/nodes and /api/v2/ipinterfaces, and was tested against Horizon 35.0.5.
• A dedicated OpenNMS user for rConfig. It needs no extra roles (see below).
• Network access from rConfig to the OpenNMS web UI, usually port 8980. The API is served on the same address and port.

rConfig V8.4.2+:

• rConfig V8 Pro. Device Sync is not part of rConfig Core.
• Administrator access.
• At least one Device Profile for the kinds of device you will import.

Create the service user

In the OpenNMS web UI, open Admin → Configure Users, Groups and On-Call Roles → Configure Users and add a user, for example rconfig-api, with a strong password.

Don’t give it any extra roles. Every OpenNMS user can read nodes and interfaces through the REST API, and that is all rConfig does. ROLE_REST and ROLE_ADMIN add the right to change OpenNMS data, which rConfig never needs.

Restricted users see fewer nodes

If the user belongs to a group that is limited to certain surveillance categories, OpenNMS returns only the nodes in those categories, without an error. rConfig would import only those nodes and could treat the rest as missing upstream. Use a user with no category restrictions.

Step 1: Create the Integration Instance (Setup Tab)

1.1 Open the V2 driver picker

Navigate to Platform → Integrations. Scroll to the Device Sync section and click + Add Driver under V2 Drivers. The picker shows every V2 driver split into Configured Drivers and Not Configured Yet.

V2 driver picker. Shown with the LibreNMS card selected. The OpenNMS card is in the same list.

Each card carries the driver’s verification badge (Lab tested for OpenNMS), plus a link to its docs page. Click the OpenNMS card.

1.2 Fill in the Setup tab

The driver picker drops you straight into the instance Detail page on the Setup tab.

Connectivity

Field	Default	Notes
Base URL	required	URL of the OpenNMS web UI including its path, for example https://opennms.example.com:8980/opennms. If you leave off the path, rConfig adds /opennms. A URL ending in /rest or /api/v2 also works.
Timeout (Seconds)	60	Time allowed for each request. rConfig reads nodes 500 at a time, so the default suits large installs. Range 1 to 600.
Verify TLS Peer	on	Leave on in production.
Verify TLS Hostname	on	Leave on in production.
Import Categories as Tags	off	When on, OpenNMS surveillance category names become rConfig tags on Apply.

Authentication

Field	Notes
Username	The OpenNMS service user. rConfig sends it with HTTP basic auth.
Password	Password for that user.

1.3 Test the connection

Click Test Connection in the action bar at the top of the page.

Setup tab after a successful Test Connection. Shown with the Zabbix driver. The OpenNMS screen is the same.

rConfig calls /rest/info for the version, then asks for the node count, and shows both on success, for example Connection successful (OpenNMS 35.0.5, 120 nodes visible). Common failures:

What you see	Most likely fix
rejected the username or password (HTTP 401)	Wrong username or password, or the user was deleted. New users can take a few seconds to work after they are created.
No OpenNMS REST API at this URL (HTTP 404)	The Base URL path is wrong. Most installs use /opennms, for example https://opennms.example.com:8980/opennms.
did not return an OpenNMS API response	The Base URL points somewhere else, for example a login page or proxy. Use the URL of the OpenNMS web UI.
this user can see no nodes	The login works but the user sees nothing. Check it isn’t limited to categories with no nodes.
Connection refused or timeout	Firewall, wrong port (OpenNMS listens on 8980 by default), or OpenNMS is down.
SSL or certificate error	Self-signed certificate. Turn off Verify TLS Peer / Hostname in a lab only.

1.4 Save

Click Save. The save indicator in the action bar flips to Saved once persisted.

You now have a working OpenNMS integration instance, but no node has a Device Profile yet. Do not run a preview yet. Move to Step 2.

Step 2: Give Each Node a Device Profile

Every imported device needs a Device Profile, which sets its vendor, category, template and credentials. Nodes without one go to Problem Devices instead of being created.

2.1 Open the Device Profiles page

Navigate to Inventory → Device Profiles.

2.2 Create a Device Profile per device class

For each device class you want to sync (for example Cisco IOS Core Switches, Juniper Edge Routers), click New Device Profile and fill in:

• Name: human-readable.
• Slug: the value your OpenNMS category names will reference.
• Vendor, Category, Template, Credential set: standard rConfig device classification.
• SNMP group, Vector agent, default tags, default model / prompt patterns: optional.

2.3 Add profile categories in OpenNMS

OpenNMS groups nodes with surveillance categories, so the driver uses them for profiles. Create one category per profile, named with the rconfig::device_profile:: prefix and the profile slug:

rconfig::device_profile::cisco-ios-core
rconfig::device_profile::juniper-junos

Add the category to each node that should use that profile:

• Nodes from a requisition: add the category to the node in Admin → Manage Provisioning Requisitions, then synchronize the requisition. Set it in the requisition rather than on the node page, so the next import doesn’t remove it.
• Nodes added by auto-discovery: add the category on the node page, under Edit surveillance categories.

A few rules:

• The prefix is not case-sensitive, but the slug after it must match the Device Profile slug in rConfig.
• If a node has more than one profile category, the slug that sorts first wins.
• Other rconfig:: category names are ignored. Categories without the prefix only matter if Import Categories as Tags is on.

Step 3: Filters (Optional)

The Filters card on the Setup tab limits which nodes are imported. Leave every field empty to import all nodes.

Filter	Matches
Categories	Nodes in any of the listed surveillance categories, for example Routers.
Requisitions	Nodes from any of the listed requisitions (the OpenNMS foreign source), for example Network-Core.
Monitoring Locations	Nodes at any of the listed monitoring locations, for example Default or Dublin.

Values in one field are combined with OR, and different fields with AND. The card shows the result in plain words, for example Import devices in category Routers or Switches AND at monitoring location Dublin.

OpenNMS applies the filters itself before it sends anything, so a filtered sync transfers only the nodes you asked for. rConfig checks the result again on its side.

Names must match exactly

OpenNMS matches category, requisition and location names exactly, including case. routers does not match a category called Routers, and a filter with a misspelled name imports nothing. Copy names from the OpenNMS UI.

Nodes added by auto-discovery have no requisition, so a Requisitions filter always leaves them out. Leave that field empty to include them.

Step 4: Run an Extract Preview

Switch to the Extract Preview tab (amber download icon in the action bar).

Extract Preview hits OpenNMS exactly the way a real sync would, but stops the moment the nodes come back: no canonicalize, no reconcile, no writes.

Extract Preview tab with summary cards and result table. Shown with the Zabbix driver. The OpenNMS screen is the same.

Check the hostname and IP columns, and open a row’s Details hover to see the payload. Confirm the categories list contains the expected rconfig::device_profile:: category, and that primaryIp holds the address rConfig should connect to.

For the full anatomy of this tab, see the Extract Preview Tab reference.

Step 5: Run a Sync Preview

Click Preview Sync in the action bar (sky icon). Sync Preview runs the complete pipeline through decide and stops without writing.

Switch to the Run Insights tab to inspect the result.

Run Insights tab populated after a Sync Preview. Shown with the Zabbix driver. The OpenNMS screen is the same.

For OpenNMS the most-watched stage metrics are:

• extract.items_extracted: should match the Extract Preview count.
• total_count in the extract stage: how many nodes OpenNMS matched with the filters, before rConfig’s own checks.
• selfmonitor_skipped and deleted_skipped: the OpenNMS server’s own monitoring node and nodes OpenNMS has marked as deleted. Both are always skipped.
• primary_ip_missing: nodes with no usable IP address. See How the primary IP is chosen.
• canonicalize.invalid: a high count usually means nodes without a profile category.
• reconcile.ambiguous: non-zero means more than one rConfig device matches the same OpenNMS node.

If Open Problems is greater than zero, switch to the Problem Devices tab and triage the rows.

For the full anatomy of these tabs, see the Run Insights Tab reference and Problem Devices Tab reference.

Step 6: Run a Full Sync (Apply)

When the Sync Preview decisions look correct and Open Problems is at an acceptable level, click Full Sync in the action bar (indigo icon).

Full Sync re-runs the full pipeline and finishes by executing the apply stage:

1. Creates new devices for each decision = create.
2. Updates existing devices for each decision = update.
3. Assigns the resolved Device Profile to each affected device.
4. Adds OpenNMS category names as tags when Import Categories as Tags is on.
5. Updates integration_device_links (first_seen, last_seen).
6. Schedules an initial configuration backup for newly created devices.

Run Insights tab after a Full Sync. Shown with the Zabbix driver. The OpenNMS screen is the same.

Re-check Problem Devices after Apply: Apply does not auto-resolve ambiguous_match or conflict rows; those still need a human.

On a device imported from OpenNMS, the device page has an Open in OpenNMS button that goes to the node page (/opennms/element/node.jsp?node=<id>) on your OpenNMS server.

Step 7: The Debug Console

For any of the runs above, you can swap the action-bar button for the Open Debug Console button (shimmer icon). The Debug Console runs the same Artisan command synchronously and streams its native stdout/stderr into a modal:

Debug Console modal mid-run. Shown with the Zabbix driver. The OpenNMS screen is the same.

For the full anatomy of the dialog, see the Debug Console reference.

Step 8: Schedule the Sync

Once a manual Full Sync completes cleanly, schedule it. Navigate to Tasks and click New Task. Choose task type Integration V2 Job, pick the OpenNMS instance, choose Apply mode, and set the cron schedule.

A common production pattern:

• Hourly Preview: drift detection only, no writes. Surfaces new Problem Devices fast.
• Nightly Apply: commits real changes during the maintenance window.

CLI Reference

# Sync Preview (does not write)
php artisan rconfig:integration-v2-run --driver=opennms --mode=preview

# Full Sync with debug output
php artisan rconfig:integration-v2-run --driver=opennms --mode=apply --debug

# Queue an async run by explicit instance ID
php artisan rconfig:integration-v2-run 12 --mode=apply --queue

See the V2 Overview for the full option list.

Driver Reference

Fields the driver reads

rConfig field	OpenNMS field
External ID	The node ID. The requisition name and its foreign ID are kept alongside for reference.
Hostname	The node label. When the label is an IP address, sysName is used instead.
Primary IP	Chosen from the node’s IP interfaces, as described below.
Model	Asset record Model Number
Serial	Asset record Serial Number
Vendor	Asset record Manufacturer, or worked out from the sysObjectID when that is empty. Shown in previews only; the device’s vendor comes from its Device Profile.
Profile / Tags	Surveillance categories, as described in Step 2.

How the primary IP is chosen

OpenNMS nodes can have several IP interfaces, so rConfig picks one per node, in this order:

1. The interface marked as the SNMP primary (P).
2. A secondary SNMP interface (S).
3. Any other interface, managed interfaces before unmanaged ones.

Loopback addresses (127.x.x.x, ::1) and interfaces OpenNMS has marked as deleted are never used. If nothing is left and the node label is an IP address, rConfig uses the label. Otherwise the device is imported with no IP address and its backups fail, so give the node a managed interface in OpenNMS.

rConfig fetches interfaces for up to 100 nodes per request, so a sync makes a handful of requests even on large installs.

What rConfig never stores

OpenNMS asset records can hold device login details for its own provisioning: Username, Password, Enable Password, Auto Enable, Connection and SNMP Community. rConfig removes them before saving anything, so they never appear in the database, previews or debug output. rConfig uses the credentials from the device’s Device Profile instead.

Reconciliation and missing devices

• Strong match: by the OpenNMS node ID already linked to this instance.
• Medium match: hostname and primary IP both unique in rConfig; sent to Problem Devices for review.
• Missing upstream: the default is disable_link_only. When a node disappears from OpenNMS, rConfig disables the link but leaves the device.

If you delete a node in OpenNMS and import it again, it gets a new node ID. rConfig then sees a new node and the old link goes missing. Expect a medium match in Problem Devices for that device.

Troubleshooting

Common gotchas

• Filter names are case-sensitive and must match OpenNMS exactly.
• A user limited to certain categories returns fewer nodes with no error, and the missing nodes can be treated as gone upstream.
• Categories added on the node page of a requisition node can be removed by the next requisition import. Add them in the requisition.

• Fewer nodes than expected. Check the filters, the user’s category restrictions, and total_count and client_filtered_out in the extract stage metrics on Run Insights. The OpenNMS server’s own localhost node is always skipped.
• Nodes land in Problem Devices with no profile. The node has no rconfig::device_profile:: category, or the slug doesn’t match an active Device Profile. Open Details on the Extract Preview row and check its categories list.
• Device imported with no IP address. The node has no usable IP interface. Add or manage an interface in OpenNMS, ideally marked as SNMP primary, then run the sync again.
• Reconciliation produces ambiguous matches. Two rConfig devices share the same hostname or primary IP. Resolve in Problem Devices by picking the correct target, or de-duplicate the device list.

Related Documentation

• Device Sync V2 Overview
• Statseeker Device Sync: the model V2 setup
• LibreNMS Device Sync
• Extract Preview Tab
• Run Insights Tab
• Problem Devices Tab
• Debug Console
• Scheduled Tasks