| blob | f96ec00ea6f13fdeb08c5dfeba18a97227827535 |
1 Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
2 Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
3 See COPYRIGHT in the source root or http://isc.org/copyright.html for
4 terms.
6 BIND 8 to BIND 9 Migration Notes
7 includes BIND 9.2.4 to BIND 9.3.4 changes
10 BIND 9 is designed to be mostly upwards compatible with BIND 8, but
11 there is still a number of caveats you should be aware of when
12 upgrading an existing BIND 8 installation to use BIND 9.
14 Introduction
15 ------------
17 This document provides information about differences between BIND 8 and
18 BIND 9. BIND 9 is upwards compatible with most BIND 8 features. However,
19 there are still a number of caveats you should be aware of when upgrading
20 an existing BIND 8 installation to use BIND 9. Be sure to read this
21 entire document before installing and using BIND 9.
23 This document contains the following sections:
24 * Section A, 1-7 Overview of Differences Between BIND 8 and BIND 9
25 * Section 8 BIND 9 name server and the Service Management Facility
26 * Appendix I Implementing rndc
27 * Appendix II BIND 9 Commands, Options, Files, and Tools
28 * Appendix III The named.conf Options
30 Additional information and documentation about BIND 9, including an
31 Administrator Reference Manual (ARM) is available on the ISC web site
32 at http://www.isc.org
34 The words "named", "DNS server", "name server" and "BIND 9 server"
35 are used interchangeably to denote the Internet Systems Consortium
36 BIND version 9 DNS server throughout this document.
38 Overview of Differences Between BIND 8 and BIND 9
39 -------------------------------------------------
41 Below is a list of changes between BIND 8 and BIND 9, including brief
42 descriptions. For more detailed information, see the appropriate
43 subsection for each item.
45 Configuration File Compatibility, Section 1.0
46 * unimplemented options warning message 1.1
47 * "transfer-format" option changes 1.1
48 * configuration file errors 1.2
49 * logging categories have changed 1.3
50 * configuration file startup errors 1.3
51 * "query-source" is deprecated 1.4
52 * multiple classes change 1.5
54 Zone File Compatibility, Section 2.0
55 * stricter rules for TTLs in zone file 2.1
56 * SOA serial number changes 2.2
57 * unbalanced quotes cause errors 2.3
58 * line breaks, syntax change 2.4
59 * use /$ instead of $$ in domain names 2.5
61 Interoperability Impact of New Protocol
62 Features, Section 3.0
63 * EDNS0 new in BIND 9 3.1
64 * zone transfers default change 3.2
66 Unrestricted Character Set, Section 4.0
67 * no restrictions on character set 4.0
68 * security issue, improper naming 4.0
70 Server Administration Tools, Section 5.0
71 * the rndc program replaces ndc 5.1
72 * nsupdate: changes in multiple updates 5.2
74 No Information Leakage Between Zones, Section 6.0
75 * glue NS records handled differently 6.0
77 Umask Not Modified, Section 7.0
78 * possible umask permissions issues 7.0
82 1. Configuration File Compatibility
84 1.1. Unimplemented Options and Changed Defaults
86 The BIND 9 name server supports most, but not all, of the configuration
87 options of the BIND 8 name server. For a complete list of implemented
88 options, see Appendix III of this document.
90 If your named.conf file uses an unimplemented option, the BIND 9 name
91 server will log a warning message. A message is also logged about each
92 option whose default has changed unless the option is set explicitly
93 in named.conf.
95 The default of the "transfer-format" option has changed from
96 "one-answer" to "many-answers". If you have slave servers that do
97 not understand the "many-answers" zone transfer format (e.g., BIND
98 4.9.5 and older) you need to explicitly specify
99 "transfer-format one-answer;" in either the options block or a
100 server statement.
102 1.2. Handling of Configuration File Errors
104 In BIND 9, named refuses to start if it detects an error in
105 named.conf. Earlier versions would start despite errors, causing
106 the server to run with a partial configuration. Errors detected
107 during subsequent reloads do not cause the server to exit.
109 Errors in master files do not cause the server to exit, but they
110 do cause the zone not to load.
112 1.3. Logging
114 The set of logging categories in BIND 9 is different from that
115 in BIND 8. If you have customized your logging on a per-category
116 basis, you need to modify your logging statement to use the
117 new categories.
119 Another difference is that the "logging" statement only takes effect
120 after the entire named.conf file has been read. This means that when
121 the server starts up, any messages about errors in the configuration
122 file are always logged to the default destination (syslog) when the
123 server first starts up, regardless of the contents of the "logging"
124 statement. In BIND 8, the new logging configuration took effect
125 immediately after the "logging" statement was read.
127 1.4. Notify Messages and Refresh Queries
129 The source address and port for these is now controlled by
130 "notify-source" and "transfer-source", respectively, rather than
131 "query-source" as in BIND 8.
133 1.5. Multiple Classes
135 Multiple classes have to be put into explicit views for each class.
138 2. Zone File Compatibility
140 2.1. Strict RFC1035 Interpretation of TTLs in Zone Files
142 BIND 9 strictly complies with the RFC1035 and RFC2308 rules regarding
143 omitted time-to-live (TTL) entries in zone files. Omitted TTLs are
144 replaced by the value specified with the $TTL directive, or by the
145 previous explicit TTL if there is no $TTL directive.
147 If there is no $TTL directive and the first Resource Record (RR) in the
148 file does not have an explicit TTL field, the zone file is illegal
149 according to RFC1035 since the TTL of the first RR is undefined.
150 Unfortunately, BIND 4 and many versions of BIND 8 accept such files
151 without warning and use the value of the SOA MINTTL field as a default
152 for missing TTL values.
154 Earlier versions of BIND 9 refused to load such files. However, BIND
155 9.2.4 loads the files anyway (provided the SOA is the first record
156 in the file), but will issue a TTL warning message.
158 To avoid problems, we recommend that you use a $TTL directive in each
159 zone file.
161 2.2. Periods in SOA Serial Numbers Deprecated
163 Some versions of BIND allow SOA serial numbers with an embedded
164 period, like "3.002", and convert them into integers in a rather
165 unintuitive way. This feature is not supported by BIND 9; serial
166 numbers must be integers.
168 2.3. Handling of Unbalanced Quotes
170 TXT records with unbalanced quotes, like 'host TXT "foo', were not
171 treated as errors in some versions of BIND. If your zone files
172 contain such records, you will get potentially confusing error
173 messages like "unexpected end of file" because BIND 9 will interpret
174 everything up to the next quote character as a literal string.
176 2.4. Handling of Line Breaks
178 Some versions of BIND accept RRs containing line breaks that are not
179 properly quoted with parentheses, like the following SOA:
181 @ IN SOA ns.example. hostmaster.example.
182 ( 1 3600 1800 1814400 3600 )
184 This is not legal master file syntax and will be treated as an error
185 by BIND 9. The fix is to move the opening parenthesis to the first
186 line.
188 2.5. Unimplemented BIND 8 Extensions
190 $GENERATE: The "$$" construct for getting a literal $ into a domain
191 name is deprecated. Use \$ instead.
193 2.6. TXT records are no longer automatically split.
195 Some versions of BIND accepted strings TXT RDATA that contained more
196 than 255 characters and silently split them in to multiple RDATA
197 records to comply with protocol. This feature has been removed, and
198 the following error is produced upon reading these records:
199 "dns_rdata_fromtext: local.db:119: ran out of space"
200 To address split the string in the zone data file at or before the 255
201 character in to two or more TXT records.
203 3. Interoperability Impact of New Protocol Features
205 3.1. EDNS0
207 BIND 9 uses EDNS0 (RFC2671) to advertise its receive buffer size. It
208 also sets an EDNS flag bit in queries to indicate that it wishes to
209 receive DNSSEC responses; this flag bit usage is not yet standardised,
210 but we hope it will be.
212 Most older servers that do not support EDNS0, including prior versions
213 of BIND, will send a FORMERR or NOTIMP response to these queries.
214 When this happens, BIND 9 will automatically retry the query without
215 EDNS0.
217 Unfortunately, there exists at least one non-BIND name server
218 implementation that silently ignores these queries instead of sending
219 an error response. Resolving names in zones where all or most
220 authoritative servers use this server will be very slow or fail
221 completely. The manufacturer of the name server is working on a
222 solution.
224 When BIND 9 communicates with a server that does support EDNS0, such
225 as another BIND 9 server, responses of up to 4096 bytes may be
226 transmitted as a single UDP datagram which is subject to fragmentation
227 at the IP level. If a firewall incorrectly drops IP fragments, it can
228 cause resolution to slow down dramatically or fail.
230 3.2. Zone Transfers
232 Outgoing zone transfers now use the "many-answers" format by default.
233 This format is not understood by certain old versions of BIND 4.
234 You can work around this problem using the option "transfer-format
235 one-answer;", but since these old versions all have known security
236 problems, the correct fix is to upgrade the slave servers.
238 Zone transfers to Windows 2000 DNS servers sometimes fail due to a
239 bug in the Windows 2000 DNS server where DNS messages larger than
240 16K are not handled properly. Obtain the latest service pack for
241 Windows 2000 from Microsoft to address this issue. In the meantime,
242 the problem can be worked around by setting "transfer-format
243 one-answer;".
244 http://support.microsoft.com/default.aspx?scid=kb;en-us;297936
246 4. Unrestricted Character Set
248 BIND 9 does not restrict the character set of domain names; it is
249 fully 8-bit clean in accordance with RFC2181 section 11.
251 It is strongly recommended that hostnames published in the DNS follow
252 the RFC952 rules, but BIND 9.2.4 and above will not enforce this
253 restriction.
255 Historically, some applications have suffered from security flaws
256 where data originating from the network, such as names returned by
257 gethostbyaddr(), are used with insufficient checking and may cause a
258 breach of security when containing unexpected characters; see
259 <http://www.cert.org/advisories/CA-96.04.corrupt_info_from_servers.html>
260 for details. Some earlier versions of BIND attempt to protect these
261 flawed applications from attack by discarding data containing
262 characters deemed inappropriate in host names or mail addresses, under
263 the control of the "check-names" option in named.conf and/or "options
264 no-check-names" in resolv.conf. BIND 9.2.4 provided no such
265 protection; advice was that applications with these flaws should be
266 upgraded. Subsequently however, BIND 9.3.x implements 'check-names'.
269 5. Server Administration Tools
271 5.1 ndc Replaced by rndc
273 The "ndc" program has been replaced by "rndc", which is capable of
274 remote operation. Unlike ndc, rndc requires a configuration file.
275 The easiest way to generate a configuration file is to run
276 "rndc-confgen -a"; see the man pages for rndc(1M), rndc-confgen(1M),
277 and rndc.conf(5) for details. While upgrading from previous Solaris
278 releases to Solaris 10, the upgrade process will detect if a
279 /etc/rndc.key or /etc/rndc.conf file exists. If neither file is
280 found, it runs "rndc-confgen -a" and generates /etc/rndc.key
281 so that rndc can be run with a local DNS name server without
282 further user intervention.
284 More information about rndc is available in "Implementing rndc",
285 later in this document.
289 5.2. nsupdate Differences
291 The BIND 8 implementation of nsupdate had an undocumented feature
292 where an update request would be broken down into multiple requests
293 based upon the discovered zones that contained the records. This
294 behaviour has not been implemented in BIND 9. Each update request
295 must pertain to a single zone, but it is still possible to do
296 multiple updates in a single invocation of nsupdate by terminating
297 each update with an empty line or a "send" command.
300 6. No Information Leakage Between Zones
302 BIND 9 stores the authoritative data for each zone in a separate data
303 structure, as recommended in RFC1035 and as required by DNSSEC and
304 IXFR. When a BIND 9 server is authoritative for both a child zone
305 and its parent, it will have two distinct sets of NS records at the
306 delegation point: the authoritative NS records at the child's apex,
307 and a set of glue NS records in the parent.
309 BIND 8 was unable to properly distinguish between these two sets of
310 NS records and would "leak" the child's NS records into the parent,
311 effectively causing the parent zone to be silently modified: responses
312 and zone transfers from the parent contained the child's NS records
313 rather than the glue configured into the parent (if any). In the
314 case of children of type "stub", this behaviour was documented as a
315 feature, allowing the glue NS records to be omitted from the parent
316 configuration.
318 Sites that were relying on this BIND 8 behaviour need to add any
319 omitted glue NS records, and any necessary glue A records, to the
320 parent zone.
322 Although stub zones can no longer be used as a mechanism for
323 injecting NS records into their parent zones, they are still useful
324 as a way of directing queries for a given domain to a particular
325 set of name servers.
328 7. Umask Not Modified
330 The BIND 8 named unconditionally sets the umask to 022. BIND 9 does
331 not; the umask inherited from the parent process remains in effect.
332 This may cause files created by named, such as journal files, to be
333 created with different file permissions than they did in BIND 8. If
334 necessary, the umask should be set explicitly in the script used to
335 start the named process.
337 8. BIND 9 name server and the Service Management Facility
339 The DNS BIND 9 named(1M) service can be managed by using the Service
340 Management Facility (SMF). For more information, see the smf(5) man
341 page. The SUNWbindr package provides the BIND 9 service manifest
342 and must be installed.
344 When you use SMF, the following items apply.
346 - Administrative actions on this service, such as enabling, disabling,
347 or restarting, can be performed by using the svcadm(1M) command.
349 - The default Fault Managed Resource Identifier (FMRI) for the BIND 9
350 DNS server is svc:/network/dns/server. The FMRI for the DNS client is
351 svc:/network/dns/client.
353 - You can query the state of the BIND 9 DNS service by using svcs(1).
354 For example:
356 # svcs svc:network/dns/server:default
357 STATE STIME FMRI
358 online 16:24:04 svc:/network/dns/server:default
360 The upgrade to Solaris 10 will detect an existing /etc/named.conf file
361 and enable the BIND 9 service to startup after the upgrade is completed
362 and the system is rebooted.
364 To start the BIND 9 DNS service on a Solaris 10 system:
366 a. Create/Copy a valid /etc/named.conf file.
367 b. Verify that the SUNWbind and SUNWbindr packages, including any
368 required packages are installed correctly.
369 c. Enable the default service instance using svcadm(1M). For example:
370 # svcadm enable svc:network/dns/server:default
372 While it is recommended that you use svcadm(1M) to administer the server,
373 you can use rndc(1M) as well. SMF is aware of the state change of the BIND
374 9 named service, whether administered by using svcadm(1M) or rndc(1M).
376 NOTE: smf(5) will not be aware of the BIND 9 named(1M) service
377 if the service is manually executed from the command line.
379 NOTE: rndc(1M) is not able to stop the service when used in a chroot(2)
380 environment under smf(1M) control.
382 8.1 Name Server SMF Properties
384 Relevant named(1M) options for use with smf(1) may be applied using
385 service application properties:
387 - options/configuration_file
389 Specifies the configuration file to be used instead of
390 the default /etc/named.conf. To ensure that reloading
391 the configuration file continues to work after the server
392 has changed its working directory due to to a possible
393 directory option in the configuration file, the
394 configuration file should be an absolute pathname. The
395 configuration pathname should not include the chroot_dir
396 pathname. This property is synonymous to the -c option.
398 - options/ip_interfaces
400 specifies which IP transport BIND will transmit on.
401 Possible values are 'IPv4' or 'IPv6'. Any other setting
402 assumes 'all', the default. This property is synonymous
403 to command line option '-4' or '-6'
405 - options/listen_on_port
407 Specifies the default UDP and TCP port which will be used
408 to listen for DNS requests. This property is synonymous
409 to command line option '-p port'.
412 - options/debug_level
414 Specifies the default debug level. The default is 0; no
415 debugging. The Higher the number the more verbose debug
416 information becomes. Synonymous to command line option
417 '-d debug-level'.
419 - options/threads
421 Specifies the number of cpu worker threads to create.
422 The default of 0 causes named to try and determine the
423 number of CPUs present and create one thread per
424 CPU. Synonymous to command line option '-n #cpus'.
426 - options/chroot_dir
428 Specifies the directory to be used as the root directory
429 after processing SMF properties and the command line
430 arguments but before reading the configuration file. Use
431 this property when using a chroot(2) environment.
432 Synonymous to command line option '-t <pathname>'.
434 When using chroot(2) named is unable to disable its self
435 when receiving rndc(1M) stop or halt commands and you must
436 instead use the svcadm(1M) disable command.
438 - options/server
440 Specifies an alternative execution path. If unset then the
441 default server /usr/sbin/named is assumed.
443 The following examples show how the application properties may be used:
445 Example 1: Configuring named(1m) in future to only transmit
446 over IPv4 networks:
448 # svccfg -s svc:network/dns/server:default setprop \
449 options/ip_interfaces=IPv4
450 # svcadm refresh svc:network/dns/server:default
451 # scvadm restart svc:network/dns/server:default
453 Example 2: List current configuration file and change to
454 an alternative file:
456 # svcprop -p options/configuration_file dns/server:default
457 ""
458 # svccfg -s dns/server:default setprop \
459 options/configuration_file=/var/named/named.conf
460 # svcadm refresh dns/server:default
461 # svcprop -p options/configuration_file dns/server:default
462 /var/named/named.conf
463 # scvadm restart svc:network/dns/server:default
465 The dns/server smf_method(5) script converts the application properties
466 to the relevant command line option.
468 Changing the "start method" property of the BIND 9 service is no longer
469 recommended as was stated here previously.
471 For more information about the Service Management Facility, refer to
472 "Managing Services (Overview)" in System Administration Guide: Basic
473 Administration, available on http://docs.sun.com. Also refer to smf(5),
474 svcs(1), svcadm(1M), svccfg(1M) man pages and the BIND 9 name service
475 manifest server.xml in /lib/svc/manifest/network/dns.
478 *************************************
481 APPENDICES I-III
484 Appendix I. Implementing rndc
485 -----------------
487 The BIND 8 ndc(1M) and BIND 9 rndc(1M) name server control tools are
488 NOT backward compatible: rndc can't talk to the BIND 8 name server
489 and ndc can't talk to the BIND 9 name server. Features, options,
490 default modes of operation, and configuration file requirements
491 have changed.
494 Ia. The rndc.conf Configuration File
495 --------------------------------
497 The most significant difference between ndc in BIND 8 and rndc in BIND 9
498 is that rndc needs its own configuration file, rndc.conf. This file can
499 be generated by rndc-confgen(1M) commands. The rndc.conf file specifies
500 which server controls and what algorithm the server should use. Note that
501 the /etc/rndc.conf and matching /etc/named.conf information is only needed
502 when using rndc to manage a remote BIND 9 name server. If rndc is only
503 used to manage a local BIND 9 name server, the /etc/rndc.key is sufficient.
505 Sample rndc.conf File
506 ---------------------
508 options {
509 default-server localhost;
510 default-key "rndc-key";
511 };
513 key "rndc-key" {
514 algorithm hmac-md5;
515 secret "qPWZ3Ndl81aBRY9AmJhVtU==";
516 };
519 Sample named.conf File Entry for rndc
520 -------------------------------------
522 controls {
523 inet * allow { any; } keys { "rndc-key"; };
524 };
526 key "rndc-key" {
527 algorithm hmac-md5;
528 secret "qPWZ3Ndl81aBRY9AmJhVtU==";
529 };
533 Ib. Differences in the Control Channels
534 -----------------------------------
536 Both the ndc(1M) and the rndc(1M) utilities use a control channel to
537 send commands to and retrieve information from a name server. However,
538 there are differences between the utilities.
540 * In BIND 8, ndc can use AF_UNIX domain sockets (UNIX control
541 channel) or TCP/IP sockets (inet control channel). By default, ndc
542 does not need any support in /etc/named.conf, because BIND 8
543 servers use a UNIX domain socket with a path (/var/run/ndc.d/ndc)
544 compiled into in.named.
546 In BIND 9, rndc uses an authenticated TCP/IP inet control channel,
547 by default and is not backward compatible with BIND 8.
549 * When using rndc, you need to specify a 'key' clause to communicate
550 with the name server. It is mandatory that the BIND 9 server and
551 the rndc client share the same key. Using the BIND 8 controls
552 entry in BIND 9 will result in an error message.
554 * Some command options have changed from the ndc to the rndc
555 implementation. This includes the "-c" option, which has a
556 different syntax in BIND 9. Therefore, to specify the control
557 channel in BIND 9, use "rndc -s <server> -p <port>".
560 Ic. Commands of BIND 9.3 rndc
561 ---------------------------
562 reload Reload configuration file and zones.
563 reload zone [class [view]] Reload a single zone.
564 refresh zone [class [view]] Schedule immediate maintenance
565 for a zone.
566 retransfer zone [class [view]] Retransfer a single zone without
567 checking serial number.
568 freeze zone [class [view]]** Suspend updates to a dynamic zone.
569 thaw zone [class [view]]** Enable updates to a frozen dynamic
570 zone and reload it.
571 reconfig Reload configuration file and new
572 zones only.
573 stats Write server statistics to the
574 statistics file.
575 querylog Toggle query logging.
576 dumpdb [-all|-cache|-zones] [view ...]**
577 Dump cache(s) to the dump file
578 (named_dump.db).
579 stop [-p]** Save pending updates to master files
580 and stop the server; report process
581 number if -p provided.
582 halt [-p]** Stop the server without saving
583 pending updates; report process
584 number if -p provided
585 trace Increment debugging level by one.
586 trace level Change the debugging level.
587 notrace Set debugging level to 0.
588 flush Flushes all of the server's caches.
589 flush [view] Flushes the server's cache for a view.
590 status Display status of the server.
591 recursing** Dump the queries that are currently
592 recursing (named.recursing)
593 restart* Restart the server.
595 * = not yet implemented
596 ** = New command or option in bind 9.3.
599 Appendix II BIND 9 Commands, Files, Tools, and Options
600 ------------------------------------------
602 IIa. Comparison of BIND 8 and BIND 9 Commands and Files
603 --------------------------------------------------
605 The table below compares BIND 8 and BIND 9 commands and
606 configuration files. BIND 9 man pages install in /usr/man.
608 -------------------------------------------------
609 | BIND 8 Command | BIND 9.3 replacement |
610 -------------------------------------------------
611 | dnskeygen(1M) | dnssec-keygen(1M) |
612 | ndc(1M) | rndc(1M) |
613 | named-bootconf(1M) | NONE NEEDED |
614 | nsupdate(1M) | nsupdate(1M) |
615 | nslookup(1M) | nslookup(1M) |
616 | named-xfer(1M) | NONE NEEDED |
617 | in.named(1M) | named(1M) |
618 | named.conf(4) | named.conf* |
619 | dig(1M) | dig(1M) |
620 -------------------------------------------------
622 * A detailed named.conf man page was not included with BIND 9 originally.
623 Appendix III includes a summary of the named.conf options that are
624 supported in BIND 9.3.x at this time.
627 IIb. BIND 9 Tools and Configuration Files
628 ------------------------------------
630 The following BIND 9.3 tools are available in the SUNWbind
631 package and installed in /usr/sbin:
633 named
634 nsupdate
635 rndc
636 dnssec-keygen
637 nslookup
638 dig
639 dnssec-signzone
640 named-checkconf
641 named-checkzone
642 rndc-confgen
643 host
645 The following BIND 9.3 configuration files are supported.
647 /etc/rndc.conf
650 IIc. Descriptions of Command and Option Changes from 8.x to 9.x
651 ----------------------------------------------------------
653 Listed below are BIND 8 features/interfaces that are not supported in
654 the equivalent BIND 9 binary. This is not intended to be an exhaustive
655 list of the options, command line options or features for any BIND 9.x
656 command.
658 1. in.named(1M): DNS Name server in.named command line options.
660 In the BIND 9.3 name server, the "-g group_name", "-q", "-r" and "-w
661 directory" options are not supported, and "-c config_file" replaces
662 the BIND 8.x "-b config_file". See the named man page for further
663 details.
665 2. dnssec-keygen: dnskeygen(1M) in BIND 8.x and dnssec-keygen from BIND
666 9.2.x and above, have no common options. See the dnssec-keygen man
667 page or further details.
669 3. rndc(1M): See Appendix I in this document.
671 4. nsupdate(1M): in BIND 9.2.x and above, the syntax of the "-k" option
672 changes in nsupdate. Instead of "-k keydir::keyname" the syntax is now
673 "-k keyfile". The only other difference is that whereas a blank line was
674 used to signal sending the input to the server, an explicit "send"
675 sub-command is now used to do the same. See the nsupdate man page for
676 further details.
678 5. nslookup(1M): the following options are unsupported in the
679 BIND 9.2.x and above version.
681 help, host server, set ignoretc, set noignoretc,
682 set srch[list]=N1[/N2/.../N6], set ro[ot]=host, root,
683 finger [USER], ls [opt] DOMAIN [> FILE].
685 6. named.conf: several options are unsupported, not implemented or
686 have changed defaults. For a list of the option changes and a
687 summary of all named.conf options, see Appendix III.
689 IId. Differences in BIND 9.3 from BIND 9.2
690 -------------------------------------
692 BIND 9.3 provides several changes from BIND 9.2, including but
693 not limited to:
695 1. DNSSEC tools provided by BIND 9.2.4 are not compatible with BIND 9.3.4
696 and are replaced where applicable. Specifically, DNSSEC-bis
697 functionality removes the need for dnssec-signkey(1M) and
698 dnssec-makekeyset(1M); dnssec-keygen(1M) and dnssec-signzone(1M) now
699 provide alternative functionality.
701 2. dig(1M) and nslookup(1M) now report "Not Implemented" as NOTIMP rather
702 than NOTIMPL. This will have impact on scripts that are looking for
703 NOTIMPL.
705 3. named(1M): BIND server process includes new command line options to
706 overcome certain operating environment issues; CR 6320428. These
707 options are:
709 * '-4' specifies to only send queries on IPv4 interfaces
710 * '-6' specifies to only send queries on IPv6 interfaces.
712 named(1M) by default will reject master zone files where hostnames
713 or mail domain names have invalid syntax or characters. The rules
714 for legal hostnames / mail domains are derived from RFC 952 and RFC
715 821 as modified by RFC 1123.
717 * Corrective action should be to change the host names with
718 illegal syntax or characters, such as underscore (_)
719 characters. Use "named-checkconf -z /etc/named.conf" to check
720 validity of the named configuration file and any zone files
721 referenced by it.
723 To aid migration the default functionality may be
724 overridden using the check-names option of named.conf. For
725 example to allow zones with name failures to load but log
726 warning messages (as is the default for slave (secondary)
727 zones) modify or add an option statement to named.conf:
729 options {
730 check-names master warn;
731 };
733 named(1M) no longer provides the following functionality:
735 * Inverse IPv6 queries to the obsolete ip6.int domain. The
736 ip6.arpa domain is obsoleted by the ip6.int domain. See RFC
737 3596.
739 * IPv6 does not forward A6 lookups, deprecated by RFC 3363
741 * IPv6 "bitstring" not supported, primary will refuse to load zone
742 files with binary labels. Deprecated by rfc3363.
744 * Zones containing MD (Mail Destination) and MF (Mail Forwarder)
745 will now be rejected. The MD and MF resource record (RR) types
746 were originally introduced in RFC 882 and subsequently obsoleted
747 in RFC 1035 by the MX RR.
749 4. named.conf: Has additional options:
751 * allow-update-forwarding
752 * alt-transfer-source
753 * alt-transfer-source-v6
754 * avoid-v4-udp-ports
755 * avoid-v6-udp-ports
756 * check-names: Validate names in zones (from BIND 8).
757 * disable-algorithms
758 * dnssec-enable
759 * dnssec-lookaside
760 * dnssec-must-be-secure
761 * dual-stack-servers: provides IPv4/IPv6 transition support.
762 * edns-udp-size: Set advertised EDNS UDP size.
763 * flush-zones-on-shutdown
764 * hostname (chaos)'
765 * ixfr-from-differences: use IXFR deltas when loading master files.
766 * masters: define masters for a zone.
767 * max-journal-size: specify the size of a journal
768 * multi-master
769 * querylog
770 * server-id (chaos)
771 * Server statement grammar includes:
772 * transfer-source
773 * transfer-source-v6
774 * tcp-listen-queue
775 * use-alt-transfer-source
776 * zone statement grammar:
777 * multi-master
778 * key-directory
780 named.conf removed options:
782 * allow-v6-synthesis: Obsolete. Caused named to translate ip6.int
783 requests to ip6.arpa requests. As the ip6.int domain is now
784 obsolete this option has been removed.
786 * zone-statistics has been removed from the 'view' statement.
788 5. dig(1M) has new command line options:
789 -4: use IPv4 query transport only
790 -6: use IPv6 query transport only
791 +[no]aaflag: Set AA flag in query (+[no]aaflag)
792 +[no]cl: Control display of class in records
793 +[no]ttlid: Control display of ttls in records
794 +tries=#: Set number of UDP attempts [3]
795 +retry=#: Set number of UDP retries [2]
797 6. named.checkconf(1M) has new options:
798 -z: Perform a check load of the master zone files found in named.conf.
799 -j: When loading a zonefile read the journal if it exists.
801 7. named-checkzone(1M) has new options:
802 -k mode: Perform "check-name" checks with the specified failure mode.
803 -n mode: Check NS records are addresses, mode is warn, fail or ignore.
804 -o filename: Write zone output to filename.
805 -t directory: chroot to directory, useful for include statements.
806 -w directory: chdir to directory, useful for include statements.
807 -D: Dump zone file in canonical format.
809 8. rndc(1M) has several new subcommands including:
810 freeze, thaw, flushname and recursing (see above).
811 Several subcommands have new options namely stop, halt and dumpdb.
813 9. nsupdate(1M) generates SIG(0) signed messages.
816 Appendix III The named.conf Options
817 ----------------------
819 IIIa. Changes in the Options Section
820 ------------------------------
822 The following list compares the named.conf options between BIND 8
823 and BIND 9. It also provides a brief description of the change.
824 "OK" denotes the option works unchanged for the BIND 9 named.
826 options {
827 [ version version_string; ] OK
828 [ directory path_name; ] OK
829 [ named-xfer path_name; ] Obsolete (*1)
830 [ dump-file path_name; ] OK
831 [ memstatistics-file path_name; ] Not Implemented
832 [ pid-file path_name; ] OK
833 [ statistics-file path_name; ] OK
834 [ auth-nxdomain yes_or_no; ] OK (*2)
835 [ dialup yes_or_no; ] OK
836 [ fake-iquery yes_or_no; ] Obsolete
837 [ fetch-glue yes_or_no; ] Obsolete
838 [ has-old-clients yes_or_no; ] Obsolete
839 [ host-statistics yes_or_no; ] Not Implemented
840 [ host-statistics-max number; ] Not Implemented
841 [ multiple-cnames yes_or_no; ] Obsolete
842 [ notify yes_or_no | explicit; ] OK
843 [ recursion yes_or_no; ] OK
844 [ rfc2308-type1 yes_or_no; ] Not Implemented
845 [ use-id-pool yes_or_no; ] Obsolete
846 [ treat-cr-as-space yes_or_no; ] Obsolete
847 [ also-notify yes_or_no; ] Syntax Changed (*3)
848 [ forward ( only | first ); ] OK (*4)
849 [ forwarders { in_addr ; \
850 [ in_addr ; ... ] }; ] OK (*5)
851 [ check-names ( master | slave | \
852 response ) ( warn | fail | ignore); ] OK (*8)
853 [ allow-query { address_match_list }; ] OK
854 [ allow-recursion { address_match_list }; ] OK
855 [ allow-transfer { address_match_list }; ] OK
856 [ blackhole { address_match_list }; ] OK
857 [ listen-on [ port ip_port ] \
858 { address_match_list }; ] OK
859 [ query-source [ address ( ip_addr | * ) ] \
860 [ port ( ip_port | * ) ] ; ] OK
861 [ lame-ttl number; ] OK
862 [ max-transfer-time-in number; ] OK
863 [ max-ncache-ttl number; ] OK
864 [ min-roots number; ] Not Implemented
865 [ transfer-format ( one-answer | \
866 many-answers ); ] OK (*6)
867 [ transfers-in number; ] OK
868 [ transfers-out number; ] OK
869 [ transfers-per-ns number; ] OK
870 [ transfer-source ip_addr; ] OK
871 [ maintain-ixfr-base yes_or_no; ] Obsolete
872 [ max-ixfr-log-size number; ] Obsolete (*7)
873 [ coresize size_spec ; ] OK
874 [ datasize size_spec ; ] OK
875 [ files size_spec ; ] OK
876 [ stacksize size_spec ; ] OK
877 [ cleaning-interval number; ] OK
878 [ heartbeat-interval number; ] OK
879 [ interface-interval number; ] OK
880 [ statistics-interval number; ] Not Implemented
881 [ topology { address_match_list }; ] Not Implemented
882 [ sortlist { address_match_list }; ] OK
883 [ rrset-order { order_spec ; \
884 [ order_spec ; ... ] }; ] Not Implemented
885 };
887 (*1) Obsolete due to architectural differences.
888 (*2) Default set to yes in BIND 8, no in BIND 9.
889 (*3) Needs an IP address for "yes".
890 (*4) Doesn't work if no forwarder specified; Gives an error of "no
891 matching 'forwarders' statement" in that case.
892 (*5) See [ forward ] clause
893 (*6) Default set to one-answer in BIND 8 and many-answers in BIND 9.
894 (*7) No need for this option as BIND 9 trims the size of its
895 log file automatically.
896 (*8) Implemented in BIND 9.3.4
899 IIIb. Statements in BIND 9
900 --------------------
902 The Controls Statement
903 ----------------------
904 Syntax
905 controls {
906 [ inet ip_addr
907 port ip_port
908 allow { address_match_list; }; ] OK
909 [ unix path_name
910 perm number
911 owner number
912 group number; ] Not Implemented
913 };
915 Note: "unix" is the default for ndc(1M) and all of the arguments
916 are compiled in.
918 "inet" is the only option for rndc and nothing is compiled in.
920 Logging syntax has changed significantly. See section IIIc for a
921 list of named.conf options.
924 The Zone Statement
925 ------------------
926 The syntax for the zone statement in the BIND 8 named.conf man page
927 is mostly supported for BIND 9 except for the following:
929 [ pubkey number number number string; ] Obsolete
932 The ACL Statement
933 -----------------
934 Syntax
935 acl name {
936 address_match_list
937 };
939 Works unchanged in BIND 9.
942 The Key Statement
943 -----------------
944 Syntax
945 key key_id {
946 algorithm algorithm_id;
947 secret secret_string;
948 };
950 Works unchanged in BIND 9.
953 The Trusted-Keys Statement
954 --------------------------
955 Syntax
956 trusted-keys {
957 [ domain_name flags protocol algorithm key; ]
958 };
960 Works unchanged, however the code to use this
961 statement has been turned off in BIND 9.2.4.
964 The Server Statement
965 --------------------
966 Syntax
967 server ip_addr {
968 [ bogus yes_or_no; ]
969 [ transfers number; ]
970 [ transfer-format ( one-answer | many-answers ); ]
971 [ keys { key_id [ key_id ... ] }; ]
972 [ edns yes_or_no; ]
973 };
975 "support-ixfr" is obsolete, however all of the above options work
976 unchanged in BIND 9. Note the default for transfer-format has changed.
979 The Include Statement
980 ---------------------
981 Syntax
982 include path_name;
984 Works unchanged in BIND 9.
989 IIIc. Summary of the named.conf Options
990 ---------------------------------
992 A detailed named.conf man page was not included with BIND 9 originally.
993 Following is a summary of the named.conf options that are
994 supported in BIND 9.3.6
996 acl string { address_match_element; ... };
998 key domain_name {
999 algorithm string;
1000 secret string;
1001 };
1003 masters string [ port integer ] {
1004 ( masters | ipv4_address [port integer] |
1005 ipv6_address [port integer] ) [ key string ]; ...
1006 };
1008 server ( ipv4_address | ipv6_address ) {
1009 bogus boolean;
1010 edns boolean;
1011 provide-ixfr boolean;
1012 request-ixfr boolean;
1013 keys server_key;
1014 transfers integer;
1015 transfer-format ( many-answers | one-answer );
1016 transfer-source ( ipv4_address | * )
1017 [ port ( integer | * ) ];
1018 transfer-source-v6 ( ipv6_address | * )
1019 [ port ( integer | * ) ];
1020 support-ixfr boolean; // obsolete
1021 };
1023 trusted-keys {
1024 domain_name flags protocol algorithm key; ...
1025 };
1027 controls {
1028 inet ( ipv4_address | ipv6_address | * )
1029 [ port ( integer | * ) ]
1030 allow { address_match_element; ... }
1031 [ keys { string; ... } ];
1032 unix unsupported; // not implemented
1033 };
1035 logging {
1036 channel string {
1037 file log_file;
1038 syslog optional_facility;
1039 null;
1040 stderr;
1041 severity log_severity;
1042 print-time boolean;
1043 print-severity boolean;
1044 print-category boolean;
1045 };
1046 category string { string; ... };
1047 };
1049 options {
1050 avoid-v4-udp-ports { port; ... };
1051 avoid-v6-udp-ports { port; ... };
1052 blackhole { address_match_element; ... };
1053 coresize size;
1054 datasize size;
1055 directory quoted_string;
1056 cache-file quoted_string; // test option
1057 dump-file quoted_string;
1058 files size;
1059 heartbeat-interval integer;
1060 host-statistics boolean; // not implemented
1061 host-statistics-max number; // not implemented
1062 hostname ( quoted_string | none );
1063 interface-interval integer;
1064 listen-on [ port integer ] { address_match_element; ... };
1065 listen-on-v6 [ port integer ] { address_match_element; ... };
1066 match-mapped-addresses boolean;
1067 memstatistics-file quoted_string;
1068 pid-file ( quoted_string | none );
1069 port integer;
1070 querylog boolean;
1071 recursing-file quoted_string;
1072 reserved-sockets integer;
1073 random-device quoted_string;
1074 recursive-clients integer;
1075 serial-query-rate integer;
1076 server-id ( quoted_string | none );
1077 stacksize size;
1078 statistics-file quoted_string;
1079 statistics-interval integer; // not yet implemented
1080 tcp-clients integer;
1081 tcp-listen-queue integer;
1082 tkey-dhkey quoted_string integer;
1083 tkey-gssapi-credential quoted_string;
1084 tkey-domain quoted_string;
1085 transfers-per-ns integer;
1086 transfers-in integer;
1087 transfers-out integer;
1088 use-ixfr boolean;
1089 version ( quoted_string | none );
1090 allow-recursion { address_match_element; ... };
1091 sortlist { address_match_element; ... };
1092 topology { address_match_element; ... }; // not implemented
1093 auth-nxdomain boolean; // default changed
1094 minimal-responses boolean;
1095 recursion boolean;
1096 rrset-order {
1097 [ class string ] [ type string ]
1098 [ name quoted_string ] string string; ...
1099 };
1100 provide-ixfr boolean;
1101 request-ixfr boolean;
1102 rfc2308-type1 boolean; // not yet implemented
1103 additional-from-auth boolean;
1104 additional-from-cache boolean;
1105 query-source [ address ( ipv4_address | * ) ] [ port ( integer | * ) ];
1106 query-source-v6 [ address ( ipv6_address | * ) ] [ port ( integer | * ) ];
1107 cleaning-interval integer;
1108 min-roots integer; // not implemented
1109 lame-ttl integer;
1110 max-ncache-ttl integer;
1111 max-cache-ttl integer;
1112 transfer-format ( many-answers | one-answer );
1113 max-cache-size size_no_default;
1114 check-names ( master | slave | response )
1115 ( fail | warn | ignore );
1116 cache-file quoted_string;
1117 suppress-initial-notify boolean; // not yet implemented
1118 preferred-glue string;
1119 dual-stack-servers [ port integer ] {
1120 ( quoted_string [port integer] |
1121 ipv4_address [port integer] |
1122 ipv6_address [port integer] ); ...
1123 }
1124 edns-udp-size integer;
1125 root-delegation-only [ exclude { quoted_string; ... } ];
1126 disable-algorithms string { string; ... };
1127 dnssec-enable boolean;
1128 dnssec-lookaside string trust-anchor string;
1129 dnssec-must-be-secure string boolean;
1130 dialup dialuptype;
1131 ixfr-from-differences ixfrdiff;
1132 allow-query { address_match_element; ... };
1133 allow-transfer { address_match_element; ... };
1134 allow-update-forwarding { address_match_element; ... };
1135 notify notifytype;
1136 notify-source ( ipv4_address | * ) [ port ( integer | * ) ];
1137 notify-source-v6 ( ipv6_address | * ) [ port ( integer | * ) ];
1138 also-notify [ port integer ] { ( ipv4_address | ipv6_address )
1139 [ port integer ]; ... };
1140 allow-notify { address_match_element; ... };
1141 forward ( first | only );
1142 forwarders [ port integer ] {
1143 ( ipv4_address | ipv6_address ) [ port integer ]; ...
1144 };
1145 max-journal-size size_no_default;
1146 max-transfer-time-in integer;
1147 max-transfer-time-out integer;
1148 max-transfer-idle-in integer;
1149 max-transfer-idle-out integer;
1150 max-retry-time integer;
1151 min-retry-time integer;
1152 max-refresh-time integer;
1153 min-refresh-time integer;
1154 multi-master boolean;
1155 sig-validity-interval integer;
1156 transfer-source ( ipv4_address | * )
1157 [ port ( integer | * ) ];
1158 transfer-source-v6 ( ipv6_address | * )
1159 [ port ( integer | * ) ];
1160 alt-transfer-source ( ipv4_address | * )
1161 [ port ( integer | * ) ];
1162 alt-transfer-source-v6 ( ipv6_address | * )
1163 [ port ( integer | * ) ];
1164 use-alt-transfer-source boolean;
1165 zone-statistics boolean;
1166 key-directory quoted_string;
1167 allow-v6-synthesis { address_match_element; ... }; // obsolete
1168 deallocate-on-exit boolean; // obsolete
1169 fake-iquery boolean; // obsolete
1170 fetch-glue boolean; // obsolete
1171 has-old-clients boolean; // obsolete
1172 maintain-ixfr-base boolean; // obsolete
1173 max-ixfr-log-size size; // obsolete
1174 multiple-cnames boolean; // obsolete
1175 named-xfer quoted_string; // obsolete
1176 serial-queries integer; // obsolete
1177 treat-cr-as-space boolean; // obsolete
1178 use-id-pool boolean; // obsolete
1179 };
1181 view string optional_class {
1182 match-clients { address_match_element; ... };
1183 match-destinations { address_match_element; ... };
1184 match-recursive-only boolean;
1185 key string {
1186 algorithm string;
1187 secret string;
1188 };
1189 zone string optional_class {
1190 ...
1191 };
1192 server ( ipv4_address | ipv6_address ) {
1193 ...
1194 };
1195 trusted-keys {
1196 string integer integer integer quoted_string; ...
1197 };
1198 allow-recursion { address_match_element; ... };
1199 sortlist { address_match_element; ... };
1200 topology { address_match_element; ... }; // not implemented
1201 auth-nxdomain boolean; // default changed
1202 minimal-responses boolean;
1203 recursion boolean;
1204 rrset-order {
1205 [ class string ] [ type string ]
1206 [ name quoted_string ] string string; ...
1207 };
1208 provide-ixfr boolean;
1209 request-ixfr boolean;
1210 rfc2308-type1 boolean; // not yet implemented
1211 additional-from-auth boolean;
1212 additional-from-cache boolean;
1213 query-source [ address ( ipv4_address | * ) ] [ port ( integer | * ) ];
1214 query-source-v6 [ address ( ipv6_address | * ) ] [ port ( integer | * ) ];
1215 cleaning-interval integer;
1216 min-roots integer; // not implemented
1217 lame-ttl integer;
1218 max-ncache-ttl integer;
1219 max-cache-ttl integer;
1220 transfer-format ( many-answers | one-answer );
1221 max-cache-size size_no_default;
1222 check-names ( master | slave | response )
1223 ( fail | warn | ignore );
1224 cache-file quoted_string;
1225 suppress-initial-notify boolean; // not yet implemented
1226 preferred-glue string;
1227 dual-stack-servers [ port integer ] {
1228 ( quoted_string [port integer] |
1229 ipv4_address [port integer] |
1230 ipv6_address [port integer] ); ...
1231 };
1232 edns-udp-size integer;
1233 root-delegation-only [ exclude { quoted_string; ... } ];
1234 disable-algorithms string { string; ... };
1235 dnssec-enable boolean;
1236 dnssec-lookaside string trust-anchor string;
1237 dnssec-must-be-secure string boolean;
1238 dialup dialuptype;
1239 ixfr-from-differences ixfrdiff;
1240 allow-query { address_match_element; ... };
1241 allow-transfer { address_match_element; ... };
1242 allow-update-forwarding { address_match_element; ... };
1243 notify notifytype;
1244 notify-source ( ipv4_address | * ) [ port ( integer | * ) ];
1245 notify-source-v6 ( ipv6_address | * ) [ port ( integer | * ) ];
1246 also-notify [ port integer ] { ( ipv4_address | ipv6_address )
1247 [ port integer ]; ... };
1248 allow-notify { address_match_element; ... };
1249 forward ( first | only );
1250 forwarders [ port integer ] {
1251 ( ipv4_address | ipv6_address ) [ port integer ]; ...
1252 };
1253 max-journal-size size_no_default;
1254 max-transfer-time-in integer;
1255 max-transfer-time-out integer;
1256 max-transfer-idle-in integer;
1257 max-transfer-idle-out integer;
1258 max-retry-time integer;
1259 min-retry-time integer;
1260 max-refresh-time integer;
1261 min-refresh-time integer;
1262 multi-master boolean;
1263 sig-validity-interval integer;
1264 transfer-source ( ipv4_address | * )
1265 [ port ( integer | * ) ];
1266 transfer-source-v6 ( ipv6_address | * )
1267 [ port ( integer | * ) ];
1268 alt-transfer-source ( ipv4_address | * )
1269 [ port ( integer | * ) ];
1270 alt-transfer-source-v6 ( ipv6_address | * )
1271 [ port ( integer | * ) ];
1272 use-alt-transfer-source boolean;
1273 zone-statistics boolean;
1274 key-directory quoted_string;
1275 allow-v6-synthesis { address_match_element; ... }; // obsolete
1276 fetch-glue boolean; // obsolete
1277 maintain-ixfr-base boolean; // obsolete
1278 max-ixfr-log-size size; // obsolete
1279 };
1281 zone string optional_class {
1282 type ( master | slave | stub | hint |
1283 forward | delegation-only );
1284 file quoted_string;
1285 masters [ port integer ] {
1286 ( masters |
1287 ipv4_address [port integer] |
1288 ipv6_address [ port integer ] ) [ key string ]; ...
1289 };
1290 database string;
1291 delegation-only boolean;
1292 check-names ( fail | warn | ignore );
1293 dialup dialuptype;
1294 ixfr-from-differences boolean;
1295 allow-query { address_match_element; ... };
1296 allow-transfer { address_match_element; ... };
1297 allow-update { address_match_element; ... };
1298 allow-update-forwarding { address_match_element; ... };
1299 update-policy {
1300 ( grant | deny ) string
1301 ( name | subdomain | wildcard | self ) string
1302 rrtypelist; ...
1303 };
1304 notify notifytype;
1305 notify-source ( ipv4_address | * ) [ port ( integer | * ) ];
1306 notify-source-v6 ( ipv6_address | * ) [ port ( integer | * ) ];
1307 also-notify [ port integer ] { ( ipv4_address | ipv6_address )
1308 [ port integer ]; ... };
1309 allow-notify { address_match_element; ... };
1310 forward ( first | only );
1311 forwarders [ port integer ] {
1312 ( ipv4_address | ipv6_address ) [ port integer ]; ...
1313 };
1314 max-journal-size size_no_default;
1315 max-transfer-time-in integer;
1316 max-transfer-time-out integer;
1317 max-transfer-idle-in integer;
1318 max-transfer-idle-out integer;
1319 max-retry-time integer;
1320 min-retry-time integer;
1321 max-refresh-time integer;
1322 min-refresh-time integer;
1323 multi-master boolean;
1324 sig-validity-interval integer;
1325 transfer-source ( ipv4_address | * )
1326 [ port ( integer | * ) ];
1327 transfer-source-v6 ( ipv6_address | * )
1328 [ port ( integer | * ) ];
1329 alt-transfer-source ( ipv4_address | * )
1330 [ port ( integer | * ) ];
1331 alt-transfer-source-v6 ( ipv6_address | * )
1332 [ port ( integer | * ) ];
1333 use-alt-transfer-source boolean;
1334 zone-statistics boolean;
1335 key-directory quoted_string;
1336 ixfr-base quoted_string; // obsolete
1337 ixfr-tmp-file quoted_string; // obsolete
1338 maintain-ixfr-base boolean; // obsolete
1339 max-ixfr-log-size size; // obsolete
1340 pubkey integer integer integer quoted_string; // obsolete
1341 };