Observium Device Sync V2

From V8.4.2, rConfig can import devices from Observium through its REST API. Each Observium device becomes an rConfig device with the right template, credentials and category, and stays in step with Observium on a schedule. The setup follows the same steps as LibreNMS Device Sync V2, which started as a fork of Observium.

Unverified: built from the Observium API documentation

The Observium driver was built from Observium’s published API documentation and has not yet been tested against a live Observium instance. The parts of this page marked Unverified are where the documentation is silent and rConfig had to assume how Observium behaves. If you run it, please send your results to rConfig support, including any errors from Test Connection or the Logs tab.

Platform	rConfig V8 Support	Auth supported	V2 Status
Observium	V8.4.2+	API token (Bearer), or username and password	Unverified

Prerequisites

Observium:

• Observium Professional or Enterprise. The API is only in the subscription editions. Community Edition has no API, so this driver can’t connect to it.

• The API turned on in Observium’s config.php:

  $config['api']['enable'] = TRUE;

  The key is enable, not enabled. With the wrong key Observium still answers The API is disabled.

• An Observium user that can see every device you want to import. Observium docs don’t name a level for “read everything”; level 5 (global read) or higher is what rConfig recommends.

• Network access from rConfig to the Observium web UI.

rConfig V8.4.2+:

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

Choose how rConfig signs in

API token (recommended). Recent subscription builds have API tokens under My Profile → API Tokens. Create a read-only token for the rConfig user. rConfig sends it as Authorization: Bearer <token>.

Username and password. Older subscription builds don’t have tokens. rConfig then signs in with HTTP Basic authentication as an Observium user.

Failed logins lock the API

Observium blocks API logins after repeated failures (by default 10 failures in 300 seconds) and answers HTTP 429 until the block expires. rConfig never retries a 429, so a wrong password does not extend the block. Test Connection shows how long to wait when Observium says.

Step 1: Create the integration instance

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

Connectivity

Field	Default	Notes
Base URL	required	Root URL of the Observium web UI, for example https://observium.example.com. rConfig adds /api/v0 itself.
Timeout (Seconds)	60	Time allowed for each request. 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 Observium are skipped. Ignored devices are always included.
Import Device Groups as Tags	off	When on, Observium device group names become rConfig tags on Apply.

Authentication

Field	Shown when	Notes
Authentication Mode	always	API Token or Username and Password.
API Token	API Token	A read-only token for the rConfig user.
Username	Username and Password	Observium user with global read access.
Password	Username and Password	That user’s password.

Click Test Connection. rConfig asks Observium for one device and reports how many devices the user can see, for example Connection successful (412 devices visible). Then click Save.

What you see	Most likely fix
The Observium API is disabled	Set $config['api']['enable'] = TRUE; in config.php. Check you are on Professional or Enterprise.
rejected the credentials (HTTP 401)	Wrong token, or wrong username and password. Unverified: the exact status code Observium uses here.
blocking logins after too many failed attempts	Wait for the time shown, then fix the credentials before testing again.
can see no devices	The user’s level is too low. Use a user with global read (level 5) or higher.
did not return an Observium API response	The Base URL points somewhere else, such as a login page or proxy.

Step 2: Give each device a Device Profile

Every imported device needs a Device Profile. Devices without one go to Problem Devices instead of being created.

Create one Observium device 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

Observium groups can be rule-based, so a group matching OS ios keeps every IOS device in that profile as devices are added.

• 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.
• Only groups of devices count. Port or sensor groups with the prefix are ignored.

Unverified: Observium’s documentation lists the /groups/ endpoint and its filters but shows no example response. rConfig reads the group ID and name from group_id/id and group_name/name, and fetches each group’s members through the documented group_id device filter. If profile groups are not picked up, send the output of /api/v0/groups/?entity_type=device to rConfig support.

Step 3: Filters (optional)

The Filters card on the Setup tab works the same way as for LibreNMS:

Filter	Matches
Device Groups	Devices in any of the listed groups, by name (not case-sensitive) or ID.
OS	The Observium os value exactly, for example ios, iosxe, junos.
Device Types	The Observium 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. A single OS or device type is sent to Observium as a filter; everything else is checked by rConfig after the devices are fetched. As with LibreNMS, a device group that doesn’t exist fails the sync rather than unlinking devices.

Step 4: Preview, sync and schedule

These steps are the same for every V2 driver:

1. Extract Preview shows what Observium returned. Check the hostname and IP columns, and open Details on a row to see the payload.
2. Preview Sync runs the whole pipeline without writing. Check Run Insights and Problem Devices.
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 Observium instance and Apply mode, and set the schedule.

On a device imported from Observium, the device page has an Open in Observium button that goes to /device/device=<device_id>/. Unverified: this is Observium’s long-standing device URL; it has not been checked on a current subscription build.

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

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

Driver reference

Fields the driver reads

rConfig field	Observium field
External ID	device_id
Hostname	hostname. When that is an IP address, sysName is used instead.
Primary IP	ip, then hostname if it is an IP address.
Model	hardware
Serial	serial
Vendor	Observium’s vendor field. When it is empty, worked out from os. Shown in previews only; the device’s vendor comes from its Device Profile.
Profile / Tags	Device group membership, as described in Step 2.

Observium returns every value as text and uses "" or - for empty fields. rConfig treats both as empty.

Paging

rConfig asks for 1,000 devices per page (pagesize, pageno) and stops at a short page or when it reaches the total Observium reports. If a page comes back the same as the one before, the build is ignoring the paging parameters, and the sync stops with non-advancing page instead of looping.

What rConfig never stores

rConfig asks Observium for a fixed list of fields that leaves out SNMP credentials, and removes any snmp_* field that comes back anyway. Unverified: Observium’s documentation doesn’t say whether the API hides SNMP credentials on its own, so rConfig assumes it doesn’t.

Reconciliation and missing devices

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

Related Documentation

• Device Sync V2 Overview
• LibreNMS Device Sync V2
• Problem Devices Tab
• Scheduled Tasks