Bv9ARM.ch12.html 20.4 KB
Newer Older
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
Tinderbox User's avatar
Tinderbox User committed
2
<!--
Tinderbox User's avatar
Tinderbox User committed
3
 - Copyright (C) 2000-2020 Internet Systems Consortium, Inc. ("ISC")
Tinderbox User's avatar
Tinderbox User committed
4
 - 
Tinderbox User's avatar
Tinderbox User committed
5 6 7
 - This Source Code Form is subject to the terms of the Mozilla Public
 - License, v. 2.0. If a copy of the MPL was not distributed with this
 - file, You can obtain one at http://mozilla.org/MPL/2.0/.
Tinderbox User's avatar
Tinderbox User committed
8
-->
9
<html lang="en">
Tinderbox User's avatar
Tinderbox User committed
10 11 12
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Appendix D. BIND 9 DNS Library Support</title>
Tinderbox User's avatar
Tinderbox User committed
13
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
Evan Hunt's avatar
Evan Hunt committed
14
<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
Tinderbox User's avatar
Tinderbox User committed
15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
<link rel="prev" href="Bv9ARM.ch11.html" title="Appendix C. General DNS Reference Information">
<link rel="next" href="Bv9ARM.ch13.html" title="Manual pages">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">Appendix D. BIND 9 DNS Library Support</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="Bv9ARM.ch11.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="Bv9ARM.ch13.html">Next</a>
</td>
</tr>
</table>
<hr>
</div>
Tinderbox User's avatar
Tinderbox User committed
33 34 35
<div class="appendix">
<div class="titlepage"><div><div><h1 class="title">
<a name="Bv9ARM.ch12"></a>BIND 9 DNS Library Support</h1></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
36 37
<div class="toc">
<p><b>Table of Contents</b></p>
Tinderbox User's avatar
Tinderbox User committed
38
<dl class="toc">
Evan Hunt's avatar
Evan Hunt committed
39
<dt><span class="section"><a href="Bv9ARM.ch12.html#bind9.library">BIND 9 DNS Library Support</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
40
<dd><dl>
Tinderbox User's avatar
Tinderbox User committed
41 42 43 44 45
<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.5">Installation</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.6">Known Defects/Restrictions</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.7">The dns.conf File</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.8">Sample Applications</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch12.html#id-1.13.2.9">Library References</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
46 47 48
</dl></dd>
</dl>
</div>
Tinderbox User's avatar
Tinderbox User committed
49
      <div class="section">
Tinderbox User's avatar
Tinderbox User committed
50 51
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="bind9.library"></a>BIND 9 DNS Library Support</h2></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
52 53
  
  <p>
Tinderbox User's avatar
Tinderbox User committed
54 55 56 57 58 59 60 61
    This version of BIND 9 "exports" its internal libraries so
    that they can be used by third-party applications more easily (we
    call them "export" libraries in this document). Certain library
    functions are altered from specific BIND-only behavior to more generic
    behavior when used by other applications; to enable this generic behavior,
    the calling program initializes the libraries by calling
    <span class="command"><strong>isc_lib_register()</strong></span>.
  </p>
Tinderbox User's avatar
Tinderbox User committed
62
  <p>
Tinderbox User's avatar
Tinderbox User committed
63 64 65
    In addition to DNS-related APIs that are used within BIND 9, the
    libraries provide the following features:
  </p>
Tinderbox User's avatar
Tinderbox User committed
66 67 68
  <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
      <p>
Tinderbox User's avatar
Tinderbox User committed
69 70 71 72 73 74
	The "DNS client" module. This is a higher level API that
	provides an interface to name resolution, single DNS transaction
	with a particular server, and dynamic update. Regarding name
	resolution, it supports advanced features such as DNSSEC validation
	and caching. This module supports both synchronous and asynchronous
	mode.
Tinderbox User's avatar
Tinderbox User committed
75 76 77 78
      </p>
    </li>
<li class="listitem">
      <p>
Tinderbox User's avatar
Tinderbox User committed
79 80 81 82 83
	The "IRS" (Information Retrieval System) library.  It provides an
	interface to parse the traditional <code class="filename">resolv.conf</code>
	file and more advanced, DNS-specific configuration file for the
	rest of this package (see the description for the
	<code class="filename">dns.conf</code> file below).
