Using BIND's XML statistics-channels

AA-00769


In addition to the output from rndc stats, BIND can be monitored (and in more detail) via its XML-based statistics channels.

To use this functionality BIND needs to be built with libxml2.  All current distributions of BIND for Windows available from the ISC website have been built with libxml2 support. 

In a non-Windows environment, you build with libxml2 support by specifying --with-libxml2 when running ./configure.  For example:

./configure --with-openssl --enable-threads --with-libxml2

Make sure that you have both libxml2 and its headers files installed

The build will apparently succeed, but it will not be possible to use the statistics channel (and if configured, named will give a warning on start-up) unless both are present and named knows where to find them.  In many environments, this means that you need both libxml2 and libxml2-dev packages installed.  See the Troubleshooting section below for more information on diagnosing problems.


Next, you need to add the necessary configuration to named.conf, for example:

statistics-channels {
        inet 10.1.10.10 port 8080 allow { 192.168.2.10; 10.1.10.2; };
        inet 127.0.0.1 port 8080 allow { 127.0.0.1; };
};


The syntax for this statement is defined in the BIND Administrator's Reference Manual (distributed in electronic form with BIND and also available on our website at https://www.isc.org/software/bind/documentation/) and allows flexible control over which machines may query for the statistics information. The example given above configures BIND to listen on
two separate interfaces (10.1.10.10 and 127.0.0.1) and allow queries only from source IPs that match a specified address match list.

Statistics are not collected on a per-zone basis by default. If you wish per-zone statistics, you can specify them on a zone-by-zone basis using the "zone-statistics yes;" statement
inside a zone declaration or make the same declaration in the global options to enable zone statistics for all defined zones.  For example:

zone "example.net" in {
        type master;
        file "master/example.net";
        zone-statistics yes;
};


BIND9 provides a basic xml stylesheet bind9.xsl which is accessible automatically once you have configured statistics-channels and are connecting from an allowed client.

So now that you have both the functionality and the configuration, you can view the statistics via a stylesheet-capable web browser (for example, if your nameserver is at 192.168.2.13 and you have instructed the server to listen on that interface on port 8080, navigate to http://192.168.2.13:8080/). A graphic browser is not the only intended method for checking; any script or application that can use HTTP to access the statistics interface can collect the xml file directly if the origin of the request matches the permissions defined in the statistics-channels configuration block.  You can also create your own stylesheet if you prefer.

This is how the XML output is formatted (we also have two full samples attached to this knowledge base article):


Note the difference between a zone that does have "zone-statistics yes;" configured (example.net) versus the one just preceding it that doesn't collect or emit per-zone statistics:


Below is an example of server statistics as viewed from a web browser using the default stylesheet bind9.xsl:



Troubleshooting

If you are having trouble getting the statistics server to function, check the output of named -V to ensure that BIND was configured with libxml2, e.g.:

$ named -V
BIND 9.9.1-P2 built with '--prefix=/usr/local/bind-9.9.1-P2' '--with-libxml2'



If the server is responding to http queries on the port you specify but is giving 404 errors for every request, inspect the named logs for an error in this format:

07-Aug-2012 11:35:26.771 statistics-channels specified but not effective due to missing XML library

In order to use the statistics channel, BIND must be configured and built with the option --with-libxml2 or the statistics server functionality is not available.  This can be somewhat confusing because nameserver will still accept a statistics channel declaration in named.conf if the library is not present, but the statistics server will not respond properly to http requests unless libxml2 has been properly included in the build and the libxml2 libraries are accessible.

If you are experiencing this problem, verify that you have both libxml2 and libxml2-dev installed.