NAME

dhcpd-snmp

SYNOPSIS

$ dhcpd-snmp [--test] dhcpd-snmp.conf

DESCRIPTION

dhcpd-snmp is an extension for the Net-SNMP agent and the ISC DHCP server. It allows you to monitor and track the address usage of your dynamic IP address pools through SNMP.

CONFIGURATION FILE

The configuration file defines the location of the dhcpd.leases file as well as the pools of which you want to access the lease counts.

The file is in key: value format and allows only two keys:

leases: /var/lib/dhcp3/dhcpd.leases

Location of the dhcpd.leases file. This file needs to be accessible by the script.

pool: index, description, ip1-ip2, ip3-ip4...

Defines a pool to monitor. index is a unique numeric index, description a textual description of this pool, and ip1-ip2, ip3-ip4, ... defines the ranges of IP addresses belonging to this pool.

Since this extension is a persistent script, changes to the configuration file require a restart of snmpd.

INSTALLATION

After installing the dhcpd-snmp script and adapting the configuration file, test if the configuration is valid:

$ path/to/dhcpd-snmp --test path/to/dhcpd-snmp.conf

This will print per-pool stats.

If this works, it can be installed in Net-SNMP. To install it, the following line needs to be inserted in the snmpd.conf file:

pass_persist .1.3.6.1.4.1.21695.1.2 path/to/dhcpd-snmp path/to/dhcpd-snmp.conf

Net-SNMP will need to be restarted after this change.

You should now be able to get the statistics using snmpwalk, for example:

$ snmpwalk host community .1.3.6.1.4.1.21695.1.2

This should give you a list of the statistics of your DHCP server.

RUNNING THE SCRIPT INTERACTIVELY

dhcpd-snmp is a simple script which is run by Net-SNMP and which is controlled using stdin/stdout. If you run it interactively, you can control it as follows:

PING

The script should return "PONG".

get
.1.3.6.1.4.1.21695.1.2.1

The script should return three lines: the OID, "integer", and the number of configured pools.

get
.1.3.6.1.4.1.21695.1.2.2.2.1

OID, "string", and the name of your first address pool.

get
.1.3.6.1.4.1.21695.1.2.2.4.1

OID, "integer", and the number of active leases.

Quit the dialog using CTRL-D.

MIB

The script returns the following variables:

.1.3.6.1.4.1.21695.1.2.1: number of configured pools
.1.3.6.1.4.1.21695.1.2.2.<pool>: pool description
.1.3.6.1.4.1.21695.1.2.3.<pool>: size of the pool (number of addresses)
.1.3.6.1.4.1.21695.1.2.4.<pool>: active leases
.1.3.6.1.4.1.21695.1.2.5.<pool>: expired leases
.1.3.6.1.4.1.21695.1.2.6.<pool>: available addresses (size - active leases)

For a complete MIB file see the mibs directory in the source archive.

SECURITY

It is assumed that users of this script know how to properly secure their snmpd. Please read the corresponding man pages on more information about this.

COPYRIGHT AND LICENSE

Copyright (C) 2006-2015 Oliver Hitz

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.