==== Updating MaraDNS ====

=== Table of contents ===

* Updating from 1.0 to 1.2

* Updating from 1.2.03 to a later 1.2 release

* Updating from 1.2.12 to a 1.3 release

* Updating from 1.3 to a 1.4 release

* Updatring from MaraDNS 1.4 to MaraDNS 2.0

This document is divided in to two parts; anyone upgrading from a 1.0 
release to a recent 1.2 release will need to look over both sections of 
this document. 

=== Updating from 1.0 to 1.2 ===

MaraDNS 1.2 has a number of advantages over 1.0, including Y2038 
compliance, full support for DNS over TCP, and a new zone file format. 
While including a number of new features, MaraDNS 1.2 is almost 
completely compatible with all MaraDNS 1.0 data files. An update from 
1.0 to 1.2 will, with very few exceptions, not need any data files to 
be changed. All MaraDNS 1.0 zone files will work with MaraDNS 1.2, and 
almost all 1.0 mararc configuration files will work with MaraDNS 1.2. 

To update a MaraDNS install from 1.0 to 1.2, download the MaraDNS 1.2 
tarball, and type in the following command:

	./configure ; make

This is followed by:

	make install

No configuration files will be overwritten by the installation of 
the new MaraDNS 1.2 binaries (making backups of all data files, 
naturally, is always a good idea).  The only time a 1.0 mararc file 
will not work is when there is a misspelled mararc variable in the 
mararc file. For example, let us suppose we have a mararc file that 
looks like this:

bind_address = "127.0.0.1" 
chroot_dir = "/etc/maradns" 
maradns_uid = 99 
maxprocs = 96 
default_rrany_set = 3 
verbose_levul = 1

This will run fine in MaraDNS 1.0. However, when we try to run 
this file in MaraDNS 1.2, we will get this error message:

FATAL ERROR: Unknown mararc variable verbose_levul 
Please look for the uncommented string "verbose_levul" 
in your mararc file and remove this line. 
 
The line this error is on looks like this: 
verbose_levul = 1

This misspelled mararc variable needs to either be completely 
removed from the mararc file, or disabled by commenting out. The 
following mararc snippet will work identically in MaraDNS 1.0 as the 
above snippet, and will parse in MaraDNS 1.2 without a fatal error:

bind_address = "127.0.0.1" 
chroot_dir = "/etc/maradns" 
maradns_uid = 99 
maxprocs = 96 
default_rrany_set = 3 
# Comment out the misspelled mararc variable 
#verbose_levul = 1

 Since MaraDNS 1.2 is usually started with the new duende 
daemonizing program, timestamps are, by default, no longer shown (since 
otherwise the system logs would have a redundant timestamp in them). If 
the older behavior of showing a UNIX time stamp is desired, add the 
following to a MaraDNS 1.2 mararc file:

timestamp_type = 0

=== Updating from 1.2.03 to a later 1.2 release ===

There are a few minor changes between the 1.2.03 branch and later 1.2 
releases of MaraDNS: The special remote queries have been 
changed The special remote queries, which can obtain information 
about MaraDNS' internal state, have been changed: 

* The admin_acl variable needs to be set for these variables to work. 
  E.g. admin_acl = "127.0.0.1, 192.168.116.0/24", which only allows 
  127.0.0.1 (the same machine) or any machine with an IP that 
  starts with 192.168.116 to access this information.

* The TXT query erre-con-erre-cigarro.maradns.org is now done with 
  version.maradns

* The TXT query numthreads (this and all other special queries except 
  version.maradns are only enabled when debug_msg_level is set) is 
  now numthreads.maradns

* The TXT query cache-elements is now cache-elements.maradns

* The TXT query memusage is now memusage.maradns

* The TXT query timestamp is now timestamp.maradns

* The TXT query number.verbose_level.maradns has been added, but is 
  only enabled if the remote_admin mararc variable is set.

