Copyright (C) 2004  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

	      includes BIND 9.2.4 to BIND 9.3.4 changes

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.

Introduction

------------

This document provides information about differences between BIND 8 and

BIND 9. BIND 9 is upwards compatible with most BIND 8 features. However,

there are still a number of caveats you should be aware of when upgrading

an existing BIND 8 installation to use BIND 9. Be sure to read this

entire document before installing and using BIND 9.

This document contains the following sections:

	* Section A, 1-7 Overview of Differences Between BIND 8 and BIND 9

	* Section 8      BIND 9 name server and the Service Management Facility

	* Appendix I     Implementing rndc

	* Appendix II    BIND 9 Commands, Options, Files, and Tools

	* Appendix III   The named.conf Options

Additional information and documentation about BIND 9, including an

Administrator Reference Manual (ARM) is available on the ISC web site

at http://www.isc.org

The words "named", "DNS server", "name server" and "BIND 9 server"

are used interchangeably to denote the Internet Systems Consortium

BIND version 9 DNS server throughout this document.

Overview of Differences Between BIND 8 and BIND 9

-------------------------------------------------

Below is a list of changes between BIND 8 and BIND 9, including brief

descriptions. For more detailed information, see the appropriate

subsection for each item.

Configuration File Compatibility, 	Section 1.0

    * unimplemented options warning message	1.1

    * "transfer-format" option changes		1.1

    * configuration file errors 		1.2

    * logging categories have changed		1.3

    * configuration file startup errors		1.3

    * "query-source" is deprecated		1.4

    * multiple classes change			1.5

Zone File Compatibility, 		Section 2.0

    * stricter rules for TTLs in zone file	2.1

    * SOA serial number changes			2.2

    * unbalanced quotes cause errors		2.3

    * line breaks, syntax change		2.4

    * use /$ instead of $$ in domain names	2.5

Interoperability Impact of New Protocol

Features,				Section 3.0

    * EDNS0 new in BIND 9			3.1

    * zone transfers default change		3.2

Unrestricted Character Set,		Section 4.0

    * no restrictions on character set		4.0

    * security issue, improper naming		4.0

Server Administration Tools, 		Section 5.0

    * the rndc program replaces ndc		5.1

    * nsupdate: changes in multiple updates 	5.2

No Information Leakage Between Zones,	Section 6.0

    * glue NS records handled differently	6.0

Umask Not Modified,			Section 7.0

    * possible umask permissions issues		7.0

1. Configuration File Compatibility

1.1. Unimplemented Options and Changed Defaults

The BIND 9 name server supports most, but not all, of the configuration

options of the BIND 8 name server. For a complete list of implemented

options, see Appendix III of this document.

If your named.conf file uses an unimplemented option, the BIND 9 name

server 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 and older) you need to explicitly specify

"transfer-format one-answer;" in either the options block or a

server statement.

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 customized 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 than

"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 time-to-live (TTL) entries 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 Resource Record (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.

Earlier versions of BIND 9 refused to load such files. However, BIND

9.2.4 loads the files anyway (provided the SOA is the first record

in the file), but will issue a TTL warning message.

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 TXT RDATA that contained more

than 255 characters and silently split them in to multiple RDATA

records to comply with protocol.  This feature has been removed, and

the following error is produced upon reading these records:

        "dns_rdata_fromtext: local.db:119: ran out of space"

To address split the string in the zone data file at or before the 255

character in to two or more TXT records.

3. Interoperability Impact of New Protocol Features

3.1. EDNS0

BIND 9 uses EDNS0 (RFC2671) to advertise its receive buffer size.  It

also sets an EDNS flag bit in queries to indicate that it wishes to

receive DNSSEC responses; this flag bit usage is not yet standardised,

but we hope it will be.

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. The manufacturer of the name server is 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 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.2.4 and above 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.2.4 provided no such

protection; advice was that applications with these flaws should be

upgraded. Subsequently however, BIND 9.3.x 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(1M), rndc-confgen(1M),

and rndc.conf(5) for details. While upgrading from previous Solaris

releases to Solaris 10, the upgrade process will detect if a

/etc/rndc.key or /etc/rndc.conf file exists. If neither file is

found, it runs "rndc-confgen -a" and generates /etc/rndc.key

so that rndc can be run with a local DNS name server without

further user intervention.

More information about rndc is available in "Implementing rndc",

later in this document.

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.

8. BIND 9 name server and the Service Management Facility

The DNS BIND 9 named(1M) service can be managed by using the Service

Management Facility (SMF). For more information, see the smf(5) man

page. The SUNWbindr package provides the BIND 9 service manifest

and must be installed.

When you use SMF, the following items apply.

- Administrative actions on this service, such as enabling, disabling,

or restarting, can be performed by using the svcadm(1M) command.

- The default Fault Managed Resource Identifier (FMRI) for the BIND 9

DNS server is svc:/network/dns/server. The FMRI for the DNS client is

svc:/network/dns/client.

- You can query the state of the BIND 9 DNS service by using svcs(1).

  For example:

	# svcs svc:network/dns/server:default

	STATE          STIME    FMRI

	online         16:24:04 svc:/network/dns/server:default

The upgrade to Solaris 10 will detect an existing /etc/named.conf file

and enable the BIND 9 service to startup after the upgrade is completed

and the system is rebooted.

