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

About

What is munin-pihole-plugins?

To expand on the project's tag line somewhat, munin-pihole-plugins is a Munin node plugin and management script for monitoring various Pi-hole® statistics, capable of transforming an existing server into a powerful, full time full system monitoring server and/or distributed client with relatively low system overhead and requirements.

Okay, sure, …Why?

Pi-hole®'s web interface is fine and dandy for telling you what is happening right now, or over the last 24 hour period, but what if we wanted to know what was happening at a precise time yesterday? Or the day before? What if we have multiple Pi-hole® servers? What if we wanted to see correlation over indeterminate periods of time? Pi-hole®'s long term query database can only tell us so much, and it may not even be enabled.

Back in eleventeen-ought-dickity-twain, our forebearers dreamed of way to bring distributed system monitoring platforms to the masses…

More seriously, this project exists because of the non-zero overlap between the type of people likely to be hosting their own local DNS server(s), and the type of people who may be interested in a full system monitoring platform, while recognising that most people don't know how to or are intimidated by setting such an environment up. This is where the management script portion of munin-pihole-plugins really shines, typically allowing installation in a few simple commands, in ~5 minutes or less.

Features

alt text

  • Extensive configuration options
  • Fifty+ different Pi-hole® data points to monitor
  • Monolithic plugin
  • Munin capabilities: autoconf, dirtyconf, suggest
  • Opportunistic bash-completion support, type complex commands with ease
  • Opportunistic pagination support using either less (preferred), or more
  • Optional self update, always run the latest script version
  • Pi-hole® JSON/REST API support
  • Pi-hole® Telnet API support
  • Rich help commands
  • Simple yet powerful configuration directly from the command line
  • User configurable critical/warning alert values for every Pi-hole® data point monitored
  • User manual
  • Variable levels of verbosity
  • Zero user configuration required in many cases

What systems does munin-pihole-plugins run on?

The management script has been constructed and tested primarily within Debian and Ubuntu derivative environments, with dependency satisfaction revolving around dpkg-query and apt. The intention is that munin-pihole-plugins and pihole are deployed on the same server, as there are several common dependencies, but this does not necessarily have to be the case and the plugin(s) are capable of being configured to monitor a remote pihole instance.

In short, if the machine can run Pi-hole®, it can probably run munin-pihole-plugins as well. The defaults should Just Work™ in the majority of cases, but if not, munin-pihole-plugins is able to be extensively configured, allowing for a high degree of "wiggle room".

You said "plugin(s)", but I only see one in the repository. Didn't there used to be more? What gives?

The munin-pihole-plugins plugin is monolithic. That is to say that it is capable of opperating in different capacities depending on the basename it is executed with, allowing a single plugin script to offer a wide range of possible functions. The munin-pihole-plugins script manages installation of selected plugins by creating symbolic links to the primary plugin script which are named after the intended plugin ID.

munin-pihole-plugins is too long/hard to type/something else, can I call it mpp for short?

Yes.

However, I would really rather that you didn't. The proper terms of reference for plugin and script components should be "(the) munin-pihole-plugins plugin" and "(the) munin-pihole-plugins script" respectively.

How do I install munin-pihole-plugins?

Installing munin-pihole-plugins is easy, check out the installation documentation here.

How do I update munin-pihole-plugins?

Updating munin-pihole-plugins is just as easy, check out the documentation for updating here.