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' ]
Ansible tags¶
You can use Ansible --tags
or --skip-tags
parameters to limit what
tasks are performed during Ansible run. This can be used after the host is first
configured to speed up playbook execution, when you are sure that most of the
configuration has not been changed.
Available role tags:
role::librenms
- Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.
role::librenms:source
- Clone or pull latest changes from LibreNMS repository.
role::librenms:config
- Run tasks related to LibreNMS configuration, including
~/.snmp/snmp.conf
,config.php
, creation of admin accounts and device discovery. role::librenms:database
- Configure and initialize LibreNMS database.
role::librenms:snmp_conf
- Update
~/.snmp/snmp.conf
configuration files. role::librenms:admins
- Create missing LibreNMS admin accounts.
role::librenms:devices
- Add missing devices to LibreNMS database.