> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# LibreNMS

> Ready-to-run LibreNMS container template you can run directly or inherit to integrate network monitoring and autodiscovery into your infrastructure.

## Overview

This template provides a production‑ready LibreNMS instance as a Monk runnable. You can:

* Run it directly to get a managed network monitoring platform with sensible defaults
* Inherit it in your own infrastructure to seamlessly add network monitoring to your stack

LibreNMS is a fully featured network monitoring system with automatic discovery, alerting, and graphing. It exposes a web UI on port 8000, persists data to host volumes, and supports a wide range of network hardware and operating systems including Cisco, Linux, FreeBSD, Juniper, and many more.

## What this template manages

* LibreNMS application server container
* MySQL/MariaDB for data storage
* RRDCached for performance graphing
* SNMP polling and discovery
* Web UI and RESTful API on port 8000
* Alerting engine with multiple transports
* Persistent volumes for data, graphs, and database

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run LibreNMS stack with defaults

```bash theme={null}
monk run librenms/librenms
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `librenms/librenms.yaml`, then `monk load MANIFEST` and run.

Once started, access LibreNMS at `http://localhost:8000` (or the runnable hostname inside Monk networks).

Default credentials: `admin` / `admin` (change immediately!)

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  # LibreNMS
  librenms-image-tag: "latest"        # container image tag
  librenms-port: "8000"               # web UI port (env: exposed as service)
  timezone: "UTC"                     # timezone (env: TZ)
  
  # Database
  db-host: "mysql"                    # database host
  db-name: "librenms"                 # database name (env: MYSQL_DATABASE)
  db-user: "librenms"                 # database user (env: MYSQL_USER)
  db-password: "..."                  # database password (env: MYSQL_PASSWORD)
  db-root-password: "..."             # root password (env: MYSQL_ROOT_PASSWORD)
  
  # Monitoring
  poller-threads: "16"                # number of poller threads
  discovery-threads: "1"              # number of discovery threads
```

Data is persisted under `${monk-volume-path}/librenms` and `${monk-volume-path}/mysql` on the host.

## Use by inheritance (recommended for network ops)

Inherit the LibreNMS runnable in your infrastructure and declare connections. Example:

```yaml theme={null}
namespace: netops
monitoring:
  defines: runnable
  inherits: librenms/librenms
  variables:
    db-password:
      value: <- secret("librenms-db-password")
    db-root-password:
      value: <- secret("mysql-root-password")
    timezone:
      value: "America/New_York"
    poller-threads:
      value: "32"
```

Then set the secrets once and run your infrastructure:

```bash theme={null}
monk secrets add -g librenms-db-password="STRONG_PASSWORD"
monk secrets add -g mysql-root-password="STRONG_ROOT_PASSWORD"
monk run netops/monitoring
```

## Ports and connectivity

* Service: `librenms` on TCP port `8000` (Web UI)
* SNMP traps: UDP port `162` (if enabled)
* Syslog: TCP/UDP port `514` (if enabled)
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the LibreNMS host.

## Persistence and configuration

* LibreNMS data: `${monk-volume-path}/librenms/data:/data`
* RRD files: `${monk-volume-path}/librenms/rrd:/data/rrd`
* MySQL data: `${monk-volume-path}/mysql:/var/lib/mysql`
* Ensure the host volumes are writable by the container user.

## Features

* **Auto-Discovery**: Automatically discover network devices
* **SNMP Monitoring**: Poll devices via SNMPv1/v2c/v3
* **Graphing**: Historical performance graphs with RRDtool
* **Alerting**: Flexible alerting with multiple transports (email, Slack, webhooks)
* **Device Support**: 1000+ device types
* **API**: RESTful API for automation
* **Distributed Polling**: Scale with multiple pollers
* **Customizable Dashboards**: Create custom views
* **Billing**: Track bandwidth usage

## Adding Devices

Add devices via:

1. **Web UI**: Devices → Add Device
2. **Auto-discovery**: Settings → Discovery → Discover new devices
3. **API**: Use REST API to add devices programmatically

Example device configuration:

* **Hostname/IP**: 192.168.1.1
* **SNMP Version**: v2c or v3
* **Community**: public (v2c) or credentials (v3)

## Alerting

Configure alerts:

* Set thresholds for metrics (CPU, memory, bandwidth)
* Create alert rules with conditions
* Configure alert transports (email, Slack, PagerDuty, etc.)
* Set maintenance windows

## Device Support

LibreNMS supports:

* **Networking**: Cisco, Juniper, Arista, HP, MikroTik, Ubiquiti
* **Servers**: Linux, Windows, FreeBSD, ESXi
* **Storage**: NetApp, EMC, Synology
* **Appliances**: Firewalls, load balancers, UPS
* **IoT**: Environmental sensors, PDUs

## API Usage

Example API call:

```bash theme={null}
# List devices
curl -H "X-Auth-Token: YOUR_API_TOKEN" \
  http://localhost:8000/api/v0/devices

# Add device
curl -X POST -H "X-Auth-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"192.168.1.1","community":"public"}' \
  http://localhost:8000/api/v0/devices
```

## Use cases

LibreNMS excels at:

* Network infrastructure monitoring
* Server and service monitoring
* SNMP device monitoring
* Bandwidth accounting
* Environmental monitoring (temperature, humidity)
* Alerting and notifications
* Capacity planning

## Related templates

* Integrate with databases and services for comprehensive monitoring
* Use with alerting systems (PagerDuty, Slack, email)
* Combine with log aggregation tools (`elk/`, `fluentbit/`)
* High‑availability setup: see the `librenms-ha/` template in this repository for distributed polling.

## Troubleshooting

* Access LibreNMS UI at `http://localhost:8000`
* Check poller status: System → Pollers
* Validate installation: `./validate.php` in container
* Ensure the host volumes are writable by the container user.
* Check logs:

```bash theme={null}
monk logs -l 500 -f librenms/librenms
```

**Common issues:**

* **Device discovery issues:**
  * Verify SNMP connectivity: `snmpwalk -v2c -c public \<device-ip>`
  * Check firewall rules for UDP 161
  * Verify SNMP community string
* **Slow polling:** Increase `poller-threads` variable
* **Graph issues:** Check RRD file permissions in data volume
* **Database performance:** Monitor MySQL performance for large deployments
* **Authentication fails after password change:** Either reset the data volume or update credentials inside the DB to match