mirror of
https://github.com/isc-projects/bind9.git
synced 2026-02-13 07:43:21 -05:00
515 lines
17 KiB
XML
515 lines
17 KiB
XML
<!--
|
|
- Copyright (C) 2010, 2014-2017 Internet Systems Consortium, Inc. ("ISC")
|
|
-
|
|
- This Source Code Form is subject to the terms of the Mozilla Public
|
|
- License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
- file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
|
-->
|
|
|
|
<!-- Converted by db4-upgrade version 1.0 -->
|
|
<section xmlns:db="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). Certain library
|
|
functions are altered from specific BIND-only behavior to more generic
|
|
behavior when used by other applications; to enable this generic behavior,
|
|
the calling program initializes the libraries by calling
|
|
<command>isc_lib_register()</command>.
|
|
</para>
|
|
<para>
|
|
In addition to DNS-related APIs that are used within BIND 9, the
|
|
libraries provide the following features:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
The "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 "IRS" (Information Retrieval System) library. It provides an
|
|
interface to parse the traditional <filename>resolv.conf</filename>
|
|
file and more advanced, DNS-specific configuration file for the
|
|
rest of this package (see the description for the
|
|
<filename>dns.conf</filename> file below).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
As part of the IRS library, the standard address-name
|
|
mapping functions, <command>getaddrinfo()</command> and
|
|
<command>getnameinfo()</command>, 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
|
|
<command>getaddrinfo()</command> 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>Installation</title>
|
|
</info>
|
|
<screen>
|
|
$ <userinput>make install</userinput>
|
|
</screen>
|
|
<para>
|
|
Normal installation of BIND will also install library object
|
|
and header files. Root privilege is normally required.
|
|
</para>
|
|
<para>
|
|
To see how to build your own application after the installation, see
|
|
<filename>lib/samples/Makefile-postinstall.in</filename>.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<info>
|
|
<title>Known Defects/Restrictions</title>
|
|
</info>
|
|
<itemizedlist>
|
|
<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>
|
|
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 <command>debug</command> and <command>ndots</command>.
|
|
</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
|
|
statement in <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>
|
|
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" (also 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>
|
|
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 <command>getaddrinfo()</command> and
|
|
<command>getnameinfo()</command> behavior. It takes a host name as an
|
|
argument, calls <command>getaddrinfo()</command> with the given host
|
|
name, and calls <command>getnameinfo()</command> with the resulting
|
|
IP addresses returned by <command>getaddrinfo()</command>. If the
|
|
dns.conf file exists and defines a trust anchor, the underlying
|
|
resolver will act as a validating resolver, and
|
|
<command>getaddrinfo()</command>/<command>getnameinfo()</command>
|
|
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>
|
|
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>
|
|
<simpara>
|
|
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.
|
|
</simpara>
|
|
</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>
|
|
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 "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" for the libraries,
|
|
except this document, header files (some of which provide pretty
|
|
detailed explanations), and sample application programs.
|
|
</para>
|
|
</section>
|
|
</section>
|