<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="bind9.library"><info><title>BIND 9 DNS Library Support</title></info>

<para>This version of BIND 9 "exports" its internal libraries so

that they can be used by third-party applications more easily (we

call them "export" libraries in this document). In addition to

all major DNS-related APIs BIND 9 is currently using, the export

libraries provide the following features:</para>

<itemizedlist>

<listitem>

<para>The newly created "DNS client" module. This is a higher

level API that provides an interface to name resolution,

single DNS transaction with a particular server, and dynamic

update. Regarding name resolution, it supports advanced

features such as DNSSEC validation and caching. This module

supports both synchronous and asynchronous mode.</para>

</listitem>

<listitem>

<para>The new "IRS" (Information Retrieval System) library.

It provides an interface to parse the traditional resolv.conf

file and more advanced, DNS-specific configuration file for

the rest of this package (see the description for the

dns.conf file below).</para>

</listitem>

<listitem>

<para>As part of the IRS library, newly implemented standard

address-name mapping functions, getaddrinfo() and

getnameinfo(), are provided. They use the DNSSEC-aware

validating resolver backend, and could use other advanced

features of the BIND 9 libraries such as caching. The

getaddrinfo() function resolves both A and AAAA RRs

concurrently (when the address family is unspecified).</para>

</listitem>

<listitem>

<para>An experimental framework to support other event

libraries than BIND 9's internal event task system.</para>

</listitem>

</itemizedlist>

<section><info><title>Prerequisite</title></info>

<para>GNU make is required to build the export libraries (other

part of BIND 9 can still be built with other types of make). In

the reminder of this document, "make" means GNU make. Note that

in some platforms you may need to invoke a different command name

than "make" (e.g. "gmake") to indicate it's GNU make.</para>

</section>

<section><info><title>Compilation</title></info>

<screen>

$ <userinput>/configure --enable-exportlib <replaceable>[other flags]</replaceable></userinput>

$ <userinput>make</userinput>

</screen>

<para>

This will create (in addition to usual BIND 9 programs) and a

separate set of libraries under the lib/export directory. For

example, <filename>lib/export/dns/libdns.a</filename> is the archive file of the

export version of the BIND 9 DNS library. Sample application

programs using the libraries will also be built under the

lib/export/samples directory (see below).</para>

</section>

<section><info><title>Installation</title></info>

<screen>

$ <userinput>cd lib/export</userinput>

$ <userinput>make install</userinput>

</screen>

<para>

This will install library object files under the directory

specified by the --with-export-libdir configure option (default:

EPREFIX/lib/bind9), and header files under the directory

specified by the --with-export-includedir configure option

(default: PREFIX/include/bind9).

Root privilege is normally required.

"<command>make install</command>" at the top directory will do the

same.

</para>

<para>

To see how to build your own

application after the installation, see

<filename>lib/export/samples/Makefile-postinstall.in</filename>.</para>

</section>

<section><info><title>Known Defects/Restrictions</title></info>

<itemizedlist>

<listitem>

<para>Currently, win32 is not supported for the export

library. (Normal BIND 9 application can be built as

before).</para>

</listitem>

<listitem>

<para>The "fixed" RRset order is not (currently) supported in

the export library. If you want to use "fixed" RRset order

for, e.g. <command>named</command> while still building the

export library even without the fixed order support, build

them separately:

<screen>

$ <userinput>/configure --enable-fixed-rrset <replaceable>[other flags, but not --enable-exportlib]</replaceable></userinput>

$ <userinput>make</userinput>

$ <userinput>/configure --enable-exportlib <replaceable>[other flags, but not --enable-fixed-rrset]</replaceable></userinput>

$ <userinput>cd lib/export</userinput>

$ <userinput>make</userinput>

</screen>

</para>

</listitem>

<listitem>

<para>The client module and the IRS library currently do not

support DNSSEC validation using DLV (the underlying modules

can handle it, but there is no tunable interface to enable

the feature).</para>

</listitem>

<listitem>

<para>RFC 5011 is not supported in the validating stub

resolver of the export library. In fact, it is not clear

whether it should: trust anchors would be a system-wide

configuration which would be managed by an administrator,

while the stub resolver will be used by ordinary applications

run by a normal user.</para>

</listitem>

<listitem>

<para>Not all common <filename>/etc/resolv.conf</filename>

options are supported

in the IRS library. The only available options in this

version are "debug" and "ndots".</para>

</listitem>

</itemizedlist>

</section>

<section><info><title>The dns.conf File</title></info>

<para>The IRS library supports an "advanced" configuration file

related to the DNS library for configuration parameters that

would be beyond the capability of the

<filename>resolv.conf</filename> file.

Specifically, it is intended to provide DNSSEC related

configuration parameters. By default the path to this

configuration file is <filename>/etc/dns.conf</filename>.

This module is very

