LibreNMS Device Sync V2

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

Lab tested: customer field testing required

The LibreNMS driver was tested against LibreNMS 26.10 in the rConfig lab. It has not yet run in a customer environment. 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
LibreNMS	V8.4.2+	API token (X-Auth-Token)	Lab tested

How it fits together

You set this up once, check it with a preview, then let a scheduled task keep rConfig in step with LibreNMS:

1. Create the integration instance in the Setup tab and run Test Connection.
2. Create Device Profiles under Inventory → Device Profiles.
3. Create device groups in LibreNMS named rconfig::device_profile::<slug>, so each device knows which profile to use.
4. Run an Extract Preview, then a Sync Preview, then a Full Sync.
5. Schedule the sync as an Integration V2 Job task.

Prerequisites

LibreNMS:

• LibreNMS with the v0 API, which every current release has. The driver was built and tested against 26.10.
• A dedicated LibreNMS user with the global-read role, and an API token for that user.
• Network access from rConfig to the LibreNMS web UI (the API is served on the same address and port).

rConfig V8.4.2+:

• Administrator access.
• At least one Device Profile for the kinds of device you will import.

Create the service user and token

Create the user and token in the LibreNMS web UI (Settings → API → API Settings), or from the LibreNMS server:

# Read-only service user for rConfig
lnms user:add rconfig --role=global-read

# Token for that user. Copy it now: LibreNMS shows it only once.
lnms api:token-create rconfig --name="rConfig device sync"

Use the global-read role

LibreNMS doesn’t refuse a token whose user can see only some devices. It returns a shorter list, without an error. A user with the plain user role sees only the devices assigned to it, so rConfig would import only those and could treat the rest as missing. Use global-read (or admin) for the rConfig token.

Step 1: Create the integration instance

Navigate to Platform → Integrations. In the Device Sync section, click + Add Driver under V2 Drivers and choose LibreNMS.

Connectivity

Field	Default	Notes
Base URL	required	Root URL of the LibreNMS web UI, for example https://librenms.example.com. rConfig adds /api/v0 itself. A URL that already ends in /api/v0 also works.
Timeout (Seconds)	120	LibreNMS returns every device in one response, so large installs need a longer timeout. Range 1 to 600.
Verify TLS Peer	on	Leave on in production.
Verify TLS Hostname	on	Leave on in production.
Include Disabled Devices	off	When off, devices disabled in LibreNMS are skipped. Ignored devices (alerting turned off) are always included.
Import Device Groups as Tags	off	When on, LibreNMS device group names become rConfig tags on Apply.

Authentication

Field	Notes
API Token	The token from the service user. rConfig sends it as X-Auth-Token.

Click Test Connection. rConfig calls /api/v0/ping, then /api/v0/system, and shows the LibreNMS version on success, for example Connection successful (LibreNMS 26.10.2). Then click Save.

What you see	Most likely fix
rejected the API token (HTTP 401)	The token is wrong, has expired, or its user is disabled. Create a new token.
did not return a LibreNMS API response	The Base URL points somewhere else, for example a login page or proxy. Use the URL of the LibreNMS web UI.
Connection refused or timeout	Firewall, wrong port, or LibreNMS is down.
SSL or certificate error	Self-signed certificate. Turn off Verify TLS Peer / Hostname in a lab only.

Step 2: Give each device a Device Profile

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

LibreNMS devices have no free-form tags, so the driver uses device groups. Create one group per profile, named with the rconfig::device_profile:: prefix and the profile slug:

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

Dynamic groups work well here. A group with the rule os = iosxe puts every IOS-XE device in that profile automatically, including devices added to LibreNMS later.

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

Step 3: Filters (optional)

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

Filter	Matches
Device Groups	Devices in any of the listed groups, by name (not case-sensitive) or numeric ID.
OS	The LibreNMS os value exactly, for example iosxe, nxos, junos.
Device Types	The LibreNMS device type, for example network or firewall.
Location Contains	Any part of the device’s location text.

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 device group Core Switches AND with OS iosxe or nxos.

A missing device group fails the sync

If a group named in the filter doesn’t exist in LibreNMS, the sync stops with device group [name] was not found. This is on purpose: if the run carried on with no devices, every device from the old group would be treated as missing upstream. Update the filter after renaming a group in LibreNMS.

LibreNMS’s API accepts only one filter per request. rConfig sends the most specific one to LibreNMS and checks the rest itself, so you can combine filters freely.

Step 4: Preview, sync and schedule

These steps are the same for every V2 driver:

1. Extract Preview shows what LibreNMS returned, before any matching. Check the hostname and IP columns, and open Details on a row to see the payload. See the Extract Preview Tab reference.
2. Preview Sync runs the whole pipeline without writing. Check Run Insights and Problem Devices. A high canonicalize.invalid count usually means devices without a profile group. See the Run Insights Tab reference.
3. Full Sync creates and updates devices, assigns profiles and queues a first backup for new devices.
4. In Tasks, click New Task, choose Integration V2 Job, pick the LibreNMS instance and Apply mode, and set the schedule.

On a device imported from LibreNMS, the device page has an Open in LibreNMS button that goes to /device/<device_id> on your LibreNMS server.

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

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

Driver reference

Fields the driver reads

rConfig field	LibreNMS field
External ID	device_id. Hostnames can be renamed in LibreNMS, so they are never used as the ID.
Hostname	hostname. When that is an IP address, sysName is used instead.
Primary IP	overwrite_ip, then ip, then hostname if it is an IP address. This is the same order LibreNMS polls in.
Model	hardware
Serial	serial
Vendor	Worked out from os, for example iosxe gives Cisco and junos gives Juniper. Shown in previews only; the device’s vendor comes from its Device Profile.
Profile / Tags	Device group membership, as described in Step 2.

What rConfig never stores

LibreNMS 26.10 returns SNMP credentials (community, authpass, cryptopass and related fields) in plain text to any user who can see the device. rConfig removes them before saving anything, so they never appear in the database, previews or debug output.

Reconciliation and missing devices

• Strong match: by the LibreNMS device_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 device disappears from LibreNMS, rConfig disables the link but leaves the device.

Large installs

LibreNMS has no paging on its device list. One request returns every device the token can see, with every field. On installs with thousands of devices, raise Timeout (Seconds), and use a device group filter so each sync fetches less.

Troubleshooting

• Fewer devices than expected. Check the token’s user has the global-read role. Check Include Disabled Devices. Check the filters, and look at client_filtered_out and disabled_skipped in the extract stage metrics on Run Insights.
• Devices land in Problem Devices with no profile. The device is not in any rconfig::device_profile:: group, or the slug doesn’t match an active Device Profile. Open Details on the Extract Preview row and check its groups list.
• Timeout during extract. Raise Timeout (Seconds), or narrow the sync with a device group filter.
• Device imported with no IP address. LibreNMS fills in ip when it resolves the hostname during discovery. A device added by a DNS name that LibreNMS has never resolved has no IP yet, so rConfig imports it without one and its backups fail. Fix the DNS record, or set Overwrite IP on the device in LibreNMS, then run the sync again.

Related Documentation

• Device Sync V2 Overview
• Observium Device Sync V2
• Problem Devices Tab
• Debug Console
• Scheduled Tasks