Tinderbox User's avatar
Tinderbox User committed
84 85 86 87
      </p>
    </li>
<li class="listitem">
      <p>
Tinderbox User's avatar
Tinderbox User committed
88 89 90 91 92 93 94 95
	As part of the IRS library, the standard address-name
	mapping functions, <span class="command"><strong>getaddrinfo()</strong></span> and
	<span class="command"><strong>getnameinfo()</strong></span>, are provided. They use the
	DNSSEC-aware validating resolver backend, and could use other
	advanced features of the BIND 9 libraries such as caching. The
	<span class="command"><strong>getaddrinfo()</strong></span> function resolves both A
	and AAAA RRs concurrently when the address family is
	unspecified.
Tinderbox User's avatar
Tinderbox User committed
96 97 98 99
      </p>
    </li>
<li class="listitem">
      <p>
Tinderbox User's avatar
Tinderbox User committed
100 101
	An experimental framework to support other event
	libraries than BIND 9's internal event task system.
Tinderbox User's avatar
Tinderbox User committed
102 103
      </p>
    </li>
Tinderbox User's avatar
Tinderbox User committed
104
</ul></div>
Tinderbox User's avatar
Tinderbox User committed
105
  <div class="section">
Tinderbox User's avatar
Tinderbox User committed
106
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
107
<a name="id-1.13.2.5"></a>Installation</h3></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
108 109
    
    <pre class="screen">
Tinderbox User's avatar
Tinderbox User committed
110
$ <strong class="userinput"><code>make install</code></strong>
Tinderbox User's avatar
Tinderbox User committed
111
    </pre>
Tinderbox User's avatar
Tinderbox User committed
112
    <p>
Tinderbox User's avatar
Tinderbox User committed
113 114 115
      Normal installation of BIND will also install library object
      and header files.  Root privilege is normally required.
    </p>
Tinderbox User's avatar
Tinderbox User committed
116
    <p>
Tinderbox User's avatar
Tinderbox User committed
117 118 119
      To see how to build your own application after the installation, see
      <code class="filename">lib/samples/Makefile-postinstall.in</code>.
    </p>
Tinderbox User's avatar
Tinderbox User committed
120 121
  </div>
  <div class="section">
Tinderbox User's avatar
Tinderbox User committed
122
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
123
<a name="id-1.13.2.6"></a>Known Defects/Restrictions</h3></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
124 125
    
    <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
Tinderbox User's avatar
Tinderbox User committed
126
<li class="listitem">
Tinderbox User's avatar
Tinderbox User committed
127
        <p>
Tinderbox User's avatar
Tinderbox User committed
128 129 130 131
	The "fixed" RRset order is not (currently) supported in the export
	library. If you want to use "fixed" RRset order for, e.g.
	<span class="command"><strong>named</strong></span> while still building the export library
	even without the fixed order support, build them separately:
Tinderbox User's avatar
Tinderbox User committed
132 133 134 135 136 137 138 139 140
      </p>
<pre class="screen">
$ <strong class="userinput"><code>./configure --enable-fixed-rrset <em class="replaceable"><code>[other flags, but not --enable-exportlib]</code></em></code></strong>
$ <strong class="userinput"><code>make</code></strong>
$ <strong class="userinput"><code>./configure --enable-exportlib <em class="replaceable"><code>[other flags, but not --enable-fixed-rrset]</code></em></code></strong>
$ <strong class="userinput"><code>cd lib/export</code></strong>
$ <strong class="userinput"><code>make</code></strong>
</pre>
<p>
Tinderbox User's avatar
Tinderbox User committed
141
      </p>
Tinderbox User's avatar
Tinderbox User committed
142 143 144
      </li>
<li class="listitem">
        <p>
Tinderbox User's avatar
Tinderbox User committed
145 146 147 148 149
	RFC 5011 is not supported in the validating stub resolver of the
	export library. In fact, it is not clear whether it should: trust
	anchors would be a system-wide configuration which would be managed
	by an administrator, while the stub resolver will be used by
	ordinary applications run by a normal user.
