Skip to content

Latest commit

 

History

History
887 lines (497 loc) · 16 KB

REFERENCE.md

File metadata and controls

887 lines (497 loc) · 16 KB
Raw

Reference

Table of Contents

Classes

Functions

Classes

librenms

Manages the whole LibreNMS installation, on a single node

Examples

# LibreNMS with Oxidized + Weathermap plugins, active Netscaler poller, AD logins, and sample TLS config
class { '::librenms':
  config_admin_email              => $admin_email,
  config_poller_threads           => 32,
  mysql_librenms_password         => $mysql_librenms_password,
  mysql_root_password             => $mysql_root_password,
  oxidized_auth_token             => $oxidized_api_token,
  oxidized_enabled                => true,
  oxidized_manage_repo            => true,
  snmp_location                   => 'Null Island',
  snmp_ro_community               => $snmp_ro_community,
  weathermap_enabled              => true,
  config_override_pollers         => {
    'netscaler-vsvr' => 1,
  },
  config_raw_input                => {
    'active_directory.users_purge'         => 14, # days
    'auth_ad_base_dn'                      => 'DC=domain,DC=com',
    'auth_ad_bindpassword'                 => $ad_bind_password,
    'auth_ad_binduser'                     => $ad_bind_username,
    'auth_ad_check_certificates'           => 0,
    'auth_ad_domain'                       => 'domain.com',
    'auth_ad_groups.LibreNMS_Admins.level' => 10,
    'auth_ad_groups.LibreNMS_Users.level'  => 5,
    'auth_ad_require_groupmembership'      => 1,
    'auth_ad_url'                          => 'ldaps://domain.com',
    'auth_mechanism'                       => 'active_directory',
    'authlog_purge'                        => 15, # days
    'oxidized.enabled'                     => true,
    'oxidized.url'                         => 'http://127.0.0.1:8888',
    'oxidized.group_support'               => true,
    'oxidized.features.versioning'         => true,
    'oxidized.reload_nodes'                => false,
    'oxidized.group.os'                    => [
      { 'match' => 'asa',       'group' => 'cisco-asa-device' },
      { 'match' => 'ios',       'group' => 'cisco-device' },
      { 'match' => 'iosxe',     'group' => 'cisco-device' },
      { 'match' => 'netscaler', 'group' => 'netscaler-device' },
      { 'match' => 'procurve',  'group' => 'procurve-device' },
    ],
    'oxidized.group.hostname'              => [
      { 'regex' => '/^switch\d.*/', 'group' => 'switches' },
      { 'regex' => '/^router\d.*/', 'group' => 'routers' },
    ],
  }
  # TLS settings are primary taken from these:
  # https://ssl-config.mozilla.org/#server=nginx&config=intermediate&ocsp=false
  # https://cipherli.st/
  nginx_ssl_enable                => true,
  nginx_ssl_protocols             => 'TLSv1.2 TLSv1.3',
  nginx_ssl_ciphers               => 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384', #lint:ignore:140chars
  nginx_ssl_cert                  => "${cert_root_path}/full_cert.pem",
  nginx_ssl_key                   => "${cert_root_path}/cert.key",
  nginx_ssl_prefer_server_ciphers => 'on',
  nginx_ssl_cache                 => 'shared:ssl_cache:10m',
  nginx_ssl_session_tickets       => 'off',
  nginx_ssl_session_timeout       => '1d',
  nginx_ssl_dhparam               => "${cert_root_path}/dhparam.pem",
  nginx_ssl_headers               => {
    'Strict-Transport-Security' => 'max-age=31557600',
    'X-Frame-Options'           => 'DENY',
    'X-Content-Type-Options'    => 'nosniff',
    'X-XSS-Protection'          => '1; mode=block',
  },
  oxidized_configuration          => {
    'groups'    => $oxidized_config_groups,
    'input'     => {
      'ssh' => {
        'secure' => false, # Disable hostkey verification
      },
    },
    'model_map' => {
      'procurve'   => 'procurve',
      'cisco'      => 'ios',
      'asa'        => 'asa',
      'ciscowlc'   => 'aireos',
      'arista'     => 'eos'
    },
  },
}

Parameters

The following parameters are available in the librenms class.

config_admin_email

Data type: String

The admin email used for Oxidized and SNMP contact (required)

config_discover_threads

Data type: Integer

The number of discover pollers should be running at a time

Default value: 1

config_override_pollers

Data type: Hash

A hash of pollers to enable (1) or disable (0)

Default value: {}

config_poller_threads

Data type: Integer

The number of pollers should be running at a time

Default value: 16

config_raw_input

Data type: Hash

A hash of configuration options for LibreNMS

Default value: {}

cron_manage_service

Data type: Boolean

Whether to manage the Cron service or not

Default value: false

