/contrib/bind9/doc/misc/migration

  1Copyright (C) 2004, 2007, 2008  Internet Systems Consortium, Inc. ("ISC")
  2Copyright (C) 2000, 2001, 2003  Internet Software Consortium.
  3See COPYRIGHT in the source root or http://isc.org/copyright.html for terms.
  4
  5                   BIND 8 to BIND 9 Migration Notes
  6
  7BIND 9 is designed to be mostly upwards compatible with BIND 8, but
  8there is still a number of caveats you should be aware of when
  9upgrading an existing BIND 8 installation to use BIND 9.
 10
 11
 121. Configuration File Compatibility
 13
 141.1. Unimplemented Options and Changed Defaults
 15
 16BIND 9 supports most, but not all of the named.conf options of BIND 8.
 17For a complete list of implemented options, see doc/misc/options.
 18
 19If your named.conf file uses an unimplemented option, named will log a
 20warning message.  A message is also logged about each option whose
 21default has changed unless the option is set explicitly in named.conf.
 22
 23The default of the "transfer-format" option has changed from
 24"one-answer" to "many-answers".  If you have slave servers that do not
 25understand the many-answers zone transfer format (e.g., BIND 4.9.5 or
 26older) you need to explicitly specify "transfer-format one-answer;" in
 27either the options block or a server statement.
 28
 29BIND 9.4 onwards implements "allow-query-cache".  The "allow-query"
 30option is no longer used to specify access to the cache.  The
 31"allow-query" option continues to specify which hosts are allowed
 32to ask ordinary DNS questions.  The new "allow-query-cache" option
 33is used to specify which hosts are allowed to get answers from the
 34cache. Since BIND 9.4.1, if "allow-query-cache" is not set then
 35"allow-recursion" is used if it is set, otherwise "allow-query" is
 36used if it is set, otherwise the default localnets and localhost
 37is used.
 38
 391.2. Handling of Configuration File Errors
 40
 41In BIND 9, named refuses to start if it detects an error in
 42named.conf.  Earlier versions would start despite errors, causing the
 43server to run with a partial configuration.  Errors detected during
 44subsequent reloads do not cause the server to exit.
 45
 46Errors in master files do not cause the server to exit, but they
 47do cause the zone not to load.
 48
 491.3. Logging
 50
 51The set of logging categories in BIND 9 is different from that
 52in BIND 8.  If you have customised your logging on a per-category
 53basis, you need to modify your logging statement to use the
 54new categories.
 55
 56Another difference is that the "logging" statement only takes effect
 57after the entire named.conf file has been read.  This means that when
 58the server starts up, any messages about errors in the configuration
 59file are always logged to the default destination (syslog) when the
 60server first starts up, regardless of the contents of the "logging"
 61statement.  In BIND 8, the new logging configuration took effect
 62immediately after the "logging" statement was read.
 63
 641.4. Notify messages and Refresh queries
 65
 66The source address and port for these is now controlled by
 67"notify-source" and "transfer-source", respectively, rather that
 68query-source as in BIND 8.
 69
 701.5. Multiple Classes.
 71
 72Multiple classes have to be put into explicit views for each class.
 73
 74
 752. Zone File Compatibility
 76
 772.1. Strict RFC1035 Interpretation of TTLs in Zone Files
 78
 79BIND 9 strictly complies with the RFC1035 and RFC2308 rules regarding
 80omitted TTLs in zone files.  Omitted TTLs are replaced by the value
 81specified with the $TTL directive, or by the previous explicit TTL if
 82there is no $TTL directive.
 83
 84If there is no $TTL directive and the first RR in the file does not
 85have an explicit TTL field, the zone file is illegal according to
 86RFC1035 since the TTL of the first RR is undefined.  Unfortunately,
 87BIND 4 and many versions of BIND 8 accept such files without warning
 88and use the value of the SOA MINTTL field as a default for missing TTL
 89values.
 90
 91BIND 9.0 and 9.1 completely refused to load such files.  BIND 9.2
 92emulates the nonstandard BIND 4/8 SOA MINTTL behaviour and loads the
 93files anyway (provided the SOA is the first record in the file), but
 94will issue the warning message "no TTL specified; using SOA MINTTL
 95instead".
 96
 97To avoid problems, we recommend that you use a $TTL directive in each
 98zone file.
 99
