Librenms

---
name: librenms
description: "Expert coverage of LibreNMS open-source network monitoring system: SNMP auto-discovery, device library, distributed polling, RRDtool/InfluxDB storage, alerting with transports, Oxidized config backup, Grafana integration, REST API, and large-scale deployment architecture. Use for \"LibreNMS\", \"Oxidized\", \"librenms auto-discovery\", \"librenms alerting\", \"distributed polling\", \"RRDtool\", \"open-source NMS\", \"librenms API\". Do NOT use for cross-vendor comparison, platform selection, or category-wide architecture -- use the `network-monitoring` skill."
license: MIT
---

# LibreNMS

This skill covers LibreNMS, the leading open-source network monitoring system. Areas of expertise include:

- SNMP auto-discovery via SNMP, CDP, LLDP, BGP, ARP
- Device library (10,000+ device definitions with custom OIDs and graphs)
- Distributed polling for large-scale deployments
- Time-series storage (RRDtool, InfluxDB, Prometheus)
- Alert engine with SQL-like rules and multiple transports
- Oxidized integration for network configuration backup
- Custom dashboards and Grafana integration
- REST API for device management and data access
- PHP/Laravel architecture, MySQL/MariaDB backend, Redis caching

## How to Approach Tasks

1. **Classify** the request:
   - **Troubleshooting** -- Device not polling, discovery failures, alerting issues, performance problems
   - **Architecture** -- Load `references/architecture.md` for deployment patterns, distributed polling, storage
   - **Configuration** -- Discovery settings, SNMP credentials, alert rules, transport configuration
   - **Integration** -- Oxidized, Grafana, API, SIEM, CMDB
   - **Scale** -- Distributed polling, rrdcached, database optimization

2. **Identify deployment model** -- Single-server or distributed polling? RRDtool or InfluxDB? Docker or bare-metal?

3. **Load context** -- Read the reference file for deep knowledge.

4. **Analyze** -- Apply LibreNMS-specific reasoning. Understand that LibreNMS is SNMP-centric and community-maintained; solutions should leverage existing device definitions and community resources.

5. **Recommend** -- Provide specific configuration paths, CLI commands, and SQL/alert rule examples.

## Core Architecture

### Components
- **Web Application** -- PHP 8.x / Laravel framework; serves dashboards, configuration, and API
- **MySQL/MariaDB** -- All device, interface, sensor, and alert data
- **Redis** -- Caching layer for frequently accessed data
- **Polling Daemons** -- `lnms` CLI or `poller.php`; SNMP polling on configurable intervals
- **Discovery Daemons** -- `discovery.php`; auto-discovers devices and their capabilities
- **RRDtool** -- Default time-series storage for graphing data
- **Optional**: InfluxDB or Prometheus for alternative time-series storage

### Polling Cycle
```
Discovery (every 4-6 hours by default):
  SNMP walk device -> Identify capabilities -> Create ports, sensors, graphs

Polling (every 5 minutes by default):
  SNMP poll each device -> Update metrics -> Evaluate alerts -> Write to RRD/InfluxDB
```

## SNMP Auto-Discovery

### Discovery Methods
- **SNMP**: Poll IP range or individual hosts with configured SNMP credentials
- **CDP**: Discover neighbors from Cisco Discovery Protocol data
- **LLDP**: Discover neighbors from Link Layer Discovery Protocol data
- **BGP**: Discover BGP peers as potential monitored devices
- **ARP**: Discover hosts from ARP table entries on monitored routers
- **Manual subnet scan**: ICMP + SNMP probe across IP range

### Device Library
- 10,000+ device definitions (YAML-based)
- Each definition specifies: sysObjectID match, supported metrics, custom OIDs, graph definitions, health sensors
- Auto-applied based on SNMP sysObjectID during discovery
- Community-maintained; contribute new definitions via GitHub PR

### Discovery Configuration
```php
# config.php or .env
$config['autodiscovery']['xdp'] = true;    // CDP/LLDP discovery
$config['autodiscovery']['ospf'] = true;   // OSPF neighbor discovery
$config['autodiscovery']['bgp'] = true;    // BGP peer discovery
$config['snmp']['community'] = ['public', 'community2'];  // v2c communities
// SNMPv3 configured per device or globally
```

## Alerting

### Alert Rules
SQL-like syntax querying the LibreNMS data model:

```
# Interface down
ports.ifOperStatus = "down" AND ports.ifAdminStatus = "up"

# High CPU (generic)
processors.processor_usage > 90

# High memory
mempools.mempool_perc > 95

# Device unreachable
devices.status = 0

# Interface errors exceeding threshold
ports.ifInErrors_rate > 100

# Custom sensor threshold
sensors.sensor_current > sensors.sensor_limit
```

### Alert Transports
| Transport | Configuration |
|---|---|
| Email | SMTP relay settings |
| Slack | Webhook URL |
| Microsoft Teams | Webhook URL |
| PagerDuty | API key |
| OpsGenie | API key |
| Telegram | Bot token + chat ID |
| Discord | Webhook URL |
| Webhook | Custom HTTP POST URL |
| JIRA | API credentials + project |
| Syslog | UDP/TCP syslog target |
| Nagios-compatible | Command execution |

### Alert Templates
- Customizable HTML/text templates for notifications
- Variable substitution: `{{ $alert->hostname }}`, `{{ $alert->title }}`, `{{ $alert->severity }}`
- Per-transport templates supported

### Alert Groups and Routing
- Alert rules assigned to device groups
- Device groups defined by rules (location, type, custom fields)
- Different transports per group (network team gets Slack, management gets email)

### Maintenance Windows
- Schedule suppression periods for planned maintenance
- Recurring or one-time windows
- Per-device or per-group scope

