/contrib/bind9/doc/arm/libdns.xml
https://bitbucket.org/freebsd/freebsd-head/ · XML · 530 lines · 509 code · 4 blank · 17 comment · 0 complexity · b4ed988a7812a60cd1dcd319a38b8a9d MD5 · raw file
- <?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 $ -->