2N/A - Copyright (C) 2000-2016 Internet Systems Consortium, Inc. ("ISC") 2N/A - This Source Code Form is subject to the terms of the Mozilla Public 2N/A - License, v. 2.0. If a copy of the MPL was not distributed with this 2N/A<
meta http-
equiv="Content-Type" content="text/html; charset=ISO-8859-1">
2N/A<
title>Appendix�D.�BIND 9 DNS Library Support</
title>
2N/A<
meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
2N/A<
link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
2N/A<
link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
2N/A<
body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
2N/A<
div class="navheader">
2N/A<
table width="100%" summary="Navigation header">
2N/A<
tr><
th colspan="3" align="center">Appendix�D.�BIND 9 DNS Library Support</
th></
tr>
2N/A<
td width="20%" align="left">
2N/A<
th width="60%" align="center">�</
th>
2N/A<
div class="appendix">
2N/A<
div class="titlepage"><
div><
div><
h1 class="title">
2N/A<
a name="Bv9ARM.ch12"></
a>BIND 9 DNS Library Support</
h1></
div></
div></
div>
2N/A<
p><
b>Table of Contents</
b></
p>
2N/A<
dt><
span class="section"><
a href="Bv9ARM.ch12.html#id-1.13.2.9">Sample Applications</
a></
span></
dt>
2N/A<
dt><
span class="section"><
a href="Bv9ARM.ch12.html#id-1.13.2.10">Library References</
a></
span></
dt>
2N/A <
div class="section">
2N/A<
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both">
2N/A <
p>This version of BIND 9 "exports" its internal libraries so
2N/A that they can be used by third-party applications more easily (we
2N/A call them "export" libraries in this document). In addition to
2N/A all major DNS-related APIs BIND 9 is currently using, the export
2N/A libraries provide the following features:</
p>
2N/A <
div class="itemizedlist"><
ul class="itemizedlist" style="list-style-type: disc; ">
2N/A<
li class="listitem">
2N/A <
p>The newly created "DNS client" module. This is a higher
2N/A level API that provides an interface to name resolution,
2N/A single DNS transaction with a particular server, and dynamic
2N/A update. Regarding name resolution, it supports advanced
2N/A features such as DNSSEC validation and caching. This module
2N/A supports both synchronous and asynchronous mode.</
p>
2N/A<
li class="listitem">
2N/A <
p>The new "IRS" (Information Retrieval System) library.
2N/A file and more advanced, DNS-specific configuration file for
2N/A the rest of this package (see the description for the
2N/A<
li class="listitem">
2N/A <
p>As part of the IRS library, newly implemented standard
2N/A address-name mapping functions, getaddrinfo() and
2N/A getnameinfo(), are provided. They use the DNSSEC-aware
2N/A validating resolver backend, and could use other advanced
2N/A features of the BIND 9 libraries such as caching. The
2N/A getaddrinfo() function resolves both A and AAAA RRs
2N/A concurrently (when the address family is unspecified).</
p>
2N/A<
li class="listitem">
2N/A <
p>An experimental framework to support other event
2N/A libraries than BIND 9's internal event task system.</
p>
2N/A <
div class="section">
2N/A<
div class="titlepage"><
div><
div><
h3 class="title">
2N/A<
a name="id-1.13.2.4"></
a>Prerequisite</
h3></
div></
div></
div>
2N/A <
p>GNU make is required to build the export libraries (other
2N/A part of BIND 9 can still be built with other types of make). In
2N/A the reminder of this document, "make" means GNU make. Note that
2N/A in some platforms you may need to invoke a different command name
2N/A than "make" (
e.g. "gmake") to indicate it's GNU make.</
p>
2N/A <
div class="section">
2N/A<
div class="titlepage"><
div><
div><
h3 class="title">
2N/A<
a name="id-1.13.2.5"></
a>Compilation</
h3></
div></
div></
div>
2N/A <
pre class="screen">
2N/A$ <
strong class="userinput"><
code>/
configure --enable-exportlib <
em class="replaceable"><
code>[other flags]</
code></
em></
code></
strong>
2N/A$ <
strong class="userinput"><
code>make</
code></
strong>
2N/A This will create (in addition to usual BIND 9 programs) and a
2N/A separate set of libraries under the
lib/
export directory. For
2N/A export version of the BIND 9 DNS library. Sample application
2N/A programs using the libraries will also be built under the
2N/A <
div class="section">
2N/A<
div class="titlepage"><
div><
div><
h3 class="title">
2N/A<
a name="id-1.13.2.6"></
a>Installation</
h3></
div></
div></
div>
2N/A <
pre class="screen">
2N/A$ <
strong class="userinput"><
code>cd
lib/
export</
code></
strong>
2N/A$ <
strong class="userinput"><
code>make install</
code></
strong>
2N/A This will install library object files under the directory
2N/A specified by the --with-export-libdir configure option (default:
2N/A specified by the --with-export-includedir configure option
2N/A Root privilege is normally required.
2N/A "<
span class="command"><
strong>make install</
strong></
span>" at the top directory will do the
2N/A To see how to build your own
2N/A application after the installation, see
2N/A <
div class="section">
2N/A<
div class="titlepage"><
div><
div><
h3 class="title">
2N/A <
div class="itemizedlist"><
ul class="itemizedlist" style="list-style-type: disc; ">
2N/A<
li class="listitem">
2N/A <
p>Currently, win32 is not supported for the export
2N/A library. (Normal BIND 9 application can be built as
2N/A<
li class="listitem">
2N/A <
p>The "fixed" RRset order is not (currently) supported in
2N/A the export library. If you want to use "fixed" RRset order
2N/A for,
e.g. <
span class="command"><
strong>named</
strong></
span> while still building the
2N/A export library even without the fixed order support, build
2N/A$ <
strong class="userinput"><
code>/
configure --enable-fixed-rrset <
em class="replaceable"><
code>[other flags, but not --enable-exportlib]</
code></
em></
code></
strong>
2N/A$ <
strong class="userinput"><
code>make</
code></
strong>
2N/A$ <
strong class="userinput"><
code>/
configure --enable-exportlib <
em class="replaceable"><
code>[other flags, but not --enable-fixed-rrset]</
code></
em></
code></
strong>
2N/A$ <
strong class="userinput"><
code>cd
lib/
export</
code></
strong>
2N/A$ <
strong class="userinput"><
code>make</
code></
strong>
2N/A<
li class="listitem">
2N/A <
p>The client module and the IRS library currently do not
2N/A support DNSSEC validation using DLV (the underlying modules
2N/A can handle it, but there is no tunable interface to enable
2N/A<
li class="listitem">
2N/A <
p>RFC 5011 is not supported in the validating stub
2N/A resolver of the export library. In fact, it is not clear
2N/A whether it should: trust anchors would be a system-wide
2N/A configuration which would be managed by an administrator,
2N/A while the stub resolver will be used by ordinary applications
2N/A run by a normal user.</
p>
2N/A<
li class="listitem">
2N/A options are supported
2N/A in the IRS library. The only available options in this
2N/A version are "debug" and "ndots".</
p>
2N/A <
div class="section">
2N/A<
div class="titlepage"><
div><
div><
h3 class="title">
2N/A<
a name="id-1.13.2.8"></
a>The
dns.conf File</
h3></
div></
div></
div>
2N/A <
p>The IRS library supports an "advanced" configuration file
2N/A related to the DNS library for configuration parameters that
2N/A would be beyond the capability of the
2N/A Specifically, it is intended to provide DNSSEC related
2N/A configuration parameters. By default the path to this
2N/A experimental and the configuration syntax or library interfaces
2N/A may change in future versions. Currently, only the
2N/A <
span class="command"><
strong>trusted-keys</
strong></
span>
2N/A statement is supported, whose syntax is the same as the same name
2N/A <
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>
2N/A <
div class="section">
2N/A<
div class="titlepage"><
div><
div><
h3 class="title">
2N/A<
a name="id-1.13.2.9"></
a>Sample Applications</
h3></
div></
div></
div>
2N/A <
p>Some sample application programs using this API are
2N/A provided for reference. The following is a brief description of
2N/A <
div class="section">
2N/A<
div class="titlepage"><
div><
div><
h4 class="title">
2N/A<
a name="id-1.13.2.9.3"></
a>sample: a simple stub resolver utility</
h4></
div></
div></
div>
2N/A It sends a query of a given name (of a given optional RR type) to a
2N/A specified recursive server, and prints the result as a list of
2N/A RRs. It can also act as a validating stub resolver if a trust
2N/A anchor is given via a set of command line options.</
p>
2N/A Usage: sample [options] server_address hostname
2N/A Options and Arguments:
2N/A <
div class="variablelist"><
dl class="variablelist">
2N/A<
dt><
span class="term">
2N/A specify the RR type of the query. The default is the A RR.
2N/A<
dt><
span class="term">
2N/A [-a algorithm] [-e] -k keyname -K keystring
2N/A specify a command-line DNS key to validate the answer. For
2N/A<
div class="literallayout"><
p><
br>
2N/A specify the options as follows:
2N/A<
strong class="userinput"><
code>
2N/A -e means that this key is a zone's "key signing key" (as known
2N/A as "secure Entry point").
2N/A When -a is omitted rsasha1 will be used by default.
2N/A<
dt><
span class="term">
2N/A -s domain:alt_server_address
2N/A specify a separate recursive server address for the specific
2N/A<
dt><
span class="term">server_address</
span></
dt>
2N/A an IP(
v4/
v6) address of the recursive server to which queries
2N/A<
dt><
span class="term">hostname</
span></
dt>
2N/A the domain name for the query
2N/A <
div class="section">
2N/A<
div class="titlepage"><
div><
div><
h4 class="title">
2N/A<
a name="id-1.13.2.9.4"></
a>sample-async: a simple stub resolver, working asynchronously</
h4></
div></
div></
div>
2N/A Similar to "sample", but accepts a list
2N/A of (query) domain names as a separate file and resolves the names
2N/A Usage: sample-async [-s server_address] [-t RR_type] input_file</
p>
2N/A Options and Arguments:
2N/A <
div class="variablelist"><
dl class="variablelist">
2N/A<
dt><
span class="term">
2N/A an IPv4 address of the recursive server to which queries are sent.
2N/A (IPv6 addresses are not supported in this implementation)
2N/A<
dt><
span class="term">
2N/A specify the RR type of the queries. The default is the A
2N/A<
dt><
span class="term">
2N/A a list of domain names to be resolved. each line
2N/A consists of a single domain name. Example:
2N/A <
div class="literallayout"><
p><
br>
2N/A <
div class="section">
2N/A<
div class="titlepage"><
div><
div><
h4 class="title">
2N/A<
a name="id-1.13.2.9.5"></
a>sample-request: a simple DNS transaction client</
h4></
div></
div></
div>
2N/A It sends a query to a specified server, and
2N/A prints the response with minimal processing. It doesn't act as a
2N/A "stub resolver": it stops the processing once it gets any
2N/A response from the server, whether it's a referral or an alias
2N/A (CNAME or DNAME) that would require further queries to get the
2N/A ultimate answer. In other words, this utility acts as a very
2N/A simplified <
span class="command"><
strong>dig</
strong></
span>.
2N/A Usage: sample-request [-t RRtype] server_address hostname
2N/A Options and Arguments:
2N/A <
div class="variablelist"><
dl class="variablelist">
2N/A<
dt><
span class="term">
2N/A specify the RR type of
2N/A the queries. The default is the A RR.
2N/A<
dt><
span class="term">
2N/A address of the recursive server to which the query is sent.
2N/A<
dt><
span class="term">
2N/A the domain name for the query
2N/A <
div class="section">
2N/A<
div class="titlepage"><
div><
div><
h4 class="title">
2N/A<
a name="id-1.13.2.9.6"></
a>sample-gai: getaddrinfo() and getnameinfo() test code</
h4></
div></
div></
div>
2N/A This is a test program
2N/A to check getaddrinfo() and getnameinfo() behavior. It takes a
2N/A host name as an argument, calls getaddrinfo() with the given host
2N/A name, and calls getnameinfo() with the resulting IP addresses
2N/A returned by getaddrinfo(). If the
dns.conf file exists and
2N/A defines a trust anchor, the underlying resolver will act as a
2N/A validating resolver, and getaddrinfo()/getnameinfo() will fail
2N/A with an EAI_INSECUREDATA error when DNSSEC validation fails.
2N/A Usage: sample-gai hostname
2N/A <
div class="section">
2N/A<
div class="titlepage"><
div><
div><
h4 class="title">
2N/A<
a name="id-1.13.2.9.7"></
a>sample-update: a simple dynamic update client program</
h4></
div></
div></
div>
2N/A It accepts a single update command as a
2N/A command-line argument, sends an update request message to the
2N/A authoritative server, and shows the response from the server. In
2N/A other words, this is a simplified <
span class="command"><
strong>nsupdate</
strong></
span>.
2N/A Usage: sample-update [options] (add|delete) "update data"
2N/A Options and Arguments:
2N/A <
div class="variablelist"><
dl class="variablelist">
2N/A<
dt><
span class="term">
2N/A An IP address of the authoritative server that has authority
2N/A for the zone containing the update name. This should normally
2N/A be the primary authoritative server that accepts dynamic
2N/A updates. It can also be a secondary server that is configured
2N/A to forward update requests to the primary server.
2N/A<
dt><
span class="term">
2N/A A TSIG key file to secure the update transaction. The keyfile
2N/A format is the same as that for the nsupdate utility.
2N/A<
dt><
span class="term">
2N/A A prerequisite for the update (only one prerequisite can be
2N/A specified). The prerequisite format is the same as that is
2N/A accepted by the nsupdate utility.
2N/A<
dt><
span class="term">
2N/A An IP address of a recursive server that this utility will
2N/A use. A recursive server may be necessary to identify the
2N/A authoritative server address to which the update request is
2N/A<
dt><
span class="term">
2N/A The domain name of the zone that contains
2N/A<
dt><
span class="term">
2N/A Specify the type of update operation. Either "add" or "delete"
2N/A<
dt><
span class="term">
2N/A Specify the data to be updated. A typical example of the data
2N/A would look like "name TTL RRtype RDATA".
2N/A <
div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
2N/A<
h3 class="title">Note</
h3>
2N/A In practice, either -a or -r must be specified. Others can
2N/A be optional; the underlying library routine tries to identify the
2N/A appropriate server and the zone name for the update.
2N/A Examples: assuming the primary authoritative server of the
2N/A <
pre class="screen">
2N/A <
pre class="screen">
2N/A <
pre class="screen">
2N/A <
div class="section">
2N/A<
div class="titlepage"><
div><
div><
h4 class="title">
2N/A<
a name="id-1.13.2.9.8"></
a>nsprobe:
domain/
name server checker in terms of RFC 4074</
h4></
div></
div></
div>
2N/A of domains to see the name servers of the domains behave
2N/A correctly in terms of RFC 4074. This is included in the set of
2N/A sample programs to show how the export library can be used in a
2N/A DNS-related application.
2N/A Usage: nsprobe [-d] [-v [-v...]] [-c cache_address] [input_file]
2N/A <
div class="variablelist"><
dl class="variablelist">
2N/A<
dt><
span class="term">
2N/A run in the "debug" mode. with this option nsprobe will dump
2N/A every RRs it receives.
2N/A<
dt><
span class="term">
2N/A increase verbosity of other normal log messages. This can be
2N/A specified multiple times
2N/A<
dt><
span class="term">
2N/A specify an IP address of a recursive (caching) name server.
2N/A nsprobe uses this server to get the NS RRset of each domain and
2N/A the A
and/
or AAAA RRsets for the name servers. The default
2N/A<
dt><
span class="term">
2N/A a file name containing a list of domain (zone) names to be
2N/A probed. when omitted the standard input will be used. Each
2N/A line of the input file specifies a single domain name such as
2N/A name of some DNS zone (unlike normal "host names" such as
2N/A the given domain name, and sends A and AAAA queries to these
2N/A servers for some "widely used" names under the zone;
2N/A specifically, adding "www" and "ftp" to the zone name.
2N/A <
div class="section">
2N/A<
div class="titlepage"><
div><
div><
h3 class="title">
2N/A<
a name="id-1.13.2.10"></
a>Library References</
h3></
div></
div></
div>
2N/A <
p>As of this writing, there is no formal "manual" of the
2N/A libraries, except this document, header files (some of them
2N/A provide pretty detailed explanations), and sample application
2N/A<
div class="navfooter">
2N/A<
table width="100%" summary="Navigation footer">
2N/A<
td width="40%" align="left">
2N/A<
td width="20%" align="center">�</
td>
2N/A<
td width="40%" align="left" valign="top">Appendix�C.�General <
acronym class="acronym">DNS</
acronym> Reference Information�</
td>
2N/A<
td width="20%" align="center"><
a accesskey="h" href="Bv9ARM.html">Home</
a></
td>
2N/A<
td width="40%" align="right" valign="top">�Manual pages</
td>