Appendix D. BIND 9 DNS Library Support
+Prev		Next +

+BIND 9 DNS Library Support

Table of Contents

Installation
Known Defects/Restrictions
The dns.conf File
Sample Applications
Library References

+BIND 9 DNS Library Support

+ +

+ 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 + isc_lib_register(). +

+ In addition to DNS-related APIs that are used within BIND 9, the + libraries provide the following features: +

+
+ 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. +
+
+
+ The "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, the 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. +
+
+
+ An experimental framework to support other event + libraries than BIND 9's internal event task system. +
+

+Installation

+ +

+$ make install
+

+ Normal installation of BIND will also install library object + and header files. Root privilege is normally required. +

+ To see how to build your own application after the installation, see + lib/samples/Makefile-postinstall.in. +

+Known Defects/Restrictions

+ +

+
+ 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
+$ ./configure --enable-exportlib [other flags, but not --enable-fixed-rrset]
+$ cd lib/export
+$ make
+
```
+
+
+
+
+ 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. +
+
+
+ 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 + statement in named.conf. (See + the section called “trusted-keys Statement Grammar” for details.) +

+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

+ +

+ 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" (also 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.example.net
+      ns.xxx.example
+
+

+sample-request: a simple DNS transaction client

+ +

+ 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

+ +

+ 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 RFC 4074

+ +

+ 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. +

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

+ Options +

-d: +
+ Run in "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" for the libraries, + except this document, header files (some of which provide pretty + detailed explanations), and sample application programs. +

+Prev		Next +
Appendix C. General DNS Reference Information	Home	Manual pages