1DHCPD-POOLS(1) User Commands DHCPD-POOLS(1)
2
6 dhcpd-pools - ISC dhcpd pools usage analysis
7
9 dhcpd-pools [--config file] [--leases file] [--sort nimcptTe]
10 [--reverse] [--format tHcxXjJ] [--mustach template]
11 [--output file] [--limit nr] [--color when]
12 [--warning percent] [--critical percent]
13 [--warn-count number] [--crit-count number] [--snet-alarms]
14 [--minsize size] [--perfdata] [--version] [--help]
15
17 The program analyses ISC dhcpd shared network and pool usage and out‐
18 puts the results in a format selected by user.
19
21 shared net name
22 Name of the shared-network for the range.
23 first ip
25 First IP in lease pool range.
26 last ip
28 Last IP in lease pool range.
29 max Number of IPs which exist in a pool, shared network or all to‐
31 gether.
32 cur Number of leases currently in use.
34 percent
36 Percent of IPs currently in use compared to max.
37 touch Number of IP's which appear in the lease file, but who's leases
39 have expired. A touched IP is either expired or abandoned. The
40 touched IP count is somewhat misleading when you try to deter‐
41 mine if an IP pool is big enough; it is a better indicator of
42 whether a pool is too large.
43 t+c The sum of Touched and Currently in-use leases.
45 t+c perc
47 Percent of IPs either touched or currently in use, compared to
48 max.
49 bu Failover pair can allocate these addresses. The count appears
51 only if there is failover configuration.
52 bu perc
54 Percent of addresses that failover pair can allocate. The per‐
55 cent appears only if there is failover configuration.
56
58 -c, --config=FILE
59 Path to the dhcpd.conf file. If the dhcpd.conf has include
60 files they can be analysed separately, that can be useful when
61 trying to understand or monitor subset of data.
62 -l, --leases=FILE
64 Path to the dhcpd.leases file.
65 -s, --sort=[nimcptTe]
67 Sort ranges by chosen fields as a sorting keys. Keys weight
68 from left to right, i.e., if more weighting keys are equal next
69 one is used. The IP field is default sort key.
70 -r, --reverse
72 Sort results in reverse order.
73 -f, --format=[tHcxXjJ]
75 Output format. Text (t). Full-html (H) page output. In html
76 page critical and warning thresholds can be visualized with
77 --color=always option. The (c) stands for comma-separated val‐
78 ues. Output format xml (x) is similar to the dhcpstatus Perl
79 module output. The extended xml (X) format will print ethernet
80 address details. The (j) will output in json format, which can
81 be extended with (J) to include ethernet address.
82 The default format is text.
84 --mustach=TEMPLATE
86 Output using mustach template file. This is useful when the na‐
87 tive output formats controlled with --format option do not pro‐
88 vide what you need. See below example mustach template that is
89 using all available {{tags}} to demonstrate what can be dis‐
90 played and how.
91 /usr/bin/dhcpd-pools --config /usr/share/doc/dhcpd-
93 pools/dhcpd.conf --leases /usr/share/doc/dhcpd-
94 pools/dhcpd.leases --mustach /usr/share/doc/dhcpd-pools/mus‐
95 tach.template
96 -o, --output=FILE
98 File where output is written. Default is stdout.
99 -L, --limit=NR
101 The NR will limit what will be printed. Syntax is similar to
102 chmod(1) permission string. The NR limit string uses two digits
103 which vary between 0 to 7. The first digit determines which
104 headers to display, and the second digit determines which nu‐
105 meric analysis tables to include in the output. The following
106 values are "OR'd" together to create the desired output. The
107 default is 77.
108 01 Print ranges
110 02 Print shared networks
111 04 Print total summary
112 10 Print range header
113 20 Print shared network header
114 40 Print total summary header
115 The output limit for total summary has special meaning in
117 --warning and --critical alarming context. When the alarming is
118 in use, and total is not wanted to be seen then in the case of
119 alarming returning success nothing is printed.
120 --color=when
122 Use yellow for warning, red for critical, green for suppressed
123 by --minsize and blue when --snet-alarms is the cause of sup‐
124 pression or shared network does not have any ranges. The when
125 string can be always, never, or auto. Default is auto, that
126 uses colors when command is running in interactive terminal.
127 With use of --warning or --critical coloring thresholds can be
128 changed, but one must also use --format=text to avoid turning on
129 alarting mode.
130 --skip=when
132 The when can be one of the following: ok, warning, critical,
133 minsize, or suppressed. The skipping criteria is exact match
134 with colors in --color option.
135 --warning=percent
137 Turn on alarm output format, and specify percentage number which
138 will cause an alarm. If either a range or shared network will
139 exceed warning level return value of the command is 1. If only
140 range monitoring is needed one can use limit option for scoping,
141 for example -L10. To monitor shared network only the limit
142 would be -L20. If warning percentage is not specified it de‐
143 faults to 80. The percent argument allows fractions, e.g.,
144 88.8, to be used.
145 --critical=percent
147 The option is similar to warning, with exception of return value
148 which is 2. If critical percentage is not specified it defaults
149 to 90.
150 --warn-count=number
152 A number of free leases before alarm is raised. When specified
153 both --warning percent and count number are required to be ex‐
154 ceeded in order to alarm criteria being fulfilled.
155 This option is intended to be used in setup where very large and
157 small shared-networks and ranges co-exists. In such environ‐
158 ments percent based alarming can lead to either flood of alarms
159 about small ranges, or way too great overhead of free addresses
160 in large shared-networks. Suggested usage is to set percentage
161 to a level that makes small ranges to ring, and set the count to
162 match level when an enormous shared-network is too few free
163 leases.
164 Defaults to 2^32, that is size of entire IPv4 address space.
166 --crit-count=number
168 Same as --warn-count, but for critical alarms.
169 --snet-alarms
171 Suppress range alarms that are part of shared networks. Use of
172 this option will keep alarm criteria applied to ranges that are
173 not part of shared-net along with shared-net alarms. This op‐
174 tion may help reducing alarm noise for configurations that has
175 lots of small ranges in big shared-networks.
176 --minsize=size
178 Ignore ranges and shared networks that are smaller or equal to
179 the defined size. This option is meaningful only in context of
180 alarming, and will intended to suppress for example single host
181 ranges. By default this option is not in use.
182 -p, --perfdata
184 Print additional performance data, like lease count, touched
185 leases and backup leases. This option is meaningful only in
186 context of alarming and will print lots of data, if there are
187 many networks. By default this option is not in use.
188 -A, --all-as-shared
190 Treat all stand-alone subnets as shared-network with named
191 formed from it's CIDR. By default this option is not in use for
192 backwards compatibility.
193 --ip-version=4|6
195 Force command to read configuration and leases files in IPv4 or
196 IPv6 mode. Notice that when inputs do not match with what is
197 forced analysis output is garbage. This option should not be
198 necessary to use, and exists only to allow debugging.
199 -v, --version
201 Print version information to standard output and exit success‐
202 fully.
203 -h, --help
205 Print help to standard output and exit successfully.
206
208 Print ranges header, and analysis.
209 $ dhcpd-pools -L 11 -c dhcpd.conf -l dhcpd.leases
210 Ranges:
211 shared net name [...]
212 Print shared networks and totals, both headers and results
214 $ dhcpd-pools -L 66 -c dhcpd.conf -l dhcpd.leases shared net
215 name
216 [...]
217 Alarming
219 $ dhcpd-pools -c dhcpd.conf -l dhcpd.leases --critical 80.1
220 --warning 75
221 CRITICAL: dhcpd-pools: Ranges; crit: 14 warn: 22 ok: 220 Shared
222 nets; crit: 1 warn: 0 ok: 4
223 $ dhcpd-pools -c dhcpd.conf -l dhcpd.leases -L 22 --critical 70
225 --warning 50
226 [no-output]
227 Suppress printing OK, and make alarm only to go off if shared
228 networks exceed critial or warning levels.
229
231 /etc/dhcp/dhcpd.conf
232 ISC dhcpd configuration file.
233 /var/lib/dhcpd/dhcpd.leases
235 ISC dhcpd lease file.
236 /usr/share/doc/dhcpd-pools/prometheus.template
238 Prometheus text file collector mustach template.
239
241 Original design by Sami Kerola.
242 uthash by Troy D. Hanson.
243 XML support by Dominic Germain, Sogetel inc.
244 IPv6 support by Cheer Xiao.
245 Mustache templating support by José Bollo.
246
248 The dhcpd-pools uses FreeBSD License, uthash uses BSD license, the mus‐
249 tache uses Apache License, and the gnulib modules are mostly, but not
250 entirely, GPL.
251
253 Report bugs to Sami Kerola ⟨kerolasa@iki.fi⟩
254 Home page ⟨http://dhcpd-pools.sourceforge.net/⟩
255
257 dhcpd.leases(5), dhcpd.conf(5), chmod(1), ⟨https://mustache.github.io/⟩
2583.2 2017-11-15 DHCPD-POOLS(1)