Bv9ARM.ch12.html revision fd2597f75693a2279fdf588bd40dfe2407c42028
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User - Copyright (C) 2004-2015 Internet Systems Consortium, Inc. ("ISC")
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User - Copyright (C) 2000-2003 Internet Software Consortium.
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User - Permission to use, copy, modify, and/or distribute this software for any
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User - purpose with or without fee is hereby granted, provided that the above
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User - copyright notice and this permission notice appear in all copies.
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User - PERFORMANCE OF THIS SOFTWARE.
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<title>Appendix�D.�BIND 9 DNS Library Support</title>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<link rel="prev" href="Bv9ARM.ch11.html" title="Appendix�C.�General DNS Reference Information">
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<link rel="next" href="Bv9ARM.ch13.html" title="Manual pages">
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<table width="100%" summary="Navigation header">
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<tr><th colspan="3" align="center">Appendix�D.�BIND 9 DNS Library Support</th></tr>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<a accesskey="p" href="Bv9ARM.ch11.html">Prev</a>�</td>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<td width="20%" align="right">�<a accesskey="n" href="Bv9ARM.ch13.html">Next</a>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<div class="titlepage"><div><div><h1 class="title">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<a name="Bv9ARM.ch12"></a>BIND 9 DNS Library Support</h1></div></div></div>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<dt><span class="section"><a href="Bv9ARM.ch12.html#bind9.library">BIND 9 DNS Library Support</a></span></dt>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.4">Prerequisite</a></span></dt>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.5">Compilation</a></span></dt>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.6">Installation</a></span></dt>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.7">Known Defects/Restrictions</a></span></dt>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.8">The dns.conf File</a></span></dt>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.9">Sample Applications</a></span></dt>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.10">Library References</a></span></dt>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<div class="titlepage"><div><div><h2 class="title" style="clear: both">
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<a name="bind9.library"></a>BIND 9 DNS Library Support</h2></div></div></div>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<p>This version of BIND 9 "exports" its internal libraries so
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User that they can be used by third-party applications more easily (we
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User call them "export" libraries in this document). In addition to
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User all major DNS-related APIs BIND 9 is currently using, the export
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User libraries provide the following features:</p>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<li class="listitem"><p>The newly created "DNS client" module. This is a higher
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User level API that provides an interface to name resolution,
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User single DNS transaction with a particular server, and dynamic
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User update. Regarding name resolution, it supports advanced
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User features such as DNSSEC validation and caching. This module
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User supports both synchronous and asynchronous mode.</p></li>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<li class="listitem"><p>The new "IRS" (Information Retrieval System) library.
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User It provides an interface to parse the traditional resolv.conf
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User file and more advanced, DNS-specific configuration file for
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User the rest of this package (see the description for the
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<li class="listitem"><p>As part of the IRS library, newly implemented standard
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User address-name mapping functions, getaddrinfo() and
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User getnameinfo(), are provided. They use the DNSSEC-aware
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User validating resolver backend, and could use other advanced
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User features of the BIND 9 libraries such as caching. The
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User getaddrinfo() function resolves both A and AAAA RRs
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User concurrently (when the address family is unspecified).</p></li>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<li class="listitem"><p>An experimental framework to support other event
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User libraries than BIND 9's internal event task system.</p></li>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<div class="titlepage"><div><div><h3 class="title">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<a name="id-1.13.2.4"></a>Prerequisite</h3></div></div></div>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<p>GNU make is required to build the export libraries (other
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User part of BIND 9 can still be built with other types of make). In
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User the reminder of this document, "make" means GNU make. Note that
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User in some platforms you may need to invoke a different command name
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User than "make" (e.g. "gmake") to indicate it's GNU make.</p>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<div class="titlepage"><div><div><h3 class="title">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<a name="id-1.13.2.5"></a>Compilation</h3></div></div></div>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User$ <strong class="userinput"><code>/configure --enable-exportlib <em class="replaceable"><code>[other flags]</code></em></code></strong>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User$ <strong class="userinput"><code>make</code></strong>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User This will create (in addition to usual BIND 9 programs) and a
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User separate set of libraries under the lib/export directory. For
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User example, <code class="filename">lib/export/dns/libdns.a</code> is the archive file of the
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User export version of the BIND 9 DNS library. Sample application
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User programs using the libraries will also be built under the
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User lib/export/samples directory (see below).</p>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<div class="titlepage"><div><div><h3 class="title">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<a name="id-1.13.2.6"></a>Installation</h3></div></div></div>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User$ <strong class="userinput"><code>cd lib/export</code></strong>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User$ <strong class="userinput"><code>make install</code></strong>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User This will install library object files under the directory
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User specified by the --with-export-libdir configure option (default:
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User EPREFIX/lib/bind9), and header files under the directory
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User specified by the --with-export-includedir configure option
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User Root privilege is normally required.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt "<span class="command"><strong>make install</strong></span>" at the top directory will do the
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User To see how to build your own
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User application after the installation, see
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User <code class="filename">lib/export/samples/Makefile-postinstall.in</code>.</p>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<div class="titlepage"><div><div><h3 class="title">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<a name="id-1.13.2.7"></a>Known Defects/Restrictions</h3></div></div></div>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<li class="listitem"><p>Currently, win32 is not supported for the export
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User library. (Normal BIND 9 application can be built as
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<p>The "fixed" RRset order is not (currently) supported in
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User the export library. If you want to use "fixed" RRset order
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt for, e.g. <span class="command"><strong>named</strong></span> while still building the
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User export library even without the fixed order support, build
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User them separately:
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User$ <strong class="userinput"><code>/configure --enable-fixed-rrset <em class="replaceable"><code>[other flags, but not --enable-exportlib]</code></em></code></strong>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User$ <strong class="userinput"><code>make</code></strong>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User$ <strong class="userinput"><code>/configure --enable-exportlib <em class="replaceable"><code>[other flags, but not --enable-fixed-rrset]</code></em></code></strong>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User$ <strong class="userinput"><code>cd lib/export</code></strong>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User$ <strong class="userinput"><code>make</code></strong>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<li class="listitem"><p>The client module and the IRS library currently do not
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User support DNSSEC validation using DLV (the underlying modules
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User can handle it, but there is no tunable interface to enable
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<li class="listitem"><p>RFC 5011 is not supported in the validating stub
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User resolver of the export library. In fact, it is not clear
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User whether it should: trust anchors would be a system-wide
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User configuration which would be managed by an administrator,
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User while the stub resolver will be used by ordinary applications
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<li class="listitem"><p>Not all common <code class="filename">/etc/resolv.conf</code>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User options are supported
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User in the IRS library. The only available options in this
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<div class="titlepage"><div><div><h3 class="title">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<a name="id-1.13.2.8"></a>The dns.conf File</h3></div></div></div>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<p>The IRS library supports an "advanced" configuration file
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User related to the DNS library for configuration parameters that
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User would be beyond the capability of the
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User <code class="filename">resolv.conf</code> file.
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User Specifically, it is intended to provide DNSSEC related
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User configuration parameters. By default the path to this
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User configuration file is <code class="filename">/etc/dns.conf</code>.
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User This module is very
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User experimental and the configuration syntax or library interfaces
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User may change in future versions. Currently, only the
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <span class="command"><strong>trusted-keys</strong></span>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User statement is supported, whose syntax is the same as the same name
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User of statement for <code class="filename">named.conf</code>. (See
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <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>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<div class="titlepage"><div><div><h3 class="title">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<a name="id-1.13.2.9"></a>Sample Applications</h3></div></div></div>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<p>Some sample application programs using this API are
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User provided for reference. The following is a brief description of
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User these applications.
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<div class="titlepage"><div><div><h4 class="title">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<a name="id-1.13.2.9.3"></a>sample: a simple stub resolver utility</h4></div></div></div>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User It sends a query of a given name (of a given optional RR type) to a
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User specified recursive server, and prints the result as a list of
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User RRs. It can also act as a validating stub resolver if a trust
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User anchor is given via a set of command line options.</p>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User Usage: sample [options] server_address hostname
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User Options and Arguments:
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<div class="variablelist"><dl class="variablelist">
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt specify the RR type of the query. The default is the A RR.
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User [-a algorithm] [-e] -k keyname -K keystring
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt specify a command-line DNS key to validate the answer. For
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt example, to specify the following DNSKEY of example.com:
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt specify the options as follows:
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt -e -k example.com -K "xxx"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt -e means that this key is a zone's "key signing key" (as known
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt as "secure Entry point").
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt When -a is omitted rsasha1 will be used by default.
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User -s domain:alt_server_address
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt specify a separate recursive server address for the specific
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt "domain". Example: -s example.com:2001:db8::1234
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<dt><span class="term">server_address</span></dt>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt an IP(v4/v6) address of the recursive server to which queries
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt the domain name for the query
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<div class="titlepage"><div><div><h4 class="title">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<a name="id-1.13.2.9.4"></a>sample-async: a simple stub resolver, working asynchronously</h4></div></div></div>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User Similar to "sample", but accepts a list
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User of (query) domain names as a separate file and resolves the names
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User asynchronously.</p>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User Usage: sample-async [-s server_address] [-t RR_type] input_file</p>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User Options and Arguments:
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<div class="variablelist"><dl class="variablelist">
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User -s server_address
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User an IPv4 address of the recursive server to which queries are sent.
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User (IPv6 addresses are not supported in this implementation)
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User specify the RR type of the queries. The default is the A
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User a list of domain names to be resolved. each line
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User consists of a single domain name. Example:
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<div class="titlepage"><div><div><h4 class="title">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<a name="id-1.13.2.9.5"></a>sample-request: a simple DNS transaction client</h4></div></div></div>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User It sends a query to a specified server, and
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User prints the response with minimal processing. It doesn't act as a
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User "stub resolver": it stops the processing once it gets any
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User response from the server, whether it's a referral or an alias
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User (CNAME or DNAME) that would require further queries to get the
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User ultimate answer. In other words, this utility acts as a very
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt simplified <span class="command"><strong>dig</strong></span>.
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User Usage: sample-request [-t RRtype] server_address hostname
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User Options and Arguments:
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<div class="variablelist"><dl class="variablelist">
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User specify the RR type of
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User the queries. The default is the A RR.
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User server_address
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User address of the recursive server to which the query is sent.
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User the domain name for the query
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<div class="titlepage"><div><div><h4 class="title">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<a name="id-1.13.2.9.6"></a>sample-gai: getaddrinfo() and getnameinfo() test code</h4></div></div></div>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User This is a test program
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User to check getaddrinfo() and getnameinfo() behavior. It takes a
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User host name as an argument, calls getaddrinfo() with the given host
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User name, and calls getnameinfo() with the resulting IP addresses
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User returned by getaddrinfo(). If the dns.conf file exists and
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User defines a trust anchor, the underlying resolver will act as a
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User validating resolver, and getaddrinfo()/getnameinfo() will fail
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User with an EAI_INSECUREDATA error when DNSSEC validation fails.
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User Usage: sample-gai hostname
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<div class="titlepage"><div><div><h4 class="title">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<a name="id-1.13.2.9.7"></a>sample-update: a simple dynamic update client program</h4></div></div></div>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User It accepts a single update command as a
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User command-line argument, sends an update request message to the
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User authoritative server, and shows the response from the server. In
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt other words, this is a simplified <span class="command"><strong>nsupdate</strong></span>.
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User Usage: sample-update [options] (add|delete) "update data"
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User Options and Arguments:
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<div class="variablelist"><dl class="variablelist">
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User -a auth_server
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt An IP address of the authoritative server that has authority
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt for the zone containing the update name. This should normally
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt be the primary authoritative server that accepts dynamic
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt updates. It can also be a secondary server that is configured
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt to forward update requests to the primary server.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt A TSIG key file to secure the update transaction. The keyfile
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt format is the same as that for the nsupdate utility.
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User -p prerequisite
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt A prerequisite for the update (only one prerequisite can be
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt specified). The prerequisite format is the same as that is
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt accepted by the nsupdate utility.
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User -r recursive_server
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt An IP address of a recursive server that this utility will
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt use. A recursive server may be necessary to identify the
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt authoritative server address to which the update request is
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt The domain name of the zone that contains
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt Specify the type of update operation. Either "add" or "delete"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt must be specified.
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User "update data"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt Specify the data to be updated. A typical example of the data
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt would look like "name TTL RRtype RDATA".
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<h3 class="title">Note</h3>In practice, either -a or -r must be specified. Others can
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User be optional; the underlying library routine tries to identify the
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User appropriate server and the zone name for the update.</div>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User Examples: assuming the primary authoritative server of the
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User dynamic.example.com zone has an IPv6 address 2001:db8::1234,
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User$ <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>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User adds an A RR for foo.dynamic.example.com using the given key.
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User$ <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>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User removes all A RRs for foo.dynamic.example.com using the given key.
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User$ <strong class="userinput"><code>sample-update -a sample-update -k Kxxx.+nnn+mmmm.key delete "foo.dynamic.example.com"</code></strong></pre>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User removes all RRs for foo.dynamic.example.com using the given key.
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<div class="titlepage"><div><div><h4 class="title">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<a name="id-1.13.2.9.8"></a>nsprobe: domain/name server checker in terms of RFC 4074</h4></div></div></div>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User It checks a set
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User of domains to see the name servers of the domains behave
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User correctly in terms of RFC 4074. This is included in the set of
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User sample programs to show how the export library can be used in a
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User DNS-related application.
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User Usage: nsprobe [-d] [-v [-v...]] [-c cache_address] [input_file]
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<div class="variablelist"><dl class="variablelist">
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt run in the "debug" mode. with this option nsprobe will dump
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt every RRs it receives.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt increase verbosity of other normal log messages. This can be
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt specified multiple times
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User -c cache_address
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt specify an IP address of a recursive (caching) name server.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt nsprobe uses this server to get the NS RRset of each domain and
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt the A and/or AAAA RRsets for the name servers. The default
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt value is 127.0.0.1.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt a file name containing a list of domain (zone) names to be
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt probed. when omitted the standard input will be used. Each
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt line of the input file specifies a single domain name such as
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt "example.com". In general this domain name must be the apex
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt name of some DNS zone (unlike normal "host names" such as
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt "www.example.com"). nsprobe first identifies the NS RRsets for
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt the given domain name, and sends A and AAAA queries to these
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt servers for some "widely used" names under the zone;
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt specifically, adding "www" and "ftp" to the zone name.
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<div class="titlepage"><div><div><h3 class="title">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<a name="id-1.13.2.10"></a>Library References</h3></div></div></div>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<p>As of this writing, there is no formal "manual" of the
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User libraries, except this document, header files (some of them
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User provide pretty detailed explanations), and sample application
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User programs.</p>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<table width="100%" summary="Navigation footer">
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<a accesskey="p" href="Bv9ARM.ch11.html">Prev</a>�</td>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<td width="40%" align="right">�<a accesskey="n" href="Bv9ARM.ch13.html">Next</a>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<td width="40%" align="left" valign="top">Appendix�C.�General <acronym class="acronym">DNS</acronym> Reference Information�</td>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td>
fae13836a33b474a6aa2c147df8334f5b1ffae45Tinderbox User<td width="40%" align="right" valign="top">�Manual pages</td>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.0pre-alpha</p>