<HEAD><TITLE>Updating MaraDNS</TITLE>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">

</HEAD>
<BODY>

<!-- Copyright 2005-2010 Sam Trenholme

    TERMS

    Redistribution and use, with or without modification, are permitted 
    provided that the following condition is met:

    1. Redistributions must retain the above copyright notice, this 
       list of conditions and the following disclaimer.

    This documentation is provided 'as is' with no guarantees of 
    correctness or fitness for purpose.

 -->

<h1>Table of contents</h1>
<ul>
<li><A href="#1.0">Updating from 1.0 to 1.2</A>
<li><A href="#1.2.03">Updating from 1.2.03 to a later 1.2 release</A>
<li><A href="#1.2.12">Updating from 1.2.12 to a 1.3 release</A>
<li><A href="#1.3">Updating from 1.3 to a 1.4 release</A>
<li><A href="#2.0">Updatring from MaraDNS 1.4 to MaraDNS 2.0</A>
</ul>

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.

<A name=1.0>
<h1>Updating from 1.0 to 1.2</h1>
</A>

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 <tt>mararc</tt>
configuration files will work with MaraDNS 1.2.

<p>

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

<pre>
	./configure ; make
</pre>

This is followed by:

<pre>
	make install
</pre>

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).

<hr>

The only time a 1.0 <tt>mararc</tt> file will not work is when there
is a misspelled mararc variable in the mararc file.  For example, let
us suppose we have a <tt>mararc</tt> file that looks like this:

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

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:

<pre>
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
</pre>

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

<pre>
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
</pre>

<hr>

Since MaraDNS 1.2 is usually started with the new <tt>duende</tt>
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 <tt>mararc</tt> file:

<pre>
timestamp_type = 0
</pre>

<A name=1.2.03>
<h1>Updating from 1.2.03 to a later 1.2 release</h1>

There are a few minor changes between the 1.2.03 branch and later 1.2
releases of MaraDNS:

<h3>The special remote queries have been changed</h3>

The special remote queries, which can obtain information about MaraDNS'
internal state, have been changed:

<ul>
<li>The <tt>admin_acl</tt> variable needs to be set for these variables
    to work.  E.g. <tt>admin_acl = "127.0.0.1, 192.168.116.0/24"</tt>, 
    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.
<li>The TXT query <tt>erre-con-erre-cigarro.maradns.org</tt> is now done
    with <tt>version.maradns</tt>
<li>The TXT query <tt>numthreads</tt> (this and all other special queries
    except <tt>version.maradns</tt> are only enabled when 
    <tt>debug_msg_level</tt> is set) is now <tt>numthreads.maradns</tt>
<li>The TXT query <tt>cache-elements</tt> is now 
    <tt>cache-elements.maradns</tt>
<li>The TXT query <tt>memusage</tt> is now <tt>memusage.maradns</tt>
<li>The TXT query <tt>timestamp</tt> is now <tt>timestamp.maradns</tt>
<li>The TXT query <i>number</i><tt>.verbose_level.maradns</tt> has been
    added, but is only enabled if the <tt>remote_admin</tt> mararc
    variable is set.
</ul>

Further information about these queries can be obtained by looking at
the <A href=man.mararc.html>mararc man page</A>; in particular, look
for <tt>admin_acl</tt>, <tt>debug_msg_level</tt>, and <tt>remote_admin</tt>.

<h3>Zone names are now case-insensitive</h3>

Zone names are now case-insensitive.  In other words, a line like this in
the mararc file:

<pre>
csv2["EXAMPLE.COM."] = "DB.EXAMPLE.COM"
</pre>

Is converted as if the line were:

<pre>
csv2["example.com."] = "DB.EXAMPLE.COM"
</pre>

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.

<h3>Dictionary variables now must be initialized before being used</h3>

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:

<pre>
upstream_servers["."] = "10.1.2.3"
</pre>

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

<pre>
upstream_servers = {}
upstream_servers["."] = "10.1.2.3"
</pre>

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.

<A name=1.2.12>
<h1>Updating from 1.2.12 to a 1.3 release</h1>

<h3>Updates to the csv2 parser</h3>

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

<ul>
<li>The first record in a csv2 zone file can no longer be a TXT, WKS, or
LOC record.  
<li>TXT (and SPF) records can no loner have tildes (the '~' character) in them.
</ul>

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 <tt>mararc</tt> file:

<pre>
csv2_tilde_handling = 0
</pre>

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.

<p>

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:

<pre>
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!'
</pre>

Now can look like this:

<pre>
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!'
</pre>

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.

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

<ul>
<li>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'

<li>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'

<li>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.
</ul>
<p>
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:

<pre>
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 
</pre>

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

<pre>
joe.example.com. NS ns.joe.example.com. ~
ns.joe.example.com. A 10.1.2.5
</pre>

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:

<pre>
recurse_delegation = 1
</pre>

<h3>bind_star_handling</h3>

<tt>bind_star_handling</tt> 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 <tt>mararc</tt> file:

<pre>
bind_star_handling = 0
</pre>

<h3>max_mem</h3>

<tt>max_mem</tt> 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.  

<p>

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

<pre>
max_mem = 0
</pre>

<A name=1.3> </A>
<h1>Updating from 1.3 to a 1.4 release</h1>

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

<ul>
<li>NAPTR support
<li>askmara, askmara-tcp and fetchzone now can have IPv6 support
<li>Bugfix: The RA bit is set if recursion is enabled; otherwise it is
	not set.
<li>stdint.h (instead of the old BSD-specific types.h) is now used for
	fixed-sized integers.
<li>New parameter: notthere_ip
<li>Zoneserver now supports dns_port parameter
<li>It is no longer possible to have the * character in zone names
<li>Documentation updates
<li>Other bug fixes
</ul>

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:

<pre>
csv2["*.example.com."] = "db.example.star"
</pre>

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

<pre>
*.example.com.	A	10.2.3.4
</pre>

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.

<A name=2.0> </A>
<h1>Updatring from MaraDNS 1.4 to MaraDNS 2.0</h1>

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

<ul>

<li>MaraDNS can no longer serve both authoritative and recursive records on 
    the same IP.

<li>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.

</ul>

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:

<ul>
<li>csv1
<li>csv2
<li>ipv4_alias
<li>admin_acl
<li>bind_star_handling
<li>csv2_default_zonefile
<li>csv2_synthip_list
<li>csv2_tilde_handling
<li>debug_msg_level
<li>default_rrany_set
<li>dos_protection_level
<li>hide_disclaimer
<li>long_packet_ipv4
<li>ipv6_bind_address (bind_address supports one or more ipv6 addresses if 
    Deadwood is compiled with IPv6 support)
<li>max_chain
<li>max_mem
<li>max_total
<li>min_ttl
<li>min_ttl_cname
<li>min_visible_ttl
<li>notthere_ip (If you want to make money with NX redirects, let's talk money)
<li>recurse_delegation
<li>reject_ptr (but Deadwood does support reject_aaaa)
<li>remote_admin
<li>retry_cycles (use num_retries instead)
<li>spammers
<li>synth_soa_origin
<li>synth_soa_serial
<li>tcp_convert_acl
<li>tcp_convert_server
<li>timestamp_type (We assume the logger makes a timestamp for us)
<li>verbose_query (verbose_level will do this at a level of 100 or more)
<li>zone_transfer_acl
</ul>

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

</BODY></HTML>