Tinderbox User's avatar
Tinderbox User committed
150 151 152 153
      </p>
      </li>
<li class="listitem">
        <p>
Tinderbox User's avatar
Tinderbox User committed
154 155 156
	Not all common <code class="filename">/etc/resolv.conf</code> options are
	supported in the IRS library. The only available options in this
	version are <span class="command"><strong>debug</strong></span> and <span class="command"><strong>ndots</strong></span>.
Tinderbox User's avatar
Tinderbox User committed
157 158
      </p>
      </li>
Tinderbox User's avatar
Tinderbox User committed
159
</ul></div>
Tinderbox User's avatar
Tinderbox User committed
160 161
  </div>
  <div class="section">
Tinderbox User's avatar
Tinderbox User committed
162
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
163
<a name="id-1.13.2.7"></a>The dns.conf File</h3></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
164 165
    
    <p>
Tinderbox User's avatar
Tinderbox User committed
166 167 168 169 170 171 172 173 174 175 176 177
      The IRS library supports an "advanced" configuration file related to
      the DNS library for configuration parameters that would be beyond the
      capability of the <code class="filename">resolv.conf</code> file.
      Specifically, it is intended to provide DNSSEC related configuration
      parameters. By default the path to this configuration file is
      <code class="filename">/etc/dns.conf</code>.  This module is very experimental
      and the configuration syntax or library interfaces may change in
      future versions. Currently, only the <span class="command"><strong>trusted-keys</strong></span>
      statement is supported, whose syntax is the same as the same
      statement in <code class="filename">named.conf</code>. (See
      <a class="xref" href="Bv9ARM.ch06.html#trusted-keys" title="trusted-keys Statement Grammar">the section called &#8220;<span class="command"><strong>trusted-keys</strong></span> Statement Grammar&#8221;</a> for details.)
    </p>
Tinderbox User's avatar
Tinderbox User committed
178 179
  </div>
  <div class="section">
Tinderbox User's avatar
Tinderbox User committed
180
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
181
<a name="id-1.13.2.8"></a>Sample Applications</h3></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
182 183
    
    <p>
Tinderbox User's avatar
Tinderbox User committed
184 185 186 187
      Some sample application programs using this API are provided for
      reference. The following is a brief description of these
      applications.
    </p>
Tinderbox User's avatar
Tinderbox User committed
188
    <div class="section">
Tinderbox User's avatar
Tinderbox User committed
189
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
Tinderbox User committed
190
<a name="id-1.13.2.8.3"></a>sample: a simple stub resolver utility</h4></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
191 192
      
      <p>
Tinderbox User's avatar
Tinderbox User committed
193 194 195 196 197
	Sends a query of a given name (of a given optional RR type) to a
	specified recursive server and prints the result as a list of RRs.
	It can also act as a validating stub resolver if a trust anchor is
	given via a set of command line options.
      </p>
Tinderbox User's avatar
Tinderbox User committed
198
      <p>
Tinderbox User's avatar
Tinderbox User committed
199 200
	Usage: sample [options] server_address hostname
      </p>
Tinderbox User's avatar
Tinderbox User committed
201
      <p>
Tinderbox User's avatar
Tinderbox User committed
202 203
	Options and Arguments:
      </p>
Tinderbox User's avatar
Tinderbox User committed
204
      <div class="variablelist"><dl class="variablelist">
Tinderbox User's avatar
Tinderbox User committed
205
<dt><span class="term">-t RRtype</span></dt>
Tinderbox User's avatar
Tinderbox User committed
206 207
<dd>
            <p>
Tinderbox User's avatar
Tinderbox User committed
208
	      specify the RR type of the query.  The default is the A RR.
Tinderbox User's avatar
Tinderbox User committed
209 210
	    </p>
          </dd>
Tinderbox User's avatar
Tinderbox User committed
211 212
<dt><span class="term">[-a algorithm] [-e] -k keyname -K keystring</span></dt>
<dd>
Tinderbox User's avatar
Tinderbox User committed
213
            <p>
Tinderbox User's avatar
Tinderbox User committed
214 215 216
	      specify a command-line DNS key to validate the answer.  For
	      example, to specify the following DNSKEY of example.com:
	      </p>
Tinderbox User's avatar
Tinderbox User committed
217
<div class="literallayout"><p><br>
Tinderbox User's avatar
Tinderbox User committed
218 219
	              example.com. 3600 IN DNSKEY 257 3 5 xxx<br>
	      </p></div>
Tinderbox User's avatar
Tinderbox User committed
220
<p>
Tinderbox User's avatar
Tinderbox User committed
221 222
	      specify the options as follows:
	      </p>
Tinderbox User's avatar
Tinderbox User committed
223
<pre class="screen">
Tinderbox User's avatar
Tinderbox User committed
224 225
<strong class="userinput"><code>-e -k example.com -K "xxx"</code></strong>
	      </pre>
Tinderbox User's avatar
Tinderbox User committed
226
<p>
Tinderbox User's avatar
Tinderbox User committed
227 228 229 230
	      -e means that this key is a zone's "key signing key" (also known
	      as "secure entry point").
	      When -a is omitted rsasha1 will be used by default.
	    </p>
