graham/towerops
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
towerops/LIBRENMS_INTEGRATION.md

8 KiB
Raw Blame History

LibreNMS Integration

This document explains how to import MIB files and device profiles from a LibreNMS installation into Towerops.

Quick Start

Import device profiles from LibreNMS (no authentication needed):

mix upload_librenms --librenms-path ~/dev/librenms

Upload everything including MIBs (requires superuser API token):

mix upload_librenms --librenms-path ~/dev/librenms --token your-api-token

This will:

  1. Upload all MIB files from ~/dev/librenms/mibs/ to the server (if --token provided)
  2. Import all device profiles from ~/dev/librenms/resources/definitions/

Options

Basic Usage

# Upload to local server (default: http://localhost:4000)
mix upload_librenms --librenms-path ~/dev/librenms

# Upload to production server
mix upload_librenms --librenms-path ~/dev/librenms \
  --url https://towerops.net \
  --token your-api-token-here

# Upload specific profiles only
mix upload_librenms --librenms-path ~/dev/librenms \
  --profiles routeros,ios,iosxe

Command-Line Options

  • --librenms-path - Path to LibreNMS installation (required)
  • --url - Server URL (default: http://localhost:4000)
  • --token - API token for authentication (required for remote servers)
  • --profiles - Comma-separated list of profiles to import (default: all)

What Gets Uploaded

MIB Files

All MIB files from {librenms-path}/mibs/ are uploaded, organized by vendor:

~/dev/librenms/mibs/
  ├── mikrotik/
  │   ├── MIKROTIK-MIB
  │   └── ...
  ├── cisco/
  │   ├── CISCO-SMI
  │   └── ...
  └── ...

Each vendor's MIBs are uploaded separately with the vendor name preserved.

Device Profiles

Device profiles are imported from LibreNMS YAML definitions:

~/dev/librenms/resources/definitions/
  ├── os_detection/
  │   ├── routeros.yaml    # Detection patterns
  │   └── ios.yaml
  └── os_discovery/
      ├── routeros.yaml    # Device info & sensors
      └── ios.yaml

For each profile, the following is imported:

  • Detection patterns (sysObjectID, sysDescr regex)
  • Device info OIDs (serial number, firmware version, hardware)
  • Sensor OIDs (temperature, voltage, current, power, fanspeed)

Note: Only scalar sensors (ending with .0) are imported. Table-based sensors with {{ $index }} templates are skipped.

Authentication

Profile Import Only (No Token Needed)

Profile imports work without authentication since they only write to the local database:

# Import profiles without uploading MIBs
mix upload_librenms --librenms-path ~/dev/librenms

MIB Upload (Token Required)

MIB uploads require a superuser API token for both local and remote servers:

# Upload MIBs + import profiles (local server)
mix upload_librenms --librenms-path ~/dev/librenms \
  --token your-superuser-token

# Upload to remote server
mix upload_librenms --librenms-path ~/dev/librenms \
  --url https://towerops.net \
  --token your-superuser-token

Creating an API Token:

  1. Log in to Towerops as a superuser
  2. Navigate to Settings → API Tokens
  3. Create a new token
  4. Copy the token value

Note: The token MUST be from a superuser account. Regular user tokens will be rejected with a 403 Forbidden error.

Examples

Example 1: Import Profiles Only (Quick Start)

Import device profiles without uploading MIBs (no token needed):

mix upload_librenms --librenms-path ~/dev/librenms

Output:

Skipping MIB upload: --token is required for MIB uploads (superuser API token needed)
Step 2/2: Importing device profiles from ~/dev/librenms/resources/definitions...
Importing 150 specified profiles
Importing profile: routeros
✓ routeros: created/updated successfully
...
Import complete: 150 succeeded, 0 failed

Upload complete!

Example 2: Upload Everything (MIBs + Profiles)

Upload MIBs and import profiles (requires superuser token):

mix upload_librenms --librenms-path ~/dev/librenms --token sk_dev_abc123...

Output:

Step 1/2: Uploading MIB files from ~/dev/librenms/mibs...
Found 500 vendor directories
Uploading MIBs for vendor: mikrotik
  Uploading: MIKROTIK-MIB
  Uploading: ...
MIB upload complete: 5000 succeeded, 0 failed

Step 2/2: Importing device profiles from ~/dev/librenms/resources/definitions...
Importing 150 specified profiles
Importing profile: routeros
✓ routeros: created/updated successfully
...
Import complete: 150 succeeded, 0 failed

Upload complete!

Example 3: Update Specific Profiles

Re-import just the MikroTik and Cisco profiles (no MIB upload):

mix upload_librenms --librenms-path ~/dev/librenms \
  --profiles routeros,ios,iosxe,nxos

Example 4: Production Deployment

Upload everything to production server:

mix upload_librenms --librenms-path ~/dev/librenms \
  --url https://towerops.net \
  --token sk_live_abc123...

Manual Tasks

You can also run each step separately if needed:

Upload MIBs Only

mix upload_mibs --source-dir ~/dev/librenms/mibs \
  --url https://towerops.net \
  --token your-token

Import Profiles Only

mix import_profiles --source-path ~/dev/librenms/resources/definitions \
  --profiles routeros,ios

Troubleshooting

Error: "LibreNMS directory not found"

Make sure the path to your LibreNMS installation is correct:

ls -la ~/dev/librenms
# Should show mibs/ and resources/ directories

Error: "No vendor directories found"

The mibs directory structure should have vendor subdirectories:

ls -la ~/dev/librenms/mibs/
# Should show directories like mikrotik/, cisco/, etc.

Error: "Superuser access required"

MIB uploads require a superuser API token. Make sure you're using a token created by a superuser account.

Warning: "Definitions directory not found"

LibreNMS moved the definitions from includes/definitions/ to resources/definitions/ in recent versions. Update your path accordingly.

What's Imported

RouterOS (MikroTik) Example

For the routeros profile, the following is imported:

Profile Metadata:

  • Name: routeros
  • Vendor: Mikrotik RouterOS
  • Detection OID: .1.3.6.1.4.1.14988.1
  • Priority: 100

Device OIDs:

  • Serial number: MIKROTIK-MIB::mtxrSerialNumber.0
  • Firmware version: MIKROTIK-MIB::mtxrLicVersion.0

Sensor OIDs:

  • None (routeros only has table-based sensors which are skipped)

Cisco IOS Example

For the ios profile:

Profile Metadata:

  • Name: ios
  • Vendor: Cisco IOS
  • Detection Pattern: "Cisco Internetwork Operating System Software"
  • Detection OID: .1.3.6.1.4.1.9.1.2330
  • Priority: 100

Device OIDs:

  • None (IOS doesn't define them in os_discovery)

Sensor OIDs:

  • None (IOS only has table-based sensors which are skipped)

Database Schema

The imported profiles are stored in the database:

  • device_profiles - Profile metadata (name, vendor, detection patterns)
  • profile_device_oids - Device identification OIDs (serial, firmware, etc.)
  • profile_sensor_oids - Sensor discovery OIDs (temperature, voltage, etc.)

You can query them:

# Get all profiles
Towerops.Profiles.list_profiles()

# Get specific profile with associations
Towerops.Profiles.get_profile("routeros")

# Match a device to a profile
system_info = %{
  sys_descr: "RouterOS 7.16.1",
  sys_object_id: ".1.3.6.1.4.1.14988.1"
}
Towerops.Profiles.match_profile(system_info)

Next Steps

After importing profiles:

  1. Test device discovery - Discover a MikroTik or Cisco device to verify profile matching works
  2. Check MIB translation - Verify that MIB names are being translated to numeric OIDs correctly
  3. Add more profiles - Import additional vendor profiles as needed
  4. Build Web UI - Create LiveView pages for managing profiles in the browser

Related Documentation

  • PROFILES_README.md - Database-driven profile system documentation
  • lib/mix/tasks/upload_librenms.ex - Task implementation
  • lib/mix/tasks/import_profiles.ex - Profile import implementation
  • lib/mix/tasks/upload_mibs.ex - MIB upload implementation