migration revision 0c27b3fe77ac1d5094ba3521e8142d9e7973133f
7abd0c58a5ce51db13f93de82407b2188d55d298Christian MaederCopyright (C) 2000, 2001, 2003, 2004, 2007, 2008, 2016 Internet Systems Consortium, Inc. ("ISC")
fbad935054f262160c184f9ef8586dee8af9396eChristian MaederThis Source Code Form is subject to the terms of the Mozilla Public
97018cf5fa25b494adffd7e9b4e87320dae6bf47Christian MaederLicense, v. 2.0. If a copy of the MPL was not distributed with this
7abd0c58a5ce51db13f93de82407b2188d55d298Christian Maederfile, You can obtain one at http://mozilla.org/MPL/2.0/.
7abd0c58a5ce51db13f93de82407b2188d55d298Christian Maeder BIND 8 to BIND 9 Migration Notes
f3a94a197960e548ecd6520bb768cb0d547457bbChristian MaederBIND 9 is designed to be mostly upwards compatible with BIND 8, but
5581c4644d91dcb9b7e2e7f6052f7cbf5f97b6deChristian Maederthere is still a number of caveats you should be aware of when
0205259ae45f1fc559cef00e69ca54a3aea10acaChristian Maederupgrading an existing BIND 8 installation to use BIND 9.
0205259ae45f1fc559cef00e69ca54a3aea10acaChristian Maeder1. Configuration File Compatibility
1c67beb3720d0b84d8d71ee2012166a09be81fbdChristian Maeder1.1. Unimplemented Options and Changed Defaults
e8ffec0fa3d3061061bdc16e44247b9cf96b050fChristian MaederBIND 9 supports most, but not all of the named.conf options of BIND 8.
4cb2ce69a8998bf13679428a9182cefc74225af3Christian MaederFor a complete list of implemented options, see doc/misc/options.
ad270004874ce1d0697fb30d7309f180553bb315Christian MaederIf your named.conf file uses an unimplemented option, named will log a
e8ffec0fa3d3061061bdc16e44247b9cf96b050fChristian Maederwarning message. A message is also logged about each option whose
3cafc73a998493f9ed3d5e934c0ab80bcfb465c2Christian Maederdefault has changed unless the option is set explicitly in named.conf.
1c67beb3720d0b84d8d71ee2012166a09be81fbdChristian MaederThe default of the "transfer-format" option has changed from
9cb4aa4ea6685489a38f9b609f5dbe5d37f25bc7Christian Maeder"one-answer" to "many-answers". If you have slave servers that do not
1c67beb3720d0b84d8d71ee2012166a09be81fbdChristian Maederunderstand the many-answers zone transfer format (e.g., BIND 4.9.5 or
7abd0c58a5ce51db13f93de82407b2188d55d298Christian Maederolder) you need to explicitly specify "transfer-format one-answer;" in
e8ffec0fa3d3061061bdc16e44247b9cf96b050fChristian Maedereither the options block or a server statement.
6e39bfd041946fce4982ac89834be73fd1bfb39aChristian MaederBIND 9.4 onwards implements "allow-query-cache". The "allow-query"
f8f78a2c8796a387a4348cc672ae08e8d9f69315Christian Maederoption is no longer used to specify access to the cache. The
975642b989852fc24119c59cf40bc1af653608ffChristian Maeder"allow-query" option continues to specify which hosts are allowed
5581c4644d91dcb9b7e2e7f6052f7cbf5f97b6deChristian Maederto ask ordinary DNS questions. The new "allow-query-cache" option
53301de22afd7190981b363b57c48df86fcb50f7Christian Maederis used to specify which hosts are allowed to get answers from the
0205259ae45f1fc559cef00e69ca54a3aea10acaChristian Maedercache. Since BIND 9.4.1, if "allow-query-cache" is not set then
975642b989852fc24119c59cf40bc1af653608ffChristian Maeder"allow-recursion" is used if it is set, otherwise "allow-query" is
975642b989852fc24119c59cf40bc1af653608ffChristian Maederused if it is set, otherwise the default localnets and localhost
5581c4644d91dcb9b7e2e7f6052f7cbf5f97b6deChristian Maeder1.2. Handling of Configuration File Errors
2329a87b052e8aef57e419ed533751710a6be648Christian MaederIn BIND 9, named refuses to start if it detects an error in
2329a87b052e8aef57e419ed533751710a6be648Christian Maedernamed.conf. Earlier versions would start despite errors, causing the
2329a87b052e8aef57e419ed533751710a6be648Christian Maederserver to run with a partial configuration. Errors detected during
2329a87b052e8aef57e419ed533751710a6be648Christian Maedersubsequent reloads do not cause the server to exit.
2329a87b052e8aef57e419ed533751710a6be648Christian MaederErrors in master files do not cause the server to exit, but they
5581c4644d91dcb9b7e2e7f6052f7cbf5f97b6deChristian Maederdo cause the zone not to load.
975642b989852fc24119c59cf40bc1af653608ffChristian MaederThe set of logging categories in BIND 9 is different from that
2329a87b052e8aef57e419ed533751710a6be648Christian Maederin BIND 8. If you have customised your logging on a per-category
975642b989852fc24119c59cf40bc1af653608ffChristian Maederbasis, you need to modify your logging statement to use the
975642b989852fc24119c59cf40bc1af653608ffChristian Maedernew categories.
2329a87b052e8aef57e419ed533751710a6be648Christian MaederAnother difference is that the "logging" statement only takes effect
2329a87b052e8aef57e419ed533751710a6be648Christian Maederafter the entire named.conf file has been read. This means that when
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maederthe server starts up, any messages about errors in the configuration
2329a87b052e8aef57e419ed533751710a6be648Christian Maederfile are always logged to the default destination (syslog) when the
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maederserver first starts up, regardless of the contents of the "logging"
2329a87b052e8aef57e419ed533751710a6be648Christian Maederstatement. In BIND 8, the new logging configuration took effect
975642b989852fc24119c59cf40bc1af653608ffChristian Maederimmediately after the "logging" statement was read.
836e72a3c413366ba9801726f3b249c7791cb9caChristian Maeder1.4. Notify messages and Refresh queries
2329a87b052e8aef57e419ed533751710a6be648Christian MaederThe source address and port for these is now controlled by
836e72a3c413366ba9801726f3b249c7791cb9caChristian Maeder"notify-source" and "transfer-source", respectively, rather that
2329a87b052e8aef57e419ed533751710a6be648Christian Maederquery-source as in BIND 8.
836e72a3c413366ba9801726f3b249c7791cb9caChristian Maeder1.5. Multiple Classes.
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian MaederMultiple classes have to be put into explicit views for each class.
2329a87b052e8aef57e419ed533751710a6be648Christian Maeder2. Zone File Compatibility
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maeder2.1. Strict RFC1035 Interpretation of TTLs in Zone Files
9c5b1136299d9052e4e995614a3a36a051a2682fChristian MaederBIND 9 strictly complies with the RFC1035 and RFC2308 rules regarding
c1031ac42b3f3d7d0fe7d9d6b54423a092d473a0Christian Maederomitted TTLs in zone files. Omitted TTLs are replaced by the value
c1031ac42b3f3d7d0fe7d9d6b54423a092d473a0Christian Maederspecified with the $TTL directive, or by the previous explicit TTL if
c1031ac42b3f3d7d0fe7d9d6b54423a092d473a0Christian Maederthere is no $TTL directive.
2329a87b052e8aef57e419ed533751710a6be648Christian MaederIf there is no $TTL directive and the first RR in the file does not
c1031ac42b3f3d7d0fe7d9d6b54423a092d473a0Christian Maederhave an explicit TTL field, the zone file is illegal according to
6e39bfd041946fce4982ac89834be73fd1bfb39aChristian MaederRFC1035 since the TTL of the first RR is undefined. Unfortunately,
2329a87b052e8aef57e419ed533751710a6be648Christian MaederBIND 4 and many versions of BIND 8 accept such files without warning
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maederand use the value of the SOA MINTTL field as a default for missing TTL
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian MaederBIND 9.0 and 9.1 completely refused to load such files. BIND 9.2
2329a87b052e8aef57e419ed533751710a6be648Christian Maederemulates the nonstandard BIND 4/8 SOA MINTTL behaviour and loads the
42626cd6acc59504dff56b5b81043c272778c5fbTill Mossakowskifiles anyway (provided the SOA is the first record in the file), but
c1031ac42b3f3d7d0fe7d9d6b54423a092d473a0Christian Maederwill issue the warning message "no TTL specified; using SOA MINTTL
2329a87b052e8aef57e419ed533751710a6be648Christian MaederTo avoid problems, we recommend that you use a $TTL directive in each
2329a87b052e8aef57e419ed533751710a6be648Christian Maeder2.2. Periods in SOA Serial Numbers Deprecated
f8f78a2c8796a387a4348cc672ae08e8d9f69315Christian MaederSome versions of BIND allow SOA serial numbers with an embedded
2329a87b052e8aef57e419ed533751710a6be648Christian Maederperiod, like "3.002", and convert them into integers in a rather
9c5b1136299d9052e4e995614a3a36a051a2682fChristian Maederunintuitive way. This feature is not supported by BIND 9; serial
2329a87b052e8aef57e419ed533751710a6be648Christian Maedernumbers must be integers.
36c6cc568751e4235502cfee00ba7b597dae78dcChristian Maeder2.3. Handling of Unbalanced Quotes
36c6cc568751e4235502cfee00ba7b597dae78dcChristian MaederTXT records with unbalanced quotes, like 'host TXT "foo', were not
81946e2b3f6dde6167f48769bd02c7a634736856Christian Maedertreated as errors in some versions of BIND. If your zone files
36c6cc568751e4235502cfee00ba7b597dae78dcChristian Maedercontain such records, you will get potentially confusing error
975642b989852fc24119c59cf40bc1af653608ffChristian Maedermessages like "unexpected end of file" because BIND 9 will interpret
2329a87b052e8aef57e419ed533751710a6be648Christian Maedereverything up to the next quote character as a literal string.
ff9a53595208f532c25ac5168f772f48fd80fdb5Christian Maeder2.4. Handling of Line Breaks
abd8dd44106c507dd2cb64359b63d7d56fa0a9c8Christian MaederSome versions of BIND accept RRs containing line breaks that are not
2329a87b052e8aef57e419ed533751710a6be648Christian Maederproperly quoted with parentheses, like the following SOA:
2329a87b052e8aef57e419ed533751710a6be648Christian Maeder ( 1 3600 1800 1814400 3600 )
2329a87b052e8aef57e419ed533751710a6be648Christian MaederThis is not legal master file syntax and will be treated as an error
975642b989852fc24119c59cf40bc1af653608ffChristian Maederby BIND 9. The fix is to move the opening parenthesis to the first
2329a87b052e8aef57e419ed533751710a6be648Christian Maeder2.5. Unimplemented BIND 8 Extensions
a5893eedee9aae242d4de28662d98878781a3dc1Christian Maeder$GENERATE: The "$$" construct for getting a literal $ into a domain
81946e2b3f6dde6167f48769bd02c7a634736856Christian Maedername is deprecated. Use \$ instead.
975642b989852fc24119c59cf40bc1af653608ffChristian Maeder2.6. TXT records are no longer automatically split.
a5893eedee9aae242d4de28662d98878781a3dc1Christian MaederSome versions of BIND accepted strings in TXT RDATA consisting of more
a5893eedee9aae242d4de28662d98878781a3dc1Christian Maederthan 255 characters and silently split them to be able to encode the
81946e2b3f6dde6167f48769bd02c7a634736856Christian Maederstrings in a protocol conformant way. You may now see errors like this
2329a87b052e8aef57e419ed533751710a6be648Christian Maeder dns_rdata_fromtext: local.db:119: ran out of space
02c3f2769d85281508e6671a908da9c52787578eChristian Maederif you have TXT RRs with too longs strings. Make sure to split the
975642b989852fc24119c59cf40bc1af653608ffChristian Maederstring in the zone data file at or before a single one reaches 255
975642b989852fc24119c59cf40bc1af653608ffChristian Maeder3. Interoperability Impact of New Protocol Features
7abd0c58a5ce51db13f93de82407b2188d55d298Christian MaederBIND 9 uses EDNS0 (RFC2671) to advertise its receive buffer size. It
81946e2b3f6dde6167f48769bd02c7a634736856Christian Maederalso sets DO EDNS flag bit in queries to indicate that it wishes to
975642b989852fc24119c59cf40bc1af653608ffChristian Maederreceive DNSSEC responses.
2329a87b052e8aef57e419ed533751710a6be648Christian MaederMost older servers that do not support EDNS0, including prior versions
2329a87b052e8aef57e419ed533751710a6be648Christian Maederof BIND, will send a FORMERR or NOTIMP response to these queries.
975642b989852fc24119c59cf40bc1af653608ffChristian MaederWhen this happens, BIND 9 will automatically retry the query without
3cafc73a998493f9ed3d5e934c0ab80bcfb465c2Christian MaederUnfortunately, there exists at least one non-BIND name server
7abd0c58a5ce51db13f93de82407b2188d55d298Christian Maederimplementation that silently ignores these queries instead of sending
2329a87b052e8aef57e419ed533751710a6be648Christian Maederan error response. Resolving names in zones where all or most
9c5b1136299d9052e4e995614a3a36a051a2682fChristian Maederauthoritative servers use this server will be very slow or fail
2329a87b052e8aef57e419ed533751710a6be648Christian Maedercompletely. We have contacted the manufacturer of the name server in
163524ad00619e364fbe2fc19eb96b17d75652e5Christian Maedercase, and they are working on a solution.
9c5b1136299d9052e4e995614a3a36a051a2682fChristian MaederWhen BIND 9 communicates with a server that does support EDNS0, such as
9c5b1136299d9052e4e995614a3a36a051a2682fChristian Maederanother BIND 9 server, responses of up to 4096 bytes may be
42c01284bba8d7c8d995c8dfb96ace57d28ed1bcTill Mossakowskitransmitted as a single UDP datagram which is subject to fragmentation
2329a87b052e8aef57e419ed533751710a6be648Christian Maederat the IP level. If a firewall incorrectly drops IP fragments, it can
163524ad00619e364fbe2fc19eb96b17d75652e5Christian Maedercause resolution to slow down dramatically or fail.
163524ad00619e364fbe2fc19eb96b17d75652e5Christian Maeder3.2. Zone Transfers
2329a87b052e8aef57e419ed533751710a6be648Christian MaederOutgoing zone transfers now use the "many-answers" format by default.
81946e2b3f6dde6167f48769bd02c7a634736856Christian MaederThis format is not understood by certain old versions of BIND 4.
36c6cc568751e4235502cfee00ba7b597dae78dcChristian MaederYou can work around this problem using the option "transfer-format
975642b989852fc24119c59cf40bc1af653608ffChristian Maederone-answer;", but since these old versions all have known security
975642b989852fc24119c59cf40bc1af653608ffChristian Maederproblems, the correct fix is to upgrade the slave servers.
163524ad00619e364fbe2fc19eb96b17d75652e5Christian MaederZone transfers to Windows 2000 DNS servers sometimes fail due to a
975642b989852fc24119c59cf40bc1af653608ffChristian Maederbug in the Windows 2000 DNS server where DNS messages larger than
9c5b1136299d9052e4e995614a3a36a051a2682fChristian Maeder16K are not handled properly. Obtain the latest service pack for
2329a87b052e8aef57e419ed533751710a6be648Christian MaederWindows 2000 from Microsoft to address this issue. In the meantime,
2329a87b052e8aef57e419ed533751710a6be648Christian Maederthe problem can be worked around by setting "transfer-format one-answer;".
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maederhttp://support.microsoft.com/default.aspx?scid=kb;en-us;297936
9c5b1136299d9052e4e995614a3a36a051a2682fChristian Maeder4. Unrestricted Character Set
9c5b1136299d9052e4e995614a3a36a051a2682fChristian Maeder BIND 9.2 only
9c5b1136299d9052e4e995614a3a36a051a2682fChristian MaederBIND 9 does not restrict the character set of domain names - it is
369454f9b2dbea113cbb40544a9b0f31425b2c69Christian Maederfully 8-bit clean in accordance with RFC2181 section 11.
9c5b1136299d9052e4e995614a3a36a051a2682fChristian MaederIt is strongly recommended that hostnames published in the DNS follow
369454f9b2dbea113cbb40544a9b0f31425b2c69Christian Maederthe RFC952 rules, but BIND 9 will not enforce this restriction.
9c5b1136299d9052e4e995614a3a36a051a2682fChristian MaederHistorically, some applications have suffered from security flaws
2329a87b052e8aef57e419ed533751710a6be648Christian Maederwhere data originating from the network, such as names returned by
975642b989852fc24119c59cf40bc1af653608ffChristian Maedergethostbyaddr(), are used with insufficient checking and may cause a
975642b989852fc24119c59cf40bc1af653608ffChristian Maederbreach of security when containing unexpected characters; see
36c6cc568751e4235502cfee00ba7b597dae78dcChristian Maeder<http://www.cert.org/advisories/CA-96.04.corrupt_info_from_servers.html>
975642b989852fc24119c59cf40bc1af653608ffChristian Maederfor details. Some earlier versions of BIND attempt to protect these
975642b989852fc24119c59cf40bc1af653608ffChristian Maederflawed applications from attack by discarding data containing
163524ad00619e364fbe2fc19eb96b17d75652e5Christian Maedercharacters deemed inappropriate in host names or mail addresses, under
2329a87b052e8aef57e419ed533751710a6be648Christian Maederthe control of the "check-names" option in named.conf and/or "options
9c5b1136299d9052e4e995614a3a36a051a2682fChristian Maederno-check-names" in resolv.conf. BIND 9 provides no such protection;
9c5b1136299d9052e4e995614a3a36a051a2682fChristian Maederif applications with these flaws are still being used, they should
7abd0c58a5ce51db13f93de82407b2188d55d298Christian Maeder BIND 9.3 onwards implements check-names.
9c5b1136299d9052e4e995614a3a36a051a2682fChristian Maeder5. Server Administration Tools
2329a87b052e8aef57e419ed533751710a6be648Christian Maeder5.1 Ndc Replaced by Rndc
14f86b92900f3248952c94e980db715802433cdbChristian MaederThe "ndc" program has been replaced by "rndc", which is capable of
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maederremote operation. Unlike ndc, rndc requires a configuration file.
2329a87b052e8aef57e419ed533751710a6be648Christian MaederThe easiest way to generate a configuration file is to run
2329a87b052e8aef57e419ed533751710a6be648Christian Maeder"rndc-confgen -a"; see the man pages for rndc(8), rndc-confgen(8),
36c6cc568751e4235502cfee00ba7b597dae78dcChristian Maederand rndc.conf(5) for details.
2329a87b052e8aef57e419ed533751710a6be648Christian Maeder5.2. Nsupdate Differences
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian MaederThe BIND 8 implementation of nsupdate had an undocumented feature
163524ad00619e364fbe2fc19eb96b17d75652e5Christian Maederwhere an update request would be broken down into multiple requests
9c5b1136299d9052e4e995614a3a36a051a2682fChristian Maederbased upon the discovered zones that contained the records. This
2329a87b052e8aef57e419ed533751710a6be648Christian Maederbehaviour has not been implemented in BIND 9. Each update request
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maedermust pertain to a single zone, but it is still possible to do multiple
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maederupdates in a single invocation of nsupdate by terminating each update
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maederwith an empty line or a "send" command.
163524ad00619e364fbe2fc19eb96b17d75652e5Christian Maeder6. No Information Leakage between Zones
2329a87b052e8aef57e419ed533751710a6be648Christian MaederBIND 9 stores the authoritative data for each zone in a separate data
2329a87b052e8aef57e419ed533751710a6be648Christian Maederstructure, as recommended in RFC1035 and as required by DNSSEC and
42c01284bba8d7c8d995c8dfb96ace57d28ed1bcTill MossakowskiIXFR. When a BIND 9 server is authoritative for both a child zone and
36c6cc568751e4235502cfee00ba7b597dae78dcChristian Maederits parent, it will have two distinct sets of NS records at the
2329a87b052e8aef57e419ed533751710a6be648Christian Maederdelegation point: the authoritative NS records at the child's apex,
9c5b1136299d9052e4e995614a3a36a051a2682fChristian Maederand a set of glue NS records in the parent.
2329a87b052e8aef57e419ed533751710a6be648Christian MaederBIND 8 was unable to properly distinguish between these two sets of NS
2329a87b052e8aef57e419ed533751710a6be648Christian Maederrecords and would "leak" the child's NS records into the parent,
9c5b1136299d9052e4e995614a3a36a051a2682fChristian Maedereffectively causing the parent zone to be silently modified: responses
9c5b1136299d9052e4e995614a3a36a051a2682fChristian Maederand zone transfers from the parent contained the child's NS records
6ecc709f7982792c6558384d4d6788c044233991Christian Maederrather than the glue configured into the parent (if any). In the case
836e72a3c413366ba9801726f3b249c7791cb9caChristian Maederof children of type "stub", this behaviour was documented as a feature,
2329a87b052e8aef57e419ed533751710a6be648Christian Maederallowing the glue NS records to be omitted from the parent
2329a87b052e8aef57e419ed533751710a6be648Christian Maederconfiguration.
81946e2b3f6dde6167f48769bd02c7a634736856Christian MaederSites that were relying on this BIND 8 behaviour need to add any
81946e2b3f6dde6167f48769bd02c7a634736856Christian Maederomitted glue NS records, and any necessary glue A records, to the
36c6cc568751e4235502cfee00ba7b597dae78dcChristian MaederAlthough stub zones can no longer be used as a mechanism for injecting
36c6cc568751e4235502cfee00ba7b597dae78dcChristian MaederNS records into their parent zones, they are still useful as a way of
c18e9c3c6d5039618f1f2c05526ece84c7794ea3Christian Maederdirecting queries for a given domain to a particular set of name
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maeder7. Umask not Modified
163524ad00619e364fbe2fc19eb96b17d75652e5Christian MaederThe BIND 8 named unconditionally sets the umask to 022. BIND 9 does
36c6cc568751e4235502cfee00ba7b597dae78dcChristian Maedernot; the umask inherited from the parent process remains in effect.
163524ad00619e364fbe2fc19eb96b17d75652e5Christian MaederThis may cause files created by named, such as journal files, to be
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maedercreated with different file permissions than they did in BIND 8. If
e0fc085c18022cd3feb88dd6aa030b76e231b833Christian Maedernecessary, the umask should be set explicitly in the script used to
ccf3de3d66b521a260e5c22d335c64a48e3f0195Christian Maederstart the named process.
2329a87b052e8aef57e419ed533751710a6be648Christian Maeder$Id: migration,v 1.49 2008/03/18 15:42:53 jreed Exp $