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