import_mysqldump

Data type: Optional[String]

An optional mysqldump to import

Default value: undef

librenms_group

Data type: String

The LibreNMS Linux group name

Default value: 'librenms'

librenms_owner

Data type: String

The LibreNMS Linux owner name

Default value: 'librenms'

mysql_backup_revisions

Data type: Integer

The number of mysql backup revisions to keep on disk

Default value: 5

mysql_client_package_ensure

Data type: String

The ensure value for MySQL client

Default value: 'latest'

mysql_client_package_name

Data type: String

The package name for MySQL client

Default value: 'mariadb-client'

mysql_configuration

Data type: Hash

A hash of configuration options for MySQL

Default value: {}

mysql_librenms_password

Data type: String

The password for the LibreNMS database user (required)

mysql_librenms_username

Data type: String

The username for the LibreNMS database user

Default value: 'librenms'

mysql_root_password

Data type: String

The password for the root database user (required)

mysql_server_package_ensure

Data type: String

The ensure value for MySQL server

Default value: 'latest'

mysql_server_package_name

Data type: String

The package name for MySQL server

Default value: 'mariadb-server-10.1'

nginx_enable_mon_sites

Data type: Boolean

Whether to enable monitoring pages for NGINX and PHP-FPM

Default value: false

nginx_fastcgi_read_timeout

Data type: Integer

The number of seconds before the timeout error in NGINX occurs

Default value: 600

nginx_http2_enable

Data type: Enum['on','off']

Whether to enable http2 or not

Default value: 'on'

nginx_listen_port

Data type: Integer

The NGINX listen port (http)

Default value: 80

nginx_manage_repo

Data type: Boolean

Whether to manage the NGINX repo or not

Default value: false

nginx_server_name

Data type: Variant[String,Array]

The NGINX server name

Default value: $facts['networking']['fqdn']

nginx_ssl_buffer_size

Data type: Optional[String]

The size of the buffer used for sending data

Default value: undef

nginx_ssl_cache

Data type: Optional[String]

The cache string to use (e.g. 'shared:ssl_cache:10m')

Default value: undef

nginx_ssl_cert

Data type: Optional[Variant[String, Boolean]]

Path to the certificate

Default value: undef

nginx_ssl_ciphers

Data type: Optional[String]

Colon seperated string of ciphers to use

Default value: undef

nginx_ssl_client_cert

Data type: Optional[String]

Path to a client reference certificate

Default value: undef

nginx_ssl_crl

Data type: Optional[String]

Path to a file of revoked certificates

Default value: undef

nginx_ssl_dhparam

Data type: Optional[String]

Path to the DHPARAM file

Default value: undef

nginx_ssl_ecdh_curve

Data type: Optional[String]

Which ECDH curve to use

Default value: undef

nginx_ssl_enable

Data type: Boolean

Whether to enable SSL/TLS or not

Default value: false

nginx_ssl_headers

Data type: Optional[Hash]

A hash of SSL/TLS headers to use

Default value: undef

nginx_ssl_key

Data type: Optional[Variant[String, Boolean]]

Path to the certificate key

Default value: undef

nginx_ssl_listen_option

Data type: Optional[Boolean]

Whether to listen for SSL/TLS traffic or not

Default value: undef

nginx_ssl_port

Data type: Integer

The NGINX listen port (https)

Default value: 443

nginx_ssl_prefer_server_ciphers

Data type: Optional[Enum['on', 'off']]

Whether to prefer SSL/TLS ciphers or not

Default value: undef

nginx_ssl_protocols

Data type: Optional[String]

Space seperated string of SSL/TLS protocols to use

Default value: undef

nginx_ssl_redirect_port

Data type: Optional[Integer]

Override $nginx_ssl_port for redirects (generally not needed)

Default value: undef

nginx_ssl_session_ticket_key

Data type: Optional[String]

A file containing the secret key used to encrypt and decrypt SSL/TLS session tickets

Default value: undef

nginx_ssl_session_tickets

Data type: Optional[String]

Whether to use session tickets or not

Default value: undef

nginx_ssl_session_timeout

Data type: Optional[String]

How long before ssl session times out (e.g. '1d')

Default value: undef

nginx_ssl_stapling

Data type: Optional[Boolean]

Whether to enable OCSP responses or not

Default value: undef

nginx_ssl_stapling_file

Data type: Optional[String]

When set, the stapled OCSP response will be taken from the specified file instead of querying the OCSP responder specified in the server certificate

Default value: undef

nginx_ssl_stapling_responder

Data type: Optional[String]

Overrides the URL of the OCSP responder specified in the Authority Information Access certificate extension

Default value: undef

nginx_ssl_stapling_verify

Data type: Optional[Boolean]

Whether to enable OCSP verification or not

Default value: undef