Tinderbox User's avatar
Tinderbox User committed
231
          </dd>
Tinderbox User's avatar
Tinderbox User committed
232
<dt><span class="term">-s domain:alt_server_address</span></dt>
Tinderbox User's avatar
Tinderbox User committed
233 234
<dd>
            <p>
Tinderbox User's avatar
Tinderbox User committed
235 236
	       specify a separate recursive server address for the specific
	       "domain".  Example: -s example.com:2001:db8::1234
Tinderbox User's avatar
Tinderbox User committed
237 238
	    </p>
          </dd>
Tinderbox User's avatar
Tinderbox User committed
239
<dt><span class="term">server_address</span></dt>
Tinderbox User's avatar
Tinderbox User committed
240 241
<dd>
            <p>
Tinderbox User's avatar
Tinderbox User committed
242 243
	      an IP(v4/v6) address of the recursive server to which queries
	      are sent.
Tinderbox User's avatar
Tinderbox User committed
244 245
	    </p>
          </dd>
Tinderbox User's avatar
Tinderbox User committed
246
<dt><span class="term">hostname</span></dt>
Tinderbox User's avatar
Tinderbox User committed
247 248
<dd>
            <p>
Tinderbox User's avatar
Tinderbox User committed
249
	      the domain name for the query
Tinderbox User's avatar
Tinderbox User committed
250 251
	</p>
          </dd>
Tinderbox User's avatar
Tinderbox User committed
252
</dl></div>
Tinderbox User's avatar
Tinderbox User committed
253 254
    </div>
    <div class="section">
Tinderbox User's avatar
Tinderbox User committed
255
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
Tinderbox User committed
256
<a name="id-1.13.2.8.4"></a>sample-async: a simple stub resolver, working asynchronously</h4></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
257 258
      
      <p>
Tinderbox User's avatar
Tinderbox User committed
259 260 261
      Similar to "sample", but accepts a list
      of (query) domain names as a separate file and resolves the names
      asynchronously.</p>
Tinderbox User's avatar
Tinderbox User committed
262
      <p>
Tinderbox User's avatar
Tinderbox User committed
263
	Usage: sample-async [-s server_address] [-t RR_type] input_file</p>
Tinderbox User's avatar
Tinderbox User committed
264
      <p>
Tinderbox User's avatar
Tinderbox User committed
265 266
     Options and Arguments:
      </p>
Tinderbox User's avatar
Tinderbox User committed
267
      <div class="variablelist"><dl class="variablelist">
Tinderbox User's avatar
Tinderbox User committed
268
<dt><span class="term">-s server_address</span></dt>
Tinderbox User's avatar
Tinderbox User committed
269
<dd>
Tinderbox User's avatar
Tinderbox User committed
270 271 272 273
       an IPv4 address of the recursive server to which queries are sent.
      (IPv6 addresses are not supported in this implementation)
      </dd>