To start the BIND 9 DNS service on a Solaris 10 system:

a. Create/Copy a valid /etc/named.conf file.

b. Verify that the SUNWbind and SUNWbindr packages, including any

   required packages are installed correctly.

c. Enable the default service instance using svcadm(1M). For example:

	# svcadm enable svc:network/dns/server:default

While it is recommended that you use svcadm(1M) to administer the server,

you can use rndc(1M) as well. SMF is aware of the state change of the BIND

9 named service, whether administered by using svcadm(1M) or rndc(1M).

NOTE: smf(5) will not be aware of the BIND 9 named(1M) service

if the service is manually executed from the command line.

NOTE: rndc(1M) is not able to stop the service when used in a chroot(2)

environment under smf(1M) control.

8.1 Name Server SMF Properties

Relevant named(1M) options for use with smf(1) may be applied using

service application properties:

 - options/configuration_file

	Specifies  the configuration file   to be used instead of

	the  default /etc/named.conf.   To ensure  that reloading

	the configuration file continues to work after the server

	has  changed its working directory due  to  to a possible

	directory  option    in   the  configuration   file,  the

	configuration file should be  an absolute  pathname.  The

	configuration  pathname should not include the chroot_dir

	pathname.  This property is synonymous to the -c option.

 - options/ip_interfaces

	specifies  which  IP  transport  BIND  will transmit  on.

	Possible values are 'IPv4' or  'IPv6'.  Any other setting

	assumes 'all',  the default.  This property is synonymous

	to command line option '-4' or '-6'

 - options/listen_on_port

	Specifies the default UDP and TCP port which will be used

	to listen for  DNS requests.  This property is synonymous

	to command line option '-p port'.

 - options/debug_level

	Specifies the default debug  level.  The default is 0; no

	debugging. The  Higher the number  the more verbose debug

	information becomes.  Synonymous  to command  line option

	'-d debug-level'.

 - options/threads

	 Specifies  the number of cpu  worker  threads to create.

	 The default of  0 causes named to  try and determine the

	 number  of CPUs  present    and create one   thread  per

	 CPU. Synonymous to command line option '-n #cpus'.

 - options/chroot_dir

	Specifies the directory to be  used as the root directory

	after processing SMF   properties and  the  command  line

	arguments but before reading the configuration file.  Use

	this   property  when  using   a   chroot(2) environment.

	Synonymous to command line option '-t <pathname>'.

	When using chroot(2) named is unable  to disable its self

	when receiving rndc(1M) stop or halt commands and you must

	instead use the svcadm(1M) disable command.

- options/server

	Specifies an alternative execution path.  If unset then the

	default server /usr/sbin/named is assumed.

The following examples show how the application properties may be used:

  Example 1: Configuring named(1m) in future to only transmit

             over IPv4 networks:

	# svccfg -s svc:network/dns/server:default setprop \

	options/ip_interfaces=IPv4

	# svcadm refresh svc:network/dns/server:default

	# scvadm restart svc:network/dns/server:default

  Example 2: List current configuration file and change to

             an alternative file:

	# svcprop -p options/configuration_file dns/server:default

	""

	# svccfg -s dns/server:default setprop \

	options/configuration_file=/var/named/named.conf

	# svcadm refresh dns/server:default

	# svcprop -p options/configuration_file dns/server:default

	/var/named/named.conf

	# scvadm restart svc:network/dns/server:default

The dns/server smf_method(5) script converts the application properties

to the relevant command line option.

Changing the "start method" property of the BIND 9 service is no longer

recommended as was stated here previously.

For more information about the Service Management Facility, refer to

"Managing Services (Overview)" in System Administration Guide: Basic

Administration, available on http://docs.sun.com. Also refer to smf(5),

svcs(1), svcadm(1M), svccfg(1M) man pages and the BIND 9 name service

manifest server.xml in /lib/svc/manifest/network/dns.

		*************************************

			    APPENDICES I-III

Appendix I. Implementing rndc

            -----------------

The BIND 8 ndc(1M) and BIND 9 rndc(1M) name server control tools are

NOT backward compatible: rndc can't talk to the BIND 8 name server

and ndc can't talk to the BIND 9 name server. Features, options,

default modes of operation, and configuration file requirements

have changed.

Ia. The rndc.conf Configuration File

    --------------------------------

The most significant difference between ndc in BIND 8 and rndc in BIND 9

is that rndc needs its own configuration file, rndc.conf. This file can

be generated by rndc-confgen(1M) commands. The rndc.conf file specifies

which server controls and what algorithm the server should use. Note that

the /etc/rndc.conf and matching /etc/named.conf information is only needed

when using rndc to manage a remote BIND 9 name server. If rndc is only

used to manage a local BIND 9 name server, the /etc/rndc.key is sufficient.

     Sample rndc.conf File

     ---------------------

     options {

             default-server localhost;

             default-key "rndc-key";

     };

     key "rndc-key" {

             algorithm hmac-md5;

             secret "qPWZ3Ndl81aBRY9AmJhVtU==";

     };

     Sample named.conf File Entry for rndc

     -------------------------------------

     controls {

             inet * allow { any; } keys { "rndc-key"; };

     };

     key "rndc-key" {

             algorithm hmac-md5;

             secret "qPWZ3Ndl81aBRY9AmJhVtU==";