Configuration - saint-lascivious/munin-pihole-plugins GitHub Wiki

Configuration

Provided munin-node and Pi-hole® exist on the same host, the default configuration should Just Work™.

Plugin Configuration

The munin-pihole-plugins plugin uses Pi-hole®'s telnet (default) API, but can be alternately configured to use Pi-hole®'s json API, the latter is useful for monitoring a Pi-hole® instance on another host but requires Pi-hole®'s web interface to be installed.

If you have a non-standard configuration or Pi-hole® is running on a separate host, you will need to edit the plugin configuration file /etc/munin/plugin-conf.d/pihole.conf (default). The plugin attempts to obtain a local Pi-hole®'s web password (env.webpassword) value itself if required (Pi-hole®'s json API requires authentication for some functions), if it can not do so the required value for env.webpassword can be located within the intended target Pi-hole® host's /etc/pihole/setupVars.conf (default) file.

The Pi-hole® FTL port env.ftlport is derived from the /etc/pihole/pihole-FTL.conf (default) file if present, or is otherwise assumed to be 4711 (default). Likewise, the Pi-hole® setupVars.conf file path env.setupvars is derived from the /etc/pihole/pihole-FTL.conf (default) file if present, or is otherwise assumed to be /etc/pihole/setupVars.conf (default).

Default munin-pihole-plugins pihole_ plugin configuration

Default /etc/munin/plugin-conf.d/pihole.conf plugin configuration

[pihole_*]

    user root

    env.api_method telnet
    env.ftl_conf /etc/pihole/pihole-FTL.conf
    #env.ftl_port 4711
    env.host 127.0.0.1
    env.json_api /admin/api.php
    env.json_cachesuffix ?getCacheInfo&auth=
    env.json_port 80
    env.json_querysuffix ?getQueryTypes&auth=
    #env.setupvars /etc/pihole/setupVars.conf
    #env.webpassword PIHOLE_SETUPVARS_WEBPASSWORD_HERE

    env.graph_category dns
    env.graph_height 200
    env.graph_scale no
    env.graph_type GAUGE
    env.graph_width 400

    # pihole_blocked
    env.blocked_rate 3600

    # pihole_cache
    #env.cache_rate

    # pihole_cache_by_type
    #env.cache_by_type_rate

    # pihole_clients
    #env.clients_rate

    # pihole_percent
    #env.percent_rate

    # pihole_privacy
    #env.privacy_rate

    # pihole_queries
    #env.queries_rate

    # pihole_queries_by_type
    #env.queries_by_type_rate

    # pihole_replies_by_type
    #env.replies_by_type_rate

    # pihole_status
    #env.status_rate

    # pihole_unique_domains
    #env.unique_domains_rate

Uncomment and/or (re-)define relevant env.* variables to override the default values to suit your requirement.

The graph_category value determines which category munin-pihole-plugins graphs will appear in Munin's interface. This value MUST be lower case, allowed characters [a-z0-9].

The graph_scale value determines graph y axis value scaling and may be either no or yes.

The graph_type value determines the graph data type, and can be one of ABSOLUTE, COUNTER, DERIVE, or GAUGE. This value MUST be upper case.

The values for *_rate is a value in seconds. E.g. "60", "300", "3600".

The values for graph_height and graph_width specify the dimensions of the graph in pixels, not including the graph legend.

More specific definitions will override less specific definitions, allowing for a very high degree of customisation on a per-plugin basis. For example:

[pihole_*]
    env.graph_category pihole

[pihole_clients]
    env.graph_type COUNTER

[pihole_replies_by_type]
    env.graph_type DERIVE

Default munin-pihole-plugins pihole_alerts plugin configuration

Default /etc/munin/plugin-conf.d/pihole_alerts.conf plugin configuration

