diff options
Diffstat (limited to 'doc/misc')
| -rw-r--r-- | doc/misc/Makefile.in | 48 | ||||
| -rw-r--r-- | doc/misc/dnssec | 84 | ||||
| -rw-r--r-- | doc/misc/format-options.pl | 49 | ||||
| -rw-r--r-- | doc/misc/ipv6 | 113 | ||||
| -rw-r--r-- | doc/misc/migration | 267 | ||||
| -rw-r--r-- | doc/misc/migration-4to9 | 57 | ||||
| -rw-r--r-- | doc/misc/options | 537 | ||||
| -rw-r--r-- | doc/misc/rfc-compliance | 62 | ||||
| -rw-r--r-- | doc/misc/roadmap | 47 | ||||
| -rw-r--r-- | doc/misc/sdb | 169 | ||||
| -rw-r--r-- | doc/misc/sort-options.pl | 50 |
11 files changed, 1483 insertions, 0 deletions
diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in new file mode 100644 index 0000000..501e3be --- /dev/null +++ b/doc/misc/Makefile.in @@ -0,0 +1,48 @@ +# Copyright (C) 2004, 2007 Internet Systems Consortium, Inc. ("ISC") +# Copyright (C) 2001 Internet Software Consortium. +# +# Permission to use, copy, modify, and/or distribute this software for any +# purpose with or without fee is hereby granted, provided that the above +# copyright notice and this permission notice appear in all copies. +# +# THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH +# REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +# AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, +# INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +# LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +# OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +# PERFORMANCE OF THIS SOFTWARE. + +# $Id: Makefile.in,v 1.7 2007/09/24 04:21:59 marka Exp $ + +srcdir = @srcdir@ +VPATH = @srcdir@ +top_srcdir = @top_srcdir@ + +@BIND9_MAKE_RULES@ + +PERL = @PERL@ + +MANOBJS = options + +doc man:: ${MANOBJS} + +docclean manclean maintainer-clean:: + rm -f options + +# Do not make options depend on ../../bin/tests/cfg_test, doing so +# will cause excessively clever versions of make to attempt to build +# that program right here, right now, if it is missing, which will +# cause make doc to bomb. + +CFG_TEST = ../../bin/tests/cfg_test + +options: FORCE + if test -x ${CFG_TEST} && \ + ${CFG_TEST} --named --grammar | \ + ${PERL} ${srcdir}/sort-options.pl | \ + ${PERL} ${srcdir}/format-options.pl >$@.new ; then \ + mv -f $@.new $@ ; \ + else \ + rm -f $@.new ; \ + fi diff --git a/doc/misc/dnssec b/doc/misc/dnssec new file mode 100644 index 0000000..4451e6c --- /dev/null +++ b/doc/misc/dnssec @@ -0,0 +1,84 @@ +Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") +Copyright (C) 2000-2002 Internet Software Consortium. +See COPYRIGHT in the source root or http://isc.org/copyright.html for terms. + +DNSSEC Release Notes + +This document summarizes the state of the DNSSEC implementation in +this release of BIND9. + + +OpenSSL Library Required + +To support DNSSEC, BIND 9 must be linked with version 0.9.6e or newer of +the OpenSSL library. As of BIND 9.2, the library is no longer +included in the distribution - it must be provided by the operating +system or installed separately. + +To build BIND 9 with OpenSSL, use "configure --with-openssl". If +the OpenSSL library is installed in a nonstandard location, you can +specify a path as in "configure --with-openssl=/var". + + +Key Generation and Signing + +The tools for generating DNSSEC keys and signatures are now in the +bin/dnssec directory. Documentation for these programs can be found +in doc/arm/Bv9ARM.4.html and the man pages. + +The random data used in generating DNSSEC keys and signatures comes +from either /dev/random (if the OS supports it) or keyboard input. +Alternatively, a device or file containing entropy/random data can be +specified. + + +Serving Secure Zones + +When acting as an authoritative name server, BIND9 includes KEY, SIG +and NXT records in responses as specified in RFC2535 when the request +has the DO flag set in the query. + + +Secure Resolution + +Basic support for validation of DNSSEC signatures in responses has +been implemented but should still be considered experimental. + +When acting as a caching name server, BIND9 is capable of performing +basic DNSSEC validation of positive as well as nonexistence responses. +This functionality is enabled by including a "trusted-keys" clause +in the configuration file, containing the top-level zone key of the +the DNSSEC tree. + +Validation of wildcard responses is not currently supported. In +particular, a "name does not exist" response will validate +successfully even if it does not contain the NXT records to prove the +nonexistence of a matching wildcard. + +Proof of insecure status for insecure zones delegated from secure +zones works when the zones are completely insecure. Privately +secured zones delegated from secure zones will not work in all cases, +such as when the privately secured zone is served by the same server +as an ancestor (but not parent) zone. + +Handling of the CD bit in queries is now fully implemented. Validation +is not attempted for recursive queries if CD is set. + + +Secure Dynamic Update + +Dynamic update of secure zones has been implemented, but may not be +complete. Affected NXT and SIG records are updated by the server when +an update occurs. Advanced access control is possible using the +"update-policy" statement in the zone definition. + + +Secure Zone Transfers + +BIND 9 does not implement the zone transfer security mechanisms of +RFC2535 section 5.6, and we have no plans to implement them in the +future as we consider them inferior to the use of TSIG or SIG(0) to +ensure the integrity of zone transfers. + + +$Id: dnssec,v 1.19 2004/03/05 05:04:53 marka Exp $ diff --git a/doc/misc/format-options.pl b/doc/misc/format-options.pl new file mode 100644 index 0000000..b0b8d52 --- /dev/null +++ b/doc/misc/format-options.pl @@ -0,0 +1,49 @@ +#!/usr/bin/perl +# +# Copyright (C) 2004, 2007 Internet Systems Consortium, Inc. ("ISC") +# Copyright (C) 2001 Internet Software Consortium. +# +# Permission to use, copy, modify, and/or distribute this software for any +# purpose with or without fee is hereby granted, provided that the above +# copyright notice and this permission notice appear in all copies. +# +# THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH +# REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +# AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, +# INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +# LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +# OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +# PERFORMANCE OF THIS SOFTWARE. + +# $Id: format-options.pl,v 1.5 2007/09/24 04:21:59 marka Exp $ + +print <<END; + +This is a summary of the named.conf options supported by +this version of BIND 9. + +END + +# Break long lines +while (<>) { + chomp; + s/\t/ /g; + my $line = $_; + m!^( *)!; + my $indent = $1; + my $comment = ""; + if ( $line =~ m!//.*! ) { + $comment = $&; + $line =~ s!//.*!!; + } + my $start = ""; + while (length($line) >= 79 - length($comment)) { + $_ = $line; + # this makes sure that the comment has something in front of it + $len = 75 - length($comment); + m!^(.{0,$len}) (.*)$!; + $start = $start.$1."\n"; + $line = $indent." ".$2; + } + print $start.$line.$comment."\n"; +} diff --git a/doc/misc/ipv6 b/doc/misc/ipv6 new file mode 100644 index 0000000..4060bc3 --- /dev/null +++ b/doc/misc/ipv6 @@ -0,0 +1,113 @@ +Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") +Copyright (C) 2000, 2001 Internet Software Consortium. +See COPYRIGHT in the source root or http://isc.org/copyright.html for terms. + +Currently, there are multiple interesting problems with ipv6 +implementations on various platforms. These problems range from not +being able to use ipv6 with bind9 (or in particular the ISC socket +library, contained in libisc) to listen-on lists not being respected, +to strange warnings but seemingly correct behavior of named. + +COMPILE-TIME ISSUES +------------------- + +The socket library requires a certain level of support from the +operating system. In particular, it must follow the advanced ipv6 +socket API to be usable. The systems which do not follow this will +currently not get any warnings or errors, but ipv6 will simply not +function on them. + +These systems currently include, but are not limited to: + + AIX 3.4 (with ipv6 patches) + + +RUN-TIME ISSUES +--------------- + +In the original drafts of the ipv6 RFC documents, binding an ipv6 +socket to the ipv6 wildcard address would also cause the socket to +accept ipv4 connections and datagrams. When an ipv4 packet is +received on these systems, it is mapped into an ipv6 address. For +example, 1.2.3.4 would be mapped into ::ffff:1.2.3.4. The intent of +this mapping was to make transition from an ipv4-only application into +ipv6 easier, by only requiring one socket to be open on a given port. + +Later, it was discovered that this was generally a bad idea. For one, +many firewalls will block connection to 1.2.3.4, but will let through +::ffff:1.2.3.4. This, of course, is bad. Also, access control lists +written to accept only ipv4 addresses were suddenly ignored unless +they were rewritten to handle the ipv6 mapped addresses as well. + +Partly because of these problems, the latest IPv6 API introduces an +explicit knob (the "IPV6_V6ONLY" socket option ) to turn off the ipv6 +mapped address usage. + +In bind9, we first check if both the advanced API and the IPV6_V6ONLY +socket option are available. If both of them are available, bind9 +named will bind to the ipv6 wildcard port for both TCP and UDP. +Otherwise named will make a warning and try to bind to all available +ipv6 addresses separately. + +In any case, bind9 named binds to specific addresses for ipv4 sockets. + +The followings are historical notes when we always bound to the ipv6 +wildcard port regardless of the availability of the API support. +These problems should not happen with the closer checks above. + + +IPV6 Sockets Accept IPV4, Specific IPV4 Addresses Bindings Fail +--------------------------------------------------------------- + +The only OS which seems to do this is (some kernel versions of) linux. +If an ipv6 socket is bound to the ipv6 wildcard socket, and a specific +ipv4 socket is later bound (say, to 1.2.3.4 port 53) the ipv4 binding +will fail. + +What this means to bind9 is that the application will log warnings +about being unable to bind to a socket because the address is already +in use. Since the ipv6 socket will accept ipv4 packets and map them, +however, the ipv4 addresses continue to function. + +The effect is that the config file listen-on directive will not be +respected on these systems. + + +IPV6 Sockets Accept IPV4, Specific IPV4 Address Bindings Succeed +---------------------------------------------------------------- + +In this case, the system allows opening an ipv6 wildcard address +socket and then binding to a more specific ipv4 address later. An +example of this type of system is Digital Unix with ipv6 patches +applied. + +What this means to bind9 is that the application will respect +listen-on in regards to ipv4 sockets, but it will use mapped ipv6 +addresses for any that do not match the listen-on list. This, in +effect, makes listen-on useless for these machines as well. + + +IPV6 Sockets Do Not Accept IPV4 +------------------------------- + +On these systems, opening an IPV6 socket does not implicitly open any +ipv4 sockets. An example of these systems are NetBSD-current with the +latest KAME patch, and other systems which use the latest KAME patches +as their ipv6 implementation. + +On these systems, listen-on is fully functional, as the ipv6 socket +only accepts ipv6 packets, and the ipv4 sockets will handle the ipv4 +packets. + + +RELEVANT RFCs +------------- + +3513: Internet Protocol Version 6 (IPv6) Addressing Architecture + +3493: Basic Socket Interface Extensions for IPv6 + +3542: Advanced Sockets Application Program Interface (API) for IPv6 + + +$Id: ipv6,v 1.9 2004/08/10 04:27:51 jinmei Exp $ diff --git a/doc/misc/migration b/doc/misc/migration new file mode 100644 index 0000000..21856bf --- /dev/null +++ b/doc/misc/migration @@ -0,0 +1,267 @@ +Copyright (C) 2004, 2007, 2008 Internet Systems Consortium, Inc. ("ISC") +Copyright (C) 2000, 2001, 2003 Internet Software Consortium. +See COPYRIGHT in the source root or http://isc.org/copyright.html for terms. + + BIND 8 to BIND 9 Migration Notes + +BIND 9 is designed to be mostly upwards compatible with BIND 8, but +there is still a number of caveats you should be aware of when +upgrading an existing BIND 8 installation to use BIND 9. + + +1. Configuration File Compatibility + +1.1. Unimplemented Options and Changed Defaults + +BIND 9 supports most, but not all of the named.conf options of BIND 8. +For a complete list of implemented options, see doc/misc/options. + +If your named.conf file uses an unimplemented option, named will log a +warning message. A message is also logged about each option whose +default has changed unless the option is set explicitly in named.conf. + +The default of the "transfer-format" option has changed from +"one-answer" to "many-answers". If you have slave servers that do not +understand the many-answers zone transfer format (e.g., BIND 4.9.5 or +older) you need to explicitly specify "transfer-format one-answer;" in +either the options block or a server statement. + +BIND 9.4 onwards implements "allow-query-cache". The "allow-query" +option is no longer used to specify access to the cache. The +"allow-query" option continues to specify which hosts are allowed +to ask ordinary DNS questions. The new "allow-query-cache" option +is used to specify which hosts are allowed to get answers from the +cache. Since BIND 9.4.1, if "allow-query-cache" is not set then +"allow-recursion" is used if it is set, otherwise "allow-query" is +used if it is set, otherwise the default localnets and localhost +is used. + +1.2. Handling of Configuration File Errors + +In BIND 9, named refuses to start if it detects an error in +named.conf. Earlier versions would start despite errors, causing the +server to run with a partial configuration. Errors detected during +subsequent reloads do not cause the server to exit. + +Errors in master files do not cause the server to exit, but they +do cause the zone not to load. + +1.3. Logging + +The set of logging categories in BIND 9 is different from that +in BIND 8. If you have customised your logging on a per-category +basis, you need to modify your logging statement to use the +new categories. + +Another difference is that the "logging" statement only takes effect +after the entire named.conf file has been read. This means that when +the server starts up, any messages about errors in the configuration +file are always logged to the default destination (syslog) when the +server first starts up, regardless of the contents of the "logging" +statement. In BIND 8, the new logging configuration took effect +immediately after the "logging" statement was read. + +1.4. Notify messages and Refresh queries + +The source address and port for these is now controlled by +"notify-source" and "transfer-source", respectively, rather that +query-source as in BIND 8. + +1.5. Multiple Classes. + +Multiple classes have to be put into explicit views for each class. + + +2. Zone File Compatibility + +2.1. Strict RFC1035 Interpretation of TTLs in Zone Files + +BIND 9 strictly complies with the RFC1035 and RFC2308 rules regarding +omitted TTLs in zone files. Omitted TTLs are replaced by the value +specified with the $TTL directive, or by the previous explicit TTL if +there is no $TTL directive. + +If there is no $TTL directive and the first RR in the file does not +have an explicit TTL field, the zone file is illegal according to +RFC1035 since the TTL of the first RR is undefined. Unfortunately, +BIND 4 and many versions of BIND 8 accept such files without warning +and use the value of the SOA MINTTL field as a default for missing TTL +values. + +BIND 9.0 and 9.1 completely refused to load such files. BIND 9.2 +emulates the nonstandard BIND 4/8 SOA MINTTL behaviour and loads the +files anyway (provided the SOA is the first record in the file), but +will issue the warning message "no TTL specified; using SOA MINTTL +instead". + +To avoid problems, we recommend that you use a $TTL directive in each +zone file. + +2.2. Periods in SOA Serial Numbers Deprecated + +Some versions of BIND allow SOA serial numbers with an embedded +period, like "3.002", and convert them into integers in a rather +unintuitive way. This feature is not supported by BIND 9; serial +numbers must be integers. + +2.3. Handling of Unbalanced Quotes + +TXT records with unbalanced quotes, like 'host TXT "foo', were not +treated as errors in some versions of BIND. If your zone files +contain such records, you will get potentially confusing error +messages like "unexpected end of file" because BIND 9 will interpret +everything up to the next quote character as a literal string. + +2.4. Handling of Line Breaks + +Some versions of BIND accept RRs containing line breaks that are not +properly quoted with parentheses, like the following SOA: + + @ IN SOA ns.example. hostmaster.example. + ( 1 3600 1800 1814400 3600 ) + +This is not legal master file syntax and will be treated as an error +by BIND 9. The fix is to move the opening parenthesis to the first +line. + +2.5. Unimplemented BIND 8 Extensions + +$GENERATE: The "$$" construct for getting a literal $ into a domain +name is deprecated. Use \$ instead. + +2.6. TXT records are no longer automatically split. + +Some versions of BIND accepted strings in TXT RDATA consisting of more +than 255 characters and silently split them to be able to encode the +strings in a protocol conformant way. You may now see errors like this + dns_rdata_fromtext: local.db:119: ran out of space +if you have TXT RRs with too longs strings. Make sure to split the +string in the zone data file at or before a single one reaches 255 +characters. + +3. Interoperability Impact of New Protocol Features + +3.1. EDNS0 + +BIND 9 uses EDNS0 (RFC2671) to advertise its receive buffer size. It +also sets DO EDNS flag bit in queries to indicate that it wishes to +receive DNSSEC responses. + +Most older servers that do not support EDNS0, including prior versions +of BIND, will send a FORMERR or NOTIMP response to these queries. +When this happens, BIND 9 will automatically retry the query without +EDNS0. + +Unfortunately, there exists at least one non-BIND name server +implementation that silently ignores these queries instead of sending +an error response. Resolving names in zones where all or most +authoritative servers use this server will be very slow or fail +completely. We have contacted the manufacturer of the name server in +case, and they are working on a solution. + +When BIND 9 communicates with a server that does support EDNS0, such as +another BIND 9 server, responses of up to 4096 bytes may be +transmitted as a single UDP datagram which is subject to fragmentation +at the IP level. If a firewall incorrectly drops IP fragments, it can +cause resolution to slow down dramatically or fail. + +3.2. Zone Transfers + +Outgoing zone transfers now use the "many-answers" format by default. +This format is not understood by certain old versions of BIND 4. +You can work around this problem using the option "transfer-format +one-answer;", but since these old versions all have known security +problems, the correct fix is to upgrade the slave servers. + +Zone transfers to Windows 2000 DNS servers sometimes fail due to a +bug in the Windows 2000 DNS server where DNS messages larger than +16K are not handled properly. Obtain the latest service pack for +Windows 2000 from Microsoft to address this issue. In the meantime, +the problem can be worked around by setting "transfer-format one-answer;". +http://support.microsoft.com/default.aspx?scid=kb;en-us;297936 + +4. Unrestricted Character Set + + BIND 9.2 only + +BIND 9 does not restrict the character set of domain names - it is +fully 8-bit clean in accordance with RFC2181 section 11. + +It is strongly recommended that hostnames published in the DNS follow +the RFC952 rules, but BIND 9 will not enforce this restriction. + +Historically, some applications have suffered from security flaws +where data originating from the network, such as names returned by +gethostbyaddr(), are used with insufficient checking and may cause a +breach of security when containing unexpected characters; see +<http://www.cert.org/advisories/CA-96.04.corrupt_info_from_servers.html> +for details. Some earlier versions of BIND attempt to protect these +flawed applications from attack by discarding data containing +characters deemed inappropriate in host names or mail addresses, under +the control of the "check-names" option in named.conf and/or "options +no-check-names" in resolv.conf. BIND 9 provides no such protection; +if applications with these flaws are still being used, they should +be upgraded. + + BIND 9.3 onwards implements check-names. + +5. Server Administration Tools + +5.1 Ndc Replaced by Rndc + +The "ndc" program has been replaced by "rndc", which is capable of +remote operation. Unlike ndc, rndc requires a configuration file. +The easiest way to generate a configuration file is to run +"rndc-confgen -a"; see the man pages for rndc(8), rndc-confgen(8), +and rndc.conf(5) for details. + +5.2. Nsupdate Differences + +The BIND 8 implementation of nsupdate had an undocumented feature +where an update request would be broken down into multiple requests +based upon the discovered zones that contained the records. This +behaviour has not been implemented in BIND 9. Each update request +must pertain to a single zone, but it is still possible to do multiple +updates in a single invocation of nsupdate by terminating each update +with an empty line or a "send" command. + + +6. No Information Leakage between Zones + +BIND 9 stores the authoritative data for each zone in a separate data +structure, as recommended in RFC1035 and as required by DNSSEC and +IXFR. When a BIND 9 server is authoritative for both a child zone and +its parent, it will have two distinct sets of NS records at the +delegation point: the authoritative NS records at the child's apex, +and a set of glue NS records in the parent. + +BIND 8 was unable to properly distinguish between these two sets of NS +records and would "leak" the child's NS records into the parent, +effectively causing the parent zone to be silently modified: responses +and zone transfers from the parent contained the child's NS records +rather than the glue configured into the parent (if any). In the case +of children of type "stub", this behaviour was documented as a feature, +allowing the glue NS records to be omitted from the parent +configuration. + +Sites that were relying on this BIND 8 behaviour need to add any +omitted glue NS records, and any necessary glue A records, to the +parent zone. + +Although stub zones can no longer be used as a mechanism for injecting +NS records into their parent zones, they are still useful as a way of +directing queries for a given domain to a particular set of name +servers. + + +7. Umask not Modified + +The BIND 8 named unconditionally sets the umask to 022. BIND 9 does +not; the umask inherited from the parent process remains in effect. +This may cause files created by named, such as journal files, to be +created with different file permissions than they did in BIND 8. If +necessary, the umask should be set explicitly in the script used to +start the named process. + + +$Id: migration,v 1.49 2008/03/18 15:42:53 jreed Exp $ diff --git a/doc/misc/migration-4to9 b/doc/misc/migration-4to9 new file mode 100644 index 0000000..008cbed --- /dev/null +++ b/doc/misc/migration-4to9 @@ -0,0 +1,57 @@ +Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") +Copyright (C) 2001 Internet Software Consortium. +See COPYRIGHT in the source root or http://isc.org/copyright.html for terms. + +$Id: migration-4to9,v 1.4 2004/03/05 05:04:53 marka Exp $ + + BIND 4 to BIND 9 Migration Notes + +To transition from BIND 4 to BIND 9 you first need to convert your +configuration file to the new format. There is a conversion tool in +contrib/named-bootconf that allows you to do this. + + named-bootconf.sh < /etc/named.boot > /etc/named.conf + +BIND 9 uses a system assigned port for the UDP queries it makes rather +than port 53 that BIND 4 uses. This may conflict with some firewalls. +The following directives in /etc/named.conf allows you to specify +a port to use. + + query-source address * port 53; + transfer-source * port 53; + notify-source * port 53; + +BIND 9 no longer uses the minimum field to specify the TTL of records +without a explicit TTL. Use the $TTL directive to specify a default TTL +before the first record without a explicit TTL. + + $TTL 3600 + @ IN SOA ns1.example.com. hostmaster.example.com. ( + 2001021100 + 7200 + 1200 + 3600000 + 7200 ) + +BIND 9 does not support multiple CNAMEs with the same owner name. + + Illegal: + www.example.com. CNAME host1.example.com. + www.example.com. CNAME host2.example.com. + +BIND 9 does not support "CNAMEs with other data" with the same owner name, +ignoring the DNSSEC records (SIG, NXT, KEY) that BIND 4 did not support. + + Illegal: + www.example.com. CNAME host1.example.com. + www.example.com. MX 10 host2.example.com. + +BIND 9 is less tolerant of errors in master files, so check your logs and +fix any errors reported. The named-checkzone program can also be to check +master files. + +Outgoing zone transfers now use the "many-answers" format by default. +This format is not understood by certain old versions of BIND 4. +You can work around this problem using the option "transfer-format +one-answer;", but since these old versions all have known security +problems, the correct fix is to upgrade the slave servers. diff --git a/doc/misc/options b/doc/misc/options new file mode 100644 index 0000000..3416a3b --- /dev/null +++ b/doc/misc/options @@ -0,0 +1,537 @@ + +This is a summary of the named.conf options supported by +this version of BIND 9. + +acl <string> { <address_match_element>; ... }; + +controls { + inet ( <ipv4_address> | <ipv6_address> | * ) [ port ( <integer> | * + ) ] allow { <address_match_element>; ... } [ keys { <string>; + ... } ]; + unix <quoted_string> perm <integer> owner <integer> group <integer> + [ keys { <string>; ... } ]; +}; + +dlz <string> { + database <string>; +}; + +key <string> { + algorithm <string>; + secret <string>; +}; + +logging { + category <string> { <string>; ... }; + channel <string> { + file <quoted_string> [ versions ( "unlimited" | <integer> ) + ] [ size <size> ]; + null; + print-category <boolean>; + print-severity <boolean>; + print-time <boolean>; + severity <log_severity>; + stderr; + syslog <optional_facility>; + }; +}; + +lwres { + listen-on [ port <integer> ] { ( <ipv4_address> | <ipv6_address> ) + [ port <integer> ]; ... }; + ndots <integer>; + search { <string>; ... }; + view <string> <optional_class>; +}; + +masters <string> [ port <integer> ] { ( <masters> | <ipv4_address> [ port + <integer> ] | <ipv6_address> [ port <integer> ] ) [ key <string> ]; ... }; + +options { + acache-cleaning-interval <integer>; + acache-enable <boolean>; + additional-from-auth <boolean>; + additional-from-cache <boolean>; + allow-notify { <address_match_element>; ... }; + allow-query { <address_match_element>; ... }; + allow-query-cache { <address_match_element>; ... }; + allow-query-cache-on { <address_match_element>; ... }; + allow-query-on { <address_match_element>; ... }; + allow-recursion { <address_match_element>; ... }; + allow-recursion-on { <address_match_element>; ... }; + allow-transfer { <address_match_element>; ... }; + allow-update { <address_match_element>; ... }; + allow-update-forwarding { <address_match_element>; ... }; + allow-v6-synthesis { <address_match_element>; ... }; // obsolete + also-notify [ port <integer> ] { ( <ipv4_address> | <ipv6_address> + ) [ port <integer> ]; ... }; + alt-transfer-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ]; + alt-transfer-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | + * ) ]; + auth-nxdomain <boolean>; // default changed + avoid-v4-udp-ports { <portrange>; ... }; + avoid-v6-udp-ports { <portrange>; ... }; + blackhole { <address_match_element>; ... }; + cache-file <quoted_string>; + check-integrity <boolean>; + check-mx ( fail | warn | ignore ); + check-mx-cname ( fail | warn | ignore ); + check-names ( master | slave | response ) ( fail | warn | ignore ); + check-sibling <boolean>; + check-srv-cname ( fail | warn | ignore ); + check-wildcard <boolean>; + cleaning-interval <integer>; + clients-per-query <integer>; + coresize <size>; + datasize <size>; + deallocate-on-exit <boolean>; // obsolete + dialup <dialuptype>; + directory <quoted_string>; + disable-algorithms <string> { <string>; ... }; + disable-empty-zone <string>; + dnssec-accept-expired <boolean>; + dnssec-enable <boolean>; + dnssec-lookaside <string> trust-anchor <string>; + dnssec-must-be-secure <string> <boolean>; + dnssec-validation <boolean>; + dual-stack-servers [ port <integer> ] { ( <quoted_string> [ port + <integer> ] | <ipv4_address> [ port <integer> ] | + <ipv6_address> [ port <integer> ] ); ... }; + dump-file <quoted_string>; + edns-udp-size <integer>; + empty-contact <string>; + empty-server <string>; + empty-zones-enable <boolean>; + fake-iquery <boolean>; // obsolete + fetch-glue <boolean>; // obsolete + files <size>; + flush-zones-on-shutdown <boolean>; + forward ( first | only ); + forwarders [ port <integer> ] { ( <ipv4_address> | <ipv6_address> ) + [ port <integer> ]; ... }; + has-old-clients <boolean>; // obsolete + heartbeat-interval <integer>; + host-statistics <boolean>; // not implemented + host-statistics-max <integer>; // not implemented + hostname ( <quoted_string> | none ); + interface-interval <integer>; + ixfr-from-differences <ixfrdiff>; + key-directory <quoted_string>; + lame-ttl <integer>; + listen-on [ port <integer> ] { <address_match_element>; ... }; + listen-on-v6 [ port <integer> ] { <address_match_element>; ... }; + maintain-ixfr-base <boolean>; // obsolete + masterfile-format ( text | raw ); + match-mapped-addresses <boolean>; + max-acache-size <size_no_default>; + max-cache-size <size_no_default>; + max-cache-ttl <integer>; + max-clients-per-query <integer>; + max-ixfr-log-size <size>; // obsolete + max-journal-size <size_no_default>; + max-ncache-ttl <integer>; + max-refresh-time <integer>; + max-retry-time <integer>; + max-transfer-idle-in <integer>; + max-transfer-idle-out <integer>; + max-transfer-time-in <integer>; + max-transfer-time-out <integer>; + max-udp-size <integer>; + memstatistics <boolean>; + memstatistics-file <quoted_string>; + min-refresh-time <integer>; + min-retry-time <integer>; + min-roots <integer>; // not implemented + minimal-responses <boolean>; + multi-master <boolean>; + multiple-cnames <boolean>; // obsolete + named-xfer <quoted_string>; // obsolete + notify <notifytype>; + notify-delay <integer>; + notify-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ]; + notify-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ]; + notify-to-soa <boolean>; + nsec3-test-zone <boolean>; // test only + pid-file ( <quoted_string> | none ); + port <integer>; + preferred-glue <string>; + provide-ixfr <boolean>; + query-source <querysource4>; + query-source-v6 <querysource6>; + querylog <boolean>; + queryport-pool-ports <integer>; // obsolete + queryport-pool-updateinterval <integer>; // obsolete + random-device <quoted_string>; + recursing-file <quoted_string>; + recursion <boolean>; + recursive-clients <integer>; + request-ixfr <boolean>; + request-nsid <boolean>; + reserved-sockets <integer>; + rfc2308-type1 <boolean>; // not yet implemented + root-delegation-only [ exclude { <quoted_string>; ... } ]; + rrset-order { [ class <string> ] [ type <string> ] [ name + <quoted_string> ] <string> <string>; ... }; + serial-queries <integer>; // obsolete + serial-query-rate <integer>; + server-id ( <quoted_string> | none |; + sig-signing-nodes <integer>; + sig-signing-signatures <integer>; + sig-signing-type <integer>; + sig-validity-interval <integer> [ <integer> ]; + sortlist { <address_match_element>; ... }; + stacksize <size>; + statistics-file <quoted_string>; + statistics-interval <integer>; // not yet implemented + suppress-initial-notify <boolean>; // not yet implemented + tcp-clients <integer>; + tcp-listen-queue <integer>; + tkey-dhkey <quoted_string> <integer>; + tkey-domain <quoted_string>; + tkey-gssapi-credential <quoted_string>; + topology { <address_match_element>; ... }; // not implemented + transfer-format ( many-answers | one-answer ); + transfer-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ]; + transfer-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ]; + transfers-in <integer>; + transfers-out <integer>; + transfers-per-ns <integer>; + treat-cr-as-space <boolean>; // obsolete + try-tcp-refresh <boolean>; + update-check-ksk <boolean>; + use-alt-transfer-source <boolean>; + use-id-pool <boolean>; // obsolete + use-ixfr <boolean>; + use-queryport-pool <boolean>; // obsolete + use-v4-udp-ports { <portrange>; ... }; + use-v6-udp-ports { <portrange>; ... }; + version ( <quoted_string> | none ); + zero-no-soa-ttl <boolean>; + zero-no-soa-ttl-cache <boolean>; + zone-statistics <boolean>; +}; + +server <netprefix> { + bogus <boolean>; + edns <boolean>; + edns-udp-size <integer>; + keys <server_key>; + max-udp-size <integer>; + notify-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ]; + notify-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ]; + provide-ixfr <boolean>; + query-source <querysource4>; + query-source-v6 <querysource6>; + request-ixfr <boolean>; + support-ixfr <boolean>; // obsolete + transfer-format ( many-answers | one-answer ); + transfer-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ]; + transfer-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ]; + transfers <integer>; +}; + +statistics-channels { + inet ( <ipv4_address> | <ipv6_address> | * ) [ port ( <integer> | * + ) ] [ allow { <address_match_element>; ... } ]; +}; + +trusted-keys { <string> <integer> <integer> <integer> <quoted_string>; ... }; + +view <string> <optional_class> { + acache-cleaning-interval <integer>; + acache-enable <boolean>; + additional-from-auth <boolean>; + additional-from-cache <boolean>; + allow-notify { <address_match_element>; ... }; + allow-query { <address_match_element>; ... }; + allow-query-cache { <address_match_element>; ... }; + allow-query-cache-on { <address_match_element>; ... }; + allow-query-on { <address_match_element>; ... }; + allow-recursion { <address_match_element>; ... }; + allow-recursion-on { <address_match_element>; ... }; + allow-transfer { <address_match_element>; ... }; + allow-update { <address_match_element>; ... }; + allow-update-forwarding { <address_match_element>; ... }; + allow-v6-synthesis { <address_match_element>; ... }; // obsolete + also-notify [ port <integer> ] { ( <ipv4_address> | <ipv6_address> + ) [ port <integer> ]; ... }; + alt-transfer-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ]; + alt-transfer-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | + * ) ]; + auth-nxdomain <boolean>; // default changed + cache-file <quoted_string>; + check-integrity <boolean>; + check-mx ( fail | warn | ignore ); + check-mx-cname ( fail | warn | ignore ); + check-names ( master | slave | response ) ( fail | warn | ignore ); + check-sibling <boolean>; + check-srv-cname ( fail | warn | ignore ); + check-wildcard <boolean>; + cleaning-interval <integer>; + clients-per-query <integer>; + database <string>; + dialup <dialuptype>; + disable-algorithms <string> { <string>; ... }; + disable-empty-zone <string>; + dlz <string> { + database <string>; + }; + dnssec-accept-expired <boolean>; + dnssec-enable <boolean>; + dnssec-lookaside <string> trust-anchor <string>; + dnssec-must-be-secure <string> <boolean>; + dnssec-validation <boolean>; + dual-stack-servers [ port <integer> ] { ( <quoted_string> [ port + <integer> ] | <ipv4_address> [ port <integer> ] | + <ipv6_address> [ port <integer> ] ); ... }; + edns-udp-size <integer>; + empty-contact <string>; + empty-server <string>; + empty-zones-enable <boolean>; + fetch-glue <boolean>; // obsolete + forward ( first | only ); + forwarders [ port <integer> ] { ( <ipv4_address> | <ipv6_address> ) + [ port <integer> ]; ... }; + ixfr-from-differences <ixfrdiff>; + key <string> { + algorithm <string>; + secret <string>; + }; + key-directory <quoted_string>; + lame-ttl <integer>; + maintain-ixfr-base <boolean>; // obsolete + masterfile-format ( text | raw ); + match-clients { <address_match_element>; ... }; + match-destinations { <address_match_element>; ... }; + match-recursive-only <boolean>; + max-acache-size <size_no_default>; + max-cache-size <size_no_default>; + max-cache-ttl <integer>; + max-clients-per-query <integer>; + max-ixfr-log-size <size>; // obsolete + max-journal-size <size_no_default>; + max-ncache-ttl <integer>; + max-refresh-time <integer>; + max-retry-time <integer>; + max-transfer-idle-in <integer>; + max-transfer-idle-out <integer>; + max-transfer-time-in <integer>; + max-transfer-time-out <integer>; + max-udp-size <integer>; + min-refresh-time <integer>; + min-retry-time <integer>; + min-roots <integer>; // not implemented + minimal-responses <boolean>; + multi-master <boolean>; + notify <notifytype>; + notify-delay <integer>; + notify-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ]; + notify-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ]; + notify-to-soa <boolean>; + nsec3-test-zone <boolean>; // test only + preferred-glue <string>; + provide-ixfr <boolean>; + query-source <querysource4>; + query-source-v6 <querysource6>; + queryport-pool-ports <integer>; // obsolete + queryport-pool-updateinterval <integer>; // obsolete + recursion <boolean>; + request-ixfr <boolean>; + request-nsid <boolean>; + rfc2308-type1 <boolean>; // not yet implemented + root-delegation-only [ exclude { <quoted_string>; ... } ]; + rrset-order { [ class <string> ] [ type <string> ] [ name + <quoted_string> ] <string> <string>; ... }; + server <netprefix> { + bogus <boolean>; + edns <boolean>; + edns-udp-size <integer>; + keys <server_key>; + max-udp-size <integer>; + notify-source ( <ipv4_address> | * ) [ port ( <integer> | * + ) ]; + notify-source-v6 ( <ipv6_address> | * ) [ port ( <integer> + | * ) ]; + provide-ixfr <boolean>; + query-source <querysource4>; + query-source-v6 <querysource6>; + request-ixfr <boolean>; + support-ixfr <boolean>; // obsolete + transfer-format ( many-answers | one-answer ); + transfer-source ( <ipv4_address> | * ) [ port ( <integer> | + * ) ]; + transfer-source-v6 ( <ipv6_address> | * ) [ port ( + <integer> | * ) ]; + transfers <integer>; + }; + sig-signing-nodes <integer>; + sig-signing-signatures <integer>; + sig-signing-type <integer>; + sig-validity-interval <integer> [ <integer> ]; + sortlist { <address_match_element>; ... }; + suppress-initial-notify <boolean>; // not yet implemented + topology { <address_match_element>; ... }; // not implemented + transfer-format ( many-answers | one-answer ); + transfer-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ]; + transfer-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ]; + trusted-keys { <string> <integer> <integer> <integer> + <quoted_string>; ... }; + try-tcp-refresh <boolean>; + update-check-ksk <boolean>; + use-alt-transfer-source <boolean>; + use-queryport-pool <boolean>; // obsolete + zero-no-soa-ttl <boolean>; + zero-no-soa-ttl-cache <boolean>; + zone <string> <optional_class> { + allow-notify { <address_match_element>; ... }; + allow-query { <address_match_element>; ... }; + allow-query-on { <address_match_element>; ... }; + allow-transfer { <address_match_element>; ... }; + allow-update { <address_match_element>; ... }; + allow-update-forwarding { <address_match_element>; ... }; + also-notify [ port <integer> ] { ( <ipv4_address> | + <ipv6_address> ) [ port <integer> ]; ... }; + alt-transfer-source ( <ipv4_address> | * ) [ port ( + <integer> | * ) ]; + alt-transfer-source-v6 ( <ipv6_address> | * ) [ port ( + <integer> | * ) ]; + check-integrity <boolean>; + check-mx ( fail | warn | ignore ); + check-mx-cname ( fail | warn | ignore ); + check-names ( fail | warn | ignore ); + check-sibling <boolean>; + check-srv-cname ( fail | warn | ignore ); + check-wildcard <boolean>; + database <string>; + delegation-only <boolean>; + dialup <dialuptype>; + file <quoted_string>; + forward ( first | only ); + forwarders [ port <integer> ] { ( <ipv4_address> | + <ipv6_address> ) [ port <integer> ]; ... }; + ixfr-base <quoted_string>; // obsolete + ixfr-from-differences <boolean>; + ixfr-tmp-file <quoted_string>; // obsolete + journal <quoted_string>; + key-directory <quoted_string>; + maintain-ixfr-base <boolean>; // obsolete + masterfile-format ( text | raw ); + masters [ port <integer> ] { ( <masters> | <ipv4_address> [ + port <integer> ] | <ipv6_address> [ port <integer> ] ) + [ key <string> ]; ... }; + max-ixfr-log-size <size>; // obsolete + max-journal-size <size_no_default>; + max-refresh-time <integer>; + max-retry-time <integer>; + max-transfer-idle-in <integer>; + max-transfer-idle-out <integer>; + max-transfer-time-in <integer>; + max-transfer-time-out <integer>; + min-refresh-time <integer>; + min-retry-time <integer>; + multi-master <boolean>; + notify <notifytype>; + notify-delay <integer>; + notify-source ( <ipv4_address> | * ) [ port ( <integer> | * + ) ]; + notify-source-v6 ( <ipv6_address> | * ) [ port ( <integer> + | * ) ]; + notify-to-soa <boolean>; + nsec3-test-zone <boolean>; // test only + pubkey <integer> <integer> <integer> + <quoted_string>; // obsolete + sig-signing-nodes <integer>; + sig-signing-signatures <integer>; + sig-signing-type <integer>; + sig-validity-interval <integer> [ <integer> ]; + transfer-source ( <ipv4_address> | * ) [ port ( <integer> | + * ) ]; + transfer-source-v6 ( <ipv6_address> | * ) [ port ( + <integer> | * ) ]; + try-tcp-refresh <boolean>; + type ( master | slave | stub | hint | forward | + delegation-only ); + update-check-ksk <boolean>; + update-policy { ( grant | deny ) <string> ( name | + subdomain | wildcard | self | selfsub | selfwild | + krb5-self | ms-self | krb5-subdomain | ms-subdomain | + tcp-self | 6to4-self ) <string> <rrtypelist>; ... }; + use-alt-transfer-source <boolean>; + zero-no-soa-ttl <boolean>; + zone-statistics <boolean>; + }; + zone-statistics <boolean>; +}; + +zone <string> <optional_class> { + allow-notify { <address_match_element>; ... }; + allow-query { <address_match_element>; ... }; + allow-query-on { <address_match_element>; ... }; + allow-transfer { <address_match_element>; ... }; + allow-update { <address_match_element>; ... }; + allow-update-forwarding { <address_match_element>; ... }; + also-notify [ port <integer> ] { ( <ipv4_address> | <ipv6_address> + ) [ port <integer> ]; ... }; + alt-transfer-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ]; + alt-transfer-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | + * ) ]; + check-integrity <boolean>; + check-mx ( fail | warn | ignore ); + check-mx-cname ( fail | warn | ignore ); + check-names ( fail | warn | ignore ); + check-sibling <boolean>; + check-srv-cname ( fail | warn | ignore ); + check-wildcard <boolean>; + database <string>; + delegation-only <boolean>; + dialup <dialuptype>; + file <quoted_string>; + forward ( first | only ); + forwarders [ port <integer> ] { ( <ipv4_address> | <ipv6_address> ) + [ port <integer> ]; ... }; + ixfr-base <quoted_string>; // obsolete + ixfr-from-differences <boolean>; + ixfr-tmp-file <quoted_string>; // obsolete + journal <quoted_string>; + key-directory <quoted_string>; + maintain-ixfr-base <boolean>; // obsolete + masterfile-format ( text | raw ); + masters [ port <integer> ] { ( <masters> | <ipv4_address> [ port + <integer> ] | <ipv6_address> [ port <integer> ] ) [ key + <string> ]; ... }; + max-ixfr-log-size <size>; // obsolete + max-journal-size <size_no_default>; + max-refresh-time <integer>; + max-retry-time <integer>; + max-transfer-idle-in <integer>; + max-transfer-idle-out <integer>; + max-transfer-time-in <integer>; + max-transfer-time-out <integer>; + min-refresh-time <integer>; + min-retry-time <integer>; + multi-master <boolean>; + notify <notifytype>; + notify-delay <integer>; + notify-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ]; + notify-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ]; + notify-to-soa <boolean>; + nsec3-test-zone <boolean>; // test only + pubkey <integer> <integer> <integer> <quoted_string>; // obsolete + sig-signing-nodes <integer>; + sig-signing-signatures <integer>; + sig-signing-type <integer>; + sig-validity-interval <integer> [ <integer> ]; + transfer-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ]; + transfer-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ]; + try-tcp-refresh <boolean>; + type ( master | slave | stub | hint | forward | delegation-only ); + update-check-ksk <boolean>; + update-policy { ( grant | deny ) <string> ( name | subdomain | + wildcard | self | selfsub | selfwild | krb5-self | ms-self | + krb5-subdomain | ms-subdomain | tcp-self | 6to4-self ) <string> + <rrtypelist>; ... }; + use-alt-transfer-source <boolean>; + zero-no-soa-ttl <boolean>; + zone-statistics <boolean>; +}; + diff --git a/doc/misc/rfc-compliance b/doc/misc/rfc-compliance new file mode 100644 index 0000000..4c87c66 --- /dev/null +++ b/doc/misc/rfc-compliance @@ -0,0 +1,62 @@ +Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") +Copyright (C) 2001 Internet Software Consortium. +See COPYRIGHT in the source root or http://isc.org/copyright.html for terms. + +$Id: rfc-compliance,v 1.4 2004/03/05 05:04:53 marka Exp $ + +BIND 9 is striving for strict compliance with IETF standards. We +believe this release of BIND 9 complies with the following RFCs, with +the caveats and exceptions listed in the numbered notes below. Note +that a number of these RFCs do not have the status of Internet +standards but are proposed or draft standards, experimental RFCs, +or Best Current Practice (BCP) documents. + + RFC1034 + RFC1035 [1] [2] + RFC1123 + RFC1183 + RFC1535 + RFC1536 + RFC1706 + RFC1712 + RFC1750 + RFC1876 + RFC1982 + RFC1995 + RFC1996 + RFC2136 + RFC2163 + RFC2181 + RFC2230 + RFC2308 + RFC2535 [3] [4] + RFC2536 + RFC2537 + RFC2538 + RFC2539 + RFC2671 + RFC2672 + RFC2673 + RFC2782 + RFC2915 + RFC2930 + RFC2931 [5] + RFC3007 + + +[1] Queries to zones that have failed to load return SERVFAIL rather +than a non-authoritative response. This is considered a feature. + +[2] CLASS ANY queries are not supported. This is considered a feature. + +[3] Wildcard records are not supported in DNSSEC secure zones. + +[4] Servers authoritative for secure zones being resolved by BIND 9 +must support EDNS0 (RFC2671), and must return all relevant SIGs and +NXTs in responses rather than relying on the resolving server to +perform separate queries for missing SIGs and NXTs. + +[5] When receiving a query signed with a SIG(0), the server will only +be able to verify the signature if it has the key in its local +authoritative data; it will not do recursion or validation to +retrieve unknown keys. diff --git a/doc/misc/roadmap b/doc/misc/roadmap new file mode 100644 index 0000000..f63a469 --- /dev/null +++ b/doc/misc/roadmap @@ -0,0 +1,47 @@ +Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") +Copyright (C) 2000, 2001 Internet Software Consortium. +See COPYRIGHT in the source root or http://isc.org/copyright.html for terms. + +$Id: roadmap,v 1.2 2004/03/05 05:04:54 marka Exp $ + +Road Map to the BIND 9 Source Tree + +bin/named The name server. This relies heavily on the + libraries in lib/isc and lib/dns. + client.c Handling of incoming client requests + query.c Query processing +bin/rndc The remote name daemon control program +bin/dig The "dig" program +bin/dnssec The DNSSEC signer and other DNSSEC tools +bin/nsupdate The "nsupdate" program +bin/tests Test suites and miscellaneous test programs +bin/tests/system System tests; see bin/tests/system/README +lib/dns The DNS library + resolver.c The "full resolver" (performs recursive lookups) + validator.c The DNSSEC validator + db.c The database interface + sdb.c The simple database interface + rbtdb.c The red-black tree database +lib/dns/rdata Routines for handling the various RR types +lib/dns/sec Cryptographic libraries for DNSSEC +lib/isc The ISC library + task.c Task library + unix/socket.c Unix implementation of socket library +lib/isccfg Routines for reading and writing ISC-style + configuration files like named.conf and rndc.conf +lib/isccc The command channel library, used by rndc. +lib/tests Support code for the test suites. +lib/lwres The lightweight resolver library. +doc/draft Current internet-drafts pertaining to the DNS +doc/rfc RFCs pertaining to the DNS +doc/misc Miscellaneous documentation +doc/arm The BIND 9 Administrator Reference Manual +doc/man Man pages +contrib Contributed and other auxiliary code +contrib/idn/mdnkit The multilingual domain name evaluation kit +contrib/sdb Sample drivers for the simple database interface +make Makefile fragments, used by configure + +The library interfaces are mainly documented in the form of comments +in the header files. For example, the task subsystem is documented in +lib/isc/include/isc/task.h diff --git a/doc/misc/sdb b/doc/misc/sdb new file mode 100644 index 0000000..552028a --- /dev/null +++ b/doc/misc/sdb @@ -0,0 +1,169 @@ +Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") +Copyright (C) 2000, 2001 Internet Software Consortium. +See COPYRIGHT in the source root or http://isc.org/copyright.html for terms. + +Using the BIND 9 Simplified Database Interface + +This document describes the care and feeding of the BIND 9 Simplified +Database Interface, which allows you to extend BIND 9 with new ways +of obtaining the data that is published as DNS zones. + + +The Original BIND 9 Database Interface + +BIND 9 has a well-defined "back-end database interface" that makes it +possible to replace the component of the name server responsible for +the storage and retrieval of zone data, called the "database", on a +per-zone basis. The default database is an in-memory, red-black-tree +data structure commonly referred to as "rbtdb", but it is possible to +write drivers to support any number of alternative database +technologies such as in-memory hash tables, application specific +persistent on-disk databases, object databases, or relational +databases. + +The original BIND 9 database interface defined in <dns/db.h> is +designed to efficiently support the full set of database functionality +needed by a name server that implements the complete DNS protocols, +including features such as zone transfers, dynamic update, and DNSSEC. +Each of these aspects of name server operations places its own set of +demands on the data store, with the result that the database API is +quite complex and contains operations that are highly specific to the +DNS. For example, data are stored in a binary format, the name space +is tree structured, and sets of data records are conceptually +associated with DNSSEC signature sets. For these reasons, writing a +driver using this interface is a highly nontrivial undertaking. + + +The Simplified Database Interface + +Many BIND users wish to provide access to various data sources through +the DNS, but are not necessarily interested in completely replacing +the in-memory "rbt" database or in supporting features like dynamic +update, DNSSEC, or even zone transfers. + +Often, all you want is limited, read-only DNS access to an existing +system. For example, you may have an existing relational database +containing hostname/address mappings and wish to provide forvard and +reverse DNS lookups based on this information. Or perhaps you want to +set up a simple DNS-based load balancing system where the name server +answers queries about a single DNS name with a dynamically changing +set of A records. + +BIND 9.1 introduced a new, simplified database interface, or "sdb", +which greatly simplifies the writing of drivers for these kinds of +applications. + + +The sdb Driver + +An sdb driver is an object module, typically written in C, which is +linked into the name server and registers itself with the sdb +subsystem. It provides a set of callback functions, which also serve +to advertise its capabilities. When the name server receives DNS +queries, invokes the callback functions to obtain the data to respond +with. + +Unlike the full database interface, the sdb interface represents all +domain names and resource records as ASCII text. + + +Writing an sdb Driver + +When a driver is registered, it specifies its name, a list of callback +functions, and flags. + +The flags specify whether the driver wants to use relative domain +names where possible. + +The callback functions are as follows. The only one that must be +defined is lookup(). + + - create(zone, argc, argv, driverdata, dbdata) + Create a database object for "zone". + + - destroy(zone, driverdata, dbdata) + Destroy the database object for "zone". + + - lookup(zone, name, dbdata, lookup) + Return all the records at the domain name "name". + + - authority(zone, dbdata, lookup) + Return the SOA and NS records at the zone apex. + + - allnodes(zone, dbdata, allnodes) + Return all data in the zone, for zone transfers. + +For more detail about these functions and their parameters, see +bind9/lib/dns/include/dns/sdb.h. For example drivers, see +bind9/contrib/sdb. + + +Rebuilding the Server + +The driver module and header file must be copied to (or linked into) +the bind9/bin/named and bind9/bin/named/include directories +respectively, and must be added to the DBDRIVER_OBJS and DBDRIVER_SRCS +lines in bin/named/Makefile.in (e.g. for the timedb sample sdb driver, +add timedb.c to DBDRIVER_SRCS and timedb.@O@ to DBDRIVER_OBJS). If +the driver needs additional header files or libraries in nonstandard +places, the DBDRIVER_INCLUDES and DBDRIVER_LIBS lines should also be +updated. + +Calls to dns_sdb_register() and dns_sdb_unregister() (or wrappers, +e.g. timedb_init() and timedb_clear() for the timedb sample sdb +driver) must be inserted into the server, in bind9/bin/named/main.c. +Registration should be in setup(), before the call to +ns_server_create(). Unregistration should be in cleanup(), +after the call to ns_server_destroy(). A #include should be added +corresponding to the driver header file. + +You should try doing this with one or more of the sample drivers +before attempting to write a driver of your own. + + +Configuring the Server + +To make a zone use a new database driver, specify a "database" option +in its "zone" statement in named.conf. For example, if the driver +registers itself under the name "acmedb", you might say + + zone "foo.com" { + database "acmedb"; + }; + +You can pass arbitrary arguments to the create() function of the +driver by adding any number of whitespace-separated words after the +driver name: + + zone "foo.com" { + database "acmedb -mode sql -connect 10.0.0.1"; + }; + + +Hints for Driver Writers + + - If a driver is generating data on the fly, it probably should + not implement the allnodes() function, since a zone transfer + will not be meaningful. The allnodes() function is more relevant + with data from a database. + + - The authority() function is necessary if and only if the lookup() + function will not add SOA and NS records at the zone apex. If + SOA and NS records are provided by the lookup() function, + the authority() function should be NULL. + + - When a driver is registered, an opaque object can be provided. This + object is passed into the database create() and destroy() functions. + + - When a database is created, an opaque object can be created that + is associated with that database. This object is passed into the + lookup(), authority(), and allnodes() functions, and is + destroyed by the destroy() function. + + +Future Directions + +A future release may support dynamic loading of sdb drivers. + + +$Id: sdb,v 1.6 2004/03/05 05:04:54 marka Exp $ diff --git a/doc/misc/sort-options.pl b/doc/misc/sort-options.pl new file mode 100644 index 0000000..4251521 --- /dev/null +++ b/doc/misc/sort-options.pl @@ -0,0 +1,50 @@ +#!/bin/perl +# +# Copyright (C) 2007 Internet Systems Consortium, Inc. ("ISC") +# +# Permission to use, copy, modify, and/or distribute this software for any +# purpose with or without fee is hereby granted, provided that the above +# copyright notice and this permission notice appear in all copies. +# +# THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH +# REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +# AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, +# INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +# LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +# OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +# PERFORMANCE OF THIS SOFTWARE. + +# $Id: sort-options.pl,v 1.3 2007/09/24 23:46:48 tbox Exp $ + +sub sortlevel() { + my @options = (); + my $fin = ""; + my $i = 0; + while (<>) { + if (/^\s*};$/) { + $fin = $_; + # print 2, $_; + last; + } + next if (/^$/); + if (/{$/) { + # print 3, $_; + my $sec = $_; + push(@options, $sec . sortlevel()); + } else { + push(@options, $_); + # print 1, $_; + } + $i++; + } + my $result = ""; + foreach my $i (sort @options) { + $result = ${result}.${i}; + $result = $result."\n" if ($i =~ /^[a-z]/i); + # print 5, ${i}; + } + $result = ${result}.${fin}; + return ($result); +} + +print sortlevel(); |