source: packages/net/djbdns/README @ 15612

Last change on this file since 15612 was 15612, checked in by markus, 8 years ago

added djbdns patch provided by Johnny Halfmoon

removed dnsmasq.patch as the options were included upstream already.

File size: 21.3 KB
2# 20090409 - Don't hesitate to let me know if you decide to use it and/or what you think of it.
4This is a port of djbdns for OpenWRT (>= v8.09). Features:
6- works with the most current buildroot
7- makes use of the UCI configuration system
8- components are seperately packaged to minimize package footprint
9- most of the popular and necessary available patches are applied
10- documentation available (you're reading it)
12The djbdns package is a set of compact, reliable and fast DNS daemons and tools. This port is based on the work done by a few other people:
14- The FreeWRT project
15- Alexander Tsvyashchenko -
16- Some anonymous (Danish?) person -
18Using the previous work as a base, time went into rewriting the Make file, adding patches, adding the config system and writing this documentation. The ucspi-tcp and daemontools packages were not touched; they work just fine in the state they were found on OpenWRT TRAC.
20The following document meant to give some useful information about this package. You do not need to know all of the following to install or compile this package; it is only meant as an addition to help potential users on their way. An installation could theoretically be as simple as: "opkg install dnscache.ipk ; /etc/init.d/dnscache start". To find more about the workings of djbdns, visit:
24On the following sites you can find even more info, including text about the patches included in this package:
33Some info about the bugfixes:
38How to build
40- copy the folders djbdns, ucspi-tcp (and optionally daemontools) to your buildroot/package directory
41- make menuconfig
42- select the packages under network/DNS/djbdns and network/ucspi-tcp (and optionally network/daemontools)
43- make
44- after compilation, the package can be found at bin/packages/<targetname>
45- now do what you normally do to install self-compiled packages on your OpenWRT machine
47If you wish to tinker with the code, then here are some useful commands to run in the buildroot:
48    rm -rf build_dir/<targetname>/djbdns-1.05
49    make package/cleanup
50    make package/djbdns/compile V=99
51    make package/index
52Once you have done a "make menuconfig;make" you can use these commands to quickly rebuild only the djbdns package.
54Usage pointers
56- After installation, you can make the servers start automatically on boot by running "/etc/init.d/<servicename> enable" . The script will then appear in the /etc/rc.d directory. This is standard OpenWRT functionality.
57- All djbdns parameters are stored in the UCI configuration system. Run "uci show djbdns" to see the settings. Data files are not implemented in the UCI system, so these files must be manually backed up when and if you intend to do a sysupgrade (=reflash the firmware). Those files include: dnscache, dnscache @ file, tinydns data file, axfrdns tcp file, rbldns data file, each in their individual directories in /etc.
58- Each package is ready to run out-of-the-box, once installed. The default settings allow you to start playing immediately. The defaults are reasonably secure, but do not take my word for it. Verify it. Note: dnscache has two default example resolver IP addresses. The two default addresses are the OpenDNS resolvers, which might work at the moment, but this may change in the future.
59- You will most likely want to customize the settings for each seperate service you wish to use. Read the docs on the weblinks listed above for pointers on how to do so.
60- The ucspi-tcp package is only needed if you wish to install and run axfrdns.
61- The daemontools package is strictly optional. It is in no way linked to the djbdns package (yet). It is just there for you to play with.
62- Starting the init.d scripts from the command line with the environment variable DEBUG set to 1 will prevent the servers from daemonizing and show the servers's log dumped to stdout / stderr instead of /dev/null. Example: "DEBUG=1 /etc/init.d/dnscache start"
63- By default, all logging is disabled. Each daemon has a seperate option to activate logging. When logging activated the daemon logs to syslog using facility
64- Each djbdns server requires an IP address on which to listen on. This port of djbdns allows you to define an interface on which to listen instead of an IP address. The advantage of this is that an interface can get a different IP address assigned, the djbdns stuff will not break. The dnscache server has a patch applied so that it is possible to define multiple interfaces on which to listen, separated by slashes. Example: wan/lan .
65- By default, dnscache acts as a recursive name server. If you wish to operate in forwardonly mode, then you need to set the forwardonly flag to '1'. Then you need to do either one of the following: Put the ip addresses of the name servers you wish to use as resolvers in the UCI config (djbdns.dnscache.resolver) or alternatively you can set the useresolvconf flag which will cause the dns servers assigned by dhcp to be used.
66- If you want your OpenWRT machine to make use of its own dnscache, then you must make /etc/resolv.conf reflect this. One way of doin this is as follows: uci set network.wan.dns= . If you have dnscache listening on some other interface, you would naturally replace by the address of that interface.
67- OpenWRT has several applications that can do DNS serving in one way or another (dnsmasq, Maradns, Bind). Make sure you have none of these apps running when you start running a djbdns name server because having two DNS apps listening on the same address is not something you would usually want. A patch for the dnsmasq configuration script and its config file is included with this package. The patch will allow you to configure dnsmasq to listen only on certain interfaces, instead of on all them as it does by default on OpenWRT. Alternatively, you could completely disable and / or remove dnsmasq, if you do not intend to use any of its functionality (which is serving DNS and DHCP).
69To apply the dnsmasq patch
71NOTE: This patch has been incorporated into OpenWRT trunk per 20090409 as seen in and
73This is a patch to allow you to use dnsmasq alongside dnscache. It will allow you to configure dnsmasq to listen only on certain interfaces, instead of on all them as it does by default on OpenWRT. It only patches the startup script and configuration file of dnsmasq, not dnsmasq itself. If you need or desire to apply the patch yourself, then there are two possible ways to go about it:
75Patch the dnsmasq package source:
76- cd to svn/openwrt/branches/8.09/packages/dnsmasq/files
77- do 'patch < dnsmasq.patch
78- if all went well you can now compile the package as you nomally would
79- you can now either reinstall dnsmasq on your router or re-flash the firmware image. If you reinstall the dnsmasq package then you waste some flash memory, as dnsmasq is usually already included as a part of the firmware image. One way to reinstall the dnsmasq package is to use SSH to upload the image to the router and do: opkg update ; opgk install -force-reinstall dnsmasq.ipk . Or you could configure your OpenWRT build machine as an http server that serves OpenWRT packages and then configure opkg to use your server as an ipkg repository. This is generally a pretty good idea if you are building your own firmware and packages.
81Alternatively, you can patch the dnsmasq files on the router itself:
82Look at the patch file and manually patch the files on the router. There are only four lines to modify, so it is not hard.
84NOTE: The dnsmasq paramaters added by this patch are not shown on the Luci webinterface. You will manually have to configure dnsmasq. An example of how to make dnsmasq serve DNS and DHCP only on the lan:
85uci set dhcp.@dnsmasq[0].nonwildcard=1
86uci set dhcp.@dnsmasq[0].interfaces=br-lan
87uci commit
88This will prevent dnsmasq from binding to the wildcard IP address and instead make it listen on the designated (lan) interface. You are then free to run a DNS server on, for example, the loopback and/or the wan interface.
90Assorted notes
92- This port was put together with reasonable care. It is not a dirty hack, but that is ofcourse a very subjective statement.
93- It was created on and for Kamikaze 8.09 with both a 2.4 and a 2.6 kernel. It was not tested to work on older versions of OpenWRT, but it might.
94- This package will build into several packages. Most of the packages rely on the package djbdnsbase. It contains the shared config data for all daemons. It should automatically get installed along with the daemons by opkg.
95- The ucspi-tcp package is a requirement for installing axfrdns. If you don't user afrxdns, you won't need to install ucspi-tcp.
96- The daemontool package is supplied as a part of this port, but it is not needed or used by anything in the djbdns packages. It is included in case anyone feels the want or need to make use of it.
97- Among the applied patches are the latest (as of the 2nd of april 2009) notorious bug fixes for dnscache.
98- Most patches are vanilla, ie. unmodified as they can be found on the net. The only patch modified is the djbdns-1.05-slogging patch, which was merged with the server-1.05-nxdomain-logging patch.
99- The dnscache gets a patch applied to be able to listen on multiple IP addresses. Tinydns is not patched to have that functionality, although the patch for that is available on the net.
100- dnscache is also patched to deliver additional statistics in its log files, including hits/misses and what types of records were queried. These can be used to monitor and/or graph the behaviour of your dnscache server.
101- The dnscache package gets configured to listen to and the lan subnet by default. See "ls /etc/dnscache/ip" and  "uci show djbdns|grep dnscache" .
102- tinydns, axfrdns and rbldns include example data files that are installed by default. Their purpose is to ease installation and testing of the packages and to act as a guide to people who are not familiar with these applications.
103- The dnstools part of this package contains a script called dnsroots-update with which you can update the global root file. This is quite useful because IP addresses of the root servers change now and then, although not very often. I seems that few people actually bother to update the global roots file once they have installed dnscache. It is important to run the update script every now and them, or at least at installation time. Do the following to update the list: dnsroots-update > /etc/dnscache/ and then copy the file to /etc/dnscache/server/@ . The dnstools package is quite large (400K installed) for an embedded system. What you could do instead of running the update script on the router, is to install the djbdns package on some big machine and run the script on there and then copy the output to the dnsroots file on the router. The file included in this package is up to date as per the date of this writing (2nd of april 2009).
105Testing the installation
107The following may ease any debugging you might wish/need to do:
108- Set the syslog buffer to something like 64K or more and make it log to IP address localhost (reboot to activate the changes):
109    uci set system.@system[0].log_ip=
110    uci set system.@system[0].log_size=64
111    uci commit
112- Use "logread|less" to browse through the buffered syslog output.
113- For realtime log monitoring: Install netcat and make it listen to the syslog output:
114    opkg install netcat
115    netcat -ulp 514
117This paragraph gives a few brief pointers on how to test your installation. The general idea is as follows: Log in to the OpenWRT machine using two seperate SSH sessions or a single session and then use 'screen' to gain multiple sessions. In the first session you have to start the daemon you wish to test. In the second session you run the diagnostic commands. In the following examples, for each daemon and each diagnostic tool, I have supplied the commandline and the expected, approximate output.
119NOTE1: Make sure no other DNS servers are running. Check with "netstat -an|grep 53" and/or do a "killall dnsmasq" just to be sure.
120NOTE2: dnscache requires an active internet connection it to work
121NOTE3: In the following examples, the servers were running on IP address
122NOTE4: Most of these tests require the dnstools package to be installed
125session1 "DEBUG=1 /etc/init.d/dnscache start"
126        Starting Caching nameserver: dnscachelistening on 0a010102
127        starting
128        <a whole truckload of log data will follow>
129session2 "DNSCACHEIP=$yourwanip dnsqr a"  (note: you do no have to modify /etc/resolv.conf to use this command)
130        1
131        45 bytes, 1+1+0+0 records, response, noerror
132        query: 1
133        answer: 172800 A
134session2 "dnsip" (note: /etc/resolv.conf must point to the address on which dnscache is listening)
136session2 "nslookup" (note: /etc/resolv.conf must point to the address on which dnscache is listening)
137        Server:
138        Address 1:
139        Name:
140        Address 1:
143session1 "DEBUG=1 /etc/init.d/tinydns start"
144        Starting Authoritative nameserver: tinydnsstarting tinydns
145        0a010102:4eee:fdd8 + 0001
146        stats 1 1 0 0 0 0 0
147session2 "dnsq a $yourwanip"
148        1
149        79 bytes, 1+0+1+0 records, response, authoritative, noerror
150        query: 1
151        authority: 2560 SOA 1238703484 16384 2048 1048576 2560
154session1 "DEBUG=1 /etc/init.d/axfrdns start"
155        Starting Zone transfer name server: tcpservertcpserver: status: 0/10
156        tcpserver: status: 1/10
157        tcpserver: pid 1140 from
158        tcpserver: ok 1140 0: :
159        0a010102:040a:0000 0006
160        tcpserver: end 1140 status 0
161        tcpserver: status: 0/10
162session2 "tcpclient -RHl0 $yourwanip 53 axfr-get /tmp/zone /tmp/zone.tmp"
163        The file /tmp/zone should now contain the zone in tinydns-data format.
166session1 "DEBUG=1 /etc/init.d/rbldns start"
167        Starting Reverse DNS wall: rbldnsstarting rbldns
168        0a010102:881d:01ca + 0010
169        stats 1 1 0 0 0 0 0
170        0a010102:674a:e70f N 0010
171session2 "dnsq txt $yourwanip"
172        16
173        59 bytes, 1+1+0+0 records, response, authoritative, noerror
174        query: 16
175        answer: 2048 16 \
176session2 "dnsq txt $yourwanip"
177        16
178        30 bytes, 1+0+0+0 records, response, authoritative, nxdomain
179        query: 16
182session1 "DEBUG=1 /etc/init.d/walldns start"
183        Starting Reverse DNS wall: walldnsstarting walldns
184        0a010102:7b76:3d97 + 0001
185        stats 1 1 0 0 0 0 0
186session2 "dnsq a $yourwanip"
187        1
188        54 bytes, 1+1+0+0 records, response, authoritative, noerror
189        query: 1
190        answer: 655360 A
192axfrdns defaults
194axfrdns is run using tcpserver from the ucspi-tcp package. The following parameters are used to start the tcpserver daemon (which runs as root BTW):
195-D: Never delay sending data; enable TCP_NODELAY.
196-R: Do not attempt to obtain $TCPREMOTEINFO from the remote host. To avoid loops, you must use this option for servers on TCP ports 53 and 113.
197-H: Do not look up the remote host name in DNS; remove the environment variable $TCPREMOTEHOST. To avoid loops, you must use this option for servers on TCP port 53.
198-l localname: Do not look up the local host name in DNS; use localname for the environment variable $TCPLOCALHOST. A common choice for localname is 0. To avoid loops, you must use this option for servers on TCP port 53.
199-c n (=40): Do not handle more than n simultaneous connections. If there are n simultaneous copies of prog running, defer acceptance of a new connection until one copy finishes. n must be a positive integer. Default: 40.
200-b n (=10): Allow a backlog of approximately n TCP SYNs. On some systems, n is silently limited to 5. On systems supporting SYN cookies, the backlog is irrelevant.
202In debug mode and when logging is activated, the following parameter is also active:
203-v: Verbose. Print error messages and status messages.
205Applied patches
209Patch to make djbdns compile correctly for OpenWRT. I understand that the original patch comes from FreeWRT and was adapted for OpenWRT by Alexander Tsvyashchenko.
213This patch modifies the dnscache program to keep a counter of cache hits and cache misses. Two new fields are added to the stats output line: the fifth number is the number of cache hits; the sixth number is the number of cache misses.
217A bit of a nit-picky patch that adjusts the names of generated temorary files to be more 'correct'. A bit silly really.
221When applied, dnscache will accept a /-delimited list of IP address in $IP and bind to each in turn. NOTE: This patch is only really useful on embedded systems with very limited memory. On 'big' systems, ther are other ways to achieve listening on multiple IP adresses. Example:
225Not really a patch, but an extra command. dnsnamex prints all of the domain names that the IP address supplied to it maps to, on a single line.
229Fixes mis-handling of client-side aliases
233This patch modifies the behaviour of dnscache such that "forwardonly" mode is fully enforced.
237Patch to change the separator in ${DNSCACHEIP} to the space character
241Fixes the fact that stock tinydns-data doesn't handle semantic errors in its input
245Fixes truncation of alias chains by tinydns and axfrdns
249Patch to enable statistics logging of queried resource records.
250This patch is merged with the patch server-1.05-nxdomain-logging.patch that logs nxdomain queries.
255This patch adds an option to the dnsfilter program (-r). It's use makes dnsfilter simply replace the IP address by the host name if possible. If the IP address cannot be determined for whatever reason then it will be left alone. -r stands for replace.
259Patch to fix a potential cache-poisoning attack. This bug only affects domains that serve DNS content using tinydns and axfrdns (only for DNS queries over TCP; clients do not need AXFR permissions) from djbdns 1.05 and allow untrusted users to include arbitrary records.
263This patch prevents a class of poisoning attack by combining identical requests from clients into one outgoing query. Without this patch, an attacker can coerce dnscache into launching hundreds of identical queries at once, making a specific type of attack several orders of magnitude easier.
267This patch allows dnscache to store the responses of "SOA" type queries in its cache. SOA responses are the only type of response unconditionally uncached. dnscache uses its internal cache to prevent certain classes of poisoning attack. Attackers may choose to send floods of SOA requests to bypass these protections.
271Not really a patch, but a handy script to make dnsq query a given name server instead of the one in /etc/resolv.conf.
273Possible future enhancements to this package
275- add a Luci webinterface
276- add scripts to make the DNS daemons run using daemontools to increase the reliability of the services
277- ipv6 support
Note: See TracBrowser for help on using the repository browser.