README.par

	        pdnsd version 1.2.9a by Paul Rombouts
                =====================================

This file describes the version of pdnsd that I maintain personally and am
making available so other people can enjoy the latest features and fixes. Thomas
Moestl no longer maintains pdnsd himself, so I am effectively the new
maintainer. This README describes the new features in version 1.2. This version
has a rather large number of internal changes and also some new features, which
I am rather pleased with, even if I say so myself. I think the changes are
significant enough to warrant increasing the minor version number from 1.1 to
1.2. The differences between my previous "official" release 1.1.11 and Thomas'
last release 1.1.7a are described in my previous README, which I have renamed
REAME.par.old. In this README I restrict myself to describing changes between
1.1.11 and 1.2.
The main difference between versions 1.2 and 1.2.1, aside from some minor
changes, is that 1.2.1 has (experimental) support for the Cygwin platform.
Version 1.2.2 has further improvements in portability and should in
particular now also compile on the Darwin (Apple Mac OS X) platform.
Version 1.2.4 has some important fixes for a memory leak, a minor buffer-
overflow problem and some situations which could cause pdnsd to exit
prematurely. Note that TCP-query support is now compiled in by default, but can
still be disabled using a configure option.
The main new feature of version 1.2.5 is the new query method "udp_tcp".
Version 1.2.6 has an updated license: GPL version 3. The main new feature of
version 1.2.6 is the "reject" option, which makes it possible to censor or
correct for unwanted IP addresses in replies.
Version 1.2.7 contains an important fix for a "dangling pointer" bug and
attempts to make pdnsd less vulnerable to the issues raised in CERT
vulnerability note VU#800113. It also contains some improvements for defining
local records interactively using the pdnsd-ctl utility.
The main new feature of version 1.2.8 is automatic discovery of root servers,
as well as some minor improvements in the resolver.
Version 1.2.9 among other things supports many addtional RR types, uses data
structures that should be more slightly more memory efficient and has support
for EDNS, which allows DNS UDP messages to be larger than 512 bytes.
Version 1.2.9a is a simple bugfix release that fixes a problem with compiling
1.2.9 after configuring with --enable-strict-rfc2181. Unless you use this option
to compile pdnsd, there is no need to upgrade from 1.2.9 to 1.2.9a.

For instructions how to compile and install pdnsd see doc/html/doc.html or
doc/txt/manual.txt. Note that I am no longer distributing a patch w.r.t. Thomas'
version because the (compressed) patch file is barely smaller than the
(compressed) tar archive.

Here follows a list of some of changes in version 1.2 from a user's perspective.
For a more technical description of some of the changes in the code see the ChangeLog.
For a short history about recent releases have a look at NEWS or doc/html/index.html.

- First of all, two potentially rather nasty bugs have been fixed in the code
  for the handling of NXT and NAPTR records. A response from a remote server
  containing NXT records (even well-formed ones) will very likely cause pdnsd to
  crash. The code for handling NAPTR records contained incorrect ASSERT
  statements, which could cause pdnsd to abort in a controlled fashion, but
  completely unnecessarily.

- Sampo Lehtinen has remarked that pdnsd sometimes failed to resolve classless
  reversed-delegated IP addresses, and that this has something to do with the
  fact that pdnsd didn't accept '/' characters in domain names. After reading
  some of the relevant RFCs I decided to remove all restrictions on the types
  of characters that pdnsd accepts in domain names. Of course for most
  applications, there are many characters which don't make sense in domain
  names, but I feel that it is the responsibility of the client application to
  reject these, not the proxy server.

- At the suggestion of Dan Tihelka, I have expanded to the server_ip= option to
  allow the name of an interface to be specified instead of an IP address.
  Presently this has been tested on Linux only. Can someone running pdnsd on
  *BSD tell me if the code for getting the address of an interface is different
  for Linux and BSD-type systems?

- At the suggestion of Juliusz Chroboczek I've added an new server availability
  test which can be specified with uptest=query. This can be useful as an
  alternative to "uptest=ping" in case the remote server does not respond to
  ICMP_ECHO requests at all, which unfortunately is quite common these days.
  "uptest=query" causes pdnsd to send an empty query to remote name servers. Any
  well-formed response (apart from SERVFAIL) within the timeout period will be
  interpreted as a sign that the server is "up".

- Instead of specifying the IP addresses of the name servers that pdnsd should
  query in a server section of the config file, you may also specify a
  resolv.conf-style file. Preferably this should not be /etc/resolv.conf. If the
  contents of the resolv.conf type file changes while pdnsd is running, you can
  make pdnsd aware of the changes with the "pdnsd-ctl config" command, see
  below. Example:

    server {
	label=myisp;
	file=/etc/ppp/resolv.conf;
	timeout=10;
    }