<dt><span class="term">-t RR_type</span></dt>
Tinderbox User's avatar
Tinderbox User committed
274
<dd>
Tinderbox User's avatar
Tinderbox User committed
275 276 277 278
      specify the RR type of the queries. The default is the A
      RR.
      </dd>
<dt><span class="term">input_file</span></dt>
Tinderbox User's avatar
Tinderbox User committed
279
<dd>
Tinderbox User's avatar
Tinderbox User committed
280 281 282 283 284 285 286
	    a list of domain names to be resolved. each line consists of a
	    single domain name. Example:
      <div class="literallayout"><p><br>
      www.example.com<br>
      mx.example.net<br>
      ns.xxx.example<br>
      </p></div>
Tinderbox User's avatar
Tinderbox User committed
287
	  </dd>
Tinderbox User's avatar
Tinderbox User committed
288
</dl></div>
Tinderbox User's avatar
Tinderbox User committed
289 290
    </div>
    <div class="section">
Tinderbox User's avatar
Tinderbox User committed
291
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
Tinderbox User committed
292
<a name="id-1.13.2.8.5"></a>sample-request: a simple DNS transaction client</h4></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
293 294
      
      <p>
Tinderbox User's avatar
Tinderbox User committed
295 296 297 298 299 300 301
	Sends a query to a specified server, and prints the response with
	minimal processing. It doesn't act as a "stub resolver": it stops
	the processing once it gets any response from the server, whether
	it's a referral or an alias (CNAME or DNAME) that would require
	further queries to get the ultimate answer. In other words, this
	utility acts as a very simplified <span class="command"><strong>dig</strong></span>.
      </p>
Tinderbox User's avatar
Tinderbox User committed
302
      <p>
Tinderbox User's avatar
Tinderbox User committed
303 304
	Usage: sample-request [-t RRtype] server_address hostname
      </p>
Tinderbox User's avatar
Tinderbox User committed
305
      <p>
Tinderbox User's avatar
Tinderbox User committed
306 307
	Options and Arguments:
      </p>
Tinderbox User's avatar
Tinderbox User committed
308
      <div class="variablelist"><dl class="variablelist">
Tinderbox User's avatar
Tinderbox User committed
309
<dt><span class="term">-t RRtype</span></dt>
Tinderbox User's avatar
Tinderbox User committed
310 311
<dd>
	    <p>
Tinderbox User's avatar
Tinderbox User committed
312
	      specify the RR type of the queries. The default is the A RR.
Tinderbox User's avatar
Tinderbox User committed
313 314
            </p>
          </dd>
Tinderbox User's avatar
Tinderbox User committed
315
<dt><span class="term">server_address</span></dt>
Tinderbox User's avatar
Tinderbox User committed
316 317
<dd>
	    <p>
Tinderbox User's avatar
Tinderbox User committed
318 319
	      an IP(v4/v6) address of the recursive server to which
	      the query is sent.
Tinderbox User's avatar
Tinderbox User committed
320 321
	    </p>
          </dd>
Tinderbox User's avatar
Tinderbox User committed
322
<dt><span class="term">hostname</span></dt>
Tinderbox User's avatar
Tinderbox User committed
323 324
<dd>
	    <p>
Tinderbox User's avatar
Tinderbox User committed
325
	      the domain name for the query
Tinderbox User's avatar
Tinderbox User committed
326 327
	    </p>
          </dd>
Tinderbox User's avatar
Tinderbox User committed
328
</dl></div>
Tinderbox User's avatar
Tinderbox User committed
329 330
    </div>
    <div class="section">
Tinderbox User's avatar
Tinderbox User committed
331
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
Tinderbox User committed
332
<a name="id-1.13.2.8.6"></a>sample-gai: getaddrinfo() and getnameinfo() test code</h4></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
333 334
      
      <p>