[pihole_*]

    # pihole_blocked
    env.domains_being_blocked_crit 1:5000000
    env.domains_being_blocked_warn 0:3000000

    # pihole_cache
    #env.cache_expired_crit
    #env.cache_expired_warn
    #env.cache_immortal_crit
    #env.cache_immortal_warn
    #env.cache_inserted_crit
    #env.cache_inserted_warn
    #env.cache_live_freed_crit
    #env.cache_live_freed_warn
    env.cache_size_crit 1:10000
    env.cache_size_warn 10000:10000

    # pihole_cache_by_type
    #env.cache_A_crit
    #env.cache_A_warn
    #env.cache_AAAA_crit
    #env.cache_AAAA_warn
    #env.cache_CNAME_crit
    #env.cache_CNAME_warn
    #env.cache_DNSKEY_crit
    #env.cache_DNSKEY_warn
    #env.cache_DS_crit
    #env.cache_DS_warn
    #env.cache_OTHER_crit
    #env.cache_OTHER_warn
    #env.cache_SRV_crit
    #env.cache_SRV_warn

    # pihole_clients
    #env.clients_ever_seen_crit
    #env.clients_ever_seen_warn
    env.unique_clients_crit 100
    env.unique_clients_warn 1:50

    # pihole_percent
    env.ads_percentage_today_crit 95
    env.ads_percentage_today_warn 1:85

    # pihole_privacy
    env.privacy_level_crit 1:3
    env.privacy_level_warn 3:3

    # pihole_queries
    #env.dns_queries_today_crit
    #env.dns_queries_today_warn
    #env.ads_blocked_today_crit
    #env.ads_blocked_today_warn
    #env.queries_forwarded_crit
    #env.queries_forwarded_warn
    #env.queries_cached_crit
    #env.queries_cached_warn

    # pihole_queries_by_type
    #env.query_A_crit
    #env.query_AAAA_warn
    #env.query_ANY_crit
    #env.query_ANY_warn
    #env.query_DNSKEY_crit
    #env.query_DNSKEY_warn
    #env.query_DS_crit
    #env.query_DS_warn
    #env.query_HTTPS_crit
    #env.query_HTTPS_warn
    #env.query_MX_crit
    #env.query_MX_warn
    #env.query_NAPTR_crit
    #env.query_NAPTR_warn
    #env.query_NS_crit
    #env.query_NS_warn
    #env.query_OTHER_crit
    #env.query_OTHER_warn
    #env.query_PTR_crit
    #env.query_PTR_warn
    #env.query_RRSIG_crit
    #env.query_RRSIG_warn
    #env.query_SOA_crit
    #env.query_SOA_warn
    #env.query_SRV_crit
    #env.query_SRV_warn
    #env.query_SVCB_crit
    #env.query_SVCB_warn
    #env.query_TXT_crit
    #env.query_TXT_warn

    # pihole_replies_by_type
    #env.reply_BLOB_crit
    #env.reply_BLOB_warn
    #env.reply_CNAME_crit
    #env.reply_CNAME_warn
    #env.reply_DNSSEC_crit
    #env.reply_DNSSEC_warn
    #env.reply_DOMAIN_crit
    #env.reply_DOMAIN_warn
    #env.reply_IP_crit
    #env.reply_IP_warn
    #env.reply_NOTIMP_crit
    #env.reply_NOTIMP_warn
    #env.reply_NODATA_crit
    #env.reply_NODATA_warn
    #env.reply_NONE_crit
    #env.reply_NONE_warn
    #env.reply_NXDOMAIN_crit
    #env.reply_NXDOMAIN_warn
    #env.reply_OTHER_crit
    #env.reply_OTHER_warn
    #env.reply_REFUSED_crit
    #env.reply_REFUSED_warn
    #env.reply_RRNAME_crit
    #env.reply_RRNAME_warn
    #env.reply_SERVFAIL_crit
    #env.reply_SERVFAIL_warn
    #env.reply_UNKNOWN_crit
    #env.reply_UNKNOWN_warn

    # pihole_status
    env.status_crit 0:1
    env.status_warn 1:1

    # pihole_unique_domains
    env.unique_domains_crit 1:20000
    env.unique_domains_warn 0:10000

