Bv9ARM.ch12.html revision 8dcec3cf256105c620d02d5c84c9ccbfe495ca8d
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg - Copyright (C) 2000-2016 Internet Systems Consortium, Inc. ("ISC")
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg - This Source Code Form is subject to the terms of the Mozilla Public
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg - License, v. 2.0. If a copy of the MPL was not distributed with this
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg - file, You can obtain one at http://mozilla.org/MPL/2.0/.
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<title>Appendix�D.�BIND 9 DNS Library Support</title>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<link rel="prev" href="Bv9ARM.ch11.html" title="Appendix�C.�General DNS Reference Information">
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<link rel="next" href="Bv9ARM.ch13.html" title="Manual pages">
4f7bde67c075330b1fbd5b9abe25e347eb8e5690Trond Norbye<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<tr><th colspan="3" align="center">Appendix�D.�BIND 9 DNS Library Support</th></tr>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<a accesskey="p" href="Bv9ARM.ch11.html">Prev</a>�</td>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<td width="20%" align="right">�<a accesskey="n" href="Bv9ARM.ch13.html">Next</a>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<div class="titlepage"><div><div><h1 class="title">
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<a name="Bv9ARM.ch12"></a>BIND 9 DNS Library Support</h1></div></div></div>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<dt><span class="section"><a href="Bv9ARM.ch12.html#bind9.library">BIND 9 DNS Library Support</a></span></dt>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.4">Prerequisite</a></span></dt>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.5">Compilation</a></span></dt>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.6">Installation</a></span></dt>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.7">Known Defects/Restrictions</a></span></dt>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.8">The dns.conf File</a></span></dt>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.9">Sample Applications</a></span></dt>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.10">Library References</a></span></dt>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<div class="titlepage"><div><div><h2 class="title" style="clear: both">
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<a name="bind9.library"></a>BIND 9 DNS Library Support</h2></div></div></div>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg <p>This version of BIND 9 "exports" its internal libraries so
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg that they can be used by third-party applications more easily (we
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg call them "export" libraries in this document). In addition to
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg all major DNS-related APIs BIND 9 is currently using, the export
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg libraries provide the following features:</p>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg <p>The newly created "DNS client" module. This is a higher
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg level API that provides an interface to name resolution,
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg single DNS transaction with a particular server, and dynamic
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg update. Regarding name resolution, it supports advanced
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg features such as DNSSEC validation and caching. This module
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg supports both synchronous and asynchronous mode.</p>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg <p>The new "IRS" (Information Retrieval System) library.
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg It provides an interface to parse the traditional resolv.conf
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg file and more advanced, DNS-specific configuration file for
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg the rest of this package (see the description for the
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg <p>As part of the IRS library, newly implemented standard
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg address-name mapping functions, getaddrinfo() and
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg getnameinfo(), are provided. They use the DNSSEC-aware
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg validating resolver backend, and could use other advanced
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg features of the BIND 9 libraries such as caching. The
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg getaddrinfo() function resolves both A and AAAA RRs
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg concurrently (when the address family is unspecified).</p>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg <p>An experimental framework to support other event
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg libraries than BIND 9's internal event task system.</p>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<div class="titlepage"><div><div><h3 class="title">
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<a name="id-1.13.2.4"></a>Prerequisite</h3></div></div></div>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg <p>GNU make is required to build the export libraries (other
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg part of BIND 9 can still be built with other types of make). In
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg the reminder of this document, "make" means GNU make. Note that
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg in some platforms you may need to invoke a different command name
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg than "make" (e.g. "gmake") to indicate it's GNU make.</p>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<div class="titlepage"><div><div><h3 class="title">
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<a name="id-1.13.2.5"></a>Compilation</h3></div></div></div>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg$ <strong class="userinput"><code>/configure --enable-exportlib <em class="replaceable"><code>[other flags]</code></em></code></strong>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg$ <strong class="userinput"><code>make</code></strong>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg This will create (in addition to usual BIND 9 programs) and a
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg separate set of libraries under the lib/export directory. For
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg example, <code class="filename">lib/export/dns/libdns.a</code> is the archive file of the
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg export version of the BIND 9 DNS library. Sample application
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg programs using the libraries will also be built under the
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<div class="titlepage"><div><div><h3 class="title">
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<a name="id-1.13.2.6"></a>Installation</h3></div></div></div>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg$ <strong class="userinput"><code>cd lib/export</code></strong>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg$ <strong class="userinput"><code>make install</code></strong>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg This will install library object files under the directory
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg specified by the --with-export-libdir configure option (default:
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg EPREFIX/lib/bind9), and header files under the directory
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg specified by the --with-export-includedir configure option
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg Root privilege is normally required.
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg "<span class="command"><strong>make install</strong></span>" at the top directory will do the
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg To see how to build your own
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg application after the installation, see
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg <code class="filename">lib/export/samples/Makefile-postinstall.in</code>.</p>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<div class="titlepage"><div><div><h3 class="title">
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<a name="id-1.13.2.7"></a>Known Defects/Restrictions</h3></div></div></div>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg <p>Currently, win32 is not supported for the export
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg library. (Normal BIND 9 application can be built as
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg before).</p>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg <p>The "fixed" RRset order is not (currently) supported in
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg the export library. If you want to use "fixed" RRset order
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg for, e.g. <span class="command"><strong>named</strong></span> while still building the
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg export library even without the fixed order support, build
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg them separately:
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg$ <strong class="userinput"><code>/configure --enable-fixed-rrset <em class="replaceable"><code>[other flags, but not --enable-exportlib]</code></em></code></strong>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg$ <strong class="userinput"><code>make</code></strong>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg$ <strong class="userinput"><code>/configure --enable-exportlib <em class="replaceable"><code>[other flags, but not --enable-fixed-rrset]</code></em></code></strong>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg$ <strong class="userinput"><code>cd lib/export</code></strong>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg$ <strong class="userinput"><code>make</code></strong>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg <p>The client module and the IRS library currently do not
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg support DNSSEC validation using DLV (the underlying modules
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg can handle it, but there is no tunable interface to enable
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg the feature).</p>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg <p>RFC 5011 is not supported in the validating stub
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg resolver of the export library. In fact, it is not clear
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg whether it should: trust anchors would be a system-wide
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg configuration which would be managed by an administrator,
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg while the stub resolver will be used by ordinary applications
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg run by a normal user.</p>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg <p>Not all common <code class="filename">/etc/resolv.conf</code>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg options are supported
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg in the IRS library. The only available options in this
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg version are "debug" and "ndots".</p>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<div class="titlepage"><div><div><h3 class="title">
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<a name="id-1.13.2.8"></a>The dns.conf File</h3></div></div></div>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg <p>The IRS library supports an "advanced" configuration file
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg related to the DNS library for configuration parameters that
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg would be beyond the capability of the
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg Specifically, it is intended to provide DNSSEC related
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg configuration parameters. By default the path to this
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg configuration file is <code class="filename">/etc/dns.conf</code>.
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg This module is very
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg experimental and the configuration syntax or library interfaces
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg may change in future versions. Currently, only the
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg <span class="command"><strong>trusted-keys</strong></span>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg statement is supported, whose syntax is the same as the same name
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg of statement for <code class="filename">named.conf</code>. (See
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg <a class="xref" href="Bv9ARM.ch06.html#trusted-keys" title="trusted-keys Statement Grammar">the section called “<span class="command"><strong>trusted-keys</strong></span> Statement Grammar”</a> for details.)</p>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<div class="titlepage"><div><div><h3 class="title">
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<a name="id-1.13.2.9"></a>Sample Applications</h3></div></div></div>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg <p>Some sample application programs using this API are
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg provided for reference. The following is a brief description of
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg these applications.
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<div class="titlepage"><div><div><h4 class="title">
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg<a name="id-1.13.2.9.3"></a>sample: a simple stub resolver utility</h4></div></div></div>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg It sends a query of a given name (of a given optional RR type) to a
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg specified recursive server, and prints the result as a list of
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg RRs. It can also act as a validating stub resolver if a trust
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg anchor is given via a set of command line options.</p>
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg Usage: sample [options] server_address hostname
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg Options and Arguments:
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg <div class="variablelist"><dl class="variablelist">
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg specify the RR type of the query. The default is the A RR.
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg [-a algorithm] [-e] -k keyname -K keystring
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg specify a command-line DNS key to validate the answer. For
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg example, to specify the following DNSKEY of example.com:
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg specify the options as follows:
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg -e -k example.com -K "xxx"
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg -e means that this key is a zone's "key signing key" (as known
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg as "secure Entry point").
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg When -a is omitted rsasha1 will be used by default.
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg -s domain:alt_server_address
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg specify a separate recursive server address for the specific
b8f2cc83ded7038d6b2268f028350f59d4c939b1Jan S Berg "domain". Example: -s example.com:2001:db8::1234
<a name="id-1.13.2.9.4"></a>sample-async: a simple stub resolver, working asynchronously</h4></div></div></div>
<a name="id-1.13.2.9.6"></a>sample-gai: getaddrinfo() and getnameinfo() test code</h4></div></div></div>
returned by getaddrinfo(). If the dns.conf file exists and
<a name="id-1.13.2.9.7"></a>sample-update: a simple dynamic update client program</h4></div></div></div>
dynamic.example.com zone has an IPv6 address 2001:db8::1234,
$ <strong class="userinput"><code>sample-update -a sample-update -k Kxxx.+nnn+mmmm.key add "foo.dynamic.example.com 30 IN A 192.168.2.1"</code></strong></pre>
adds an A RR for foo.dynamic.example.com using the given key.
$ <strong class="userinput"><code>sample-update -a sample-update -k Kxxx.+nnn+mmmm.key delete "foo.dynamic.example.com 30 IN A"</code></strong></pre>
removes all A RRs for foo.dynamic.example.com using the given key.
$ <strong class="userinput"><code>sample-update -a sample-update -k Kxxx.+nnn+mmmm.key delete "foo.dynamic.example.com"</code></strong></pre>
removes all RRs for foo.dynamic.example.com using the given key.
<a name="id-1.13.2.9.8"></a>nsprobe: domain/name server checker in terms of RFC 4074</h4></div></div></div>
"example.com". In general this domain name must be the apex
"www.example.com"). nsprobe first identifies the NS RRsets for