/contrib/bind9/doc/arm/libdns.xml

  1<?xml version="1.0" encoding="utf-8"?>
  2<!--
  3 - Copyright (C) 2010  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-->
 17
 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.examle.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>
432
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>
436
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>
472
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 $ -->