1002.2. Periods in SOA Serial Numbers Deprecated
101
102Some versions of BIND allow SOA serial numbers with an embedded
103period, like "3.002", and convert them into integers in a rather
104unintuitive way.  This feature is not supported by BIND 9; serial
105numbers must be integers.
106
1072.3. Handling of Unbalanced Quotes
108
109TXT records with unbalanced quotes, like 'host TXT "foo', were not
110treated as errors in some versions of BIND.  If your zone files
111contain such records, you will get potentially confusing error
112messages like "unexpected end of file" because BIND 9 will interpret
113everything up to the next quote character as a literal string.
114
1152.4. Handling of Line Breaks
116
117Some versions of BIND accept RRs containing line breaks that are not
118properly quoted with parentheses, like the following SOA:
119
120	@	IN SOA	ns.example. hostmaster.example.
121			( 1 3600 1800 1814400 3600 )
122
123This is not legal master file syntax and will be treated as an error
124by BIND 9.  The fix is to move the opening parenthesis to the first
125line.
126
1272.5. Unimplemented BIND 8 Extensions
128
129$GENERATE: The "$$" construct for getting a literal $ into a domain
130name is deprecated.  Use \$ instead.
131
1322.6. TXT records are no longer automatically split.
133
134Some versions of BIND accepted strings in TXT RDATA consisting of more
135than 255 characters and silently split them to be able to encode the
136strings in a protocol conformant way. You may now see errors like this
137        dns_rdata_fromtext: local.db:119: ran out of space
138if you have TXT RRs with too longs strings. Make sure to split the
139string in the zone data file at or before a single one reaches 255
140characters.
141
1423. Interoperability Impact of New Protocol Features
143
1443.1. EDNS0
145
146BIND 9 uses EDNS0 (RFC2671) to advertise its receive buffer size.  It
147also sets DO EDNS flag bit in queries to indicate that it wishes to
148receive DNSSEC responses.
149
150Most older servers that do not support EDNS0, including prior versions
151of BIND, will send a FORMERR or NOTIMP response to these queries.
152When this happens, BIND 9 will automatically retry the query without
153EDNS0.
154
155Unfortunately, there exists at least one non-BIND name server
156implementation that silently ignores these queries instead of sending
157an error response.  Resolving names in zones where all or most
158authoritative servers use this server will be very slow or fail
159completely.  We have contacted the manufacturer of the name server in
160case, and they are working on a solution.
161
162When BIND 9 communicates with a server that does support EDNS0, such as
163another BIND 9 server, responses of up to 4096 bytes may be
164transmitted as a single UDP datagram which is subject to fragmentation
165at the IP level.  If a firewall incorrectly drops IP fragments, it can
166cause resolution to slow down dramatically or fail.
167
1683.2. Zone Transfers
169
170Outgoing zone transfers now use the "many-answers" format by default.
171This format is not understood by certain old versions of BIND 4.  
172You can work around this problem using the option "transfer-format
173one-answer;", but since these old versions all have known security
174problems, the correct fix is to upgrade the slave servers.
175
176Zone transfers to Windows 2000 DNS servers sometimes fail due to a
177bug in the Windows 2000 DNS server where DNS messages larger than
17816K are not handled properly.  Obtain the latest service pack for
179Windows 2000 from Microsoft to address this issue.  In the meantime,
180the problem can be worked around by setting "transfer-format one-answer;".
181http://support.microsoft.com/default.aspx?scid=kb;en-us;297936
182
1834. Unrestricted Character Set
184
185		BIND 9.2 only
186
187BIND 9 does not restrict the character set of domain names - it is
188fully 8-bit clean in accordance with RFC2181 section 11.
189
190It is strongly recommended that hostnames published in the DNS follow
191the RFC952 rules, but BIND 9 will not enforce this restriction.
192
193Historically, some applications have suffered from security flaws
194where data originating from the network, such as names returned by
195gethostbyaddr(), are used with insufficient checking and may cause a
196breach of security when containing unexpected characters; see
197<http://www.cert.org/advisories/CA-96.04.corrupt_info_from_servers.html>
198for details.  Some earlier versions of BIND attempt to protect these
199flawed applications from attack by discarding data containing
200characters deemed inappropriate in host names or mail addresses, under
201the control of the "check-names" option in named.conf and/or "options
202no-check-names" in resolv.conf.  BIND 9 provides no such protection;
203if applications with these flaws are still being used, they should
204be upgraded.
205
206	BIND 9.3 onwards implements check-names.
207
2085. Server Administration Tools
209
2105.1 Ndc Replaced by Rndc
211
212The "ndc" program has been replaced by "rndc", which is capable of
213remote operation.  Unlike ndc, rndc requires a configuration file.
214The easiest way to generate a configuration file is to run
215"rndc-confgen -a"; see the man pages for rndc(8), rndc-confgen(8),
216and rndc.conf(5) for details.
217
2185.2. Nsupdate Differences
219
220The BIND 8 implementation of nsupdate had an undocumented feature
221where an update request would be broken down into multiple requests
222based upon the discovered zones that contained the records.  This
223behaviour has not been implemented in BIND 9.  Each update request
224must pertain to a single zone, but it is still possible to do multiple
225updates in a single invocation of nsupdate by terminating each update
226with an empty line or a "send" command.
227
228
2296. No Information Leakage between Zones
230
231BIND 9 stores the authoritative data for each zone in a separate data
232structure, as recommended in RFC1035 and as required by DNSSEC and
233IXFR.  When a BIND 9 server is authoritative for both a child zone and
234its parent, it will have two distinct sets of NS records at the
235delegation point: the authoritative NS records at the child's apex,
236and a set of glue NS records in the parent.
237
238BIND 8 was unable to properly distinguish between these two sets of NS
239records and would "leak" the child's NS records into the parent,
240effectively causing the parent zone to be silently modified: responses
241and zone transfers from the parent contained the child's NS records
242rather than the glue configured into the parent (if any).  In the case
243of children of type "stub", this behaviour was documented as a feature,
244allowing the glue NS records to be omitted from the parent
245configuration.
246
247Sites that were relying on this BIND 8 behaviour need to add any
248omitted glue NS records, and any necessary glue A records, to the
249parent zone.
250
251Although stub zones can no longer be used as a mechanism for injecting
252NS records into their parent zones, they are still useful as a way of
253directing queries for a given domain to a particular set of name
254servers.
255
256
2577. Umask not Modified
258
259The BIND 8 named unconditionally sets the umask to 022.  BIND 9 does
260not; the umask inherited from the parent process remains in effect.
261This may cause files created by named, such as journal files, to be
262created with different file permissions than they did in BIND 8.  If
263necessary, the umask should be set explicitly in the script used to
264start the named process.
265
266
267$Id: migration,v 1.49 2008/03/18 15:42:53 jreed Exp $