Further information about these queries can be obtained by looking at 
the mararc man page; in particular, look for admin_acl, 
debug_msg_level, and remote_admin. Zone names are now 
case-insensitive Zone names are now case-insensitive. In other 
words, a line like this in the mararc file:

csv2["EXAMPLE.COM."] = "DB.EXAMPLE.COM"

Is converted as if the line were:

csv2["example.com."] = "DB.EXAMPLE.COM"

This affects both csv1 and csv2 zone names. Since hostnames in 
both csv1 and csv2 host names are converted to lower-case, the impact 
of this change should be minimal. Dictionary variables now must be 
initialized before being used MaraDNS 1.2.07 now mandates that 
dictionary variables must be initialized before being used. This line, 
by itself, used to parse in a mararc file:

upstream_servers["."] = "10.1.2.3"

However, this line would do nothing unless the upstream_servers 
dictionary variable was first initialized, e.g:

upstream_servers = {} 
upstream_servers["."] = "10.1.2.3"

MaraDNS 1.2.07 now mandates the initialization line or exits with 
a fatal error when parsing a mararc file. The reason for this is to 
make debugging mararc files easier. 

=== Updating from 1.2.12 to a 1.3 release ===

Updates to the csv2 parser In MaraDNS 1.3, some changes have 
been made to the csv2 parser. In particular: 

* The first record in a csv2 zone file can no longer be a TXT, WKS, or 
  LOC record.

* TXT (and SPF) records can no loner have tildes (the '~' character) 
  in them.

If these changes to the csv2 parser are not desired, it is possible to 
have MaraDNS 1.3's csv2 parser act like MaraDNS' 1.2 csv2 parser by 
adding the following line to one's mararc file:

csv2_tilde_handling = 0

The above line is also accepted by MaraDNS 1.2 releases starting 
with 1.2.12.04; this allows MaraDNS 1.2 and 1.3 use the same 
configuration file. 

The reason for this change is because MaraDNS now can use tildes to 
separate records. A MaraDNS 1.2 csv2 zone file that looked like this:

example.com. 10.1.2.4 
www.example.com. A 10.1.2.5 
example.com. MX mail.example.com. 
mail.example.com. 10.1.2.6 
example.com. TXT 'Hello, world!'

Now can look like this:

example.com. 10.1.2.4 ~ 
www.example.com. A 10.1.2.5 ~ 
example.com. MX mail.example.com. ~ 
mail.example.com. 10.1.2.6 ~ 
example.com. TXT 'Hello, world!'

The way MaraDNS figures out whether to use tilde to separate 
records is by looking between the first and second record to see if a 
tilde is present. If so, MaraDNS requires tildes to be between all 
records. If not, MaraDNS' csv2 parsing is almost completely 1.2 
compatible, the only difference being that tildes can not be in TXT 
records. 

Note that, if tildes are used to separate records, the following 
restrictions are added to TXT records: 

* The pipe (|) character is not allowed in TXT records. Use the '\x7c' 
  escape sequence instead. For example, change a TXT record that 
  looks like 'ls | more' to become 'ls '\x7c' more'