experimental and the configuration syntax or library interfaces

may change in future versions. Currently, only the

<command>trusted-keys</command>

statement is supported, whose syntax is the same as the same name

of statement for <filename>named.conf</filename>. (See

<xref linkend="trusted-keys"/> for details.)</para>

</section>

<section><info><title>Sample Applications</title></info>

<para>Some sample application programs using this API are

provided for reference. The following is a brief description of

these applications.

</para>

<section><info><title>sample: a simple stub resolver utility</title></info>

<para>

It sends a query of a given name (of a given optional RR type) to a

specified recursive server, and prints the result as a list of

RRs. It can also act as a validating stub resolver if a trust

anchor is given via a set of command line options.</para>

<para>

Usage: sample [options] server_address hostname

</para>

<para>

Options and Arguments:

</para>

<variablelist>

<varlistentry>

<term>

-t RRtype

</term>

<listitem><para>

specify the RR type of the query. The default is the A RR.

</para></listitem>

</varlistentry>

<varlistentry>

<term>

[-a algorithm] [-e] -k keyname -K keystring

</term>

<listitem><para>

specify a command-line DNS key to validate the answer. For

example, to specify the following DNSKEY of example.com:

<literallayout>

example.com. 3600 IN DNSKEY 257 3 5 xxx

</literallayout>

specify the options as follows:

<screen>

<userinput>

-e -k example.com -K "xxx"

</userinput>

</screen>

-e means that this key is a zone's "key signing key" (as known

as "secure Entry point").

When -a is omitted rsasha1 will be used by default.

</para></listitem>

</varlistentry>

<varlistentry>

<term>

-s domain:alt_server_address

</term>

<listitem><para>

specify a separate recursive server address for the specific

"domain". Example: -s example.com:2001:db8::1234

</para></listitem>

</varlistentry>

<varlistentry>

<term>server_address</term>

<listitem><para>

an IP(v4/v6) address of the recursive server to which queries

are sent.

</para></listitem>

</varlistentry>

<varlistentry>

<term>hostname</term>

<listitem><para>

the domain name for the query

</para></listitem>

</varlistentry>

</variablelist>

</section>

<section><info><title>sample-async: a simple stub resolver, working asynchronously</title></info>

<para>

Similar to "sample", but accepts a list

of (query) domain names as a separate file and resolves the names

asynchronously.</para>

<para>

Usage: sample-async [-s server_address] [-t RR_type] input_file</para>

<para>

Options and Arguments:

</para>

<variablelist>

<varlistentry>

<term>

-s server_address

</term>

<listitem>

an IPv4 address of the recursive server to which queries are sent.

(IPv6 addresses are not supported in this implementation)

</listitem>

</varlistentry>

<varlistentry>

<term>

-t RR_type

</term>

<listitem>

specify the RR type of the queries. The default is the A

RR.

</listitem>

</varlistentry>

<varlistentry>

<term>

input_file

</term>

<listitem>

a list of domain names to be resolved. each line

consists of a single domain name. Example:

<literallayout>

www.example.com

mx.example.net

ns.xxx.example

</literallayout>

</listitem>

</varlistentry>

</variablelist>

</section>

<section><info><title>sample-request: a simple DNS transaction client</title></info>

<para>

It sends a query to a specified server, and

prints the response with minimal processing. It doesn't act as a

"stub resolver": it stops the processing once it gets any

response from the server, whether it's a referral or an alias

(CNAME or DNAME) that would require further queries to get the

ultimate answer. In other words, this utility acts as a very

simplified <command>dig</command>.

</para>

<para>

Usage: sample-request [-t RRtype] server_address hostname

</para>

<para>

Options and Arguments:

</para>

<variablelist>

<varlistentry>

<term>

-t RRtype

</term>

<listitem>

<para>

specify the RR type of

the queries. The default is the A RR.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

server_address

</term>

<listitem>

<para>

an IP(v4/v6)

address of the recursive server to which the query is sent.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

hostname

</term>

<listitem>

<para>

the domain name for the query

</para>

</listitem>

</varlistentry>

</variablelist>

</section>

<section><info><title>sample-gai: getaddrinfo() and getnameinfo() test code</title></info>

<para>

This is a test program

to check getaddrinfo() and getnameinfo() behavior. It takes a

host name as an argument, calls getaddrinfo() with the given host

name, and calls getnameinfo() with the resulting IP addresses

returned by getaddrinfo(). If the dns.conf file exists and

defines a trust anchor, the underlying resolver will act as a

validating resolver, and getaddrinfo()/getnameinfo() will fail

with an EAI_INSECUREDATA error when DNSSEC validation fails.

</para>

<para>

Usage: sample-gai hostname

</para>

</section>

<section><info><title>sample-update: a simple dynamic update client program</title></info>

<para>

It accepts a single update command as a

