Ubuntu Manpage: dhcpd-pools - ISC dhcpd pools usage analysis

NAME

       dhcpd-pools - ISC dhcpd pools usage analysis

SYNOPSIS

       dhcpd-pools [--config file] [--leases file] [--sort nimcptTe] [--reverse] [--format tHcxXjJ]
                   [--mustach template] [--output file] [--limit nr] [--color when] [--warning percent]
                   [--critical percent] [--warn-count number] [--crit-count number] [--snet-alarms]
                   [--minsize size] [--perfdata] [--version] [--help]

DESCRIPTION

       The program analyses ISC dhcpd shared network and pool usage and outputs the results in a format selected
       by user.

OUTPUT FIELDS

       shared net name
              Name of the shared-network for the range.

       first ip
              First IP in lease pool range.

       last ip
              Last IP in lease pool range.

       max    Number of IPs which exist in a pool, shared network or all together.

       cur    Number of leases currently in use.

       percent
              Percent of IPs currently in use compared to max.

       touch  Number  of  IP's  which  appear in the lease file, but who's leases have expired.  A touched IP is
              either expired or abandoned.  The touched  IP  count  is  somewhat  misleading  when  you  try  to
              determine if an IP pool is big enough; it is a better indicator of whether a pool is too large.

       t+c    The sum of Touched and Currently in-use leases.

       t+c perc
              Percent of IPs either touched or currently in use, compared to max.

       bu     Failover  pair  can  allocate  these  addresses.   The  count  appears  only  if there is failover
              configuration.

       bu perc
              Percent of addresses that failover pair can allocate.   The  percent  appears  only  if  there  is
              failover configuration.

OPTIONS

-c, --config=FILE
Path to the dhcpd.conf file. If the dhcpd.conf has include files they can be analysed separately,
that can be useful when trying to understand or monitor subset of data.

-l, --leases=FILE
Path to the dhcpd.leases file.

-s, --sort=[nimcptTe]
Sort ranges by chosen fields as a sorting keys. Keys weight from left to right, i.e., if more
weighting keys are equal next one is used. The IP field is default sort key.

-r, --reverse
Sort results in reverse order.

-f, --format=[tHcxXjJ]
Output format. Text (t). Full-html (H) page output. In html page critical and warning
thresholds can be visualized with --color=always option. The (c) stands for comma-separated
values. Output format xml (x) is similar to the dhcpstatus Perl module output. The extended xml
(X) format will print ethernet address details. The (j) will output in json format, which can be
extended with (J) to include ethernet address.

The default format is text.

--mustach=TEMPLATE
Output using mustach template file. This is useful when the native output formats controlled with
--format option do not provide what you need. See below example mustach template that is using
all available {{tags}} to demonstrate what can be displayed and how.

/usr/bin/dhcpd-pools --config /usr/share/doc/dhcpd-pools/dhcpd.conf --leases /usr/share/doc/dhcpd-
pools/dhcpd.leases --mustach /usr/share/doc/dhcpd-pools/mustach.template

-o, --output=FILE
File where output is written. Default is stdout.

-L, --limit=NR
The NR will limit what will be printed. Syntax is similar to chmod(1) permission string. The NR
limit string uses two digits which vary between 0 to 7. The first digit determines which headers
to display, and the second digit determines which numeric analysis tables to include in the
output. The following values are "OR'd" together to create the desired output. The default is
77.

01 Print ranges
02 Print shared networks
04 Print total summary
10 Print range header
20 Print shared network header
40 Print total summary header

The output limit for total summary has special meaning in --warning and --critical alarming
context. When the alarming is in use, and total is not wanted to be seen then in the case of
alarming returning success nothing is printed.

--color=when
Use yellow for warning, red for critical, green for suppressed by --minsize and blue when
--snet-alarms is the cause of suppression or shared network does not have any ranges. The when
string can be always, never, or auto. Default is auto, that uses colors when command is running
in interactive terminal. With use of --warning or --critical coloring thresholds can be changed,
but one must also use --format=text to avoid turning on alarting mode.

