README.md
1# bind9stats.py
2
3Programs to obtain data from the statistics channel of a BIND9
4DNS server, and send it to some graphing and data visualization
5tools. The original program, bind9stats.py, was written to
6be a plugin for Munin, and has recently been renamed to
7bind9stats-munin.py. There is also a newer version, called
8bind9stats-graphite.py, that works with Graphite and Grafana.
9
10
11## bind9stats-munin.py: Munin plugin
12
13version 0.31
14
15A munin plugin to obtain data from a BIND9 statistics server, written
16in Python. Tested with BIND 9.10, 9.11, and 9.12's statistics server
17exporting version 3 of the statistics. In earlier versions of BIND 9.9,
18the v3 schema of statistics can be specified using the 'newstats'
19configuration directive. The newstats option was introduced in BIND 9.9.3.
20
21If you are using older versions of BIND 9.9 that only support version
222 of the XML statistics, you'll need to use the 0.1x version of this
23program, which can be obtained from:
24
25 https://github.com/shuque/bind9stats/archive/v0.12.tar.gz
26
27Software needed to use this:
28* Python 2.7 or later, or Python 3.x.
29* BIND: BIND DNS server from isc.org. https://www.isc.org/software/bind
30* Munin: a resource monitoring tool that does pretty graphs.
31 See http://munin-monitoring.org/ for details.)
32
33Some notes:
34* BIND can be configured to provide per-zone query statistics also. This
35 plugin currently doesn't process that data, and only does the aggregate
36 statistics for the entire server.
37* Only the _default view is used. Servers configured to use multiple
38 views that want per view statistics will have to extend this program
39 a bit.
40
41Instructions for using this:
42- Have a DNS server running BIND9, with the statistics server enabled.
43
44 On my BIND servers, I usually have something like the following in the
45 configuration file:
46
47 statistics-channels {
48 inet 127.0.0.1 port 8053 allow { 127.0.0.1; };
49 };
50
51- Have a munin-node running on it, install bind9stats.py in its plugins
52 directory and restart the node.
53 You can also run the plugin on another machine, if the statistics
54 server allows queries remotely. Set the HOST and PORT environment
55 variables appropriately in that case before invoking bind9stats.py.
56
57Sample munin graphs produced by this plugin:
58
59
60
61
62
63## bind9stats-graphite.py
64
65This version of the program collects BIND9 statistics and sends them
66to a [Graphite](https://graphite.readthedocs.io/en/latest/) server,
67another monitoring tool and time series data store. This runs as a long
68lived daemon, collects statistics at regular intervals (default is every
69minute), and then sends them to a Graphite server.
70
71```
72Usage: bind9stats-graphite.py [Options]
73
74 Options:
75 -h Print this usage message
76 -d Generate some diagnostic messages
77 -f Stay in foreground (default: become daemon)
78 -m metrics Comma separated metric types
79 (default: auth,res,bind,zone,memory)
80 (supported: auth,res,bind,zone,memory,socket)
81 -n name Specify server name (default: 1st component of hostname)
82 -i interval Polling interval in seconds (default: 60 sec)
83 -s server Graphite server IP address (default: 127.0.0.1)
84 -p port Graphite server port (default: 2003)
85 -r Really send data to Graphite (default: don't)
86
87 -o options Other comma separated options (default: none)
88 (supported: derive)
89```
90
91Installation:
92
93* Install the program into a suitable location on your system, e.g.
94 sudo cp bind9stats-graphite.py /usr/local/sbin/
95* Arrange for the program to be started up on system boot. A sample
96 [Systemd service file](systemd-service) and [Startup options file]
97 (sysconfig-options) is provided. The OPTIONS variable in the latter
98 specifies that command line options to start the program with, which
99 by default is set to: OPTIONS="-d -s 127.0.0.1 -r"
100
101Graphite is commonly the default backend for
102[Grafana](https://grafana.com/), a popular data visualization tool
103and dashboard. The included sample [Grafana dashboard configuration file](Grafana-BIND.json)
104produces output like the following:
105
106
107
108
109
110Author: Shumon Huque
111
112Copyright (c) 2013-2015 - Shumon Huque. All rights reserved.
113This program is free software; you can redistribute it and/or modify
114it under the same terms as Python itself.
115
