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 $ -->