LibreNMS is a fully featured network monitoring system that provides extensive support for a wide range of network devices. It is based on Observium and uses SNMP for data collection.
| File/Directory | Path | Purpose |
|---|---|---|
| Main config | /opt/librenms/config.php or /opt/librenms/config.php.d/ |
Core configuration |
| RRD storage | /opt/librenms/rrd/ |
Performance data storage |
| Logs | /opt/librenms/logs/ |
System and poller logs |
| Alert templates | /opt/librenms/html/alerts/templates/ |
Alert rule templates |
| Alert rules | /opt/librenms/alert_rules/ |
Custom alert definitions |
| Discovery scripts | /opt/librenms/lib/ |
Discovery modules |
| Poller modules | /opt/librenms/lib/polling/ |
Polling modules |
| Web config | /etc/nginx/sites-available/librenms or /etc/apache2/sites-available/librenms.conf |
Web server config |
| Cron jobs | /etc/cron.d/librenms |
Scheduled tasks |
| SNMP config | /etc/snmp/snmp.conf |
SNMP community settings |
<?php
// /opt/librenms/config.php
// Database configuration
$config['db_host'] = 'localhost';
$config['db_user'] = 'librenms';
$config['db_pass'] = 'YourSecurePassword123!';
$config['db_name'] = 'librenms';
// Base URL
$config['base_url'] = 'https://librenms.example.com';
// Display settings
$config['page_title'] = 'LibreNMS Network Monitoring';
$config['project_name'] = 'librenms';
$config['stylesheet'] = 'css/styles.css';
$config['display_logo'] = 'images/librenms.png';
// Polling settings
$config['poller_threads'] = 16; // Number of poller threads
$config['poller_frequency'] = 300; // Polling interval in seconds (5 min)
$config['discovery_frequency'] = 86400; // Discovery interval (24 hours)
$config['ping_timeout'] = 500; // Ping timeout in milliseconds
$config['ping_retries'] = 2; // Number of ping retries
// SNMP settings
$config['snmp']['version'] = 'v2c';
$config['snmp']['community'] = 'public'; // Default community string
$config['snmp']['timeout'] = 1000; // SNMP timeout in ms
$config['snmp']['retries'] = 1; // SNMP retries
$config['snmp']['transport'] = 'udp';
// Alerting settings
$config['alert']['default_mail'] = 'alerts@example.com';
$config['alert']['default_only'] = true;
$config['alert']['transports']['email'] = [
'driver' => 'smtp',
'host' => 'smtp.example.com',
'port' => 587,
'username' => 'librenms@example.com',
'password' => 'EmailPassword123!',
'encryption' => 'tls',
'timeout' => 30,
];
// Syslog settings
$config['syslog']['enable'] = true;
$config['syslog']['retention'] = 30; // Days to retain syslog data
// Location settings
$config['location']['show'] = true;
$config['location']['coordinates'] = true;
// External integrations
$config['integrations']['slack']['webhook'] = 'https://hooks.slack.com/services/XXX/YYY/ZZZ';
$config['integrations']['pagerduty']['service_key'] = 'your-pagerduty-key';
// Performance tuning
$config['rrd_purge'] = 0; // Never purge RRD files
$config['rrdgraph_defer'] = false; // Generate graphs on demand
$config['update'] = true; // Enable auto-updates
$config['update_channel'] = 'master'; // Update channel
// Security
$config['allow_user_registration'] = false;
$config['auth_mechanism'] = 'mysql';
$config['session_lifetime'] = 86400; // Session timeout in seconds
// Discovery modules
$config['discovery_modules'] = [
'ports' => true,
'ports-adsl' => true,
'ports-xdsl' => true,
'ipv4-addresses' => true,
'ipv6-addresses' => true,
'bgp-peers' => true,
'os' => true,
'entity-physical' => true,
'processors' => true,
'mempools' => true,
'storage' => true,
'netstats' => true,
'hr-mib-disks' => true,
'snmpinfo' => true,
'uptime' => true,
'sensors' => true,
'state' => true,
'fdb-table' => true,
'arp-table' => true,
'vrf' => true,
'stp' => true,
'transceivers' => true,
'cisco-cef' => true,
'slas' => true,
'cisco-otv' => true,
'cisco-ace-containers' => true,
'cisco-ace-serverfarms' => true,
'cisco-asa-ipsec-tunnels' => true,
'cisco-ipsla' => true,
'cisco-mac-accounting' => true,
'cisco-pw' => true,
'cisco-vpdn' => true,
'xfrm-tunnels' => true,
'junose-atm' => true,
'qos' => true,
'mpls' => true,
'ospf' => true,
'isis' => true,
'pseudowires' => true,
'ntp' => true,
'ipsec-tunnels' => true,
'cisco-ace-containers' => true,
];
// Ports configuration
$config['ports']['ifname'] = true;
$config['ports']['ifalias'] = true;
$config['ports']['ifdescr'] = true;
$config['ports']['iftype'] = true;
$config['ports']['speed'] = true;
$config['ports']['ifAdminStatus'] = true;
$config['ports']['ifOperStatus'] = true;
// Billing module
$config['billing']['base'] = 1000; // Set to 1000 for bits, 1024 for bytes
$config['billing']['calculate'] = true;
$config['billing']['cutoff'] = 20; // Day of month for billing cycle
// API settings
$config['api']['enabled'] = true;
$config['api']['allowed_ips'] = ['127.0.0.1', '192.168.1.0/24'];
// Two-factor authentication
$config['two_factor'] = false;
// LDAP authentication (optional)
$config['auth_ldap'] = [
'enabled' => false,
'server' => 'ldap.example.com',
'port' => 389,
'version' => 3,
'user_group' => 'librenms-users',
'admin_group' => 'librenms-admins',
'bind_dn' => 'cn=admin,dc=example,dc=com',
'bind_password' => 'LdapPassword123!',
'user_dn' => 'ou=users,dc=example,dc=com',
'user_attribute' => 'uid',
];
For better organization, use the config.php.d/ directory:
// /opt/librenms/config.php.d/01-database.php
<?php
$config['db_host'] = 'localhost';
$config['db_user'] = 'librenms';
$config['db_pass'] = 'YourSecurePassword123!';
$config['db_name'] = 'librenms';
// /opt/librenms/config.php.d/02-snmp.php
<?php
$config['snmp']['version'] = 'v2c';
$config['snmp']['community'] = 'YourCommunityString';
$config['snmp']['timeout'] = 1000;
$config['snmp']['retries'] = 1;
$config['snmp']['transport'] = 'udp';
// /opt/librenms/config.php.d/03-alerting.php
<?php
$config['alert']['default_mail'] = 'alerts@example.com';
$config['alert']['transports']['email'] = [
'driver' => 'smtp',
'host' => 'smtp.example.com',
'port' => 587,
'username' => 'librenms@example.com',
'password' => 'EmailPassword123!',
'encryption' => 'tls',
];
// /opt/librenms/config.php.d/04-integrations.php
<?php
$config['integrations']['slack']['webhook'] = 'https://hooks.slack.com/services/XXX/YYY/ZZZ';
$config['integrations']['pagerduty']['service_key'] = 'your-pagerduty-key';
$config['integrations']['webhook']['url'] = 'https://your-webhook.example.com/alert';
// Multiple SNMP communities for different device types
$config['snmp']['communities']['default'] = 'public';
$config['snmp']['communities']['routers'] = 'router-readonly';
$config['snmp']['communities']['switches'] = 'switch-readonly';
$config['snmp']['communities']['servers'] = 'server-monitoring';
// SNMPv3 configuration
$config['snmp']['v3']['username'] = 'monitoring';
$config['snmp']['v3']['authlevel'] = 'authPriv'; // authNoPriv, authPriv, noAuthNoPriv
$config['snmp']['v3']['authalgo'] = 'SHA';
$config['snmp']['v3']['authpass'] = 'AuthPassword123!';
$config['snmp']['v3']['cryptoalgo'] = 'AES';
$config['snmp']['v3']['cryptopass'] = 'CryptoPassword123!';
$config['snmp']['v3']['contextname'] = '';
// Control what gets discovered
$config['discovery_by_ip'] = true;
$config['discovery_on_add'] = true;
$config['autodiscovery']['enabled'] = true;
$config['autodiscovery']['networks'] = [
'192.168.1.0/24',
'192.168.2.0/24',
'10.0.0.0/8',
];
// ARP and FDB table retention
$config['arp_table_retention'] = 7; // Days
$config['fdb_table_retention'] = 7; // Days
// Port description parsing
$config['port_descr_parser'] = 'librenms';
$config['port_descr_type'] = 'librenms';
// Adjust polling based on device type
$config['os']['cisco']['poller_frequency'] = 180; // Cisco devices every 3 min
$config['os']['juniper']['poller_frequency'] = 180; // Juniper every 3 min
$config['os']['linux']['poller_frequency'] = 300; // Linux servers every 5 min
// Disable specific polls for performance
$config['enable_bgp'] = true;
$config['enable_ospf'] = true;
$config['enable_isis'] = false;
$config['enable_mpls'] = true;
$config['enable_pseudowires'] = false;
$config['enable_vrf'] = true;
$config['enable_stp'] = false;
$config['enable_sensors'] = true;
$config['enable_storage'] = true;
# Add a single device
./addhost.php -h 192.168.1.1 -c public -v 2c
# Add with SNMPv3
./addhost.php -h 192.168.1.1 -v 3 -u monitoring -l authPriv -a SHA -A AuthPass123 -x AES -X CryptoPass123
# Add multiple devices from file
./addhost.php -h device1,device2,device3 -c public
# Add with specific OS
./addhost.php -h 192.168.1.1 -c public -o cisco-ios
# Add with location and coordinates
./addhost.php -h 192.168.1.1 -c public -L "Data Center 1" -g 40.7128,-74.0060
// Define device groups for bulk operations
$config['device_groups'] = [
'core-routers' => [
'devices' => ['router1', 'router2', 'router3'],
'poller_frequency' => 120,
],
'access-switches' => [
'devices' => ['switch1', 'switch2', 'switch3', 'switch4'],
'poller_frequency' => 300,
],
'critical-servers' => [
'devices' => ['web01', 'db01', 'app01'],
'poller_frequency' => 60,
],
];
// Port-specific settings
$config['port']['ifDescr']['ignore'] = ['Loopback', 'Null', 'Vlan'];
$config['port']['ifName']['ignore'] = ['lo', 'docker', 'veth'];
// Port utilization thresholds
$config['port']['util_perc_warn'] = 75;
$config['port']['util_perc_crit'] = 90;
// Port error thresholds
$config['port']['errors_warn'] = 10;
$config['port']['errors_crit'] = 100;
$config['port']['discards_warn'] = 10;
$config['port']['discards_crit'] = 100;
Alert rules are stored in the database and managed via the web UI, but can also be defined:
-- Example alert rule for high CPU
INSERT INTO alert_rules (rule, name, severity, disabled) VALUES
(
'%devices.os = "cisco-ios" && %processors.processor_usage > 80',
'Cisco High CPU Usage',
'warning',
0
);
-- Alert for interface down
INSERT INTO alert_rules (rule, name, severity, disabled) VALUES
(
'%ports.ifOperStatus = "down" && %ports.ifAdminStatus = "up"',
'Interface Down',
'critical',
0
);
-- Alert for disk space
INSERT INTO alert_rules (rule, name, severity, disabled) VALUES
(
'%storage.storage_perc_used > 90',
'Disk Space Critical',
'critical',
0
);
<!-- /opt/librenms/html/alerts/templates/email.html -->
<!DOCTYPE html>
<html>
<head>
<style>
body { font-family: Arial, sans-serif; }
.alert-critical { background-color: #ff4444; color: white; }
.alert-warning { background-color: #ffbb33; color: black; }
.alert-ok { background-color: #00C851; color: white; }
table { border-collapse: collapse; width: 100%; }
td, th { border: 1px solid #ddd; padding: 8px; }
</style>
</head>
<body>
<h2 class="alert-{$severity}">LibreNMS Alert: {$title}</h2>
<p><strong>Device:</strong> {$hostname}</p>
<p><strong>Severity:</strong> {$severity}</p>
<p><strong>Timestamp:</strong> {$timestamp}</p>
<p><strong>Message:</strong> {$msg}</p>
<table>
<tr><th>Metric</th><th>Value</th><th>Threshold</th></tr>
<tr><td>{$metric_name}</td><td>{$metric_value}</td><td>{$threshold}</td></tr>
</table>
<p><a href="{$url}">View in LibreNMS</a></p>
</body>
</html>
// Email transport
$config['alert']['transports']['email'] = [
'driver' => 'smtp',
'host' => 'smtp.example.com',
'port' => 587,
'username' => 'librenms@example.com',
'password' => 'EmailPassword',
'encryption' => 'tls',
'from' => ['address' => 'librenms@example.com', 'name' => 'LibreNMS Alerts'],
];
// Slack transport
$config['alert']['transports']['slack'] = [
'driver' => 'slack',
'channel' => '#monitoring-alerts',
'username' => 'LibreNMS',
'icon' => ':warning:',
'webhook' => 'https://hooks.slack.com/services/XXX/YYY/ZZZ',
];
// PagerDuty transport
$config['alert']['transports']['pagerduty'] = [
'driver' => 'pagerduty',
'service_key' => 'your-pagerduty-service-key',
'client' => 'LibreNMS',
'client_url' => 'https://librenms.example.com',
];
// Webhook transport
$config['alert']['transports']['webhook'] = [
'driver' => 'webhook',
'url' => 'https://your-webhook.example.com/alert',
'method' => 'POST',
'headers' => [
'Content-Type' => 'application/json',
'Authorization' => 'Bearer your-token',
],
];
// Microsoft Teams transport
$config['alert']['transports']['teams'] = [
'driver' => 'webhook',
'url' => 'https://outlook.office.com/webhook/XXX/YYY/ZZZ',
];
# Change to LibreNMS directory
cd /opt/librenms
# Validate configuration syntax
./validate.php
# Check database schema
./scripts/check_db_schema.php
# Test SNMP connectivity
./snmpwalk.php -h 192.168.1.1 -c public
# Run discovery test
./discovery.php -h 192.168.1.1 -v
# Run poller test
./poller.php -h 192.168.1.1 -v
# Restart LibreNMS services
sudo systemctl restart librenms
sudo systemctl restart librenms-poller
sudo systemctl restart librenms-discovery
sudo systemctl restart librenms-alerter
# Check service status
sudo systemctl status librenms
sudo systemctl status librenms-poller
# Restart web server
sudo systemctl restart nginx
# or
sudo systemctl restart apache2
# Restart PHP-FPM if applicable
sudo systemctl restart php-fpm
# or
sudo systemctl restart php7.4-fpm
Ensure cron jobs are properly configured:
# /etc/cron.d/librenms
# LibreNMS cron jobs
# Discovery
*/5 * * * * librenms /opt/librenms/discovery.php -h all >> /dev/null 2>&1
# Polling
*/5 * * * * librenms /opt/librenms/poller.php -h all >> /dev/null 2>&1
# Alerting
*/5 * * * * librenms /opt/librenms/alert.php >> /dev/null 2>&1
# Bill calculation
*/5 * * * * librenms /opt/librenms/billcalc.php >> /dev/null 2>&1
# Cleanup
*/5 * * * * librenms /opt/librenms/cleanup.php >> /dev/null 2>&1
# Fetching weathermap data
*/5 * * * * librenms /opt/librenms/weathermap-cron.php >> /dev/null 2>&1
# ARPing
*/5 * * * * librenms /opt/librenms/arping.php >> /dev/null 2>&1
# Port availability polling
*/5 * * * * librenms /opt/librenms/ping.php >> /dev/null 2>&1
# Test device discovery
cd /opt/librenms
./discovery.php -h 192.168.1.1 -v
# List all discovered devices
./discovery.php -l
# Force rediscovery of a device
./discovery.php -h 192.168.1.1 -r
# Test polling for a device
./poller.php -h 192.168.1.1 -v
# Check poller performance
./poller.php -h all -d
# View poller statistics
./poller.php -s
# Test alerting system
./alert.php --test
# View alert log
tail -f /opt/librenms/logs/alerts.log
# Check alert rules
./alert.php --rules
# Send test alert
./alert.php --test-email admin@example.com
# View poller logs
tail -f /opt/librenms/logs/poller.log
# View discovery logs
tail -f /opt/librenms/logs/discovery.log
# View alert logs
tail -f /opt/librenms/logs/alerts.log
# View web interface logs
tail -f /var/log/nginx/librenms.error.log
# or
tail -f /var/log/apache2/librenms.error.log
poller_threads = CPU_cores * 2Running LibreNMS in regulated environments? We assist with:
Secure your deployment: office@linux-server-admin.com | Contact Page