Tinderbox User's avatar
Tinderbox User committed
335 336 337 338 339 340 341 342 343 344 345
	This is a test program to check <span class="command"><strong>getaddrinfo()</strong></span> and
	<span class="command"><strong>getnameinfo()</strong></span> behavior. It takes a host name as an
	argument, calls <span class="command"><strong>getaddrinfo()</strong></span> with the given host
	name, and calls <span class="command"><strong>getnameinfo()</strong></span> with the resulting
	IP addresses returned by <span class="command"><strong>getaddrinfo()</strong></span>. If the
	dns.conf file exists and defines a trust anchor, the underlying
	resolver will act as a validating resolver, and
	<span class="command"><strong>getaddrinfo()</strong></span>/<span class="command"><strong>getnameinfo()</strong></span>
	will fail with an EAI_INSECUREDATA error when DNSSEC validation
	fails.
      </p>
Tinderbox User's avatar
Tinderbox User committed
346
      <p>
Tinderbox User's avatar
Tinderbox User committed
347 348
	Usage: sample-gai hostname
      </p>
Tinderbox User's avatar
Tinderbox User committed
349 350
    </div>
    <div class="section">
Tinderbox User's avatar
Tinderbox User committed
351
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
Tinderbox User committed
352
<a name="id-1.13.2.8.7"></a>sample-update: a simple dynamic update client program</h4></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
353 354
      
      <p>
Tinderbox User's avatar
Tinderbox User committed
355 356 357 358 359
	Accepts a single update command as a command-line argument, sends
	an update request message to the authoritative server, and shows
	the response from the server. In other words, this is a simplified
	<span class="command"><strong>nsupdate</strong></span>.
      </p>
Tinderbox User's avatar
Tinderbox User committed
360
      <p>
Tinderbox User's avatar
Tinderbox User committed
361 362
	Usage: sample-update [options] (add|delete) "update data"
      </p>
Tinderbox User's avatar
Tinderbox User committed
363
      <p>
Tinderbox User's avatar
Tinderbox User committed
364 365
	Options and Arguments:
      </p>
Tinderbox User's avatar
Tinderbox User committed
366
      <div class="variablelist"><dl class="variablelist">
Tinderbox User's avatar
Tinderbox User committed
367
<dt><span class="term">-a auth_server</span></dt>
Tinderbox User's avatar
Tinderbox User committed
368 369
<dd>
	    <p>
Tinderbox User's avatar
Tinderbox User committed
370 371 372 373 374
	      An IP address of the authoritative server that has authority
	      for the zone containing the update name.  This should
	      normally be the primary authoritative server that accepts
	      dynamic updates.  It can also be a secondary server that is
	      configured to forward update requests to the primary server.
Tinderbox User's avatar
Tinderbox User committed
375 376
	    </p>
          </dd>
Tinderbox User's avatar
Tinderbox User committed
377
<dt><span class="term">-k keyfile</span></dt>
Tinderbox User's avatar
Tinderbox User committed
378 379
<dd>
	    <p>
Tinderbox User's avatar
Tinderbox User committed
380 381
	      A TSIG key file to secure the update transaction.  The
	      keyfile format is the same as that for the nsupdate utility.
Tinderbox User's avatar
Tinderbox User committed
382 383
	    </p>
          </dd>
Tinderbox User's avatar
Tinderbox User committed
384
<dt><span class="term">-p prerequisite</span></dt>
Tinderbox User's avatar
Tinderbox User committed
385 386
<dd>
	    <p>
Tinderbox User's avatar
Tinderbox User committed
387 388 389
	      A prerequisite for the update (only one prerequisite can be
	      specified).  The prerequisite format is the same as that is
	      accepted by the nsupdate utility.
Tinderbox User's avatar
Tinderbox User committed
390 391
	    </p>
          </dd>
Tinderbox User's avatar
Tinderbox User committed
392
<dt><span class="term">-r recursive_server</span></dt>
Tinderbox User's avatar
Tinderbox User committed
393 394
<dd>
	    <p>
Tinderbox User's avatar
Tinderbox User committed
395 396 397 398
	      An IP address of a recursive server that this utility will
	      use.  A recursive server may be necessary to identify the
	      authoritative server address to which the update request is
	      sent.
Tinderbox User's avatar
Tinderbox User committed
399 400
	    </p>
          </dd>
Tinderbox User's avatar
Tinderbox User committed
401
<dt><span class="term">-z zonename</span></dt>
Tinderbox User's avatar
Tinderbox User committed
402 403
<dd>
	    <p>
