diff options
Diffstat (limited to 'doc/arm/Bv9ARM.ch12.html')
| -rw-r--r-- | doc/arm/Bv9ARM.ch12.html | 538 |
1 files changed, 538 insertions, 0 deletions
diff --git a/doc/arm/Bv9ARM.ch12.html b/doc/arm/Bv9ARM.ch12.html new file mode 100644 index 0000000..a527131 --- /dev/null +++ b/doc/arm/Bv9ARM.ch12.html @@ -0,0 +1,538 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 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/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Appendix D. BIND 9 DNS Library Support</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="prev" href="Bv9ARM.ch11.html" title="Appendix C. General DNS Reference Information"> +<link rel="next" href="Bv9ARM.ch13.html" title="Manual pages"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center">Appendix D. BIND 9 DNS Library Support</th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="Bv9ARM.ch11.html">Prev</a> </td> +<th width="60%" align="center"> </th> +<td width="20%" align="right"> <a accesskey="n" href="Bv9ARM.ch13.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="appendix"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="Bv9ARM.ch12"></a>BIND 9 DNS Library Support</h1></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="Bv9ARM.ch12.html#bind9.library">BIND 9 DNS Library Support</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.5">Installation</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.6">Known Defects/Restrictions</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.7">The dns.conf File</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.8">Sample Applications</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.9">Library References</a></span></dt> +</dl></dd> +</dl> +</div> + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="bind9.library"></a>BIND 9 DNS Library Support</h2></div></div></div> + + <p> + 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 + <span class="command"><strong>isc_lib_register()</strong></span>. + </p> + <p> + In addition to DNS-related APIs that are used within BIND 9, the + libraries provide the following features: + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <p> + 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. + </p> + </li> +<li class="listitem"> + <p> + The "IRS" (Information Retrieval System) library. It provides an + interface to parse the traditional <code class="filename">resolv.conf</code> + file and more advanced, DNS-specific configuration file for the + rest of this package (see the description for the + <code class="filename">dns.conf</code> file below). + </p> + </li> +<li class="listitem"> + <p> + As part of the IRS library, the standard address-name + mapping functions, <span class="command"><strong>getaddrinfo()</strong></span> and + <span class="command"><strong>getnameinfo()</strong></span>, 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 + <span class="command"><strong>getaddrinfo()</strong></span> function resolves both A + and AAAA RRs concurrently when the address family is + unspecified. + </p> + </li> +<li class="listitem"> + <p> + An experimental framework to support other event + libraries than BIND 9's internal event task system. + </p> + </li> +</ul></div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.13.2.5"></a>Installation</h3></div></div></div> + + <pre class="screen"> +$ <strong class="userinput"><code>make install</code></strong> + </pre> + <p> + Normal installation of BIND will also install library object + and header files. Root privilege is normally required. + </p> + <p> + To see how to build your own application after the installation, see + <code class="filename">lib/samples/Makefile-postinstall.in</code>. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.13.2.6"></a>Known Defects/Restrictions</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <p> + The "fixed" RRset order is not (currently) supported in the export + library. If you want to use "fixed" RRset order for, e.g. + <span class="command"><strong>named</strong></span> while still building the export library + even without the fixed order support, build them separately: + </p> +<pre class="screen"> +$ <strong class="userinput"><code>./configure --enable-fixed-rrset <em class="replaceable"><code>[other flags, but not --enable-exportlib]</code></em></code></strong> +$ <strong class="userinput"><code>make</code></strong> +$ <strong class="userinput"><code>./configure --enable-exportlib <em class="replaceable"><code>[other flags, but not --enable-fixed-rrset]</code></em></code></strong> +$ <strong class="userinput"><code>cd lib/export</code></strong> +$ <strong class="userinput"><code>make</code></strong> +</pre> +<p> + </p> + </li> +<li class="listitem"> + <p> + 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. + </p> + </li> +<li class="listitem"> + <p> + Not all common <code class="filename">/etc/resolv.conf</code> options are + supported in the IRS library. The only available options in this + version are <span class="command"><strong>debug</strong></span> and <span class="command"><strong>ndots</strong></span>. + </p> + </li> +</ul></div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.13.2.7"></a>The dns.conf File</h3></div></div></div> + + <p> + The IRS library supports an "advanced" configuration file related to + the DNS library for configuration parameters that would be beyond the + capability of the <code class="filename">resolv.conf</code> file. + Specifically, it is intended to provide DNSSEC related configuration + parameters. By default the path to this configuration file is + <code class="filename">/etc/dns.conf</code>. This module is very experimental + and the configuration syntax or library interfaces may change in + future versions. Currently, only the <span class="command"><strong>trusted-keys</strong></span> + statement is supported, whose syntax is the same as the same + statement in <code class="filename">named.conf</code>. (See + <a class="xref" href="Bv9ARM.ch06.html#trusted-keys" title="trusted-keys Statement Grammar">the section called “<span class="command"><strong>trusted-keys</strong></span> Statement Grammar”</a> for details.) + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.13.2.8"></a>Sample Applications</h3></div></div></div> + + <p> + Some sample application programs using this API are provided for + reference. The following is a brief description of these + applications. + </p> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.13.2.8.3"></a>sample: a simple stub resolver utility</h4></div></div></div> + + <p> + 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. + </p> + <p> + Usage: sample [options] server_address hostname + </p> + <p> + Options and Arguments: + </p> + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-t RRtype</span></dt> +<dd> + <p> + specify the RR type of the query. The default is the A RR. + </p> + </dd> +<dt><span class="term">[-a algorithm] [-e] -k keyname -K keystring</span></dt> +<dd> + <p> + specify a command-line DNS key to validate the answer. For + example, to specify the following DNSKEY of example.com: + </p> +<div class="literallayout"><p><br> + example.com. 3600 IN DNSKEY 257 3 5 xxx<br> + </p></div> +<p> + specify the options as follows: + </p> +<pre class="screen"> +<strong class="userinput"><code>-e -k example.com -K "xxx"</code></strong> + </pre> +<p> + -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. + </p> + </dd> +<dt><span class="term">-s domain:alt_server_address</span></dt> +<dd> + <p> + specify a separate recursive server address for the specific + "domain". Example: -s example.com:2001:db8::1234 + </p> + </dd> +<dt><span class="term">server_address</span></dt> +<dd> + <p> + an IP(v4/v6) address of the recursive server to which queries + are sent. + </p> + </dd> +<dt><span class="term">hostname</span></dt> +<dd> + <p> + the domain name for the query + </p> + </dd> +</dl></div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.13.2.8.4"></a>sample-async: a simple stub resolver, working asynchronously</h4></div></div></div> + + <p> + Similar to "sample", but accepts a list + of (query) domain names as a separate file and resolves the names + asynchronously.</p> + <p> + Usage: sample-async [-s server_address] [-t RR_type] input_file</p> + <p> + Options and Arguments: + </p> + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-s server_address</span></dt> +<dd> + an IPv4 address of the recursive server to which queries are sent. + (IPv6 addresses are not supported in this implementation) + </dd> +<dt><span class="term">-t RR_type</span></dt> +<dd> + specify the RR type of the queries. The default is the A + RR. + </dd> +<dt><span class="term">input_file</span></dt> +<dd> + a list of domain names to be resolved. each line consists of a + single domain name. Example: + <div class="literallayout"><p><br> + www.example.com<br> + mx.example.net<br> + ns.xxx.example<br> + </p></div> + </dd> +</dl></div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.13.2.8.5"></a>sample-request: a simple DNS transaction client</h4></div></div></div> + + <p> + 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 <span class="command"><strong>dig</strong></span>. + </p> + <p> + Usage: sample-request [-t RRtype] server_address hostname + </p> + <p> + Options and Arguments: + </p> + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-t RRtype</span></dt> +<dd> + <p> + specify the RR type of the queries. The default is the A RR. + </p> + </dd> +<dt><span class="term">server_address</span></dt> +<dd> + <p> + an IP(v4/v6) address of the recursive server to which + the query is sent. + </p> + </dd> +<dt><span class="term">hostname</span></dt> +<dd> + <p> + the domain name for the query + </p> + </dd> +</dl></div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.13.2.8.6"></a>sample-gai: getaddrinfo() and getnameinfo() test code</h4></div></div></div> + + <p> + This is a test program to check <span class="command"><strong>getaddrinfo()</strong></span> and + <span class="command"><strong>getnameinfo()</strong></span> behavior. It takes a host name as an + argument, calls <span class="command"><strong>getaddrinfo()</strong></span> with the given host + name, and calls <span class="command"><strong>getnameinfo()</strong></span> with the resulting + IP addresses returned by <span class="command"><strong>getaddrinfo()</strong></span>. If the + dns.conf file exists and defines a trust anchor, the underlying + resolver will act as a validating resolver, and + <span class="command"><strong>getaddrinfo()</strong></span>/<span class="command"><strong>getnameinfo()</strong></span> + will fail with an EAI_INSECUREDATA error when DNSSEC validation + fails. + </p> + <p> + Usage: sample-gai hostname + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.13.2.8.7"></a>sample-update: a simple dynamic update client program</h4></div></div></div> + + <p> + 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 + <span class="command"><strong>nsupdate</strong></span>. + </p> + <p> + Usage: sample-update [options] (add|delete) "update data" + </p> + <p> + Options and Arguments: + </p> + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-a auth_server</span></dt> +<dd> + <p> + 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. + </p> + </dd> +<dt><span class="term">-k keyfile</span></dt> +<dd> + <p> + A TSIG key file to secure the update transaction. The + keyfile format is the same as that for the nsupdate utility. + </p> + </dd> +<dt><span class="term">-p prerequisite</span></dt> +<dd> + <p> + 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. + </p> + </dd> +<dt><span class="term">-r recursive_server</span></dt> +<dd> + <p> + 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. + </p> + </dd> +<dt><span class="term">-z zonename</span></dt> +<dd> + <p> + The domain name of the zone that contains + </p> + </dd> +<dt><span class="term">(add|delete)</span></dt> +<dd> + <p> + Specify the type of update operation. Either "add" or + "delete" must be specified. + </p> + </dd> +<dt><span class="term">"update data"</span></dt> +<dd> + <p> + Specify the data to be updated. A typical example of the + data would look like "name TTL RRtype RDATA". + </p> + </dd> +</dl></div> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + 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. + </p> + </div> + <p> + Examples: assuming the primary authoritative server of the + dynamic.example.com zone has an IPv6 address 2001:db8::1234, + </p> + <pre class="screen"> +$ <strong class="userinput"><code>sample-update -a sample-update -k Kxxx.+nnn+mmmm.key add "foo.dynamic.example.com 30 IN A 192.168.2.1"</code></strong></pre> + <p> + adds an A RR for foo.dynamic.example.com using the given key. + </p> + <pre class="screen"> +$ <strong class="userinput"><code>sample-update -a sample-update -k Kxxx.+nnn+mmmm.key delete "foo.dynamic.example.com 30 IN A"</code></strong></pre> + <p> + removes all A RRs for foo.dynamic.example.com using the given key. + </p> + <pre class="screen"> +$ <strong class="userinput"><code>sample-update -a sample-update -k Kxxx.+nnn+mmmm.key delete "foo.dynamic.example.com"</code></strong></pre> + <p> + removes all RRs for foo.dynamic.example.com using the given key. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.13.2.8.8"></a>nsprobe: domain/name server checker in terms of RFC 4074</h4></div></div></div> + + <p> + 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. + </p> + <p> + Usage: nsprobe [-d] [-v [-v...]] [-c cache_address] [input_file] + </p> + <p> + Options + </p> + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term">-d</span></dt> +<dd> + <p> + Run in "debug" mode. With this option nsprobe will dump + every RRs it receives. + </p> + </dd> +<dt><span class="term">-v</span></dt> +<dd> + <p> + Increase verbosity of other normal log messages. This can be + specified multiple times. + </p> + </dd> +<dt><span class="term">-c cache_address</span></dt> +<dd> + <p> + 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. + </p> + </dd> +<dt><span class="term">input_file</span></dt> +<dd> + <p> + 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. + </p> + </dd> +</dl></div> + </div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id-1.13.2.9"></a>Library References</h3></div></div></div> + + <p> + 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. + </p> + </div> +</div> + </div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="Bv9ARM.ch11.html">Prev</a> </td> +<td width="20%" align="center"> </td> +<td width="40%" align="right"> <a accesskey="n" href="Bv9ARM.ch13.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top">Appendix C. General <acronym class="acronym">DNS</acronym> Reference Information </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> Manual pages</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> |