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 the debops.secret role for more details. By default an admin account based on the ansible_ssh_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_librenms] Ansible host group:

[debops_librenms]
hostname

Example playbook

Here’s an example playbook which uses the debops.librenms role:

---
- name: Configure LibreNMS
  hosts: debops_librenms

  roles:

    - role: debops.librenms
      tags: [ 'role::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.
type::dependency
This tag specifies which tasks are defined in role dependencies. You can use this to omit them using --skip-tags parameter.
depend-of::librenms
Execute all debops.librenms role dependencies in its context.
depend::mariadb:librenms
Run debops.mariadb dependent role in debops.librenms context.
depend::php5:librenms
Run debops.php5 dependent role in debops.librenms context.
depend::nginx:librenms
Run debops.nginx dependent role in debops.librenms context.
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.