command-line argument, sends an update request message to the

authoritative server, and shows the response from the server. In

other words, this is a simplified <command>nsupdate</command>.

</para>

<para>

Usage: sample-update [options] (add|delete) "update data"

</para>

<para>

Options and Arguments:

</para>

<variablelist>

<varlistentry>

<term>

-a auth_server

</term>

<listitem><para>

An IP address of the authoritative server that has authority

for the zone containing the update name. This should normally

be the primary authoritative server that accepts dynamic

updates. It can also be a secondary server that is configured

to forward update requests to the primary server.

</para></listitem>

</varlistentry>

<varlistentry>

<term>

-k keyfile

</term>

<listitem><para>

A TSIG key file to secure the update transaction. The keyfile

format is the same as that for the nsupdate utility.

</para></listitem>

</varlistentry>

<varlistentry>

<term>

-p prerequisite

</term>

<listitem><para>

A prerequisite for the update (only one prerequisite can be

specified). The prerequisite format is the same as that is

accepted by the nsupdate utility.

</para></listitem>

</varlistentry>

<varlistentry>

<term>

-r recursive_server

</term>

<listitem><para>

An IP address of a recursive server that this utility will

use. A recursive server may be necessary to identify the

authoritative server address to which the update request is

sent.

</para></listitem>

</varlistentry>

<varlistentry>

<term>

-z zonename

</term>

<listitem><para>

The domain name of the zone that contains

</para></listitem>

</varlistentry>

<varlistentry>

<term>

(add|delete)

</term>

<listitem><para>

Specify the type of update operation. Either "add" or "delete"

must be specified.

</para></listitem>

</varlistentry>

<varlistentry>

<term>

"update data"

</term>

<listitem><para>

Specify the data to be updated. A typical example of the data

would look like "name TTL RRtype RDATA".

</para></listitem>

</varlistentry>

</variablelist>

<note>In practice, either -a or -r must be specified. Others can

be optional; the underlying library routine tries to identify the

appropriate server and the zone name for the update.</note>

<para>

Examples: assuming the primary authoritative server of the

dynamic.example.com zone has an IPv6 address 2001:db8::1234,

</para>

<screen>

$ <userinput>sample-update -a sample-update -k Kxxx.+nnn+mmmm.key add "foo.dynamic.example.com 30 IN A 192.168.2.1"</userinput></screen>

<para>

adds an A RR for foo.dynamic.example.com using the given key.

</para>

<screen>

$ <userinput>sample-update -a sample-update -k Kxxx.+nnn+mmmm.key delete "foo.dynamic.example.com 30 IN A"</userinput></screen>

<para>

removes all A RRs for foo.dynamic.example.com using the given key.

</para>

<screen>

$ <userinput>sample-update -a sample-update -k Kxxx.+nnn+mmmm.key delete "foo.dynamic.example.com"</userinput></screen>

<para>

removes all RRs for foo.dynamic.example.com using the given key.

</para>

</section>

<section><info><title>nsprobe: domain/name server checker in terms of RFC 4074</title></info>

<para>

It checks a set

of domains to see the name servers of the domains behave

correctly in terms of RFC 4074. This is included in the set of

sample programs to show how the export library can be used in a

DNS-related application.

</para>

<para>

Usage: nsprobe [-d] [-v [-v...]] [-c cache_address] [input_file]

</para>

<para>

Options

</para>

<variablelist>

<varlistentry>

<term>

-d

</term>

<listitem><para>

run in the "debug" mode. with this option nsprobe will dump

every RRs it receives.

</para></listitem>

</varlistentry>

<varlistentry>

<term>

-v

</term>

<listitem><para>

increase verbosity of other normal log messages. This can be

specified multiple times

</para></listitem>

</varlistentry>

<varlistentry>

<term>

-c cache_address

</term>

<listitem><para>

specify an IP address of a recursive (caching) name server.

nsprobe uses this server to get the NS RRset of each domain and

the A and/or AAAA RRsets for the name servers. The default

value is 127.0.0.1.

</para></listitem>

</varlistentry>

<varlistentry>

<term>

input_file

</term>

<listitem><para>

a file name containing a list of domain (zone) names to be

probed. when omitted the standard input will be used. Each

line of the input file specifies a single domain name such as

"example.com". In general this domain name must be the apex

name of some DNS zone (unlike normal "host names" such as

"www.example.com"). nsprobe first identifies the NS RRsets for

the given domain name, and sends A and AAAA queries to these

servers for some "widely used" names under the zone;

specifically, adding "www" and "ftp" to the zone name.

</para></listitem>

</varlistentry>

</variablelist>

</section>

</section>

<section><info><title>Library References</title></info>

<para>As of this writing, there is no formal "manual" of the

libraries, except this document, header files (some of them

provide pretty detailed explanations), and sample application

programs.</para>

</section>

</section>