mirror of
https://github.com/isc-projects/bind9.git
synced 2026-02-12 23:33:11 -05:00
275 lines
12 KiB
Text
275 lines
12 KiB
Text
|
|
BIND-9 DNS Library Support
|
|
|
|
This version of BIND9 "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 BIND9 is currently using, the export libraries
|
|
provide the following features:
|
|
|
|
- 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.
|
|
- 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).
|
|
- 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 BIND9 libraries such as caching. The
|
|
getaddrinfo() function resolves both A and AAAA RRs concurrently
|
|
(when the address family is unspecified).
|
|
- An experimental framework to support other event libraries than
|
|
BIND9's internal event task system.
|
|
|
|
* Prerequisite
|
|
|
|
GNU make is required to build the export libraries (other part of
|
|
BIND9 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.
|
|
|
|
* Compilation
|
|
|
|
1. ./configure --enable-exportlib [other flags]
|
|
2. make
|
|
|
|
This will create (in addition to usual BIND9 programs) and a separate
|
|
set of libraries under the lib/export directory. For example,
|
|
lib/export/dns/libdns.a is the archive file of the export version of
|
|
the BIND9 DNS library.
|
|
|
|
Sample application programs using the libraries will also be built
|
|
under the lib/export/samples directory (see below).
|
|
|
|
* Installation
|
|
|
|
1. cd lib/export
|
|
2. make install (root privilege is normally required)
|
|
(make install at the top directory will do the same)
|
|
|
|
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).
|
|
|
|
To see how to build your own application after the installation, see
|
|
lib/export/samples/Makefile-postinstall.in
|
|
|
|
* Known Defects/Restrictions
|
|
|
|
- Currently, win32 is not supported for the export library. (Normal
|
|
BIND9 application can be built as before).
|
|
- The "fixed" RRset order is not (currently) supported in the export
|
|
library. If you want to use "fixed" RRset order for, e.g. named
|
|
while still building the export library even without the fixed
|
|
order support, build them separately:
|
|
% ./configure --enable-fixed-rrset [other flags, but not --enable-exportlib]
|
|
% make (this doesn't have to be make)
|
|
% ./configure --enable-exportlib [other flags, but not --enable-fixed-rrset]
|
|
% cd lib/export
|
|
% make
|
|
- 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).
|
|
- RFC5011 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.
|
|
- Not all common /etc/resolv.conf options are supported in the IRS library.
|
|
The only available options in this version are "debug" and "ndots".
|
|
|
|
* The dns.conf File
|
|
|
|
The IRS library supports an "advanced" configuration file related to
|
|
the DNS library for configuration parameters that would be beyond the
|
|
capability of the resolv.conf file. Specifically, it is intended to
|
|
provide DNSSEC related configuration parameters.
|
|
|
|
By default the path to this configuration file is /etc/dns.conf.
|
|
|
|
This module is very experimental and the configuration syntax or
|
|
library interfaces may change in future versions. Currently, only the
|
|
'trusted-keys' statement is supported, whose syntax is the same as the
|
|
same name of statement for named.conf.
|
|
|
|
* Sample Applications
|
|
|
|
Some sample application programs using this API are provided for
|
|
reference. The following is a brief description of these
|
|
applications.
|
|
|
|
- sample: a simple stub resolver utility.
|
|
|
|
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.
|
|
|
|
Usage: sample [options] server_address hostname
|
|
|
|
Options and Arguments:
|
|
-t RRtype
|
|
specify the RR type of the query. The default is the A RR.
|
|
[-a algorithm] [-e] -k keyname -K keystring
|
|
specify a command-line DNS key to validate the answer. For
|
|
example, to specify the following DNSKEY of example.com:
|
|
example.com. 3600 IN DNSKEY 257 3 5 xxx
|
|
specify the options as follows:
|
|
-e -k example.com -K "xxx"
|
|
-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.
|
|
-s domain:alt_server_address
|
|
specify a separate recursive server address for the specific
|
|
"domain". Example: -s example.com:2001:db8::1234
|
|
server_address
|
|
an IP(v4/v6) address of the recursive server to which queries
|
|
are sent.
|
|
hostname
|
|
the domain name for the query
|
|
|
|
- sample-async: a simple stub resolver, working asynchronously.
|
|
|
|
Similar to "sample", but accepts a list of (query) domain names as a
|
|
separate file and resolves the names asynchronously.
|
|
|
|
Usage: sample-async [-s server_address] [-t RR_type] input_file
|
|
Options and Arguments:
|
|
-s server_address
|
|
an IPv4 address of the recursive server to which queries are
|
|
sent. (IPv6 addresses are not supported in this implementation)
|
|
-t RR_type
|
|
specify the RR type of the queries. The default is the A RR.
|
|
input_file
|
|
a list of domain names to be resolved. each line consists of a
|
|
single domain name. Example:
|
|
www.example.com
|
|
mx.examle.net
|
|
ns.xxx.example
|
|
|
|
- sample-request: a simple DNS transaction client.
|
|
|
|
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 dig.
|
|
|
|
Usage: sample-request [-t RRtype] server_address hostname
|
|
Options and Arguments:
|
|
-t RRtype
|
|
specify the RR type of the queries. The default is the A RR.
|
|
server_address
|
|
an IP(v4/v6) address of the recursive server to which the query is
|
|
sent.
|
|
hostname
|
|
the domain name for the query
|
|
|
|
- sample-gai: getaddrinfo() and getnameinfo() test code.
|
|
|
|
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.
|
|
|
|
Usage: sample-gai hostname
|
|
|
|
- sample-update: a simple dynamic update client program
|
|
|
|
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
|
|
nsupdate.
|
|
|
|
Usage: sample-update [options] (add|delete) "update data"
|
|
Options and Arguments:
|
|
-a auth_server
|
|
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.
|
|
-k keyfile
|
|
A TSIG key file to secure the update transaction. The keyfile
|
|
format is the same as that for the nsupdate utility.
|
|
-p prerequisite
|
|
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.
|
|
-r recursive_server
|
|
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.
|
|
-z zonename
|
|
The domain name of the zone that contains
|
|
(add|delete)
|
|
Specify the type of update operation. Either "add" or "delete"
|
|
must be specified.
|
|
"update data"
|
|
Specify the data to be updated. A typical example of the data
|
|
would look like "name TTL RRtype RDATA".
|
|
|
|
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.
|
|
|
|
Examples: assuming the primary authoritative server of the
|
|
dynamic.example.com zone has an IPv6 address 2001:db8::1234,
|
|
+ sample-update -a sample-update -k Kxxx.+nnn+mmmm.key add "foo.dynamic.example.com 30 IN A 192.168.2.1"
|
|
adds an A RR for foo.dynamic.example.com using the given key.
|
|
+ sample-update -a sample-update -k Kxxx.+nnn+mmmm.key delete "foo.dynamic.example.com 30 IN A"
|
|
removes all A RRs for foo.dynamic.example.com using the given key.
|
|
+ sample-update -a sample-update -k Kxxx.+nnn+mmmm.key delete "foo.dynamic.example.com"
|
|
removes all RRs for foo.dynamic.example.com using the given key.
|
|
|
|
- nsprobe: domain/name server checker in terms of RFC4074.
|
|
|
|
It checks a set of domains to see the name servers of the domains
|
|
behave correctly in terms of RFC4074. This is included in the set
|
|
of sample programs to show how the export library can be used in a
|
|
DNS-related application.
|
|
|
|
Usage: nsprobe [-d] [-v [-v...]] [-c cache_address] [input_file]
|
|
Options
|
|
-d
|
|
run in the "debug" mode. with this option nsprobe will dump
|
|
every RRs it receives.
|
|
-v
|
|
increase verbosity of other normal log messages. This can be
|
|
specified multiple times
|
|
-c cache_address
|
|
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.
|
|
input_file
|
|
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.
|
|
|
|
* Library References
|
|
|
|
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.
|
|
|
|
; $Id: README.libdns,v 1.3 2009/09/15 19:12:03 jinmei Exp $
|