Tinderbox User's avatar
Tinderbox User committed
404
	      The domain name of the zone that contains
Tinderbox User's avatar
Tinderbox User committed
405 406
	    </p>
          </dd>
Tinderbox User's avatar
Tinderbox User committed
407
<dt><span class="term">(add|delete)</span></dt>
Tinderbox User's avatar
Tinderbox User committed
408 409
<dd>
	    <p>
Tinderbox User's avatar
Tinderbox User committed
410 411
	      Specify the type of update operation.  Either "add" or
	      "delete" must be specified.
Tinderbox User's avatar
Tinderbox User committed
412 413
	    </p>
          </dd>
Tinderbox User's avatar
Tinderbox User committed
414
<dt><span class="term">"update data"</span></dt>
Tinderbox User's avatar
Tinderbox User committed
415 416
<dd>
	    <p>
Tinderbox User's avatar
Tinderbox User committed
417 418
	      Specify the data to be updated.  A typical example of the
	      data would look like "name TTL RRtype RDATA".
Tinderbox User's avatar
Tinderbox User committed
419 420
	    </p>
          </dd>
Tinderbox User's avatar
Tinderbox User committed
421
</dl></div>
Tinderbox User's avatar
Tinderbox User committed
422
      <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
Tinderbox User's avatar
Tinderbox User committed
423
<h3 class="title">Note</h3>
Tinderbox User's avatar
Tinderbox User committed
424
	<p>
Tinderbox User's avatar
Tinderbox User committed
425 426 427 428
	  In practice, either -a or -r must be specified.  Others can be
	  optional; the underlying library routine tries to identify the
	  appropriate server and the zone name for the update.
	</p>
Tinderbox User's avatar
Tinderbox User committed
429 430
      </div>
      <p>
Tinderbox User's avatar
Tinderbox User committed
431 432 433
	Examples: assuming the primary authoritative server of the
	dynamic.example.com zone has an IPv6 address 2001:db8::1234,
      </p>
Tinderbox User's avatar
Tinderbox User committed
434
      <pre class="screen">
Tinderbox User's avatar
Tinderbox User committed
435
$ <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>
Tinderbox User's avatar
Tinderbox User committed
436
      <p>
Tinderbox User's avatar
Tinderbox User committed
437 438
	adds an A RR for foo.dynamic.example.com using the given key.
      </p>
Tinderbox User's avatar
Tinderbox User committed
439
      <pre class="screen">
Tinderbox User's avatar
Tinderbox User committed
440
$ <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>
Tinderbox User's avatar
Tinderbox User committed
441
      <p>
Tinderbox User's avatar
Tinderbox User committed
442 443
	removes all A RRs for foo.dynamic.example.com using the given key.
      </p>
Tinderbox User's avatar
Tinderbox User committed
444
      <pre class="screen">
Tinderbox User's avatar
Tinderbox User committed
445
$ <strong class="userinput"><code>sample-update -a sample-update -k Kxxx.+nnn+mmmm.key delete "foo.dynamic.example.com"</code></strong></pre>
Tinderbox User's avatar
Tinderbox User committed
446
      <p>
Tinderbox User's avatar
Tinderbox User committed
447 448
	removes all RRs for foo.dynamic.example.com using the given key.
      </p>
Tinderbox User's avatar
Tinderbox User committed
449 450
    </div>
    <div class="section">
Tinderbox User's avatar
Tinderbox User committed
451
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
Tinderbox User committed
452
<a name="id-1.13.2.8.8"></a>nsprobe: domain/name server checker in terms of RFC 4074</h4></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
453 454
      
      <p>
Tinderbox User's avatar
Tinderbox User committed
455 456 457 458 459
	Checks a set of domains to see the name servers of the domains
	behave correctly in terms of RFC 4074. This is included in the set
	of sample programs to show how the export library can be used in a
	DNS-related application.
      </p>
Tinderbox User's avatar
Tinderbox User committed
460
      <p>
Tinderbox User's avatar
Tinderbox User committed
461 462
	Usage: nsprobe [-d] [-v [-v...]] [-c cache_address] [input_file]
      </p>
