pihole_munin_

Munin plugins for monitoring various Pi-hole® ≥ 6.0 statistics.

---

Overview

pihole_munin_ is a POSIX shell Munin wildcard plugin, providing a suite of plugins for monitoring Pi-hole installations. It supports dynamic configuration, authentication, plugin management, and state caching.

---

Features

• Comprehensive Pi-hole Metrics:

  • Cache statistics (total, evicted, expired, immortal, inserted)
  • Cache breakdown by record type (valid/stale)
  • Client statistics (active, total)
  • DNSMasq/FTLDNS statistics
  • Domains currently being blocked
  • Gravity database stats (groups, adlists, allowed/blocked domains/regex)
  • Percent blocked
  • Privacy level
  • Query statistics (blocked, cached, forwarded, total, unique domains, frequency)
  • Queries by status/type
  • Replies by type
  • Blocking status

• Configurable Alert Thresholds:
  Set warning and critical thresholds for key metrics to enable Munin alerting.

• Flexible Authentication:
  Automatically detects and supports Pi-hole app password, web password, or CLI password.

• Efficient State & Session Caching:
  Minimizes API calls by caching responses and optionally reusing API sessions for improved performance.

• Powerful Admin Commands:
  Easily install, uninstall, update, enable/disable plugins, and manage configuration variables from the command line.

• Wildcard Plugin Architecture:
  A single POSIX shell script provides multiple metrics via symlinks, simplifying deployment and updates.

• Full Munin Integration:
  Supports all standard Munin plugin capabilities: autoconf, suggest, dirtyconfig, fetch, and config.

• Strict POSIX Compliance:
  Written in 100% pure POSIX shell.

• Progressive Verbosity for Troubleshooting:
  Built-in test mode with --verbose and --trace options for detailed plugin diagnostics and Munin debug output.

• Extensive Configurability:
  Nearly every aspect of the plugin's behavior can be customized via environment variables, configuration files, or admin commands. Allowing you to tailor metrics, authentication, thresholds, caching, and more to your specific needs.

---

Requirements

• Munin munin, munin-node (not necessarily on the same host as each other)
• Pi-hole Pi-hole ≥ 6.0 (not necessarily on the same host as Munin)
• curl, jq, and mktemp These are used for API calls, JSON parsing, and temporary file handling.

---

Automatic

1. Fetch the script:

   curl -sSL github.com/saint-lascivious/pihole_munin_/raw/master/pihole_munin_ -o pihole_munin_

2. Install:

   # Make sure the script is executable
   chmod +x pihole_munin_
   # Run the install script
   ./pihole_munin_ install

   • If desired, a custom install location can be specified with the path option.
   • A dry run of the installation performed with the dry option.
   • See ./pihole_munin_ help install for details or the view the full command list can be viewed here.

Manual

1. Clone this repository

   git clone https://github.com/saint-lascivious/pihole_munin_.git

2. Copy pihole_munin_ to your Munin plugins directory (usually /usr/share/munin/plugins/).

   # Navigate to the cloned directory
   cd pihole_munin_
   # Copy the plugin script to the Munin plugins directory
   cp pihole_munin_ /usr/share/munin/plugins/
   # Make sure the script is executable
   chmod +x /usr/share/munin/plugins/pihole_munin_

3. Create symlinks in /etc/munin/plugins/ for each plugins you wish to enable

   ln -s /usr/share/munin/plugins/pihole_munin_ /etc/munin/plugins/pihole_munin_cache
   ln -s /usr/share/munin/plugins/pihole_munin_ /etc/munin/plugins/pihole_munin_cache_by_type
   ln -s /usr/share/munin/plugins/pihole_munin_ /etc/munin/plugins/pihole_munin_clients
   # repeat for other plugins as desired

   The list of default plugins is: pihole_munin_cache, pihole_munin_cache_by_type, pihole_munin_clients, pihole_munin_frequency, pihole_munin_overview, pihole_munin_percent, pihole_munin_queries, pihole_munin_queries_by_status, pihole_munin_queries_by_type, pihole_munin_replies, pihole_munin_replies_by_type, and pihole_munin_unique.

   Additional ("boring", primarily static, or requiring lower privacy levels) plugins: pihole_munin_dnsmasq, pihole_munin_domains, pihole_munin_gravity, pihole_munin_privacy, pihole_munin_status, pihole_munin_top_clients, pihole_munin_top_domains, pihole_munin_upstreams, and pihole_munin_version.

4. Restart the Munin node

   systemctl restart munin-node

5. …Wait Wait, around five minutes.

   Munin nodes run their plugins periodically, by default at 5 minute intervals past the hour. After the first run, you should see the new plugins in your Munin web interface.

---

Configuration

Example /etc/munin/plugin-conf.d/pihole_munin_ file:

# pihole_munin_ configuration for Munin
[pihole_munin_*]
    env.cli_password /etc/pihole/cli_pw
    env.proto http
    env.host 127.0.0.1
    env.port 80
    env.api /api
    env.graph_category dns
    env.state_ttl 240
    env.session_ttl 300
    user pihole

---

Usage

Fetch Data

Munin will call the plugin with the appropriate symlink name, e.g.:

/usr/share/munin/plugins/pihole_munin_cache fetch

Admin Commands

• Enable all plugins: ./pihole_munin_ admin install
• Disable all plugins: ./pihole_munin_ admin uninstall
• Add config variable: ./pihole_munin_ admin add <var> [value]
• Remove config variable: ./pihole_munin_ admin remove <var>
• List config variables: ./pihole_munin_ admin list
• Update plugin: ./pihole_munin_ admin update
• Set password: ./pihole_munin_ admin password <password>

---

Authentication

Order of precedence:

1. env.app_password
2. env.pihole_password
3. env.cli_password (if host is localhost)

---

Documentation

Documentation for pihole_munin_ can be found in the pihole_munin_ wiki.

---

Compatibility

• Munin >= 2.0.
• Pi-hole >= 6.0.

---

License

This project is licensed under the GNU GPL v3.

---

See Also

• Munin
• Pi-hole
• Munin Plugins

---

^{_{© 2025, saint-lascivious (Hayden Pearce)}}