diff --git a/CHANGES b/CHANGES index 1de0e4bcb8..ea32648a76 100644 --- a/CHANGES +++ b/CHANGES @@ -1,3 +1,6 @@ +4791. [doc] Fixed outdated documentation about export libraries. + [RT #46341] + 4790. [bug] nsupdate could trigger a require when sending a update to the second address of the server. [RT #45731] diff --git a/doc/arm/libdns.xml b/doc/arm/libdns.xml index fc940a6a2b..9bc8e96b48 100644 --- a/doc/arm/libdns.xml +++ b/doc/arm/libdns.xml @@ -7,101 +7,89 @@ --> -
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). In addition to - all major DNS-related APIs BIND 9 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 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. - - -
Prerequisite - - 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. -
-
Compilation - - -$ ./configure --enable-exportlib [other flags] -$ make - +
+ + BIND 9 DNS Library Support + - This will create (in addition to usual BIND 9 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 BIND 9 DNS library. Sample application - programs using the libraries will also be built under the - lib/export/samples directory (see below). -
-
Installation - - -$ cd lib/export -$ make install - - - 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. - "make install" at the top directory will do the - same. + 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(). - To see how to build your own - application after the installation, see - lib/export/samples/Makefile-postinstall.in. -
-
Known Defects/Restrictions - + In addition to DNS-related APIs that are used within BIND 9, the + libraries provide the following features: + - - Currently, win32 is not supported for the export - library. (Normal BIND 9 application can be built as - before). + + 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 "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: + + 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 @@ -109,415 +97,419 @@ $ ./configure --enable-exportlib [other flags, but not - $ 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 + for details.) - - - 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). - - - 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 name - of statement for named.conf. (See - 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 - - - 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.example.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". - - - - - - 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 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". + + + + + + + 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. - - + + 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. - - + + 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. - + + 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. + + + + +
-
nsprobe: domain/name server checker in terms of RFC 4074 - - - 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. - - - 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. +
+ + 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. +