--skip=when
The when can be one of the following: ok, warning, critical, minsize, or suppressed. The skipping
criteria is exact match with colors in --color option.

--warning=percent
Turn on alarm output format, and specify percentage number which will cause an alarm. If either a
range or shared network will exceed warning level return value of the command is 1. If only range
monitoring is needed one can use limit option for scoping, for example -L10. To monitor shared
network only the limit would be -L20. If warning percentage is not specified it defaults to 80.
The percent argument allows fractions, e.g., 88.8, to be used.

--critical=percent
The option is similar to warning, with exception of return value which is 2. If critical
percentage is not specified it defaults to 90.

--warn-count=number
A number of free leases before alarm is raised. When specified both --warning percent and count
number are required to be exceeded in order to alarm criteria being fulfilled.

This option is intended to be used in setup where very large and small shared-networks and ranges
co-exists. In such environments percent based alarming can lead to either flood of alarms about
small ranges, or way too great overhead of free addresses in large shared-networks. Suggested
usage is to set percentage to a level that makes small ranges to ring, and set the count to match
level when an enormous shared-network is too few free leases.

Defaults to 2^32, that is size of entire IPv4 address space.

--crit-count=number
Same as --warn-count, but for critical alarms.

--snet-alarms
Suppress range alarms that are part of shared networks. Use of this option will keep alarm
criteria applied to ranges that are not part of shared-net along with shared-net alarms. This
option may help reducing alarm noise for configurations that has lots of small ranges in big
shared-networks.

--minsize=size
Ignore ranges and shared networks that are smaller or equal to the defined size. This option is
meaningful only in context of alarming, and will intended to suppress for example single host
ranges. By default this option is not in use.

-p, --perfdata
Print additional performance data, like lease count, touched leases and backup leases. This
option is meaningful only in context of alarming and will print lots of data, if there are many
networks. By default this option is not in use.

-A, --all-as-shared
Treat all stand-alone subnets as shared-network with named formed from it's CIDR. By default this
option is not in use for backwards compatibility.

--ip-version=4|6
Force command to read configuration and leases files in IPv4 or IPv6 mode. Notice that when
inputs do not match with what is forced analysis output is garbage. This option should not be
necessary to use, and exists only to allow debugging.

-v, --version
Print version information to standard output and exit successfully.

-h, --help
Print help to standard output and exit successfully.

EXAMPLES

       Print ranges header, and analysis.
              $ dhcpd-pools -L 11 -c dhcpd.conf -l dhcpd.leases
              Ranges:
              shared net name [...]

       Print shared networks and totals, both headers and results
              $ dhcpd-pools -L 66 -c dhcpd.conf -l dhcpd.leases shared net name
              [...]

       Alarming
              $ dhcpd-pools -c dhcpd.conf -l dhcpd.leases --critical 80.1 --warning 75
              CRITICAL: dhcpd-pools: Ranges; crit: 14 warn: 22 ok: 220 Shared nets; crit: 1 warn: 0 ok: 4

              $ dhcpd-pools -c dhcpd.conf -l dhcpd.leases -L 22 --critical 70 --warning 50
              [no-output]
              Suppress printing OK, and make alarm only to go off if shared networks exceed critial  or  warning
              levels.

FILES

       /etc/dhcp/dhcpd.conf
              ISC dhcpd configuration file.

       /var/lib/dhcp/dhcpd.leases
              ISC dhcpd lease file.

       /usr/share/doc/dhcpd-pools/prometheus.template
              Prometheus text file collector mustach template.

AUTHORS

       Original design by Sami Kerola.
       uthash by Troy D. Hanson.
       XML support by Dominic Germain, Sogetel inc.
       IPv6 support by Cheer Xiao.
       Mustache templating support by José Bollo.

LICENSE

       The  dhcpd-pools uses FreeBSD License, uthash uses BSD license, the mustache uses Apache License, and the
       gnulib modules are mostly, but not entirely, GPL.

REPORTING BUGS

       Report bugs to Sami Kerola
       Home page