diff --git a/doc/arm/Makefile.am b/doc/arm/Makefile.am index 67e7057c95..f20239ea66 100644 --- a/doc/arm/Makefile.am +++ b/doc/arm/Makefile.am @@ -21,7 +21,6 @@ EXTRA_DIST = \ index.rst \ introduction.rst \ key.grammar.rst \ - libdns.rst \ logging-categories.rst \ logging.grammar.rst \ managed-keys.grammar.rst \ diff --git a/doc/arm/index.rst b/doc/arm/index.rst index 1e2aacab83..d608d73968 100644 --- a/doc/arm/index.rst +++ b/doc/arm/index.rst @@ -32,6 +32,5 @@ BIND 9 Administrator Reference Manual notes history general - libdns manpages diff --git a/doc/arm/libdns.rst b/doc/arm/libdns.rst deleted file mode 100644 index 6862d35d51..0000000000 --- a/doc/arm/libdns.rst +++ /dev/null @@ -1,329 +0,0 @@ -.. - Copyright (C) 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/. - - See the COPYRIGHT file distributed with this work for additional - information regarding copyright ownership. - -.. - Copyright (C) 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/. - - See the COPYRIGHT file distributed with this work for additional - information regarding copyright ownership. - -.. _bind9.library: - -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 :ref:`trusted-keys` 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. diff --git a/util/copyrights b/util/copyrights index cc34a7a4ea..70cf2e35fd 100644 --- a/util/copyrights +++ b/util/copyrights @@ -1124,7 +1124,6 @@ ./doc/arm/index.rst RST 2020 ./doc/arm/introduction.rst RST 2020 ./doc/arm/isc-logo.pdf X 2005,2010,2018,2019,2020 -./doc/arm/libdns.rst RST 2020 ./doc/arm/logging-categories.rst RST 2020 ./doc/arm/managed-keys.rst RST 2020 ./doc/arm/manpages.rst RST 2020