Tinderbox User's avatar
Tinderbox User committed
463
      <p>
Tinderbox User's avatar
Tinderbox User committed
464 465
	Options
      </p>
Tinderbox User's avatar
Tinderbox User committed
466
      <div class="variablelist"><dl class="variablelist">
Tinderbox User's avatar
Tinderbox User committed
467
<dt><span class="term">-d</span></dt>
Tinderbox User's avatar
Tinderbox User committed
468 469
<dd>
	    <p>
Tinderbox User's avatar
Tinderbox User committed
470 471
	      Run in "debug" mode.  With this option nsprobe will dump
	      every RRs it receives.
Tinderbox User's avatar
Tinderbox User committed
472 473
	    </p>
          </dd>
Tinderbox User's avatar
Tinderbox User committed
474
<dt><span class="term">-v</span></dt>
Tinderbox User's avatar
Tinderbox User committed
475 476
<dd>
	    <p>
Tinderbox User's avatar
Tinderbox User committed
477 478
	      Increase verbosity of other normal log messages.  This can be
	      specified multiple times.
Tinderbox User's avatar
Tinderbox User committed
479 480
	    </p>
          </dd>
Tinderbox User's avatar
Tinderbox User committed
481
<dt><span class="term">-c cache_address</span></dt>
Tinderbox User's avatar
Tinderbox User committed
482 483
<dd>
	    <p>
Tinderbox User's avatar
Tinderbox User committed
484 485 486 487
	      Specify an IP address of a recursive (caching) name server.
	      nsprobe uses this server to get the NS RRset of each domain
	      and the A and/or AAAA RRsets for the name servers.  The
	      default value is 127.0.0.1.
Tinderbox User's avatar
Tinderbox User committed
488 489
	    </p>
          </dd>
Tinderbox User's avatar
Tinderbox User committed
490
<dt><span class="term">input_file</span></dt>
Tinderbox User's avatar
Tinderbox User committed
491 492
<dd>
	    <p>
Tinderbox User's avatar
Tinderbox User committed
493 494 495 496 497 498 499 500 501
	      A file name containing a list of domain (zone) names to be
	      probed.  when omitted the standard input will be used.  Each
	      line of the input file specifies a single domain name such as
	      "example.com".  In general this domain name must be the apex
	      name of some DNS zone (unlike normal "host names" such as
	      "www.example.com").  nsprobe first identifies the NS RRsets
	      for the given domain name, and sends A and AAAA queries to
	      these servers for some "widely used" names under the zone;
	      specifically, adding "www" and "ftp" to the zone name.
Tinderbox User's avatar
Tinderbox User committed
502 503
	    </p>
          </dd>
Tinderbox User's avatar
Tinderbox User committed
504
</dl></div>
Tinderbox User's avatar
Tinderbox User committed
505 506 507
    </div>
  </div>
  <div class="section">
Tinderbox User's avatar
Tinderbox User committed
508
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
509
<a name="id-1.13.2.9"></a>Library References</h3></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
510 511
    
    <p>
Tinderbox User's avatar
Tinderbox User committed
512 513 514 515
      As of this writing, there is no formal "manual" for the libraries,
      except this document, header files (some of which provide pretty
      detailed explanations), and sample application programs.
    </p>
Tinderbox User's avatar
Tinderbox User committed
516
  </div>
Tinderbox User's avatar
Tinderbox User committed
517
</div>
Tinderbox User's avatar
Tinderbox User committed
518
    </div>
Tinderbox User's avatar
Tinderbox User committed
519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="Bv9ARM.ch11.html">Prev</a> </td>
<td width="20%" align="center"> </td>
<td width="40%" align="right"> <a accesskey="n" href="Bv9ARM.ch13.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Appendix C. General <acronym class="acronym">DNS</acronym> Reference Information </td>
<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td>
<td width="40%" align="right" valign="top"> Manual pages</td>
</tr>
</table>
</div>
Tinderbox User's avatar
Tinderbox User committed
536
<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.21 (Extended Support Version)</p>
Tinderbox User's avatar
Tinderbox User committed
537 538
</body>
</html>