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