| blob | 86bf796dd9201d1006deddbcd9513ae3f6c837dc |
1 <?xml version="1.0" encoding="utf-8"?>
2 <!--
3 - Copyright (C) 2010, 2014 Internet Systems Consortium, Inc. ("ISC")
4 -
5 - Permission to use, copy, modify, and/or distribute this software for any
6 - purpose with or without fee is hereby granted, provided that the above
7 - copyright notice and this permission notice appear in all copies.
8 -
9 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15 - PERFORMANCE OF THIS SOFTWARE.
16 -->
18 <sect1 id="bind9.library">
19 <title>BIND 9 DNS Library Support</title>
20 <para>This version of BIND 9 "exports" its internal libraries so
21 that they can be used by third-party applications more easily (we
22 call them "export" libraries in this document). In addition to
23 all major DNS-related APIs BIND 9 is currently using, the export
24 libraries provide the following features:</para>
25 <itemizedlist>
26 <listitem>
27 <para>The newly created "DNS client" module. This is a higher
28 level API that provides an interface to name resolution,
29 single DNS transaction with a particular server, and dynamic
30 update. Regarding name resolution, it supports advanced
31 features such as DNSSEC validation and caching. This module
32 supports both synchronous and asynchronous mode.</para>
33 </listitem>
34 <listitem>
35 <para>The new "IRS" (Information Retrieval System) library.
36 It provides an interface to parse the traditional resolv.conf
37 file and more advanced, DNS-specific configuration file for
38 the rest of this package (see the description for the
39 dns.conf file below).</para>
40 </listitem>
41 <listitem>
42 <para>As part of the IRS library, newly implemented standard
43 address-name mapping functions, getaddrinfo() and
44 getnameinfo(), are provided. They use the DNSSEC-aware
45 validating resolver backend, and could use other advanced
46 features of the BIND 9 libraries such as caching. The
47 getaddrinfo() function resolves both A and AAAA RRs
48 concurrently (when the address family is unspecified).</para>
49 </listitem>
50 <listitem>
51 <para>An experimental framework to support other event
52 libraries than BIND 9's internal event task system.</para>
53 </listitem>
54 </itemizedlist>
55 <sect2>
56 <title>Prerequisite</title>
57 <para>GNU make is required to build the export libraries (other
58 part of BIND 9 can still be built with other types of make). In
59 the reminder of this document, "make" means GNU make. Note that
60 in some platforms you may need to invoke a different command name
61 than "make" (e.g. "gmake") to indicate it's GNU make.</para>
62 </sect2>
63 <sect2>
64 <title>Compilation</title>
65 <screen>
66 $ <userinput>./configure --enable-exportlib <replaceable>[other flags]</replaceable></userinput>
67 $ <userinput>make</userinput>
68 </screen>
69 <para>
70 This will create (in addition to usual BIND 9 programs) and a
71 separate set of libraries under the lib/export directory. For
72 example, <filename>lib/export/dns/libdns.a</filename> is the archive file of the
73 export version of the BIND 9 DNS library. Sample application
74 programs using the libraries will also be built under the
75 lib/export/samples directory (see below).</para>
76 </sect2>
77 <sect2>
78 <title>Installation</title>
79 <screen>
80 $ <userinput>cd lib/export</userinput>
81 $ <userinput>make install</userinput>
82 </screen>
83 <para>
84 This will install library object files under the directory
85 specified by the --with-export-libdir configure option (default:
86 EPREFIX/lib/bind9), and header files under the directory
87 specified by the --with-export-includedir configure option
88 (default: PREFIX/include/bind9).
89 Root privilege is normally required.
90 "<command>make install</command>" at the top directory will do the
91 same.
92 </para>
93 <para>
94 To see how to build your own
95 application after the installation, see
96 <filename>lib/export/samples/Makefile-postinstall.in</filename>.</para>
97 </sect2>
98 <sect2>
99 <title>Known Defects/Restrictions</title>
100 <itemizedlist>
101 <listitem>
102 <!-- TODO: what about AIX? -->
103 <para>Currently, win32 is not supported for the export
104 library. (Normal BIND 9 application can be built as
105 before).</para>
106 </listitem>
107 <listitem>
108 <para>The "fixed" RRset order is not (currently) supported in
109 the export library. If you want to use "fixed" RRset order
110 for, e.g. <command>named</command> while still building the
111 export library even without the fixed order support, build
112 them separately:
113 <screen>
114 $ <userinput>./configure --enable-fixed-rrset <replaceable>[other flags, but not --enable-exportlib]</replaceable></userinput>
115 $ <userinput>make</userinput>
116 $ <userinput>./configure --enable-exportlib <replaceable>[other flags, but not --enable-fixed-rrset]</replaceable></userinput>
117 $ <userinput>cd lib/export</userinput>
118 $ <userinput>make</userinput>
119 </screen>
120 </para>
121 </listitem>
122 <listitem>
123 <para>The client module and the IRS library currently do not
124 support DNSSEC validation using DLV (the underlying modules
125 can handle it, but there is no tunable interface to enable
126 the feature).</para>
127 </listitem>
128 <listitem>
129 <para>RFC 5011 is not supported in the validating stub
130 resolver of the export library. In fact, it is not clear
131 whether it should: trust anchors would be a system-wide
132 configuration which would be managed by an administrator,
133 while the stub resolver will be used by ordinary applications
134 run by a normal user.</para>
135 </listitem>
136 <listitem>
137 <para>Not all common <filename>/etc/resolv.conf</filename>
138 options are supported
139 in the IRS library. The only available options in this
140 version are "debug" and "ndots".</para>
141 </listitem>
142 </itemizedlist>
143 </sect2>
144 <sect2>
145 <title>The dns.conf File</title>
146 <para>The IRS library supports an "advanced" configuration file
147 related to the DNS library for configuration parameters that
148 would be beyond the capability of the
149 <filename>resolv.conf</filename> file.
150 Specifically, it is intended to provide DNSSEC related
151 configuration parameters. By default the path to this
152 configuration file is <filename>/etc/dns.conf</filename>.
153 This module is very
154 experimental and the configuration syntax or library interfaces
155 may change in future versions. Currently, only the
156 <command>trusted-keys</command>
157 statement is supported, whose syntax is the same as the same name
158 of statement for <filename>named.conf</filename>. (See
159 <xref linkend="trusted-keys" /> for details.)</para>
160 </sect2>
161 <sect2>
162 <title>Sample Applications</title>
163 <para>Some sample application programs using this API are
164 provided for reference. The following is a brief description of
165 these applications.
166 </para>
167 <sect3>
168 <title>sample: a simple stub resolver utility</title>
169 <para>
170 It sends a query of a given name (of a given optional RR type) to a
171 specified recursive server, and prints the result as a list of
172 RRs. It can also act as a validating stub resolver if a trust
173 anchor is given via a set of command line options.</para>
174 <para>
175 Usage: sample [options] server_address hostname
176 </para>
177 <para>
178 Options and Arguments:
179 </para>
180 <variablelist>
181 <varlistentry>
182 <term>
183 -t RRtype
184 </term>
185 <listitem><para>
186 specify the RR type of the query. The default is the A RR.
187 </para></listitem>
188 </varlistentry>
189 <varlistentry>
190 <term>
191 [-a algorithm] [-e] -k keyname -K keystring
192 </term>
193 <listitem><para>
194 specify a command-line DNS key to validate the answer. For
195 example, to specify the following DNSKEY of example.com:
196 <literallayout>
197 example.com. 3600 IN DNSKEY 257 3 5 xxx
198 </literallayout>
199 specify the options as follows:
200 <screen>
201 <userinput>
202 -e -k example.com -K "xxx"
203 </userinput>
204 </screen>
205 -e means that this key is a zone's "key signing key" (as known
206 as "secure Entry point").
207 When -a is omitted rsasha1 will be used by default.
208 </para></listitem>
209 </varlistentry>
210 <varlistentry>
211 <term>
212 -s domain:alt_server_address
213 </term>
214 <listitem><para>
215 specify a separate recursive server address for the specific
216 "domain". Example: -s example.com:2001:db8::1234
217 </para></listitem>
218 </varlistentry>
219 <varlistentry>
220 <term>server_address</term>
221 <listitem><para>
222 an IP(v4/v6) address of the recursive server to which queries
223 are sent.
224 </para></listitem>
225 </varlistentry>
226 <varlistentry>
227 <term>hostname</term>
228 <listitem><para>
229 the domain name for the query
230 </para></listitem>
231 </varlistentry>
232 </variablelist>
233 </sect3>
234 <sect3>
235 <title>sample-async: a simple stub resolver, working asynchronously</title>
236 <para>
237 Similar to "sample", but accepts a list
238 of (query) domain names as a separate file and resolves the names
239 asynchronously.</para>
240 <para>
241 Usage: sample-async [-s server_address] [-t RR_type] input_file</para>
242 <para>
243 Options and Arguments:
244 </para>
245 <variablelist>
246 <varlistentry>
247 <term>
248 -s server_address
249 </term>
250 <listitem>
251 an IPv4 address of the recursive server to which queries are sent.
252 (IPv6 addresses are not supported in this implementation)
253 </listitem>
254 </varlistentry>
255 <varlistentry>
256 <term>
257 -t RR_type
258 </term>
259 <listitem>
260 specify the RR type of the queries. The default is the A
261 RR.
262 </listitem>
263 </varlistentry>
264 <varlistentry>
265 <term>
266 input_file
267 </term>
268 <listitem>
269 a list of domain names to be resolved. each line
270 consists of a single domain name. Example:
271 <literallayout>
272 www.example.com
273 mx.example.net
274 ns.xxx.example
275 </literallayout>
276 </listitem>
277 </varlistentry>
278 </variablelist>
279 </sect3>
280 <sect3>
281 <title>sample-request: a simple DNS transaction client</title>
282 <para>
283 It sends a query to a specified server, and
284 prints the response with minimal processing. It doesn't act as a
285 "stub resolver": it stops the processing once it gets any
286 response from the server, whether it's a referral or an alias
287 (CNAME or DNAME) that would require further queries to get the
288 ultimate answer. In other words, this utility acts as a very
289 simplified <command>dig</command>.
290 </para>
291 <para>
292 Usage: sample-request [-t RRtype] server_address hostname
293 </para>
294 <para>
295 Options and Arguments:
296 </para>
297 <variablelist>
298 <varlistentry>
299 <term>
300 -t RRtype
301 </term>
302 <listitem>
303 <para>
304 specify the RR type of
305 the queries. The default is the A RR.
306 </para>
307 </listitem>
308 </varlistentry>
309 <varlistentry>
310 <term>
311 server_address
312 </term>
313 <listitem>
314 <para>
315 an IP(v4/v6)
316 address of the recursive server to which the query is sent.
317 </para>
318 </listitem>
319 </varlistentry>
320 <varlistentry>
321 <term>
322 hostname
323 </term>
324 <listitem>
325 <para>
326 the domain name for the query
327 </para>
328 </listitem>
329 </varlistentry>
330 </variablelist>
331 </sect3>
332 <sect3>
333 <title>sample-gai: getaddrinfo() and getnameinfo() test code</title>
334 <para>
335 This is a test program
336 to check getaddrinfo() and getnameinfo() behavior. It takes a
337 host name as an argument, calls getaddrinfo() with the given host
338 name, and calls getnameinfo() with the resulting IP addresses
339 returned by getaddrinfo(). If the dns.conf file exists and
340 defines a trust anchor, the underlying resolver will act as a
341 validating resolver, and getaddrinfo()/getnameinfo() will fail
342 with an EAI_INSECUREDATA error when DNSSEC validation fails.
343 </para>
344 <para>
345 Usage: sample-gai hostname
346 </para>
347 </sect3>
348 <sect3>
349 <title>sample-update: a simple dynamic update client program</title>
350 <para>
351 It accepts a single update command as a
352 command-line argument, sends an update request message to the
353 authoritative server, and shows the response from the server. In
354 other words, this is a simplified <command>nsupdate</command>.
355 </para>
356 <para>
357 Usage: sample-update [options] (add|delete) "update data"
358 </para>
359 <para>
360 Options and Arguments:
361 </para>
362 <variablelist>
363 <varlistentry>
364 <term>
365 -a auth_server
366 </term>
367 <listitem><para>
368 An IP address of the authoritative server that has authority
369 for the zone containing the update name. This should normally
370 be the primary authoritative server that accepts dynamic
371 updates. It can also be a secondary server that is configured
372 to forward update requests to the primary server.
373 </para></listitem>
374 </varlistentry>
375 <varlistentry>
376 <term>
377 -k keyfile
378 </term>
379 <listitem><para>
380 A TSIG key file to secure the update transaction. The keyfile
381 format is the same as that for the nsupdate utility.
382 </para></listitem>
383 </varlistentry>
384 <varlistentry>
385 <term>
386 -p prerequisite
387 </term>
388 <listitem><para>
389 A prerequisite for the update (only one prerequisite can be
390 specified). The prerequisite format is the same as that is
391 accepted by the nsupdate utility.
392 </para></listitem>
393 </varlistentry>
394 <varlistentry>
395 <term>
396 -r recursive_server
397 </term>
398 <listitem><para>
399 An IP address of a recursive server that this utility will
400 use. A recursive server may be necessary to identify the
401 authoritative server address to which the update request is
402 sent.
403 </para></listitem>
404 </varlistentry>
405 <varlistentry>
406 <term>
407 -z zonename
408 </term>
409 <listitem><para>
410 The domain name of the zone that contains
411 </para></listitem>
412 </varlistentry>
413 <varlistentry>
414 <term>
415 (add|delete)
416 </term>
417 <listitem><para>
418 Specify the type of update operation. Either "add" or "delete"
419 must be specified.
420 </para></listitem>
421 </varlistentry>
422 <varlistentry>
423 <term>
424 "update data"
425 </term>
426 <listitem><para>
427 Specify the data to be updated. A typical example of the data
428 would look like "name TTL RRtype RDATA".
429 </para></listitem>
430 </varlistentry>
431 </variablelist>
433 <note>In practice, either -a or -r must be specified. Others can
434 be optional; the underlying library routine tries to identify the
435 appropriate server and the zone name for the update.</note>
437 <para>
438 Examples: assuming the primary authoritative server of the
439 dynamic.example.com zone has an IPv6 address 2001:db8::1234,
440 </para>
441 <screen>
442 $ <userinput>sample-update -a sample-update -k Kxxx.+nnn+mmmm.key add "foo.dynamic.example.com 30 IN A 192.168.2.1"</userinput></screen>
443 <para>
444 adds an A RR for foo.dynamic.example.com using the given key.
445 </para>
446 <screen>
447 $ <userinput>sample-update -a sample-update -k Kxxx.+nnn+mmmm.key delete "foo.dynamic.example.com 30 IN A"</userinput></screen>
448 <para>
449 removes all A RRs for foo.dynamic.example.com using the given key.
450 </para>
451 <screen>
452 $ <userinput>sample-update -a sample-update -k Kxxx.+nnn+mmmm.key delete "foo.dynamic.example.com"</userinput></screen>
453 <para>
454 removes all RRs for foo.dynamic.example.com using the given key.
455 </para>
456 </sect3>
457 <sect3>
458 <title>nsprobe: domain/name server checker in terms of RFC 4074</title>
459 <para>
460 It checks a set
461 of domains to see the name servers of the domains behave
462 correctly in terms of RFC 4074. This is included in the set of
463 sample programs to show how the export library can be used in a
464 DNS-related application.
465 </para>
466 <para>
467 Usage: nsprobe [-d] [-v [-v...]] [-c cache_address] [input_file]
468 </para>
469 <para>
470 Options
471 </para>
473 <variablelist>
474 <varlistentry>
475 <term>
476 -d
477 </term>
478 <listitem><para>
479 run in the "debug" mode. with this option nsprobe will dump
480 every RRs it receives.
481 </para></listitem>
482 </varlistentry>
483 <varlistentry>
484 <term>
485 -v
486 </term>
487 <listitem><para>
488 increase verbosity of other normal log messages. This can be
489 specified multiple times
490 </para></listitem>
491 </varlistentry>
492 <varlistentry>
493 <term>
494 -c cache_address
495 </term>
496 <listitem><para>
497 specify an IP address of a recursive (caching) name server.
498 nsprobe uses this server to get the NS RRset of each domain and
499 the A and/or AAAA RRsets for the name servers. The default
500 value is 127.0.0.1.
501 </para></listitem>
502 </varlistentry>
503 <varlistentry>
504 <term>
505 input_file
506 </term>
507 <listitem><para>
508 a file name containing a list of domain (zone) names to be
509 probed. when omitted the standard input will be used. Each
510 line of the input file specifies a single domain name such as
511 "example.com". In general this domain name must be the apex
512 name of some DNS zone (unlike normal "host names" such as
513 "www.example.com"). nsprobe first identifies the NS RRsets for
514 the given domain name, and sends A and AAAA queries to these
515 servers for some "widely used" names under the zone;
516 specifically, adding "www" and "ftp" to the zone name.
517 </para></listitem>
518 </varlistentry>
519 </variablelist>
520 </sect3>
521 </sect2>
522 <sect2>
523 <title>Library References</title>
524 <para>As of this writing, there is no formal "manual" of the
525 libraries, except this document, header files (some of them
526 provide pretty detailed explanations), and sample application
527 programs.</para>
528 </sect2>
529 </sect1>
530 <!-- Id: libdns.xml,v 1.3 2010/02/03 23:49:07 tbox Exp -->