diff options
Diffstat (limited to 'contrib/bind9/doc/arm/libdns.xml')
| -rw-r--r-- | contrib/bind9/doc/arm/libdns.xml | 530 |
1 files changed, 530 insertions, 0 deletions
diff --git a/contrib/bind9/doc/arm/libdns.xml b/contrib/bind9/doc/arm/libdns.xml new file mode 100644 index 0000000..6134ff6 --- /dev/null +++ b/contrib/bind9/doc/arm/libdns.xml @@ -0,0 +1,530 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + - Copyright (C) 2010 Internet Systems Consortium, Inc. ("ISC") + - + - Permission to use, copy, modify, and/or distribute this software for any + - purpose with or without fee is hereby granted, provided that the above + - copyright notice and this permission notice appear in all copies. + - + - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH + - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, + - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE + - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + - PERFORMANCE OF THIS SOFTWARE. +--> + +<sect1 id="bind9.library"> + <title>BIND 9 DNS Library Support</title> + <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). In addition to + all major DNS-related APIs BIND 9 is currently using, the export + libraries provide the following features:</para> + <itemizedlist> + <listitem> + <para>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.</para> + </listitem> + <listitem> + <para>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).</para> + </listitem> + <listitem> + <para>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).</para> + </listitem> + <listitem> + <para>An experimental framework to support other event + libraries than BIND 9's internal event task system.</para> + </listitem> + </itemizedlist> + <sect2> + <title>Prerequisite</title> + <para>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.</para> + </sect2> + <sect2> + <title>Compilation</title> + <screen> +$ <userinput>./configure --enable-exportlib <replaceable>[other flags]</replaceable></userinput> +$ <userinput>make</userinput> +</screen> + <para> + This will create (in addition to usual BIND 9 programs) and a + separate set of libraries under the lib/export directory. For + example, <filename>lib/export/dns/libdns.a</filename> 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).</para> + </sect2> + <sect2> + <title>Installation</title> + <screen> +$ <userinput>cd lib/export</userinput> +$ <userinput>make install</userinput> +</screen> + <para> + 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. + "<command>make install</command>" at the top directory will do the + same. + </para> + <para> + To see how to build your own + application after the installation, see + <filename>lib/export/samples/Makefile-postinstall.in</filename>.</para> + </sect2> + <sect2> + <title>Known Defects/Restrictions</title> + <itemizedlist> + <listitem> +<!-- TODO: what about AIX? --> + <para>Currently, win32 is not supported for the export + library. (Normal BIND 9 application can be built as + before).</para> + </listitem> + <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>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).</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 "debug" and "ndots".</para> + </listitem> + </itemizedlist> + </sect2> + <sect2> + <title>The dns.conf File</title> + <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 name + of statement for <filename>named.conf</filename>. (See + <xref linkend="trusted-keys" /> for details.)</para> + </sect2> + <sect2> + <title>Sample Applications</title> + <para>Some sample application programs using this API are + provided for reference. The following is a brief description of + these applications. + </para> + <sect3> + <title>sample: a simple stub resolver utility</title> + <para> + 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.</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" (as 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> + </sect3> + <sect3> + <title>sample-async: a simple stub resolver, working asynchronously</title> + <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.examle.net + ns.xxx.example +</literallayout> + </listitem> + </varlistentry> + </variablelist> + </sect3> + <sect3> + <title>sample-request: a simple DNS transaction client</title> + <para> + 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 <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> + </sect3> + <sect3> + <title>sample-gai: getaddrinfo() and getnameinfo() test code</title> + <para> + 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. + </para> + <para> + Usage: sample-gai hostname + </para> + </sect3> + <sect3> + <title>sample-update: a simple dynamic update client program</title> + <para> + 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 <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>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.</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> + </sect3> + <sect3> + <title>nsprobe: domain/name server checker in terms of RFC 4074</title> + <para> + 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. + </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 the "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> + </sect3> + </sect2> + <sect2> + <title>Library References</title> + <para>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.</para> + </sect2> +</sect1> +<!-- $Id: libdns.xml,v 1.3 2010/02/03 23:49:07 tbox Exp $ --> |
