3 # plugin for munin to monitor usage of unbound servers.
4 # To install copy this to /usr/local/share/munin/plugins/unbound_munin_
5 # and use munin-node-configure (--suggest, --shell).
7 # (C) 2008 W.C.A. Wijngaards. BSD Licensed.
9 # To install; enable statistics and unbound-control in unbound.conf
10 # server: extended-statistics: yes
11 # statistics-cumulative: no
12 # statistics-interval: 0
13 # remote-control: control-enable: yes
14 # Run the command unbound-control-setup to generate the key files.
16 # Environment variables for this script
17 # unbound_conf - where the unbound.conf file is located.
18 # unbound_control - where to find unbound-control executable.
19 # spoof_warn - what level to warn about spoofing
20 # spoof_crit - what level to crit about spoofing
22 # You can set them in your munin/plugin-conf.d/plugins.conf file
26 # env.unbound_conf /usr/local/etc/unbound/unbound.conf
27 # env.unbound_control /usr/local/sbin/unbound-control
29 # env.spoof_crit 100000
31 # This plugin can create different graphs depending on what name
32 # you link it as (with ln -s) into the plugins directory
33 # You can link it multiple times.
34 # If you are only a casual user, the _hits and _by_type are most interesting,
35 # possibly followed by _by_rcode.
37 # unbound_munin_hits - base volume, cache hits, unwanted traffic
38 # unbound_munin_queue - to monitor the internal requestlist
39 # unbound_munin_memory - memory usage
40 # unbound_munin_by_type - incoming queries by type
41 # unbound_munin_by_class - incoming queries by class
42 # unbound_munin_by_opcode - incoming queries by opcode
43 # unbound_munin_by_rcode - answers by rcode, validation status
44 # unbound_munin_by_flags - incoming queries by flags
45 # unbound_munin_histogram - histogram of query resolving times
47 # Magic markers - optional - used by installation scripts and
48 # munin-config: (originally contrib family but munin-node-configure ignores it)
51 #%# capabilities=autoconf suggest
57 unbound_munin_ - Munin plugin to monitor the Unbound DNS resolver.
59 =head1 APPLICABLE SYSTEMS
61 System with unbound daemon.
67 env.unbound_conf /usr/local/etc/unbound/unbound.conf
68 env.unbound_control /usr/local/sbin/unbound-control
72 Use the .env settings to override the defaults.
76 Can be used to present different graphs. Use ln -s for that name in
77 the plugins directory to enable the graph.
78 unbound_munin_hits - base volume, cache hits, unwanted traffic
79 unbound_munin_queue - to monitor the internal requestlist
80 unbound_munin_memory - memory usage
81 unbound_munin_by_type - incoming queries by type
82 unbound_munin_by_class - incoming queries by class
83 unbound_munin_by_opcode - incoming queries by opcode
84 unbound_munin_by_rcode - answers by rcode, validation status
85 unbound_munin_by_flags - incoming queries by flags
86 unbound_munin_histogram - histogram of query resolving times
90 Copyright 2008 W.C.A. Wijngaards
98 state="${MUNIN_PLUGSTATE}/unbound.state"
99 seentags="${MUNIN_PLUGSTATE}/unbound-seentags.state"
100 conf=${unbound_conf:-/usr/local/etc/unbound/unbound.conf}
101 ctrl=${unbound_control:-/usr/local/sbin/unbound-control}
102 warn=${spoof_warn:-1000}
103 crit=${spoof_crit:-100000}
106 # number of seconds between polling attempts.
107 # makes the statefile hang around for at least this many seconds,
108 # so that multiple links of this script can share the results.
111 # to keep things within 19 characters
112 ABBREV="-e s/total/t/ -e s/thread/t/ -e s/num/n/ -e s/query/q/ -e s/answer/a/ -e s/unwanted/u/ -e s/requestlist/ql/ -e s/type/t/ -e s/class/c/ -e s/opcode/o/ -e s/rcode/r/ -e s/edns/e/ -e s/mem/m/ -e s/cache/c/ -e s/mod/m/"
114 # get value from $1 into return variable $value
116 value="`grep '^'$1'=' $state | sed -e 's/^.*=//'`"
117 if test "$value"x = ""x; then
122 # Update list of seen query types etc to seentags file. This is run while
123 # holding the lock, after the state file is updated.
125 tmplist="$(cat ${seentags} 2> /dev/null)
128 num.query.opcode.QUERY
129 num.answer.rcode.NOERROR
131 (echo "${tmplist}"; grep ^num ${state} | sed -e 's/=.*//') | sort -u > ${seentags}
134 # download the state from the unbound server.
136 # obtain lock for fetching the state
137 # because there is a race condition in fetching and writing to file
139 # see if the lock is stale, if so, take it
140 if test -f $lock ; then
141 pid="`cat $lock 2>&1`"
142 kill -0 "$pid" >/dev/null 2>&1
143 if test $? -ne 0 -a "$pid" != $$ ; then
149 while test ! -f $lock || test "`cat $lock 2>&1`" != $$; do
150 while test -f $lock; do
153 if test $i -gt 1000; then
156 if test $i -gt 1500; then
157 echo "error locking $lock" "=" `cat $lock`
163 if echo $$ >$lock ; then : ; else break; fi
165 # do not refetch if the file exists and only LEE seconds old
166 if test -f $state; then
169 value="`echo $value | sed -e 's/\..*$//'`"
170 if test $now -lt `expr $value + $lee`; then
175 $ctrl -c $conf stats > $state
176 if test $? -ne 0; then
177 echo "error retrieving data from unbound server"
185 if test "$1" = "autoconf" ; then
186 if test ! -f $conf; then
187 echo no "($conf does not exist)"
190 if test ! -d `dirname $state`; then
191 echo no "(`dirname $state` directory does not exist)"
198 if test "$1" = "suggest" ; then
211 # determine my type, by name
212 id=`echo $0 | sed -e 's/^.*unbound_munin_//'`
213 if test "$id"x = ""x; then
214 # some default to keep people sane.
218 # if $1 exists in statefile, config is echoed with label $2
220 mn=`echo $1 | sed $ABBREV | tr . _`
221 if grep '^'$1'=' $state >/dev/null 2>&1; then
224 echo "$mn.type ABSOLUTE"
228 # print label and min 0 for a name $1 in unbound format
230 mn=`echo $1 | sed $ABBREV | tr . _`
236 if test "$1" = "config" ; then
237 if test ! -f $state; then
242 echo "graph_title Unbound DNS traffic and cache hits"
243 echo "graph_args --base 1000 -l 0"
244 echo "graph_vlabel queries / \${graph_period}"
245 echo "graph_scale no"
246 echo "graph_category dns"
247 for x in `grep "^thread[0-9][0-9]*\.num\.queries=" $state |
248 sed -e 's/=.*//'`; do
249 exist_config $x "queries handled by `basename $x .num.queries`"
251 p_config "total.num.queries" "total queries from clients" "ABSOLUTE"
252 p_config "total.num.cachehits" "cache hits" "ABSOLUTE"
253 p_config "total.num.prefetch" "cache prefetch" "ABSOLUTE"
254 p_config "num.query.tcp" "TCP queries" "ABSOLUTE"
255 p_config "num.query.tcpout" "TCP out queries" "ABSOLUTE"
256 p_config "num.query.udpout" "UDP out queries" "ABSOLUTE"
257 p_config "num.query.tls" "TLS queries" "ABSOLUTE"
258 p_config "num.query.tls.resume" "TLS resumes" "ABSOLUTE"
259 p_config "num.query.ipv6" "IPv6 queries" "ABSOLUTE"
260 p_config "unwanted.queries" "queries that failed acl" "ABSOLUTE"
261 p_config "unwanted.replies" "unwanted or unsolicited replies" "ABSOLUTE"
262 echo "u_replies.warning $warn"
263 echo "u_replies.critical $crit"
264 echo "graph_info DNS queries to the recursive resolver. The unwanted replies could be innocent duplicate packets, late replies, or spoof threats."
267 echo "graph_title Unbound requestlist size"
268 echo "graph_args --base 1000 -l 0"
269 echo "graph_vlabel number of queries"
270 echo "graph_scale no"
271 echo "graph_category dns"
272 p_config "total.requestlist.avg" "Average size of queue on insert" "GAUGE"
273 p_config "total.requestlist.max" "Max size of queue (in 5 min)" "GAUGE"
274 p_config "total.requestlist.overwritten" "Number of queries replaced by new ones" "GAUGE"
275 p_config "total.requestlist.exceeded" "Number of queries dropped due to lack of space" "GAUGE"
276 echo "graph_info The queries that did not hit the cache and need recursion service take up space in the requestlist. If there are too many queries, first queries get overwritten, and at last resort dropped."
279 echo "graph_title Unbound memory usage"
280 echo "graph_args --base 1024 -l 0"
281 echo "graph_vlabel memory used in bytes"
282 echo "graph_category dns"
283 p_config "mem.cache.rrset" "RRset cache memory" "GAUGE"
284 p_config "mem.cache.message" "Message cache memory" "GAUGE"
285 p_config "mem.mod.iterator" "Iterator module memory" "GAUGE"
286 p_config "mem.mod.validator" "Validator module and key cache memory" "GAUGE"
287 p_config "msg.cache.count" "msg cache count" "GAUGE"
288 p_config "rrset.cache.count" "rrset cache count" "GAUGE"
289 p_config "infra.cache.count" "infra cache count" "GAUGE"
290 p_config "key.cache.count" "key cache count" "GAUGE"
291 echo "graph_info The memory used by unbound."
294 echo "graph_title Unbound DNS queries by type"
295 echo "graph_args --base 1000 -l 0"
296 echo "graph_vlabel queries / \${graph_period}"
297 echo "graph_scale no"
298 echo "graph_category dns"
299 for nm in `grep "^num.query.type" $seentags`; do
300 tp=`echo $nm | sed -e s/num.query.type.//`
301 p_config "$nm" "$tp" "ABSOLUTE"
303 echo "graph_info queries by DNS RR type queried for"
306 echo "graph_title Unbound DNS queries by class"
307 echo "graph_args --base 1000 -l 0"
308 echo "graph_vlabel queries / \${graph_period}"
309 echo "graph_scale no"
310 echo "graph_category dns"
311 for nm in `grep "^num.query.class" $seentags`; do
312 tp=`echo $nm | sed -e s/num.query.class.//`
313 p_config "$nm" "$tp" "ABSOLUTE"
315 echo "graph_info queries by DNS RR class queried for."
318 echo "graph_title Unbound DNS queries by opcode"
319 echo "graph_args --base 1000 -l 0"
320 echo "graph_vlabel queries / \${graph_period}"
321 echo "graph_scale no"
322 echo "graph_category dns"
323 for nm in `grep "^num.query.opcode" $seentags`; do
324 tp=`echo $nm | sed -e s/num.query.opcode.//`
325 p_config "$nm" "$tp" "ABSOLUTE"
327 echo "graph_info queries by opcode in the query packet."
330 echo "graph_title Unbound DNS answers by return code"
331 echo "graph_args --base 1000 -l 0"
332 echo "graph_vlabel answer packets / \${graph_period}"
333 echo "graph_scale no"
334 echo "graph_category dns"
335 for nm in `grep "^num.answer.rcode" $seentags`; do
336 tp=`echo $nm | sed -e s/num.answer.rcode.//`
337 p_config "$nm" "$tp" "ABSOLUTE"
339 p_config "num.answer.secure" "answer secure" "ABSOLUTE"
340 p_config "num.answer.bogus" "answer bogus" "ABSOLUTE"
341 p_config "num.rrset.bogus" "num rrsets marked bogus" "ABSOLUTE"
342 echo "graph_info answers sorted by return value. rrsets bogus is the number of rrsets marked bogus per \${graph_period} by the validator"
345 echo "graph_title Unbound DNS incoming queries by flags"
346 echo "graph_args --base 1000 -l 0"
347 echo "graph_vlabel queries / \${graph_period}"
348 echo "graph_scale no"
349 echo "graph_category dns"
350 p_config "num.query.flags.QR" "QR (query reply) flag" "ABSOLUTE"
351 p_config "num.query.flags.AA" "AA (auth answer) flag" "ABSOLUTE"
352 p_config "num.query.flags.TC" "TC (truncated) flag" "ABSOLUTE"
353 p_config "num.query.flags.RD" "RD (recursion desired) flag" "ABSOLUTE"
354 p_config "num.query.flags.RA" "RA (rec avail) flag" "ABSOLUTE"
355 p_config "num.query.flags.Z" "Z (zero) flag" "ABSOLUTE"
356 p_config "num.query.flags.AD" "AD (auth data) flag" "ABSOLUTE"
357 p_config "num.query.flags.CD" "CD (check disabled) flag" "ABSOLUTE"
358 p_config "num.query.edns.present" "EDNS OPT present" "ABSOLUTE"
359 p_config "num.query.edns.DO" "DO (DNSSEC OK) flag" "ABSOLUTE"
360 echo "graph_info This graphs plots the flags inside incoming queries. For example, if QR, AA, TC, RA, Z flags are set, the query can be rejected. RD, AD, CD and DO are legitimately set by some software."
363 echo "graph_title Unbound DNS histogram of reply time"
364 echo "graph_args --base 1000 -l 0"
365 echo "graph_vlabel queries / \${graph_period}"
366 echo "graph_scale no"
367 echo "graph_category dns"
368 echo hcache.label "cache hits"
370 echo hcache.type ABSOLUTE
371 echo hcache.draw AREA
372 echo hcache.colour 999999
373 echo h64ms.label "0 msec - 66 msec"
375 echo h64ms.type ABSOLUTE
376 echo h64ms.draw STACK
377 echo h64ms.colour 0000FF
378 echo h128ms.label "66 msec - 131 msec"
380 echo h128ms.type ABSOLUTE
381 echo h128ms.colour 1F00DF
382 echo h128ms.draw STACK
383 echo h256ms.label "131 msec - 262 msec"
385 echo h256ms.type ABSOLUTE
386 echo h256ms.draw STACK
387 echo h256ms.colour 3F00BF
388 echo h512ms.label "262 msec - 524 msec"
390 echo h512ms.type ABSOLUTE
391 echo h512ms.draw STACK
392 echo h512ms.colour 5F009F
393 echo h1s.label "524 msec - 1 sec"
395 echo h1s.type ABSOLUTE
397 echo h1s.colour 7F007F
398 echo h2s.label "1 sec - 2 sec"
400 echo h2s.type ABSOLUTE
402 echo h2s.colour 9F005F
403 echo h4s.label "2 sec - 4 sec"
405 echo h4s.type ABSOLUTE
407 echo h4s.colour BF003F
408 echo h8s.label "4 sec - 8 sec"
410 echo h8s.type ABSOLUTE
412 echo h8s.colour DF001F
413 echo h16s.label "8 sec - ..."
415 echo h16s.type ABSOLUTE
417 echo h16s.colour FF0000
418 echo "graph_info Histogram of the reply times for queries."
425 # do the stats itself
428 # get the time elapsed
429 get_value "time.elapsed"
430 if test $value = 0 || test $value = "0.000000"; then
431 echo "error: time elapsed 0 or could not retrieve data"
438 mn=`echo $1 | sed $ABBREV | tr . _`
440 echo "$mn.value" $value
443 # print value if line already found in $2
444 print_value_line ( ) {
445 mn=`echo $1 | sed $ABBREV | tr . _`
446 value="`echo $2 | sed -e 's/^.*=//'`"
447 echo "$mn.value" $value
453 for x in `grep "^thread[0-9][0-9]*\.num\.queries=" $state |
454 sed -e 's/=.*//'` total.num.queries \
455 total.num.cachehits total.num.prefetch num.query.tcp \
456 num.query.tcpout num.query.udpout num.query.tls num.query.tls.resume \
457 num.query.ipv6 unwanted.queries \
459 if grep "^"$x"=" $state >/dev/null 2>&1; then
465 for x in total.requestlist.avg total.requestlist.max \
466 total.requestlist.overwritten total.requestlist.exceeded; do
471 for x in mem.cache.rrset mem.cache.message mem.mod.iterator \
472 mem.mod.validator msg.cache.count rrset.cache.count \
473 infra.cache.count key.cache.count; do
478 for nm in `grep "^num.query.type" $seentags`; do
483 for nm in `grep "^num.query.class" $seentags`; do
488 for nm in `grep "^num.query.opcode" $seentags`; do
493 for nm in `grep "^num.answer.rcode" $seentags`; do
496 print_value "num.answer.secure"
497 print_value "num.answer.bogus"
498 print_value "num.rrset.bogus"
501 for x in num.query.flags.QR num.query.flags.AA num.query.flags.TC num.query.flags.RD num.query.flags.RA num.query.flags.Z num.query.flags.AD num.query.flags.CD num.query.edns.present num.query.edns.DO; do
506 get_value total.num.cachehits
507 echo hcache.value $value
509 for x in histogram.000000.000000.to.000000.000001 \
510 histogram.000000.000001.to.000000.000002 \
511 histogram.000000.000002.to.000000.000004 \
512 histogram.000000.000004.to.000000.000008 \
513 histogram.000000.000008.to.000000.000016 \
514 histogram.000000.000016.to.000000.000032 \
515 histogram.000000.000032.to.000000.000064 \
516 histogram.000000.000064.to.000000.000128 \
517 histogram.000000.000128.to.000000.000256 \
518 histogram.000000.000256.to.000000.000512 \
519 histogram.000000.000512.to.000000.001024 \
520 histogram.000000.001024.to.000000.002048 \
521 histogram.000000.002048.to.000000.004096 \
522 histogram.000000.004096.to.000000.008192 \
523 histogram.000000.008192.to.000000.016384 \
524 histogram.000000.016384.to.000000.032768 \
525 histogram.000000.032768.to.000000.065536; do
530 get_value histogram.000000.065536.to.000000.131072
531 echo h128ms.value $value
532 get_value histogram.000000.131072.to.000000.262144
533 echo h256ms.value $value
534 get_value histogram.000000.262144.to.000000.524288
535 echo h512ms.value $value
536 get_value histogram.000000.524288.to.000001.000000
537 echo h1s.value $value
538 get_value histogram.000001.000000.to.000002.000000
539 echo h2s.value $value
540 get_value histogram.000002.000000.to.000004.000000
541 echo h4s.value $value
542 get_value histogram.000004.000000.to.000008.000000
543 echo h8s.value $value
545 for x in histogram.000008.000000.to.000016.000000 \
546 histogram.000016.000000.to.000032.000000 \
547 histogram.000032.000000.to.000064.000000 \
548 histogram.000064.000000.to.000128.000000 \
549 histogram.000128.000000.to.000256.000000 \
550 histogram.000256.000000.to.000512.000000 \
551 histogram.000512.000000.to.001024.000000 \
552 histogram.001024.000000.to.002048.000000 \
553 histogram.002048.000000.to.004096.000000 \
554 histogram.004096.000000.to.008192.000000 \
555 histogram.008192.000000.to.016384.000000 \
556 histogram.016384.000000.to.032768.000000 \
557 histogram.032768.000000.to.065536.000000 \
558 histogram.065536.000000.to.131072.000000 \
559 histogram.131072.000000.to.262144.000000 \
560 histogram.262144.000000.to.524288.000000; do