- There is a new option for "server" sections in the config file:
  root_server=on/off.
  In case a server section contains only addresses of root servers, which
  usually only give the name servers of top level domains in their reply,
  setting root_server=on will enable certain optimizations. This involves using
  cached information to reduce queries to the root servers, thus speeding up the
  resolving of new names.

- New option for "rr" sections in the config file: reverse=on/off.
  If you want a locally defined name to resolve to a numeric address and vice
  versa, you can now achieve this by setting reverse=on before defining the A
  record, making it unnecessary to define a separate PTR record for the reverse
  resolving.
  Example:

    rr {
	name = localhost;
	reverse = on;
	a = 127.0.0.1;
    }

  has the same effect as:

    rr {
	name = localhost;
	a = 127.0.0.1;
    }
    rr {
	name = 1.0.0.127.in-addr.arpa;
	ptr = localhost;
    }

- In rr sections it is now possible to specify a wildcard name, i.e. a name
  starting with the label *. The * in a wildcard can match one or more labels in
  a queried name, but only whole labels. For example, *.mydomain will match
  a.mydomain or www.a.mydomain, but not mydomain. Before you can specify an rr
  section with name=*.mydomain you must define some records for mydomain,
  typically NS and/or SOA records.
  Example:

    rr {
	name = mydomain;
	ns = localhost;
	soa = localhost, root.localhost, 42, 86400, 900, 86400, 86400;
    }
    rr {
	name = *.mydomain;
	a = 192.168.1.10;
    }

- There is a slight backwards compatibility problem which involves the name= and
  owner= options in rr sections. The new version does not allow you to place
  owner= before name=. On the other hand, you may now freely mix the owner
  option with the a,ptr,cname,mx and soa options and define as many records of
  this type as you like (including zero).

- pdnsd-ctl has three new commands:

  config: Reloads pdnsd's configuration file. This is more efficient than
  restarting pdnsd, and should not cause only noticeable interruption in DNS
  service. However, some types of configuration changes cannot be put into
  effect this way, and you will be prompted to restart pdnsd instead.

  empty-cache: Empties the cache completely, freeing all existing entries.
  In version 1.2.3 you can specify a selection of entries to delete by providing
  a list of include/exclude patterns.

  dump: Prints information about all the names stored in the cached. This is
  mainly useful for diagnostic purposes.

- There is now a pdnsd.conf(5) man page, describing pdnsd's configuration file.
  The man page has been generated from the html documentation using a customized
  Perl script.

- New in version 1.2.4: Time intervals in the configuration files can now be
  expressed in seconds, minutes, hours, days and weeks, using the suffixes
  s,m,h,d,and w.
  Example: 2h30m is interpreted as 2*60*60 + 30*60 = 9000 seconds.

- Version 1.2.5 introduces a new configuration option, contributed by Jan-Marek
  Glogowski, called "use_nss" which can be turned off to prevent nasty delays in
  certain situations.
  Besides the query methods "udp_only", "tcp_only" and "tcp_udp" you can now
  also specify "udp_tcp", which more closely adheres to the behaviour
  recommended by DNS standards.

- Version 1.2.6 introduces the "randomize_servers" and "reject" options. By
  setting "randomize_servers" on you can give each server in a server section an
  equal chance of being queried, which is useful when resolving from root
  servers, for instance. The "reject" option can be used to censor certain IP
  addresses or correct for unwanted replies from servers you don't completely
  trust.

- Version 1.2.7 contains support for "include" files which can be referenced
  from configuration files or read interactively using pdnsd-ctl. These files
  can be used to add local definitions to the cache without reconfiguring pdnsd.
  The new "pdnsd-ctl eval" command can be used to interactively define local
  records that could previously only be defined in configuration files but not
  with the "pdnsd-ctl add" command.

- Version 1.2.8 contains support for automatic discovery of root servers.
  Instead of supplying a complete list of IP addresses of root servers in a
  server section of the configuration file, you need only enter one or two
  addresses of name servers which know the names and addresses of the root
  servers and set "root_server=discover".
  The "neg_rrs_pol" option has a new default setting, which should allow
  sensible negative caching of RRs in most situations, even if "proxy_only=on".

- Version 1.2.9 contains support for EDNS (Extension mechanisms for DNS), which
  allows UDP messages to be larger than 512 bytes. Whether pdnsd uses EDNS in
  outgoing queries is determined by the configuration option "edns_query". If
  pdnsd receives a query using EDNS, it will reply using EDNS regardless of the
  configuration settings.
  Local TXT records can now be defined in the configuration file.
  If the query uptest fails due to remote servers ignoring empty queries, this
  can now be remedied using the new "query_test_name" config option.

The new features are described in greater detail in the manual doc/html/doc.html
or doc/txt/manual.txt.

Enjoy!

If you have any questions about my version of pdnsd, you can send these
to <p.a.rombouts@home.nl>. Questions about the original (unmaintained) pdnsd
version should be sent to <tmoestl@gmx.net> or <t.moestl@tu-bs.de>.