nginx_ssl_trusted_cert

Data type: Optional[String]

Path to a file of trusted certificates

Default value: undef

nginx_ssl_verify_client

Data type: Optional[String]

Whether to verify clients certificates or not

Default value: undef

nginx_ssl_verify_depth

Data type: Optional[Integer]

How deep in the client certificates chain to verify

Default value: undef

oxidized_auth_token

Data type: Optional[String]

An API token for the Oxidized user (create on in LibreNMS)

Default value: 'SetThisToYourAuthToken!'

oxidized_configuration

Data type: Hash

A hash of configuration options for Oxidized

Default value: {}

oxidized_enabled

Data type: Boolean

Whether to enable Oxidized or not

Default value: false

oxidized_install_packages

Data type: Optional[Array]

An array of packages to install before Oxidized

Default value: undef

oxidized_log_path

Data type: String

The path to the Oxidized log

Default value: '/home/oxidized/.config/oxidized/log'

oxidized_manage_repo

Data type: Boolean

Whether to manage the Oxidized repo or not

Default value: false

oxidized_ruby_packages

Data type: Optional[Array]

An array of gems to install before Oxidized

Default value: undef

php_configuration

Data type: Hash

A hash of configuration options for PHP

Default value: {}

php_fpm_pm

Data type: Enum['dynamic', 'static']

The process management state (dynamic or static)

Default value: 'dynamic'

php_fpm_pm_max_children

Data type: Optional[String]

The maximum number of child processes to run

Default value: undef

php_fpm_pm_max_spare_servers

Data type: Optional[String]

The maximum amount of idle child processes to run

Default value: undef

php_fpm_pm_min_spare_servers

Data type: Optional[String]

The minimum amount of idle child processes to run

Default value: undef

php_fpm_pm_start_servers

Data type: Optional[String]

The amount of child processes to run on start-up

Default value: undef

php_manage_repo

Data type: Boolean

Whether to manage the PHP repo or not

Default value: false

php_package_ensure

Data type: String

The ensure value for PHP

Default value: 'latest'

rrd_backup_revisions

Data type: Integer

The number of RRD backup revisions to keep on disk

Default value: 0

rrdcached_pid_file

Data type: String

The path to the PID file for RRDCached

Default value: '/run/rrdcached.pid'

rrdcached_socket_file

Data type: String

The path to the socket file for RRDCached

Default value: '/run/rrdcached.sock'

snmp_contact

Data type: Optional[String]

The SNMP contact to be listed (overrides $config_admin_email)

Default value: undef

snmp_location

Data type: String

The SNMP location value

Default value: 'Unknown'

snmp_package_ensure

Data type: String

The ensure value for SNMP

Default value: 'present'

snmp_ro_community

Data type: String

The readonly SNMP community name (required)

snmp_trap_enabled

Data type: Boolean

Whether the snmp trap daemon should be enabled or not

Default value: false

snmp_trap_ensure

Data type: String

The ensure value for the snmp trap daemon

Default value: 'stopped'

snmp_trap_mib_dirs

Data type: Array

An array of directories to load mibs from (if empty, ${librenms::vcs_root_dir}/mibs will be selected)

Default value: []

snmp_trap_mibs

Data type: Array

An array of mibs to load (has to be loaded in $snmp_trap_mib_dirs)

Default value: ['IF-MIB']

testssl_enabled

Data type: Boolean

Whether to enable the TestSSL plugin for LibreNMS or not

Default value: false

vcs_branch

Data type: String

The LibreNMS branch to follow

Default value: 'master'

vcs_ensure

Data type: String

The ensure value for the LibreNMS vcsrepo

Default value: 'latest'

vcs_root_dir

Data type: String

The local path to the LibreNMS installation

Default value: '/opt/librenms'

weathermap_enabled

Data type: Boolean

Whether to enable the Weathermap plugin for LibreNMS or not

Default value: false

librenms::cron

Manages the cron service

Examples

use main class

librenms::librenms

Manages all LibreNMS resources

Examples

use main class

librenms::mysql

Manages all MySQL resources

Examples

use main class

librenms::oxidized

Manages all Oxidized resources

Examples

use main class

librenms::rrdcached

Manages all RRD and RRDCache resources

Examples

use main class

librenms::snmp

Manages all SNMP resources

Examples

use main class

librenms::testssl

Manages the TestSSL plugin for LibreNMS

Examples

use main class

librenms::weathermap

Manages the Weathermap plugin for LibreNMS

Examples

use main class

librenms::web_services

Manages all Web related resources (NGINX, PHP and FPM)

Examples

use main class

Functions

to_phpconfig

Type: Ruby 4.x API

The to_phpconfig function.

to_phpconfig(Hash $original_hash)

The to_phpconfig function.

Returns: Hash

original_hash

Data type: Hash