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