dhcpd-pool - Monitor DHCP pools

Author: Trond Hasle Amundsen
Contact: t.h.amundsen@usit.uio.no
Date: 2008-04-14


1   About

Properly monitoring DHCP can be painful. I didn't find any tools anywhere that did the job as I wanted it done, so I made my own script for monitoring ISC DHCP. In contrast to similar scripts, dhcpd-pool reads the DHCP configuration and doesn't require a separate config file.

This is free software. Use at your own risk.

2   Download

2.1   Latest version

2.2   License

The scripts are licensed under GPLv3.

3   Documentation

Default operation for dhcpd-pool is to print status information for each pool to stdout. If given the verbose option, it will also print the entire range for each pool. This can be useful by itself, but it's not enough for the serious DHCP admin. You want notifications if an important pool is about to go full, and you may also want to graph the pool usage. This is accomplished with dhcpd-pool, by making it act as a Nagios service and as a Munin plugin.

The default output for each pool will look like this:


  1. Pool "vlan134 VOIP":

     Monitoring:      ON
     Warning limit:   80%
     Critical limit:  90%
     Active leases:   23/26 (88.5%)

In the above example, the pool is configured for dhcpd-pool (se below), and monitoring is turned on. In case of an anonymous pool (i.e. a pool without a pool declaration), the output will look like this:


  Anonymous pool:

     Monitoring:      OFF
     Active leases:   80/101 (79.2%)

At the end, there will be a short summary:


  Total pools:              12
  Total pools monitored:    8
  Total pools un-monitored: 4

  Total leases:             274
  Total active leases:      54 (19.7%)

Giving the pools proper names is recommended for your own sanity's sake.

3.1   Configuration

Which pools to monitor, their names, and notification limits are configured in dhcpd.conf, like this:

# monitor: <warning> <critical> <Y|N> [name]

Note the comment sign. The limits configuration is a comment in the DHCP config, and is only recognized by this script. The Y or N is simply a yes or no to monitoring. If monitoring is set to N, the Nagios plugin will ignore the pool. The name is optional, but it's encouraged to set a proper name for each pool.

The warning and critical limits can each be given in three different forms. In the examples, if the pool holds 200 leases total, the limits are effectively identical.


When a percent sign (%) follows the number, the limit is given in percent. E.g. if the limit is 80% and the pool range contains 200 leases, a notification will occur if the number of active leases is more than or equal to 160.


# monitor: 80% 90% Y My pool


When the limit is given as a positive integer, a notification will occur when the number of active leases is greater than or equal to the limit.


# monitor: 160 180 Y My pool

Leases left

If a minus sign (-) precedes the number, a notification will occur if the number of free (not active) leases is less than or equal to the limit.


# monitor: -40 -20 Y My pool

The limit configuration can be set in both the subnet scope and the pool scope. If set in the pool scope, that takes precedence for that particular pool. Setting the limits configuration per pool is recommended.

Here is an example of a shared network with several pools:

shared-network foobar {

    subnet netmask {
        option routers
        option broadcast-address;

        pool {
            # monitor: 90% 95% Y Unknown clients
            failover peer "dhcp-failover";
            deny members of "nortel-2004-phones";
            deny members of "cisco-phones";
            allow unknown clients;

        pool {
            # monitor: 100% 100% N PXE clients
            failover peer "dhcp-failover";
            allow members of "pxeclients";

    subnet netmask {
        option broadcast-address
        option routers

        pool {
            # monitor: 80% 90% Y Cisco phones
            failover peer "dhcp-failover";
            allow members of "cisco-phones";
        pool {
            # monitor: 80% 90% Y Nortel2004 phones
            failover peer "dhcp-failover";
            allow members of "nortel-2004-phones";

Each pool has its own "monitor" statement.

3.2   Nagios service

To configure dhcpd-pool as a Nagios service, add the following to your nrpe.cfg:

command[dhcpd-pool]=/path/to/dhcpd-pool --nagios

Also add the service in the Nagios configuration. Output from dhcpd-pool when used as a Nagios service will reflect how the limits are defined, as explained above.

You may also need to add the --config and --leases options, depending on your configuration and dhcpd version.

3.3   Munin plugin

When used as a Munin plugin, it expects to be used by a wrapper script. An example wrapper script is provided: dhcpd-munin_. One can create one graph for each pool you're interested in, and/or one graph with all pools. In case of the latter, the values for each pool is given in percentage used. Absolute values doesn't make sense. Only pools that are monitored are included in the "percentage" graph.

To use dhcpd-pool as a Munin plugin, follow these instructions:

  1. Install the wrapper script dhcpd-munin_ somewhere, for example under /usr/local/sbin:

    cp dhcpd-munin_ /usr/local/sbin/
  2. cd to your plugin dir, e.g. /etc/munin/plugins:

    cd /etc/munin/plugins
  3. Run dhcpd-pool -m -a suggest (you can also use /usr/local/sbin/dhcpd-munin_ suggest) to make the plugin suggest pools to graph:

    # ./dhcpd-pool --munin --append suggest
  4. Create symlinks for all of those:

    for f in `/usr/local/sbin/dhcpd-munin_ suggest`; do ln -sf /usr/local/sbin/dhcpd-munin_ dhcpd-munin_$f; done
  5. If you want a "percentage" graph with all pools, do:

    ln -s /usr/local/sbin/dhcpd-munin_ dhcpd-munin_total
  6. If your DHCP config file and/or leases file is in different locations than the default (/etc/dhcpd.conf and /var/db/dhcpd.leases), create an plugin config file:

    cat /etc/munin/plugin-conf.d/dhcpd-munin
    configfile /path/to/dhcpd.conf
    leasefile /path/to/dhcpd.leases
  1. Restart munin-node

This should create graphs such this one for a single pool:

Single pool

And for all pools (the "total" option):