xref: /freebsd/contrib/unbound/doc/README (revision 1e248b8346cbf585990a4da0199c6cc3b9cc2340)
1README for Unbound 1.5.8
2Copyright 2007 NLnet Labs
3http://unbound.net
4
5This software is under BSD license, see LICENSE for details.
6The DNS64 module has BSD license in dns64/dns64.c.
7The DNSTAP code has BSD license in dnstap/dnstap.c.
8
9* Download the latest release version of this software from
10  	http://unbound.net
11  or get a beta version from the svn repository at
12  	http://unbound.net/svn/
13
14* Uses the following libraries;
15  * libevent	http://www.monkey.org/~provos/libevent/		(BSD license)
16    (optional) can use builtin alternative instead.
17  * libexpat	(for the unbound-anchor helper program)		(MIT license)
18
19* Make and install: ./configure; make; make install
20  * --with-libevent=/path/to/libevent
21  	Can be set to either the system install or the build directory.
22	--with-libevent=no (default) gives a builtin alternative
23	implementation. libevent is useful when having many (thousands)
24	of outgoing ports. This improves randomization and spoof
25	resistance. For the default of 16 ports the builtin alternative
26	works well and is a little faster.
27  * --with-libexpat=/path/to/libexpat
28  	Can be set to the install directory of libexpat.
29  * --without-pthreads
30	This disables pthreads. Without this option the pthreads library
31	is detected automatically. Use this option to disable threading
32	altogether, or, on Solaris, also use --with(out)-solaris-threads.
33  * --enable-checking
34  	This enables assertions in the code that guard against a variety of
35	programming errors, among which buffer overflows.  The program exits
36	with an error if an assertion fails (but the buffer did not overflow).
37  * --enable-static-exe
38	This enables a debug option to statically link against the
39	libevent library.
40  * --enable-lock-checks
41  	This enables a debug option to check lock and unlock calls. It needs
42	a recent pthreads library to work.
43  * --enable-alloc-checks
44	This enables a debug option to check malloc (calloc, realloc, free).
45	The server periodically checks if the amount of memory used fits with
46	the amount of memory it thinks it should be using, and reports
47	memory usage in detail.
48  * --with-conf-file=filename
49  	Set default location of config file,
50	the default is /usr/local/etc/unbound/unbound.conf.
51  * --with-pidfile=filename
52  	Set default location of pidfile,
53	the default is /usr/local/etc/unbound/unbound.pid.
54  * --with-run-dir=path
55  	Set default working directory,
56	the default is /usr/local/etc/unbound.
57  * --with-chroot-dir=path
58  	Set default chroot directory,
59	the default is /usr/local/etc/unbound.
60  * --with-rootkey-file=path
61  	Set the default root.key path.  This file is read and written.
62	the default is /usr/local/etc/unbound/root.key
63  * --with-rootcert-file=path
64  	Set the default root update certificate path.  A builtin certificate
65	is used if this file is empty or does not exist.
66	the default is /usr/local/etc/unbound/icannbundle.pem
67  * --with-username=user
68  	Set default user name to change to,
69	the default is the "unbound" user.
70  * --with-pyunbound
71  	Create libunbound wrapper usable from python.
72	Needs python-devel and swig development tools.
73  * --with-pythonmodule
74  	Compile the python module that processes responses in the server.
75  * --disable-sha2
76  	Disable support for RSASHA256 and RSASHA512 crypto.
77  * --disable-gost
78  	Disable support for GOST crypto, RFC 5933.
79
80* 'make test' runs a series of self checks.
81
82Known issues
83------------
84o If there are no replies for a forward or stub zone, for a reverse zone,
85  you may need to add a local-zone: name transparent or nodefault to the
86  server: section of the config file to unblock the reverse zone.
87  Only happens for (sub)zones that are blocked by default; e.g. 10.in-addr.arpa
88o If libevent is older (before 1.3c), unbound will exit instead of reload
89  on sighup. On a restart 'did not exit gracefully last time' warning is
90  printed. Perform ./configure --with-libevent=no or update libevent, rerun
91  configure and recompile unbound to make sighup work correctly.
92  It is strongly suggested to use a recent version of libevent.
93o If you are not receiving the correct source IP address on replies (e.g.
94  you are running a multihomed, anycast server), the interface-automatic
95  option can be enabled to set socket options to achieve the correct
96  source IP address on UDP replies. Listing all IP addresses explicitly in
97  the config file is an alternative. The interface-automatic option uses
98  non portable socket options, Linux and FreeBSD should work fine.
99o The warning 'openssl has no entropy, seeding with time', with chroot
100  enabled, may be solved with a symbolic link to /dev/random from <chrootdir>.
101o On Solaris 5.10 some libtool packages from repositories do not work with
102  gcc, showing errors gcc: unrecognized option `-KPIC'
103  To solve this do ./configure libtool=./libtool [your options...].
104  On Solaris you may pass CFLAGS="-xO4 -xtarget=generic" if you use sun-cc.
105o If unbound-control (or munin graphs) do not work, this can often be because
106  the unbound-control-setup script creates the keys with restricted
107  permissions, and the files need to be made readable or ownered by both the
108  unbound daemon and unbound-control.
109o Crosscompile seems to hang.  You tried to install unbound under wine.
110  wine regedit and remove all the unbound entries from the registry or
111  delete .wine/drive_c.
112
113Acknowledgements
114----------------
115o Unbound was written in portable C by Wouter Wijngaards (NLnet Labs).
116o Thanks to David Blacka and Matt Larson (Verisign) for the unbound-java
117  prototype. Design and code from that prototype has been used to create
118  this program. Such as the iterator state machine and the cache design.
119o Other code origins are from the NSD (NLnet Labs) and LDNS (NLnet Labs)
120  projects. Such as buffer, region-allocator and red-black tree code.
121o See Credits file for contributors.
122
123
124Your Support
125------------
126NLnet Labs offers all of its software products as open source, most are
127published under a BSD license. You can download them, not only from the
128NLnet Labs website but also through the various OS distributions for
129which NSD, ldns, and Unbound are packaged. We therefore have little idea
130who uses our software in production environments and have no direct ties
131with 'our customers'.
132
133Therefore, we ask you to contact us at users@NLnetLabs.nl and tell us
134whether you use one of our products in your production environment,
135what that environment looks like, and maybe even share some praise.
136We would like to refer to the fact that your organization is using our
137products. We will only do that if you explicitly allow us. In all other
138cases we will keep the information you share with us to ourselves.
139
140In addition to the moral support you can also support us
141financially. NLnet Labs is a recognized not-for-profit charity foundation
142that is chartered to develop open-source software and open-standards
143for the Internet. If you use our software to satisfaction please express
144that by giving us a donation. For small donations PayPal can be used. For
145larger and regular donations please contact us at users@NLnetLabs.nl. Also
146see http://www.nlnetlabs.nl/labs/contributors/.
147
148
149* mailto:unbound-bugs@nlnetlabs.nl
150