Getting started
LibreNMS configuration
LibreNMS requires a MariaDB/MySQL database server. You can configure
one using debops.mariadb_server
and debops.mariadb
, either on the
same host as LibreNMS, or remotely.
The SNMP protocol is used to gather metrics from devices. Network switches / routers should
have an option to enable SNMP in their configuration, on Debian hosts you can use the
debops.snmpd
role to install and configure snmpd
service.
The debops.librenms
role will automatically use the username and password created
by the debops.snmpd
role as SNMP v3 credentials.
LLDP/xDP protocol is used for device autodiscovery and network map generation.
The debops.snmpd
role will automatically install a suitable LLDP daemon for you.
If you enable SNMP/LLDP on the LibreNMS host as well as other hosts, after
installation LibreNMS should automatically detect and add nearby devices when
it adds its own host to the database.
After installation, the LibreNMS webpage should be available at the nms.
subdomain.
You can access the LibreNMS CLI commands by switching to the librenms
system
user, for example via sudo
. You can find the installation in
the ~/sites/public
directory by default.
Useful variables
This is a list of role variables which you are most likely want to define in Ansible’s inventory to customize LibreNMS:
librenms__snmp_communities
List of SNMP v1/v2c communities LibreNMS should use to authenticate to network devices. By default it contains the community
public
.librenms__admin_accounts
List of admin accounts created in the LibreNMS database. Passwords are stored automatically in the
secret/
directory, see thedebops.secret
role for more details. By default an admin account based on theansible_user
variable is created.librenms__devices
List of devices to add to the LibreNMS database. Specify FQDN hostnames or IP addresses. By default LibreNMS will add its own host, based on the
ansible_fqdn
variable.
Example inventory
To install and configure LibreNMS on a host, you need to add the host to the
[debops_service_librenms]
Ansible host group:
[debops_service_librenms]
hostname
Example playbook
Here's an example playbook which uses the debops.librenms
role:
---
- name: Manage LibreNMS service
collections: [ 'debops.debops', 'debops.roles01',
'debops.roles02', 'debops.roles03' ]
hosts: [ 'debops_service_librenms' ]
become: True
environment: '{{ inventory__environment | d({})
| combine(inventory__group_environment | d({}))
| combine(inventory__host_environment | d({})) }}'
pre_tasks:
- name: Apply keyring configuration for php environment
import_role:
name: 'keyring'
vars:
keyring__dependent_apt_keys:
- '{{ php__keyring__dependent_apt_keys }}'
- '{{ nginx__keyring__dependent_apt_keys }}'
- '{{ mariadb__keyring__dependent_apt_keys }}'
tags: [ 'role::keyring', 'skip::keyring', 'role::php', 'role::nginx', 'role::mariadb' ]
- name: Prepare php environment
import_role:
name: 'php'
tasks_from: 'main_env'
tags: [ 'role::php', 'role::php:env', 'role::logrotate' ]
roles:
- role: apt_preferences
tags: [ 'role::apt_preferences', 'skip::apt_preferences' ]
apt_preferences__dependent_list:
- '{{ php__apt_preferences__dependent_list }}'
- '{{ nginx__apt_preferences__dependent_list }}'
- role: cron
tags: [ 'role::cron', 'skip::cron' ]
- role: logrotate
tags: [ 'role::logrotate', 'skip::logrotate' ]
logrotate__dependent_config:
- '{{ php__logrotate__dependent_config }}'
- '{{ librenms__logrotate__dependent_config }}'
- role: python
tags: [ 'role::python', 'skip::python', 'role::mariadb' ]
python__dependent_packages3:
- '{{ librenms__python__dependent_packages3 }}'
- '{{ mariadb__python__dependent_packages3 }}'
- '{{ nginx__python__dependent_packages3 }}'
python__dependent_packages2:
- '{{ librenms__python__dependent_packages2 }}'
- '{{ mariadb__python__dependent_packages2 }}'
- '{{ nginx__python__dependent_packages2 }}'
- role: ferm
tags: [ 'role::ferm', 'skip::ferm' ]
ferm__dependent_rules:
- '{{ nginx__ferm__dependent_rules }}'
- role: php
tags: [ 'role::php', 'skip::php' ]
php__dependent_packages:
- '{{ librenms__php__dependent_packages }}'
php__dependent_pools:
- '{{ librenms__php__dependent_pools }}'
- role: nginx
tags: [ 'role::nginx', 'skip::nginx' ]
nginx__dependent_servers:
- '{{ librenms__nginx__dependent_servers }}'
nginx__dependent_upstreams:
- '{{ librenms__nginx__dependent_upstreams }}'
- role: mariadb
tags: [ 'role::mariadb', 'skip::mariadb' ]
mariadb__dependent_users:
- '{{ librenms__mariadb__dependent_users }}'
- role: librenms
tags: [ 'role::librenms', 'skip::librenms' ]