README
1 README for Unbound 1.24.2 2 Copyright 2007 NLnet Labs 3 http://unbound.net 4 5 This software is under BSD license, see LICENSE for details. 6 The DNS64 module has BSD license in dns64/dns64.c. 7 The 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 gives a builtin alternative implementation. 23 Libevent is enabled by default, it is useful when having many 24 (thousands) of outgoing ports. This improves randomization and spoof 25 resistance. It also allows a higher number of outgoing queries. 26 * --with-libexpat=/path/to/libexpat 27 Can be set to the install directory of libexpat. 28 * --without-pthreads 29 This disables pthreads. Without this option the pthreads library 30 is detected automatically. Use this option to disable threading 31 altogether, or, on Solaris, also use --with(out)-solaris-threads. 32 * --enable-checking 33 This enables assertions in the code that guard against a variety of 34 programming errors, among which buffer overflows. The program exits 35 with an error if an assertion fails (but the buffer did not overflow). 36 * --enable-static-exe 37 This enables a debug option to statically link against the 38 libevent library. 39 * --enable-lock-checks 40 This enables a debug option to check lock and unlock calls. It needs 41 a recent pthreads library to work. 42 * --enable-alloc-checks 43 This enables a debug option to check malloc (calloc, realloc, free). 44 The server periodically checks if the amount of memory used fits with 45 the amount of memory it thinks it should be using, and reports 46 memory usage in detail. 47 * --with-conf-file=filename 48 Set default location of config file, 49 the default is /usr/local/etc/unbound/unbound.conf. 50 * --with-pidfile=filename 51 Set default location of pidfile, 52 the default is /usr/local/etc/unbound/unbound.pid. 53 * --with-run-dir=path 54 Set default working directory, 55 the default is /usr/local/etc/unbound. 56 * --with-chroot-dir=path 57 Set default chroot directory, 58 the default is /usr/local/etc/unbound. 59 * --with-rootkey-file=path 60 Set the default root.key path. This file is read and written. 61 the default is /usr/local/etc/unbound/root.key 62 * --with-rootcert-file=path 63 Set the default root update certificate path. A builtin certificate 64 is used if this file is empty or does not exist. 65 the default is /usr/local/etc/unbound/icannbundle.pem 66 * --with-username=user 67 Set default user name to change to, 68 the default is the "unbound" user. 69 * --with-pyunbound 70 Create libunbound wrapper usable from python. 71 Needs python-devel and swig development tools. 72 * --with-pythonmodule 73 Compile the python module that processes responses in the server. 74 * --disable-sha2 75 Disable support for RSASHA256 and RSASHA512 crypto. 76 * --disable-gost 77 Disable support for GOST crypto, RFC 5933. 78 * --enable-subnet 79 Enable EDNS client subnet processing. 80 81 * 'make test' runs a series of self checks. 82 83 Known issues 84 ------------ 85 o 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 89 o 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. 94 o 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. 100 o The warning 'openssl has no entropy, seeding with time', with chroot 101 enabled, may be solved with a symbolic link to /dev/urandom from <chrootdir>. 102 o 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. 106 o 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. 110 o 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 114 Acknowledgements 115 ---------------- 116 o Unbound was written in portable C by Wouter Wijngaards (NLnet Labs). 117 o 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. 120 o 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. 122 o See Credits file for contributors. 123 124 125 Your Support 126 ------------ 127 NLnet Labs offers all of its software products as open source, most are 128 published under a BSD license. You can download them, not only from the 129 NLnet Labs website but also through the various OS distributions for 130 which NSD, ldns, and Unbound are packaged. We therefore have little idea 131 who uses our software in production environments and have no direct ties 132 with 'our customers'. 133 134 Therefore, we ask you to contact us at users (a] NLnetLabs.nl and tell us 135 whether you use one of our products in your production environment, 136 what that environment looks like, and maybe even share some praise. 137 We would like to refer to the fact that your organization is using our 138 products. We will only do that if you explicitly allow us. In all other 139 cases we will keep the information you share with us to ourselves. 140 141 In addition to the moral support you can also support us 142 financially. NLnet Labs is a recognized not-for-profit charity foundation 143 that is chartered to develop open-source software and open-standards 144 for the Internet. If you use our software to satisfaction please express 145 that by giving us a donation. For small donations PayPal can be used. For 146 larger and regular donations please contact us at users (a] NLnetLabs.nl. Also 147 see http://www.nlnetlabs.nl/labs/contributors/. 148 149 150 * mailto:unbound-bugs (a] nlnetlabs.nl 151
README.DNS64
1 The DNS64 code was written by Viagenie, 2009, by Simon Perrault as part 2 of the Ecdysis project. The code is copyright by them, and has the BSD 3 license (see the dns64/dns64.c file). 4 5 To enable DNS64 functionality in Unbound, two directives in unbound.conf must 6 be edited: 7 8 1. The "module-config" directive must start with "dns64". For example: 9 10 module-config: "dns64 validator iterator" 11 12 If you're not using DNSSEC then you may remove "validator". 13 14 2. The "dns64-prefix" directive indicates your DNS64 prefix. For example: 15 16 dns64-prefix: 64:FF9B::/96 17 18 The prefix must be a /96 or shorter. 19 20 To test that things are working right, perform a query against Unbound for a 21 domain name for which no AAAA record exists. You should see a AAAA record in 22 the answer section. The corresponding IPv6 address will be inside the DNS64 23 prefix. 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 32 NAT64 support was added by David Lamparter in 2022; license(s) of the 33 surrounding code apply. Note that NAT64 is closely related but functionally 34 orthogonal to DNS64; it allows Unbound to send outgoing queries to IPv4-only 35 servers over IPv6 through the configured NAT64 prefix. This allows running 36 an Unbound instance on an IPv6-only host without breaking every single domain 37 that only has IPv4 servers. Whether that Unbound instance also does DNS64 is 38 an independent choice. 39 40 To enable NAT64 in Unbound, add to unbound.conf's "server" section: 41 42 do-nat64: yes 43 44 The NAT64 prefix defaults to the DNS64 prefix, which in turn defaults to the 45 standard 64:FF9B::/96 prefix. You can reconfigure it with: 46 47 nat64-prefix: 64:FF9B::/96 48 49 To test NAT64 operation, pick a domain that only has IPv4 reachability for its 50 nameservers and try resolving any names in that domain. 51
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. 5 So, I set up a transparent proxy to proxy the traffic which has been blocked only. 6 At the final step, I need to install a dns service which would work with ipset well to launch the system. 7 I 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 10 server: 11 ... 12 local-zone: "facebook.com" ipset 13 local-zone: "twitter.com" ipset 14 local-zone: "instagram.com" ipset 15 more social website 16 17 ipset: 18 name-v4: "gfwlist" 19 ``` 20 ``` 21 # iptables 22 iptables -A PREROUTING -p tcp -m set --match-set gfwlist dst -j REDIRECT --to-ports 10800 23 iptables -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 29 server: 30 ... 31 local-zone: "facebook.com" ipset 32 local-zone: "twitter.com" ipset 33 local-zone: "instagram.com" ipset 34 more social website 35 36 ipset: 37 name-v4: "blacklist" 38 name-v6: "blacklist6" 39 ``` 40 ``` 41 # iptables 42 iptables -A INPUT -m set --set blacklist src -j DROP 43 ip6tables -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 53 make && make install 54 ``` 55 56 ### Configuration: 57 ``` 58 # unbound.conf 59 server: 60 ... 61 local-zone: "example.com" ipset 62 63 ipset: 64 name-v4: "blacklist" 65 ``` 66
README.man
1 After Unbound 1.23.0, the source of the man pages is in reStructuredText format. 2 3 This helps with the online documentation at https://unbound.docs.nlnetlabs.nl 4 and makes it easier to maintain and contribute to the documentation. 5 6 The templated man pages (*.in) are still part of the code repository as to not 7 alter current procedures that could be in place by users/packagers. 8 9 The templated man pages (*.in) are generated by Sphinx (used for the online 10 documentation). 11 The online documentation has its own repository at 12 https://github.com/NLnetLabs/unbound-manual. 13 14 In the README.md there (branch test-auto for now), there are further simple 15 instructions on how to generate the templated man pages there and update them 16 in this repository. 17
README.svn
1 README.svn 2 3 For a svn checkout: 4 * configure script, aclocal.m4, as well as yacc/lex output files are 5 committed to the repository. 6 * use --enable-debug flag for configure to enable dependency tracking and 7 assertions, otherwise, use make clean; make after svn update. 8 9 * Note changes in the Changelog. 10 * Every check-in a postcommit hook is run 11 (the postcommit hook is in the svn/unbound/hooks directory). 12 * generates commit email with your changes and comment. 13 * compiles and runs the tests (with testcode/do-tests.sh). 14 * If build errors or test errors happen 15 * Please fix your errors and commit again. 16 17 * Use gnu make to compile, make or 'gmake'. 18
README.tests
1 README unbound tests 2 3 For a quick test that runs unit tests and state machine tests, use 4 make test 5 6 There is a long test setup for unbound that needs tools installed. Use 7 make longtest 8 To make and run the long tests. The results are summarized at the end. 9 10 You 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. 16 The optional programs are detected and can be omitted. 17 18 You can also use prepared Dockerfile to run tests inside docker based on latest gcc image: 19 * build container: docker build -t unbound-tester -f contrib/Dockerfile.tests . 20 * run container: docker run -it --mount type=bind,source="$(pwd)",target=/usr/src/unbound --rm unbound-tester 21 * configure environment: ./configure 22 * run test: make test 23 * run long tests: make longtest 24 It is worth to mention that you need to enable [ipv6 in your docker daemon configuration](https://docs.docker.com/config/daemon/ipv6/) because some tests need ipv6 network stack. 25 26 testdata/ contains the data for tests. 27 testcode/ contains scripts and c code for the tests. 28 29 do-tests.sh : runs all the tests in the testdata directory. 30 testbed.sh : compiles on a set of (user specific) hosts and runs do-tests. 31 32 Tests are run using testcode/mini_tpkg.sh. 33
Indexes created Tue Feb 24 01:34:59 UTC 2026