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