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_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:

    - 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' ]

    - 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.