Skip to main content

​
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
monk load MANIFEST
  1. Run LibreNMS stack with defaults
monk run librenms/librenms
  1. 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: 
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. Inherit the LibreNMS runnable in your infrastructure and declare connections. Example: 
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: 
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: 
# 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
  • 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:
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