DEBOPS.LIBRENMS(5)

NAME
debops.librenms - Manage LibreNMS service using Ansible

SYNOPSIS

debops run service/librenms [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

LibreNMS <http://www.librenms.org/> is a network monitoring dashboard written in PHP. It can use SNMP, collectd, check_mk or other agents to gather data from variety of devices (switches, routers, servers, etc.) and graph them using RRD. It's easy to use, and can perform autodiscovery to find and monitor additional devices.

debops.librenms role will manage a central LibreNMS monitoring host and web interface.

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:
    - name: Apply keyring configuration for php environment
      ansible.builtin.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
      ansible.builtin.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.

DEFAULT VARIABLES: CONFIGURATION

Some of debops.librenms default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  librenms__snmp_credentials

LibreNMS can use multiple SNMPv3 credentials at once, each one defined in a YAML dict. Default set of credentials managed by debops.snmpd which will use it for all DebOps-based hosts in the cluster will be used automatically by debops.librenms. You can add more entries in librenms__snmp_credentials list as needed.

Parameters which define SNMP credentials:

authname
    SNMP v3 username.

authpass
    SNMP v3 authentication password.

cryptopass
    SNMP v3 encryption password.

authlevel
    Authentication and privacy level required by connection, you most likely want to use authPriv to request encrypted authentication and encrypted privacy.

authalgo
    Authentication encryption algorithm used for this credentials, either SHA or MD5.

cryptoalgo
    Privacy encryption algorithm used for this credentials, either AES or DES.

    For an example of SNMP v3 credentials, check out librenms__snmp_credentials_default variable in defaults/main.yml.

  librenms__configuration_maps

LibreNMS configuration is stored as PHP $config dictionary in config.php in main project directory. To make it easier to manage using Ansible, a Jinja template is used to recursively convert a list of dictionaries in YAML format to PHP format. Configuration is split into multiple dictionaries, so that separate sections can be modified easier without the need to copy everything to Ansible inventory.

Basic YAML syntax mirrors PHP syntax for dictionaries. Specifying your configuration in a YAML dict like:

librenms__configuration_maps:
  - '{{ librenms__configuration }}'
librenms__configuration:
  comment: 'Example configuration'
  'dict_string': 'string'
  'dict_bool': True
  'dict_int': 10

Will result in PHP configuration:

### Example configuration
$config['dict_string'] = "string";
$config['dict_bool'] = TRUE;
$config['dict_int'] = 10;

Special key comment is reserved for comments in the configuration.

You can use YAML lists as well:

librenms__configuration_maps:
  - '{{ librenms__configuration }}'
librenms__configuration:
  'dict_list': [ 'first', 'second', 'third' ]

This will result in dict-like list which appends entries to already existing ones from defaults:

$config['dict_list'][] = "first";
$config['dict_list'][] = "second";
$config['dict_list'][] = "third";

You can also define a specific list without appending to existing list using array dict key:

librenms__configuration_maps:
  - '{{ librenms__configuration }}'
librenms__configuration:
  'dict_array': { array: [ 'one', 'two', 'three' ] }

This will result in PHP configuration:

$config['dict_array'] = array("one", "two", "three");

Dictionaries and list can be nested as well:

librenms__configuration_maps:
  - '{{ librenms__configuration }}'
librenms__configuration:
  'dict_nested':
    'second_level':
      'third_list': [ 'abc', 'def' ]
      'third_string': 'example string'

This will result in PHP configuration:

$config['dict_nested']['second_level']['third_list'][] = "abc";
$config['dict_nested']['second_level']['third_list'][] = "def";
$config['dict_nested']['second_level']['third_string'] = "example string";

You can use lists of dictionaries as well. They will be automatically enumerated at the correct level. This YAML configuration:

librenms__configuration_maps:
  - '{{ librenms__configuration }}'
librenms__configuration:
  'dicts':
    - key0: 'value0'
      key1: 'value1'
    - key0: 'value2'
      key1: 'value3'

will result in PHP configuration:

$config['dicts'][0]['key0'] = "value0";
$config['dicts'][0]['key1'] = "value1";
$config['dicts'][1]['key0'] = "value2";
$config['dicts'][1]['key1'] = "value3";

Template conversion might be incomplete, however at the moment it's enough to generate correct config.php file for LibreNMS.

AUTHOR
Maciej Delmanowski

COPYRIGHT
2014-2024, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others