Uncomment and/or (re-)define relevant env.* variables to override the default values to suit your requirement.

The values for *_crit and *_warn can be a max value or a range separated by colon. E.g. "min:", ":max", "min:max", "max".

Script Configuration

Usage

Initial installation, or without the munin-pihole-plugins script being locally installed: export VARIABLE="VALUE"

Example: export VERBOSITY_LEVEL="4"

Subsequent runs, with the munin-pihole-plugins script locally installed: munin-pihole-plugins --configure VARIABLE VALUE

Example: munin-pihole-plugins --configure VERBOSITY_LEVEL 4

Reset example: munin-pihole-plugins --configure VERBOSITY_LEVEL RESET

The configuration file, of which the default is /etc/munin-pihole-plugins/munin-pihole-plugins.conf, may be manually created or generated ahead of time if desired, useful for packaging or other automated deployment. This configuration file MUST be a plain text file and MUST consist of the format VARIABLE=VALUE (or VARIABLE="VALUE" for arrays, like PLUGIN_LIST), one variable per line, with no leading whitespace or indentation. Comments to assist usability may exist but MUST be preceeded with a hash (#) character.

The -C, configure, --configure command

Usage: munin-pihole-plugins {--configure [RESET_ALL]|[VARIABLE [VALUE]]}

Option	GNU long option	Function
`-C`, `configure`	`--configure`	Display or set environment variables

Display a full list of environment variables used by the munin-pihole-plugins script, and their current values. These variables and this command can be used to customise various aspects of the munin-pihole-plugins script's operation.

Takes an optional parameter in the form of a munin-pihole-plugins environment variable to list the value of that variable alone.

Example: munin-pihole-plugins --configure INSTALL_PLUGINS

Takes an optional value for a munin-pihole-plugins environment variable to set the value of that variable.

If the optional value passed is RESET, the corresponding environment variable will be reset to its default value. This functionality is only available if the munin-pihole-plugins script is found to exist within SCRIPT_DIR.

Example: munin-pihole-plugins --configure DNS_SERVER RESET

Takes an optional parameter in the form of RESET_ALL to restore all munin-pihole-plugins environment variables to their default values. Again, this functionality is only available if the munin-pihole-plugins script is found to exist within SCRIPT_DIR, whereby it's considered "installed".

Example: munin-pihole-plugins --configure RESET_ALL

Default script configuration

Default munin-pihole-plugins script environment variables

Variable	Default Value
BRANCH	`master`
DNS_PORT	`53`
DNS_SERVER	`208.67.222.222`
EXTERNAL_CONFIG_DIR	`/etc/munin-pihole-plugins`
EXTERNAL_CONFIG_FILE	`munin-pihole-plugins.conf`
FORCE_UPDATE_PLUGIN_CONFIG	`false`
HOLD_DURATION	`0`
IGNORE_PIHOLE_ON_HOST	`false`
INSTALL_PLUGINS	`true`
INSTALL_SCRIPT	`true`
INSTALL_WEBSERVER	`true`
LIGHTTPD_WEBROOT	`/var/www/html`
MUNIN_BRANCH	`stable`
MUNIN_DIR	`/etc/munin`
MUNIN_CONFIG_DIR	`/etc/munin/munin-conf.d`
MUNIN_PLUGIN_DIR	`/usr/share/munin/plugins`
NODE_PLUGIN_DIR	`/etc/munin/plugins`
PLUGIN_CONFIG_DIR	`/etc/munin/plugin-conf.d`
PLUGIN_CONFIG_LIST	`pihole pihole_alerts`
PLUGIN_LIST	`blocked cache cache_by_type clients percent privacy queries queries_by_type replies_by_type status unique_domains`
PROXY_CONFIG_DIR	`/etc/lighttpd`
SCRIPT_DIR	`/usr/local/bin`
SHOW_COLOUR	`true`
SHOW_HEADER	`true`
SKIP_DEPENDENCY_CHECK	`false`
UPDATE_SELF	`true`
VERBOSITY_LEVEL	`3`

BRANCH

BRANCH

The branch used when checking the munin-pihole-plugins script version or installing munin-pihole-plugins. Valid options are development and master, of which the default is master. Invalid options will be rejected.

Example munin-pihole-plugins --configure BRANCH development

DNS_PORT

DNS_PORT

The port which the munin-pihole-plugins script will use in order to contact DNS_SERVER.

Example munin-pihole-plugins --configure DNS_PORT 53

DNS_SERVER

DNS_SERVER

The DNS server which the munin-pihole-plugins script will contact in order to retrieve its version information (from a TXT record at munin-pihole-plugins.sainternet.xyz). This SHOULD be an IP address rather than a hostname or FQDN when configured manually, and it SHOULD be external. When configured via -c, -configure, --configure this value MUST be an IPv4 address.

When the munin-pihole-plugins script is installed locally, the -c, configure, --configure command can set the value of DNS_SERVER using user input, or one of the following optional presets:

`DNS_SERVER` Preset	Value
`CLOUDFLARE`	`1.1.1.1`
`COMODO`	`8.26.56.26`
`GOOGLE`	`8.8.8.8`
`LOCALHOST`	`127.0.0.1`
`OPENDNS`	`208.67.222.222` (default)
`QUAD9`	`9.9.9.9`
`SAINTERNET`	`119.224.127.171`

Example: munin-pihole-plugins --configure DNS_SERVER LOCALHOST

If this server is operating on a port other than 53 (default), you can change this using the DNS_PORT variable.

EXTERNAL_CONFIG_DIR

EXTERNAL_CONFIG_DIR

The directory in which an external configuration file should be located, to be created if required.

Example: munin-pihole-plugins --configure EXTERNAL_CONFIG_DIR "/etc/munin-pihole-plugins"

EXTERNAL_CONFIG_FILE

EXTERNAL_CONFIG_FILE

The name of external configuration file munin-pihole-plugins should use, to be created if required.

Example: munin-pihole-plugins --configure EXTERNAL_CONFIG_FILE "munin-pihole-plugins.conf"

FORCE_UPDATE_PLUGIN_CONFIG

FORCE_UPDATE_PLUGIN_CONFIG

Forces the re-installation of the default munin-pihole-plugins plugin configuration files pihole.conf and/or /etc/munin/plugin-conf.d/pihole_alerts.conf (default: false), which changes periodically. If the configured external configuration directory exists, the currently installed plugin configuration will be saved to the EXTERNAL_CONFIG_DIR as *.conf.save before being overwritten.

Example: munin-pihole-plugins --configure FORCE_UPDATE_PLUGIN_CONFIG true

HOLD_DURATION

HOLD_DURATION

Sets the dwell time on a scale from 0 to 5 seconds (default: 0) which the munin-pihole-plugins script should wait between outputting user information, allowing the user to see what's happening more easily.

Example: munin-pihole-plugins --configure HOLD_DURATION 2

Note: Somewhat of an oddity this one. Added upon user request (I'm happy to accomodate), to help prevent the munin-pihole-plugins script output from "whizzing by too fast to be seen", which might normally be considered a good thing. The maximum value is capped at five seconds, which doesn't seem like very much at all but (depending on the VERBOSITY_LEVEL) will slow things down considerably.

IGNORE_PIHOLE_ON_HOST

IGNORE_PIHOLE_ON_HOST

Ignore the existance of any pihole binary on the host server.

Example: munin-pihole-plugins --configure IGNORE_PIHOLE_ON_HOST true

INSTALL_PLUGINS

INSTALL_PLUGINS

Disables installation of munin-node and munin-pihole-plugins plugins if set to any value other than true.

Example munin-pihole-plugins --configure INSTALL_PLUGINS false

INSTALL_SCRIPT

INSTALL_SCRIPT

Disables installation of the munin-pihole-plugins script if set to any value other than true.

Example munin-pihole-plugins --configure INSTALL_SCRIPT false

INSTALL_WEBSERVER

INSTALL_WEBSERVER

Disables installation of the munin webserver and lighttpd proxy if set to any value other than true. Useful for additional Munin nodes in a multi-node, single-server environment.

Example munin-pihole-plugins --configure INSTALL_WEBSERVER false

LIGHTTPD_WEBROOT

LIGHTTPD_WEBROOT

The directory in which, if installed, the Pi-hole® AdminLTE web interface should be found. The presence or absence of a pihole directory here is used to determine whether or not munin-pihole-plugins should offer to remove lighttpd during munin-pihole-plugins uninstallation. The admin directory is not used for this purpose due to the ambiguity of its name.

Example munin-pihole-plugins --configure LIGHTTPD_WEBROOT "/var/www/html"

MUNIN_BRANCH

MUNIN_BRANCH

The Munin branch to target when configuring the lighttpd proxy. Available options are latest and stable, with stable being the default value. The latest branch should be selected for Munin versions 2.99 or higher.

Tag	Munin Version Target
`latest`	munin 2.99+
`stable`	munin 2.*

Example munin-pihole-plugins --configure MUNIN_BRANCH latest

MUNIN_DIR

MUNIN_DIR

The directory in which the munin munin.conf file should be located.

Example munin-pihole-plugins --configure MUNIN_DIR "/etc/munin"

MUNIN_CONFIG_DIR

MUNIN_CONFIG_DIR

The directory in which additional munin configuration files may be placed, the munin-pihole-plugins script will attempt to use this in favour of editing munin.conf directly.

Example munin-pihole-plugins --configure MUNIN_CONFIG_DIR "/etc/munin/munin-conf.d"

MUNIN_PLUGIN_DIR

MUNIN_PLUGIN_DIR

The directory in which munin plugins should be located.

Example munin-pihole-plugins --configure MUNIN_PLUGIN_DIR "/usr/share/munin/plugins"

NODE_PLUGIN_DIR

NODE_PLUGIN_DIR

The directory in which munin-node plugin symbolic links should be created.

Example munin-pihole-plugins --configure NODE_PLUGIN_DIR "/etc/munin/plugins"

PLUGIN_CONFIG_DIR

PLUGIN_CONFIG_DIR

The directory in which individual munin-node plugin configurations should be located.

Example munin-pihole-plugins --configure PLUGIN_CONFIG_DIR "/etc/munin/plugin-conf.d"

PLUGIN_CONFIG_LIST

PLUGIN_CONFIG_LIST

A comma separated list of configuration file IDs used to determine which plugin configuration files will be installed.

Config ID	Config Name	Description
`pihole`	pihole.conf	Plugin configuration base file.
`pihole_alerts`	pihole_alerts.conf	Plugin warning/critical alert configuration file.

Example munin-pihole-plugins --configure PLUGIN_CONFIG_LIST "pihole"

PLUGIN_LIST

PLUGIN_LIST

A space separated list of munin-pihole-plugins plugin IDs used to determine which plugins will be installed.

Plugin ID	Plugin Name	Description
blocked	pihole_blocked	This plugin shows the number of domains blocked by Pi-hole®.
cache	pihole_cache	This plugin shows Pi-hole®'s cache.
cache_by_type	pihole_cache_by_type	This plugin shows Pi-hole®'s cache by type.
clients	pihole_clients	This plugin shows clients seen by Pi-hole®.
percent	pihole_percent	This plugin shows Pi-hole®'s blocked query percentage.
privacy	pihole_privacy	This plugin shows Pi-hole®'s privacy level.
queries	pihole_queries	This plugin shows queries seen by Pi-hole®.
queries_by_type	pihole_queries_by_type	This plugin shows Pi-hole®'s queries by type.
replies_by_type	pihole_replies_by_type	This plugin shows Pi-hole®'s replies by type.
status	pihole_status	This plugin shows Pi-hole®'s blocking status.
unique_domains	pihole_unique_domains	This plugin shows unique domains seen by Pi-hole®.

Example: munin-pihole-plugins --configure PLUGIN_LIST "blocked percent unique_domains"

PROXY_CONFIG_DIR

PROXY_CONFIG_DIR

The directory in which lighttpd's external.conf should be located.

Example munin-pihole-plugins --configure PROXY_CONFIG_DIR "/etc/lighttpd"

SCRIPT_DIR

SCRIPT_DIR

The directory in which the munin-pihole-plugins script should be located when installed, the munin-pihole-plugins script will warn if this directory is not located in the host's $PATH variable and suggest how to correct this.

Example munin-pihole-plugins --configure SCRIPT_DIR "/etc/munin-pihole-plugins"

SHOW_COLOUR

SHOW_COLOUR

Disables coloured terminal output if set to any value other than true.

Example munin-pihole-plugins --configure SHOW_COLOUR false

SHOW_HEADER

SHOW_HEADER

I get it. It's not for everyone.

Disables the (super-duper, totally awesome) munin-pihole-plugins script ascii header if set to any value other than true.

Example munin-pihole-plugins --configure SHOW_HEADER false

SKIP_DEPENDENCY_CHECK

SKIP_DEPENDENCY_CHECK

Disables apt and dpkg-query based dependency management if set to any value other than false.

Example munin-pihole-plugins --configure SKIP_DEPENDENCY_CHECK true

Note: Basic test-before-use for required binaries is still performed in either case.

UPDATE_SELF

UPDATE_SELF

Disables self update of the munin-pihole-plugins script if set to any value other than true.

Example munin-pihole-plugins --configure UPDATE_SELF false

VERBOSITY_LEVEL

VERBOSITY_LEVEL

Sets the munin-pihole-plugins script verbosity level on a scale from 0 to 4, with 0 being total silence and 4 being the highest level of verbosity.

Verbosity Level	Output
`0`	Silent
`1`	+ Errors
`2`	++ Questions and Warnings
`3`	+++ Information
`4`	++++ Additional Information

Example: munin-pihole-plugins --configure VERBOSITY_LEVEL 4

Munin Node Configuration

Example /etc/munin/munin-node.conf multi-server, multi-node access control configuration

# Set this if the client doesn't report the correct hostname when
# telnetting to localhost, port 4949

host_name primary.home

# A list of addresses that are allowed to connect.  This must be a
# regular expression, since Net::Server does not understand CIDR-style
# network notation unless the perl module Net::CIDR is installed.  You
# may repeat the allow line as many times as you'd like

allow ^127\.0\.0\.1$
allow ^::1$

# If you have installed the Net::CIDR perl module, you can use one or more
# cidr_allow and cidr_deny address/mask patterns.  A connecting client must
# match any cidr_allow, and not match any cidr_deny.  Note that a netmask
# *must* be provided, even if it's /32

# primary.home
cidr_allow 192.168.1.10/32
# secondary.home
cidr_allow 192.168.1.20/32
# desktop.home
cidr_allow 192.168.1.40/32
# laptop.home
cidr_allow 192.168.1.100/32

Munin Server Configuration

Example /etc/munin/munin.conf or /etc/munin/munin-conf.d/00-nodes.conf multi-server, multi-node access control configuration

# primary.home
[primary.home]
    address 192.168.1.10
    use_node_name yes

# secondary.home
[secondary.home]
    address 192.168.1.20
    use_node_name yes

# desktop.home
[desktop.home]
    address 192.168.1.40
    use_node_name yes

# laptop.home
[laptop.home]
    address 192.168.1.100
    use_node_name yes