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