* The pipe (#) character is not allowed in TXT records. Use the '\x23' 
  escape sequence instead. For example, change a TXT record that 
  looks like 'press the # key' to become 'press the '\x23' key'

* Control characters, including the newline character, are not 
  allowed. The escape sequence used depends on the desired control 
  character. For example, use \x0a for a UNIX linefeed.

Another MaraDNS 1.3 change only affects the unusual case when one has 
delegation NS records. Let us suppose we have a zone file with the 
following records:

example.com. A 10.1.2.3 ~ 
www.example.com. A 10.1.2.4 ~ 
joe.example.com. NS ns.joe.example.com. ~ 
ns.joe.example.com. A 10.1.2.5

In MaraDNS 1.2, if we send a recursive request for 
www.joe.example.com, MaraDNS will convert the request in to a recursive 
request. In MaraDNS 1.3, we will get the following answer:

joe.example.com. NS ns.joe.example.com. ~ 
ns.joe.example.com. A 10.1.2.5

If the old MaraDNS 1.2 behavior is desired, such as for someone 
who is using the same nameserver to both give out delegation records 
and to recursively resolve records, add the following line to one's 
mararc file:

recurse_delegation = 1

bind_star_handling bind_star_handling is a variable that 
determines whether MaraDNS should be strictly RFC compliant with regard 
to star records. In MaraDNS 1.2, the default value for this was 0. In 
MaraDNS 1.3, the default value is 1. If, for some reason, the older 
non-RFC compliant behavior is desired, add this line to your mararc 
file:

bind_star_handling = 0

max_mem max_mem determined the maximum amount of memory 
MaraDNS is allowed to allocate. This is a numeric variable, and the 
value is in kilobytes. The default value of this is to allocate 1 
megabyte for MaraDNS' general use, and in addition, to allocate 1536 
bytes for each element we can have in the cache or DNS record that we 
are authoritatively serving. 

If, for whatever reason, you wish to disable this feature, add the 
following lint to your mararc file:

max_mem = 0

=== Updating from 1.3 to a 1.4 release ===

MaraDNS 1.4 has a few features added compared to the MaraDNS 1.3 
branch: 

* NAPTR support

* askmara, askmara-tcp and fetchzone now can have IPv6 support

* Bugfix: The RA bit is set if recursion is enabled; otherwise it is 
  not set.

* stdint.h (instead of the old BSD-specific types.h) is now used for 
  fixed-sized integers.

* New parameter: notthere_ip

* Zoneserver now supports dns_port parameter

* It is no longer possible to have the * character in zone names

* Documentation updates

* Other bug fixes

MaraDNS 1.4 is compatible with MaraDNS 1.3 unless one has a * in a zone 
name. Sometimes, people get confused and think this is how to have 
MaraDNS support wildcard records:

csv2["*.example.com."] = "db.example.star"

However, this does not work. The correct way to support star 
records is to have the star in the zone file, not the mararc file, like 
this:

*.example.com.	A	10.2.3.4

Have csv2["*.example.com."] will result in a zone file for the 
domain name "*.example.com." (with a literal star in the domain name), 
which is usually not what one wants. 

=== Updatring from MaraDNS 1.4 to MaraDNS 2.0 ===

MaraDNS 2.0 is MaraDNS 1.4 with all recursive support removed from the 
maradns daemon and done with the separate daemon Deadwood. Because of 
this: 

* MaraDNS can no longer serve both authoritative and recursive records 
  on the same IP.

* While Deadwood uses a compatible rc file format, there are enough 
  differences between a mararc file (MaraDNS' configuration file) 
  and a dwood3rc file (Deadwood's configuration file) that a 
  conversion has to be done by hand.

The most important thing to keep in mind when converting a mararc file 
to a dwood3rc file is that Deadwood does not support the following 
mararc parameters: 

* csv1

* csv2

* ipv4_alias

* admin_acl

* bind_star_handling

* csv2_default_zonefile

* csv2_synthip_list

* csv2_tilde_handling

* debug_msg_level

* default_rrany_set

* dos_protection_level

* hide_disclaimer

* long_packet_ipv4

* ipv6_bind_address (bind_address supports one or more ipv6 addresses 
  if Deadwood is compiled with IPv6 support)

* max_chain

* max_mem

* max_total

* min_ttl

* min_ttl_cname

* min_visible_ttl

* notthere_ip (If you want to make money with NX redirects, let's talk 
  money)

* recurse_delegation

* reject_ptr (but Deadwood does support reject_aaaa)

* remote_admin

* retry_cycles (use num_retries instead)

* spammers

* synth_soa_origin

* synth_soa_serial

* tcp_convert_acl

* tcp_convert_server

* timestamp_type (We assume the logger makes a timestamp for us)

* verbose_query (verbose_level will do this at a level of 100 or more)

* zone_transfer_acl

Also, Deadwood handles "verbose_level" differently; to get fully 
verbose messages, "verbose_level" has to be 200 (as opposed to MaraDNS' 
10).  

