tor-android/jni/pdnsd/README.par

217 lines
11 KiB
Plaintext

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