A Puppet module for managing LibreNMS
The Puppet manifest used by Vagrant (vagrant/librenms.pp) shows how to
The manifest used by Vagrant uses two optional features of this module that
To import a node into LibreNMS using exported resources:
class { '::snmpd':
allow_address_ipv4 => '10.0.0.0',
allow_netmask_ipv4 => '8',
users => { 'monitor' => { 'pass' => 'my-password' } },
}
class { '::librenms::device':
proto => 'v3',
user => 'monitor',
pass => 'my_password',
}
To use SNMPv2 instead:
class { '::librenms::device':
proto => 'v2',
community => 'public',
}
Create and remove devices using LibreNMS v0 API:
librenms_device { 'snmpv3.example.org':
ensure => 'present',
url => 'https://librenms.example.org/api/v0',
auth_token => '0123456789abcde0123456789abcded0',
snmpver => 'v3',
authlevel => 'noAuthNoPriv',
authname => 'snmpuser',
authpass => 'secret',
authalgo => 'sha',
cryptopass => 'secret',
cryptoalgo => 'aes',
}
librenms_device { 'snmpv2.example.org':
ensure => 'present',
url => 'https://librenms.example.org/api/v0',
auth_token => '0123456789abcde0123456789abcded0',
snmpver => 'v2c',
community => 'public',
}
# Ensure that a decommissioned node is not present in LibreNMS
librenms_device { 'decommissioned.example.org':
ensure => 'absent',
}
The provider uses the "force_add" parameter to ensure that nodes that are (temporarily) inaccessible (e.g. being provisioned) are added correctly.
You can also manage services using the LibreNMS v0 API:
librenms_service { 'http-on-librenms':
ensure => 'present',
url => 'http://librenms.example.org/api/v0',
auth_token => '0123456789abcde0123456789abcded0',
hostname => 'librenms.example.org',
type => 'http',
ip => 'librenms.example.org',
param => 'C 50 --sni -S',
}
There are couple of caveats regarding service management:
To create CustomOID checks use the librenms_customoid type. Below an example of how to use this with net-snmp-systemd-service-status:
$service = 'sshd'
# Convert human-readable (ASCII) name to an OID
$oid = librenms::name_to_oid($service)
$descr = "${service} on ${::fqdn}"
@@librenms_customoid { $descr:
ensure => present,
# Database username and password: there's no API support for manipulating
# CustomOIDs
username => 'librenms',
password => 'secret',
# Bind this CustomOID to hostname that matches value of $::fqdn fact
hostname => $::fqdn,
# Alternatively use sysName instead for the mapping
# sysName => $::hostname,
# Turn on alerting for this CustomOID.
alert => 1,
# Human readable description
descr => $descr,
# The OID, which matches the service name converted to ASCII.
oid => $oid,
# Send critical alert if the service is not up. We get 0 if it is up, 1
# otherwise.
limit => 1,
# Collect using tags
tag => 'default'
}
Then just realize the exported resources on the LibreNMS server:
Librenms_customoid <<| tag == 'default' |>>
See lib/puppet/type/librenms_customoid.rb for documentation of all the available parameters.
If you have Vagrant and virtualbox installed then setting up LibreNMS test instance from scratch should be as easy as:
$ vagrant up
LibreNMS UI can be reached via
Username is "admin" and password is "vagrant". The instance adds itself to LibreNMS, so you should see one device, "librenms.vagrant.example.lan" under devices.
If you want to use snmpwalk note that the username is "librenms" and password is "vagrant123".