Bv9ARM.ch12.html revision 71cef386fae61275b03e203825680b39fedaa8c6
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews - Copyright (C) 2000-2018 Internet Systems Consortium, Inc. ("ISC")
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - This Source Code Form is subject to the terms of the Mozilla Public
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - License, v. 2.0. If a copy of the MPL was not distributed with this
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews - file, You can obtain one at http://mozilla.org/MPL/2.0/.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<title>Appendix�D.�BIND 9 DNS Library Support</title>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<link rel="prev" href="Bv9ARM.ch11.html" title="Appendix�C.�General DNS Reference Information">
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<link rel="next" href="Bv9ARM.ch13.html" title="Manual pages">
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews<table width="100%" summary="Navigation header">
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews<tr><th colspan="3" align="center">Appendix�D.�BIND 9 DNS Library Support</th></tr>
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews<a accesskey="p" href="Bv9ARM.ch11.html">Prev</a>�</td>
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews<td width="20%" align="right">�<a accesskey="n" href="Bv9ARM.ch13.html">Next</a>
81f58902eb5a1c1ab22742c72bd6cf318acbc06aTinderbox User<div class="titlepage"><div><div><h1 class="title">
19c7b1a0293498a3e36692c59646ed6e15ffc8d0Tinderbox User<a name="Bv9ARM.ch12"></a>BIND 9 DNS Library Support</h1></div></div></div>
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews<dt><span class="section"><a href="Bv9ARM.ch12.html#bind9.library">BIND 9 DNS Library Support</a></span></dt>
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.5">Installation</a></span></dt>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.6">Known Defects/Restrictions</a></span></dt>
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.7">The dns.conf File</a></span></dt>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.8">Sample Applications</a></span></dt>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.9">Library References</a></span></dt>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<a name="bind9.library"></a>BIND 9 DNS Library Support</h2></div></div></div>
6b0434299b05b6ca05c6836b9e8fbb7e67f05fb8Mark Andrews This version of BIND 9 "exports" its internal libraries so
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt that they can be used by third-party applications more easily (we
6b0434299b05b6ca05c6836b9e8fbb7e67f05fb8Mark Andrews call them "export" libraries in this document). Certain library
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt functions are altered from specific BIND-only behavior to more generic
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt behavior when used by other applications; to enable this generic behavior,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt the calling program initializes the libraries by calling
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <span class="command"><strong>isc_lib_register()</strong></span>.
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews In addition to DNS-related APIs that are used within BIND 9, the
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt libraries provide the following features:
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews The "DNS client" module. This is a higher level API that
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews provides an interface to name resolution, single DNS transaction
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt with a particular server, and dynamic update. Regarding name
30eec077db2bdcb6f2a0dc388a3cdde2ede75ec1Mark Andrews resolution, it supports advanced features such as DNSSEC validation
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews and caching. This module supports both synchronous and asynchronous
6b0434299b05b6ca05c6836b9e8fbb7e67f05fb8Mark Andrews The "IRS" (Information Retrieval System) library. It provides an
6b0434299b05b6ca05c6836b9e8fbb7e67f05fb8Mark Andrews interface to parse the traditional <code class="filename">resolv.conf</code>
6b0434299b05b6ca05c6836b9e8fbb7e67f05fb8Mark Andrews file and more advanced, DNS-specific configuration file for the
6ce1aa190246d65eb9dbcf0d29960f2773e3ab41Evan Hunt rest of this package (see the description for the
6b0434299b05b6ca05c6836b9e8fbb7e67f05fb8Mark Andrews <code class="filename">dns.conf</code> file below).
6b0434299b05b6ca05c6836b9e8fbb7e67f05fb8Mark Andrews As part of the IRS library, the standard address-name
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews mapping functions, <span class="command"><strong>getaddrinfo()</strong></span> and
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <span class="command"><strong>getnameinfo()</strong></span>, are provided. They use the
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews DNSSEC-aware validating resolver backend, and could use other
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt advanced features of the BIND 9 libraries such as caching. The
30eec077db2bdcb6f2a0dc388a3cdde2ede75ec1Mark Andrews <span class="command"><strong>getaddrinfo()</strong></span> function resolves both A
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews and AAAA RRs concurrently when the address family is
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews unspecified.
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews An experimental framework to support other event
6b0434299b05b6ca05c6836b9e8fbb7e67f05fb8Mark Andrews libraries than BIND 9's internal event task system.
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews<div class="titlepage"><div><div><h3 class="title">
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews<a name="id-1.13.2.5"></a>Installation</h3></div></div></div>
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews$ <strong class="userinput"><code>make install</code></strong>
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews Normal installation of BIND will also install library object
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews and header files. Root privilege is normally required.
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews To see how to build your own application after the installation, see
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews <code class="filename">lib/samples/Makefile-postinstall.in</code>.
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews<div class="titlepage"><div><div><h3 class="title">
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews<a name="id-1.13.2.6"></a>Known Defects/Restrictions</h3></div></div></div>
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews The "fixed" RRset order is not (currently) supported in the export
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews library. If you want to use "fixed" RRset order for, e.g.
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews <span class="command"><strong>named</strong></span> while still building the export library
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews even without the fixed order support, build them separately:
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews$ <strong class="userinput"><code>/configure --enable-fixed-rrset <em class="replaceable"><code>[other flags, but not --enable-exportlib]</code></em></code></strong>
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews$ <strong class="userinput"><code>make</code></strong>
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews$ <strong class="userinput"><code>/configure --enable-exportlib <em class="replaceable"><code>[other flags, but not --enable-fixed-rrset]</code></em></code></strong>
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews$ <strong class="userinput"><code>cd lib/export</code></strong>
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews$ <strong class="userinput"><code>make</code></strong>
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews RFC 5011 is not supported in the validating stub resolver of the
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews export library. In fact, it is not clear whether it should: trust
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews anchors would be a system-wide configuration which would be managed
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews by an administrator, while the stub resolver will be used by
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews ordinary applications run by a normal user.
42782931073786f98d3d0a617351db40066949a4Mukund Sivaraman Not all common <code class="filename">/etc/resolv.conf</code> options are
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews supported in the IRS library. The only available options in this
42782931073786f98d3d0a617351db40066949a4Mukund Sivaraman version are <span class="command"><strong>debug</strong></span> and <span class="command"><strong>ndots</strong></span>.
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews<div class="titlepage"><div><div><h3 class="title">
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<a name="id-1.13.2.7"></a>The dns.conf File</h3></div></div></div>
30eec077db2bdcb6f2a0dc388a3cdde2ede75ec1Mark Andrews The IRS library supports an "advanced" configuration file related to
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews the DNS library for configuration parameters that would be beyond the
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews capability of the <code class="filename">resolv.conf</code> file.
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews Specifically, it is intended to provide DNSSEC related configuration
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews parameters. By default the path to this configuration file is
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews <code class="filename">/etc/dns.conf</code>. This module is very experimental
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews and the configuration syntax or library interfaces may change in
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews future versions. Currently, only the <span class="command"><strong>trusted-keys</strong></span>
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews statement is supported, whose syntax is the same as the same
a165a17a81ff3285f4f4d79785fafb465e626183Evan Hunt statement in <code class="filename">named.conf</code>. (See
a165a17a81ff3285f4f4d79785fafb465e626183Evan Hunt <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.)
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews<div class="titlepage"><div><div><h3 class="title">
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews<a name="id-1.13.2.8"></a>Sample Applications</h3></div></div></div>
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews Some sample application programs using this API are provided for
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews reference. The following is a brief description of these
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews applications.
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews<div class="titlepage"><div><div><h4 class="title">
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews<a name="id-1.13.2.8.3"></a>sample: a simple stub resolver utility</h4></div></div></div>
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews Sends a query of a given name (of a given optional RR type) to a
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews specified recursive server and prints the result as a list of RRs.
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews It can also act as a validating stub resolver if a trust anchor is
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews given via a set of command line options.
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews Usage: sample [options] server_address hostname
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews Options and Arguments:
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews <div class="variablelist"><dl class="variablelist">
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews specify the RR type of the query. The default is the A RR.
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews<dt><span class="term">[-a algorithm] [-e] -k keyname -K keystring</span></dt>
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews specify a command-line DNS key to validate the answer. For
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews example, to specify the following DNSKEY of example.com:
e939674d53a127ddeeaf4b41fd72933f0b493308Mark Andrews ��������������example.com.�3600�IN�DNSKEY�257�3�5�xxx<br>
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews specify the options as follows:
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews<strong class="userinput"><code>-e -k example.com -K "xxx"</code></strong>
6b0434299b05b6ca05c6836b9e8fbb7e67f05fb8Mark Andrews -e means that this key is a zone's "key signing key" (also known
6b0434299b05b6ca05c6836b9e8fbb7e67f05fb8Mark Andrews as "secure entry point").
6b0434299b05b6ca05c6836b9e8fbb7e67f05fb8Mark Andrews When -a is omitted rsasha1 will be used by default.
6b0434299b05b6ca05c6836b9e8fbb7e67f05fb8Mark Andrews<dt><span class="term">-s domain:alt_server_address</span></dt>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt specify a separate recursive server address for the specific
30eec077db2bdcb6f2a0dc388a3cdde2ede75ec1Mark Andrews "domain". Example: -s example.com:2001:db8::1234
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews<dt><span class="term">server_address</span></dt>
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews an IP(v4/v6) address of the recursive server to which queries
<a name="id-1.13.2.8.4"></a>sample-async: a simple stub resolver, working asynchronously</h4></div></div></div>
<a name="id-1.13.2.8.6"></a>sample-gai: getaddrinfo() and getnameinfo() test code</h4></div></div></div>
dns.conf file exists and defines a trust anchor, the underlying
<span class="command"><strong>getaddrinfo()</strong></span>/<span class="command"><strong>getnameinfo()</strong></span>
<a name="id-1.13.2.8.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.8.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
<td width="40%" align="left" valign="top">Appendix�C.�General <acronym class="acronym">DNS</acronym> Reference Information�</td>
<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.2 (Extended Support Version)</p>