unbound/doc/README

README for Unbound @version@
Copyright 2007 NLnet Labs
http://unbound.net

This software is under BSD license, see LICENSE for details.

* Download the latest release version of this software from 
  	http://unbound.net 
  or get a beta version from the svn repository at 
  	http://unbound.net/svn/

* Uses the following libraries; 
  * ldns	http://www.nlnetlabs.nl/ldns/			(BSD license)
    (required) can use tarball from source directory.
  * libevent	http://www.monkey.org/~provos/libevent/		(BSD license)
    (optional) can use builtin alternative instead.

* Make and install: ./configure; make; make install
  * Use GNU make; default on linux, often called 'gmake' on BSD and Solaris.
  * --with-ldns=/path/to/ldns
  	If ldns is not detected on the system, a prepackaged tarball
	of the ldns library is used to compile and statically link against.
	If detected on the system, it will dynamically link against it.
  * --with-libevent=/path/to/libevent
  	Can be set to either the system install or the build directory.
	--with-libevent=no (default) gives a builtin alternative 
	implementation. libevent is useful when having many (thousands) 
	of outgoing ports. This improves randomization and spoof 
	resistance. For the default of 16 ports the builtin alternative 
	works well and is a little faster.
  * --without-pthreads 
	This disables pthreads. Without this option the pthreads library 
	is detected automatically. Use this option to disable threading
	altogether, or, on Solaris, also use --with(out)-solaris-threads.
  * --enable-static-exe
	This enables a debug option to statically link, against ldns and 
	libevent libraries.
  * --enable-lock-checks
  	This enables a debug option to check lock and unlock calls. It needs
	a recent pthreads library to work.
  * --enable-alloc-checks
	This enables a debug option to check malloc (calloc, realloc, free).
	The server periodically checks if the amount of memory used fits with
	the amount of memory it thinks it should be using, and reports 
	memory usage in detail.

* 'make test' attempts to run a series of tests, depending on the support
  programs that are installed.

Known issues
------------
o If libevent is older (before 1.3c), unbound will exit instead of reload
  on sighup. On a restart 'did not exit gracefully last time' warning is 
  printed. Perform ./configure --with-libevent=no or update libevent, rerun 
  configure and recompile unbound to make sighup work correctly.
  It is strongly suggested to use the latest version of libevent (1.4 or more)
  on Solaris, because of fixes in the solaris event port code in libevent.
o If you receive no answers deploying unbound on a private network.
  Check that the zone you configure as a stub zone is correct, listing working 
  ip-addresses. Check that the NS data in the zone, those hostnames, are
  in fact those same, working, ip-addresses. Unbound will fetch the NS data
  from the zone and use that information in preference to the config 
  information. 
o If you are not receiving the correct source IP address on replies (e.g.
  you are running a multihomed, anycast server), the interface-automatic
  option can be enabled to set socket options to achieve the correct
  source IP address on UDP replies. Listing all IP addresses explicitly in
  the config file is an alternative. The interface-automatic option uses
  non portable socket options, Linux and FreeBSD should work fine.

Acknowledgements
----------------
o Unbound was written in portable C by Wouter Wijngaards (NLnet Labs).
o Thanks to David Blacka and Matt Larson (Verisign) for the unbound-java
  prototype. Design and code from that prototype has been used to create
  this program. Such as the iterator state machine and the cache design.
o Other code origins are from the NSD (NLnet Labs) and LDNS (NLnet Labs)
  projects. Such as buffer, region-allocator and red-black tree code.
o See Credits file for contributors.

* mailto:unbound-bugs@nlnetlabs.nl