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