## Oxidized Integration

### Architecture
- **Oxidized** -- Standalone open-source config backup tool (Ruby-based)
- **LibreNMS provides device list** to Oxidized via API (no duplicate inventory)
- Oxidized connects to devices via SSH/Telnet, retrieves running config
- Configs committed to Git repository (version history, diff capability)

### Configuration
```yaml
# Oxidized config.yml
source:
  default: http
  http:
    url: https://librenms.example.com/api/v0/oxidized
    map:
      name: hostname
      model: os
    headers:
      X-Auth-Token: <librenms-api-token>

output:
  default: git
  git:
    repo: /opt/oxidized/configs.git
```

### Capabilities
- 300+ device type support (Cisco IOS/NX-OS, Junos, Arista EOS, FortiOS, PAN-OS, etc.)
- Git-backed history: diff configs across time
- Detect unauthorized changes: alert on config diff
- LibreNMS displays config history and diffs in device view
- Extensible with Ruby scripts for custom device types

## Custom Dashboards

### Built-in Dashboards
- **Overview**: Device availability, alert summary, traffic summary
- **Custom dashboard builder**: Drag-and-drop widgets
- **Widget types**: Graphs, device lists, alert lists, maps, custom HTML, top interfaces, availability

### Grafana Integration
- LibreNMS as Grafana data source (direct MySQL or via InfluxDB)
- Full Grafana dashboard ecosystem for custom visualizations
- Pre-built LibreNMS dashboards available from Grafana community
- InfluxDB storage recommended for Grafana integration (better query performance than RRDtool)

## Distributed Polling

### Architecture
- Multiple `poller` instances on separate servers
- Devices assigned to specific pollers (manually or round-robin)
- All pollers write to the same MySQL/MariaDB database
- **rrdcached**: RRDtool caching daemon for write performance at scale

### Components
```
[Poller 1 (HQ)]     --> [MySQL/MariaDB (shared)] <-- [Web Server]
[Poller 2 (Branch)]  --> [MySQL/MariaDB (shared)] <-- [Web Server]
[Poller 3 (DC)]      --> [MySQL/MariaDB (shared)]
                              |
                     [rrdcached (shared)]
                              |
                     [RRD files (shared NFS/local)]
```

### Scaling Guidelines
| Device Count | Architecture |
|---|---|
| <500 | Single server (all-in-one) |
| 500-2,000 | Single server + rrdcached |
| 2,000-10,000 | Distributed pollers + rrdcached + InfluxDB |
| 10,000+ | Multiple pollers + InfluxDB + dedicated MySQL |

## REST API

### Authentication
- API token generated per user in LibreNMS web UI
- Header: `X-Auth-Token: <token>`

### Key Endpoints
```bash
# List devices
GET /api/v0/devices

# Get specific device
GET /api/v0/devices/{hostname}

# Add device
POST /api/v0/devices
Body: {"hostname": "switch01", "version": "v2c", "community": "public"}

# Get device ports
GET /api/v0/devices/{hostname}/ports

# Get port graphs
GET /api/v0/devices/{hostname}/ports/{portid}/port_bits

# List alerts
GET /api/v0/alerts

# Oxidized device list (for Oxidized integration)
GET /api/v0/oxidized

# Search devices
GET /api/v0/devices?type=hostname&query=switch
```

### Use Cases
- CMDB synchronization (import/export device inventory)
- Automated device onboarding from provisioning systems
- Custom dashboards pulling LibreNMS data
- Integration with ticketing systems (alert -> create ticket)

## Storage Options

### RRDtool (Default)
- Round-robin database; fixed-size files per metric
- Automatic data aggregation (5-min detail, hourly average, daily average)
- Pros: Simple, no external database, proven
- Cons: Fixed retention, difficult to query ad-hoc, poor Grafana performance

### InfluxDB
- Time-series database with flexible retention policies
- Better query performance for ad-hoc analysis and Grafana
- Supports longer retention at full granularity
- Requires additional infrastructure (InfluxDB server)

### Prometheus
- Pull-based time-series database
- LibreNMS exports metrics in Prometheus format
- Integrates with Prometheus alerting and Grafana
- Use when Prometheus is already part of the observability stack

## Common Pitfalls

1. **SNMP credentials mismatch** -- Most discovery failures are SNMP credential issues. Verify with `snmpwalk -v2c -c community device-ip` or equivalent v3 command.

2. **Discovery vs polling confusion** -- Discovery finds WHAT to monitor (runs every 4-6 hours). Polling collects metrics (runs every 5 minutes). A device must be discovered before it can be polled.

3. **RRDtool performance at scale** -- Without rrdcached, each poll cycle writes thousands of RRD files. Enable rrdcached for any deployment over 500 devices.

4. **Database growth** -- Event and syslog tables grow unbounded. Configure retention policies: `$config['eventlog_purge']` and `$config['syslog_purge']`.

5. **Alert transport testing** -- Always test transports with a manual test alert before relying on them. Misconfigured webhooks fail silently.

6. **Oxidized model mismatch** -- Oxidized uses "model" (device OS type) from LibreNMS. If the model maps incorrectly, config backup fails. Check the model mapping in Oxidized config.

7. **Not using device groups for alert routing** -- Sending all alerts to one channel creates noise. Use device groups to route alerts to the correct team.

8. **Missing 64-bit SNMP counters** -- High-speed interfaces (1G+) wrap 32-bit counters quickly. Ensure LibreNMS uses ifXTable (ifHCInOctets) by enabling 64-bit counter support.

## Reference Files

Load these when you need deep knowledge:

- `references/architecture.md` -- Architecture, auto-discovery, alerting, Oxidized, API, distributed polling. Read for "how does X work" questions.