Knowledge Base ISC Main Website Ask a Question/Contact ISC
Using BIND's XML statistics-channels
Author: Cathy Almond Reference Number: AA-00769 Views: 2253 Created: 2012-08-08 11:10 Last Updated: 2014-07-17 17:39 0 Rating/ Voters


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.


© 2001-2015 Internet Systems Consortium

Please help us to improve the content of our knowledge base by letting us know below how we can improve this article.

If you have a technical question or problem on which you'd like help, please don't submit it here as article feedback.

For assistance with problems and questions for which you have not been able to find an answer in our Knowledge Base, we recommend searching our community mailing list archives and/or posting your question there (you will need to register there first for your posts to be accepted). The bind-users and the dhcp-users lists particularly have a long-standing and active membership.

ISC relies on the financial support of the community to fund the development of its open source software products. If you would like to support future product evolution and maintenance as well having peace of mind knowing that our team of experts are poised to provide you with individual technical assistance whenever you call upon them, then please consider our Professional Subscription Support services - details can be found on our main website.

Attachments
statistics_example_1.xml.txt 0.1 Mb Download File
statistics_example_2_with_zone_statistics.xml.txt 0.1 Mb Download File
Feedback
  • There is no feedback for this article
Info Submit Feedback on this Article
Nickname: Your Email: Subject: Comment:
Enter the code below:
Quick Jump Menu