README
1README for Unbound 1.13.1
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 * --enable-subnet
80 Enable EDNS client subnet processing.
81
82* 'make test' runs a series of self checks.
83
84Known issues
85------------
86o If there are no replies for a forward or stub zone, for a reverse zone,
87 you may need to add a local-zone: name transparent or nodefault to the
88 server: section of the config file to unblock the reverse zone.
89 Only happens for (sub)zones that are blocked by default; e.g. 10.in-addr.arpa
90o If libevent is older (before 1.3c), unbound will exit instead of reload
91 on sighup. On a restart 'did not exit gracefully last time' warning is
92 printed. Perform ./configure --with-libevent=no or update libevent, rerun
93 configure and recompile unbound to make sighup work correctly.
94 It is strongly suggested to use a recent version of libevent.
95o If you are not receiving the correct source IP address on replies (e.g.
96 you are running a multihomed, anycast server), the interface-automatic
97 option can be enabled to set socket options to achieve the correct
98 source IP address on UDP replies. Listing all IP addresses explicitly in
99 the config file is an alternative. The interface-automatic option uses
100 non portable socket options, Linux and FreeBSD should work fine.
101o The warning 'openssl has no entropy, seeding with time', with chroot
102 enabled, may be solved with a symbolic link to /dev/urandom from <chrootdir>.
103o On Solaris 5.10 some libtool packages from repositories do not work with
104 gcc, showing errors gcc: unrecognized option `-KPIC'
105 To solve this do ./configure libtool=./libtool [your options...].
106 On Solaris you may pass CFLAGS="-xO4 -xtarget=generic" if you use sun-cc.
107o If unbound-control (or munin graphs) do not work, this can often be because
108 the unbound-control-setup script creates the keys with restricted
109 permissions, and the files need to be made readable or ownered by both the
110 unbound daemon and unbound-control.
111o Crosscompile seems to hang. You tried to install unbound under wine.
112 wine regedit and remove all the unbound entries from the registry or
113 delete .wine/drive_c.
114
115Acknowledgements
116----------------
117o Unbound was written in portable C by Wouter Wijngaards (NLnet Labs).
118o Thanks to David Blacka and Matt Larson (Verisign) for the unbound-java
119 prototype. Design and code from that prototype has been used to create
120 this program. Such as the iterator state machine and the cache design.
121o Other code origins are from the NSD (NLnet Labs) and LDNS (NLnet Labs)
122 projects. Such as buffer, region-allocator and red-black tree code.
123o See Credits file for contributors.
124
125
126Your Support
127------------
128NLnet Labs offers all of its software products as open source, most are
129published under a BSD license. You can download them, not only from the
130NLnet Labs website but also through the various OS distributions for
131which NSD, ldns, and Unbound are packaged. We therefore have little idea
132who uses our software in production environments and have no direct ties
133with 'our customers'.
134
135Therefore, we ask you to contact us at users@NLnetLabs.nl and tell us
136whether you use one of our products in your production environment,
137what that environment looks like, and maybe even share some praise.
138We would like to refer to the fact that your organization is using our
139products. We will only do that if you explicitly allow us. In all other
140cases we will keep the information you share with us to ourselves.
141
142In addition to the moral support you can also support us
143financially. NLnet Labs is a recognized not-for-profit charity foundation
144that is chartered to develop open-source software and open-standards
145for the Internet. If you use our software to satisfaction please express
146that by giving us a donation. For small donations PayPal can be used. For
147larger and regular donations please contact us at users@NLnetLabs.nl. Also
148see http://www.nlnetlabs.nl/labs/contributors/.
149
150
151* mailto:unbound-bugs@nlnetlabs.nl
152
README.DNS64
1The DNS64 code was written by Viagenie, 2009, by Simon Perrault as part
2of the Ecdysis project. The code is copyright by them, and has the BSD
3license (see the dns64/dns64.c file).
4
5To enable DNS64 functionality in Unbound, two directives in unbound.conf must
6be edited:
7
81. The "module-config" directive must start with "dns64". For example:
9
10 module-config: "dns64 validator iterator"
11
12If you're not using DNSSEC then you may remove "validator".
13
142. The "dns64-prefix" directive indicates your DNS64 prefix. For example:
15
16 dns64-prefix: 64:FF9B::/96
17
18The prefix must be a /96 or shorter.
19
20To test that things are working right, perform a query against Unbound for a
21domain name for which no AAAA record exists. You should see a AAAA record in
22the answer section. The corresponding IPv6 address will be inside the DNS64
23prefix. For example:
24
25 $ unbound -c unbound.conf
26 $ dig @localhost jazz-v4.viagenie.ca aaaa
27 [...]
28 ;; ANSWER SECTION:
29 jazz-v4.viagenie.ca. 86400 IN AAAA 64:ff9b::ce7b:1f02
30
31
README.ipset.md
1## Created a module to support the ipset that could add the domain's ip to a list easily.
2
3### Purposes:
4* In my case, I can't access the facebook, twitter, youtube and thousands web site for some reason. VPN is a solution. But the internet too slow whether all traffics pass through the vpn.
5So, I set up a transparent proxy to proxy the traffic which has been blocked only.
6At the final step, I need to install a dns service which would work with ipset well to launch the system.
7I did some research for this. Unfortunately, Unbound, My favorite dns service doesn't support ipset yet. So, I decided to implement it by my self and contribute the patch. It's good for me and the community.
8```
9# unbound.conf
10server:
11 ...
12 local-zone: "facebook.com" ipset
13 local-zone: "twitter.com" ipset
14 local-zone: "instagram.com" ipset
15 more social website
16
17ipset:
18 name-v4: "gfwlist"
19```
20```
21# iptables
22iptables -A PREROUTING -p tcp -m set --match-set gfwlist dst -j REDIRECT --to-ports 10800
23iptables -A OUTPUT -p tcp -m set --match-set gfwlist dst -j REDIRECT --to-ports 10800
24```
25
26* This patch could work with iptables rules to batch block the IPs.
27```
28# unbound.conf
29server:
30 ...
31 local-zone: "facebook.com" ipset
32 local-zone: "twitter.com" ipset
33 local-zone: "instagram.com" ipset
34 more social website
35
36ipset:
37 name-v4: "blacklist"
38 name-v6: "blacklist6"
39```
40```
41# iptables
42iptables -A INPUT -m set --set blacklist src -j DROP
43ip6tables -A INPUT -m set --set blacklist6 src -j DROP
44```
45
46### Notes:
47* To enable this module the root privileges is required.
48* Please create a set with ipset command first. eg. **ipset -N blacklist iphash**
49
50### How to use:
51```
52./configure --enable-ipset
53make && make install
54```
55
56### Configuration:
57```
58# unbound.conf
59server:
60 ...
61 local-zone: "example.com" ipset
62
63ipset:
64 name-v4: "blacklist"
65```
66
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