external/bsd/bind/dist/README.libdns

   1
   2                         BIND-9 DNS Library Support
   3
   4 This version of BIND9 "exports" its internal libraries so that they
   5 can be used by third-party applications more easily (we call them
   6 "export" libraries in this document).  In addition to all major
   7 DNS-related APIs BIND9 is currently using, the export libraries
   8 provide the following features:
   9
  10 - The newly created "DNS client" module.  This is a higher level API
  11   that provides an interface to name resolution, single DNS
  12   transaction with a particular server, and dynamic update.  Regarding
  13   name resolution, it supports advanced features such as DNSSEC
  14   validation and caching.  This module supports both synchronous and
  15   asynchronous mode.
  16 - The new "IRS" (Information Retrieval System) library.  It provides
  17   an interface to parse the traditional resolv.conf file and more
  18   advanced, DNS-specific configuration file for the rest of this
  19   package (see the description for the dns.conf file below).
  20 - As part of the IRS library, newly implemented standard address-name
  21   mapping functions, getaddrinfo() and getnameinfo(), are provided.
  22   They use the DNSSEC-aware validating resolver backend, and could use
  23   other advanced features of the BIND9 libraries such as caching.  The
  24   getaddrinfo() function resolves both A and AAAA RRs concurrently
  25   (when the address family is unspecified).
  26 - An experimental framework to support other event libraries than
  27   BIND9's internal event task system.
  28
  29 * Prerequisite
  30
  31 GNU make is required to build the export libraries (other part of
  32 BIND9 can still be built with other types of make).  In the reminder
  33 of this document, "make" means GNU make.  Note that in some platforms
  34 you may need to invoke a different command name than "make"
  35 (e.g. "gmake") to indicate it's GNU make.
  36
  37 * Compilation
  38
  39 1. ./configure --enable-exportlib [other flags]
  40 2. make
  41
  42 This will create (in addition to usual BIND9 programs) and a separate
  43 set of libraries under the lib/export directory.  For example,
  44 lib/export/dns/libdns.a is the archive file of the export version of
  45 the BIND9 DNS library.
  46
  47 Sample application programs using the libraries will also be built
  48 under the lib/export/samples directory (see below).
  49
  50 * Installation
  51
  52 1. cd lib/export
  53 2. make install (root privilege is normally required)
  54    (make install at the top directory will do the same)
  55
  56 This will install library object files under the directory specified
  57 by the --with-export-libdir configure option (default:
  58 EPREFIX/lib/bind9), and header files under the directory specified by
  59 the --with-export-includedir configure option (default:
  60 PREFIX/include/bind9).
  61
  62 To see how to build your own application after the installation, see
  63 lib/export/samples/Makefile-postinstall.in
  64
  65 * Known Defects/Restrictions
  66
  67 - Currently, win32 is not supported for the export library.  (Normal
  68   BIND9 application can be built as before).
  69 - The "fixed" RRset order is not (currently) supported in the export
  70   library.  If you want to use "fixed" RRset order for, e.g. named
  71   while still building the export library even without the fixed
  72   order support, build them separately:
  73   % ./configure --enable-fixed-rrset [other flags, but not --enable-exportlib]
  74   % make (this doesn't have to be make)
  75   % ./configure --enable-exportlib [other flags, but not --enable-fixed-rrset]
  76   % cd lib/export
  77   % make
  78 - The client module and the IRS library currently do not support
  79   DNSSEC validation using DLV (the underlying modules can handle it,
  80   but there is no tunable interface to enable the feature).
  81 - RFC5011 is not supported in the validating stub resolver of the
  82   export library.  In fact, it is not clear whether it should: trust
  83   anchors would be a system-wide configuration which would be managed
  84   by an administrator, while the stub resolver will be used by
  85   ordinary applications run by a normal user.
  86 - Not all common /etc/resolv.conf options are supported in the IRS library.
  87   The only available options in this version are "debug" and "ndots".
  88
  89 * The dns.conf File
  90
  91 The IRS library supports an "advanced" configuration file related to
  92 the DNS library for configuration parameters that would be beyond the
  93 capability of the resolv.conf file.  Specifically, it is intended to
  94 provide DNSSEC related configuration parameters.
  95
  96 By default the path to this configuration file is /etc/dns.conf.
  97
  98 This module is very experimental and the configuration syntax or
  99 library interfaces may change in future versions.  Currently, only the
 100 'trusted-keys' statement is supported, whose syntax is the same as the
 101 same name of statement for named.conf.
 102
 103 * Sample Applications
 104
 105 Some sample application programs using this API are provided for
 106 reference.  The following is a brief description of these
 107 applications.
 108
 109 - sample: a simple stub resolver utility.
 110
 111   It sends a query of a given name (of a given optional RR type)
 112   to a specified recursive server, and prints the result as a list of
 113   RRs.  It can also act as a validating stub resolver if a trust
 114   anchor is given via a set of command line options.
 115
 116   Usage: sample [options] server_address hostname
 117
 118   Options and Arguments:
 119   -t RRtype
 120         specify the RR type of the query.  The default is the A RR.
 121   [-a algorithm] [-e] -k keyname -K keystring
 122         specify a command-line DNS key to validate the answer.  For
 123         example, to specify the following DNSKEY of example.com:
 124                 example.com. 3600 IN DNSKEY 257 3 5 xxx
 125         specify the options as follows:
 126           -e -k example.com -K "xxx"
 127         -e means that this key is a zone's "key signing key" (as known
 128         as "secure Entry point").
 129         when -a is omitted rsasha1 will be used by default.
 130   -s domain:alt_server_address
 131         specify a separate recursive server address for the specific
 132         "domain".  Example: -s example.com:2001:db8::1234
 133   server_address
 134         an IP(v4/v6) address of the recursive server to which queries
 135         are sent.
 136   hostname
 137         the domain name for the query
 138
 139 - sample-async: a simple stub resolver, working asynchronously.
 140
 141   Similar to "sample", but accepts a list of (query) domain names as a
 142   separate file and resolves the names asynchronously.
 143
 144   Usage: sample-async [-s server_address] [-t RR_type] input_file
 145   Options and Arguments:
 146   -s server_address
 147         an IPv4 address of the recursive server to which queries are
 148         sent.  (IPv6 addresses are not supported in this implementation)
 149   -t RR_type
 150         specify the RR type of the queries.  The default is the A RR.
 151   input_file
 152         a list of domain names to be resolved.  each line consists of a
 153         single domain name.  Example:
 154         www.example.com
 155         mx.examle.net
 156         ns.xxx.example
 157
 158 - sample-request: a simple DNS transaction client.
 159
 160   It sends a query to a specified server, and prints the response with
 161   minimal processing.  It doesn't act as a "stub resolver": it stops
 162   the processing once it gets any response from the server, whether
 163   it's a referral or an alias (CNAME or DNAME) that would require
 164   further queries to get the ultimate answer.  In other words, this
 165   utility acts as a very simplified dig.
 166
 167   Usage: sample-request [-t RRtype] server_address hostname
 168   Options and Arguments:
 169   -t RRtype
 170         specify the RR type of the queries.  The default is the A RR.
 171   server_address
 172         an IP(v4/v6) address of the recursive server to which the query is
 173         sent.
 174   hostname
 175         the domain name for the query
 176
 177 - sample-gai: getaddrinfo() and getnameinfo() test code.
 178
 179   This is a test program to check getaddrinfo() and getnameinfo()
 180   behavior.  It takes a host name as an argument, calls getaddrinfo()
 181   with the given host name, and calls getnameinfo() with the resulting
 182   IP addresses returned by getaddrinfo().  If the dns.conf file exists
 183   and defines a trust anchor, the underlying resolver will act as a
 184   validating resolver, and getaddrinfo()/getnameinfo() will fail with
 185   an EAI_INSECUREDATA error when DNSSEC validation fails.
 186
 187   Usage: sample-gai hostname
 188
 189 - sample-update: a simple dynamic update client program
 190
 191   It accepts a single update command as a command-line argument, sends
 192   an update request message to the authoritative server, and shows the
 193   response from the server.  In other words, this is a simplified
 194   nsupdate.
 195
 196   Usage: sample-update [options] (add|delete) "update data"
 197   Options and Arguments:
 198   -a auth_server
 199         An IP address of the authoritative server that has authority
 200         for the zone containing the update name.  This should normally
 201         be the primary authoritative server that accepts dynamic
 202         updates.  It can also be a secondary server that is configured
 203         to forward update requests to the primary server.
 204   -k keyfile
 205         A TSIG key file to secure the update transaction.  The keyfile
 206         format is the same as that for the nsupdate utility.
 207   -p prerequisite
 208         A prerequisite for the update (only one prerequisite can be
 209         specified).  The prerequisite format is the same as that is
 210         accepted by the nsupdate utility.
 211   -r recursive_server
 212         An IP address of a recursive server that this utility will
 213         use.  A recursive server may be necessary to identify the
 214         authoritative server address to which the update request is
 215         sent.
 216   -z zonename
 217         The domain name of the zone that contains
 218   (add|delete)
 219         Specify the type of update operation.  Either "add" or "delete"
 220         must be specified.
 221   "update data"
 222         Specify the data to be updated.  A typical example of the data
 223         would look like "name TTL RRtype RDATA".
 224
 225    Note: in practice, either -a or -r must be specified.  Others can
 226    be optional; the underlying library routine tries to identify the
 227    appropriate server and the zone name for the update.
 228
 229    Examples: assuming the primary authoritative server of the
 230    dynamic.example.com zone has an IPv6 address 2001:db8::1234,
 231    + sample-update -a sample-update -k Kxxx.+nnn+mmmm.key add "foo.dynamic.example.com 30 IN A 192.168.2.1"
 232      adds an A RR for foo.dynamic.example.com using the given key.
 233    + sample-update -a sample-update -k Kxxx.+nnn+mmmm.key delete "foo.dynamic.example.com 30 IN A"
 234      removes all A RRs for foo.dynamic.example.com using the given key.
 235    + sample-update -a sample-update -k Kxxx.+nnn+mmmm.key delete "foo.dynamic.example.com"
 236      removes all RRs for foo.dynamic.example.com using the given key.
 237
 238 - nsprobe: domain/name server checker in terms of RFC4074.
 239
 240   It checks a set of domains to see the name servers of the domains
 241   behave correctly in terms of RFC4074.  This is included in the set
 242   of sample programs to show how the export library can be used in a
 243   DNS-related application.
 244
 245   Usage: nsprobe [-d] [-v [-v...]] [-c cache_address] [input_file]
 246   Options
 247   -d
 248         run in the "debug" mode.  with this option nsprobe will dump
 249         every RRs it receives.
 250   -v
 251         increase verbosity of other normal log messages.  This can be
 252         specified multiple times
 253   -c cache_address
 254         specify an IP address of a recursive (caching) name server.
 255         nsprobe uses this server to get the NS RRset of each domain and
 256         the A and/or AAAA RRsets for the name servers.  The default
 257         value is 127.0.0.1.
 258   input_file
 259         a file name containing a list of domain (zone) names to be
 260         probed.  when omitted the standard input will be used.  Each
 261         line of the input file specifies a single domain name such as
 262         "example.com".  In general this domain name must be the apex
 263         name of some DNS zone (unlike normal "host names" such as
 264         "www.example.com").  nsprobe first identifies the NS RRsets for
 265         the given domain name, and sends A and AAAA queries to these
 266         servers for some "widely used" names under the zone;
 267         specifically, adding "www" and "ftp" to the zone name.
 268
 269 * Library References
 270
 271 As of this writing, there is no formal "manual" of the libraries,
 272 except this document, header files (some of them provide pretty
 273 detailed explanations), and sample application programs.
 274
 275 ; Id: README.libdns,v 1.3 2009/09/15 19:12:03 jinmei Exp