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.
  * --with-conf-file=filename
  	Set default location of config file, 
	the default is /usr/local/etc/unbound/unbound.conf.
  * --with-pidfile=filename
  	Set default location of pidfile,
	the default is /usr/local/etc/unbound/unbound.pid.
  * --with-run-dir=path
  	Set default working directory,
	the default is /usr/local/etc/unbound.
  * --with-chroot-dir=path
  	Set default chroot directory,
	the default is /usr/local/etc/unbound.
  * --with-username=user
  	Set default user name to change to,
	the default is the "unbound" user.
  * --with-pyunbound
  	Create libunbound wrapper usable from python.
	Needs python-devel and swig development tools.
  * --with-pythonmodule
  	Compile the python module that processes responses in the server.
  * --enable-sha2
  	Enable draft support for RSASHA256 and RSASHA512.

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

Known issues
------------
o If there are no replies for a forward or stub zone, for a reverse zone,
  you may need to add a local-zone: name transparent or nodefault to the
  server: section of the config file to unblock the reverse zone.
  Only happens for (sub)zones that are blocked by default; e.g. 10.in-addr.arpa
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 a recent version of libevent.
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.
o The warning 'openssl has no entropy, seeding with time', with chroot 
  enabled, may be solved with a symbolic link to /dev/random from <chrootdir>.
o On Solaris 5.10 some libtool packages from repositories do not work with
  gcc, showing errors gcc: unrecognized option `-KPIC'
  To solve this do ./configure libtool=./libtool [your options...].
o If unbound-control (or munin graphs) do not work, this can often be because
  the unbound-control-setup script creates the keys with restricted 
  permissions, and the files need to be made readable or ownered by both the
  unbound daemon and unbound-control.

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