net/djbdns/README

   1
   2 # 20090409 jhalfmoon@milksnot.com - Don't hesitate to let me know if you decide to use it and/or what you think of it.
   3
   4 This is a port of djbdns for OpenWRT (>= v8.09). Features:
   5
   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)
  11
  12 The 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:
  13
  14 - The FreeWRT project
  15 - Alexander Tsvyashchenko - https://dev.openwrt.org/ticket/2497
  16 - Some anonymous (Danish?) person - https://dev.openwrt.org/ticket/3837
  17
  18 Using 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.
  19
  20 The 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:
  21
  22 http://cr.yp.to/djbdns.html
  23
  24 On the following sites you can find even more info, including text about the patches included in this package:
  25
  26 http://www.lifewithdjbdns.com/
  27 http://www.thedjbway.org/djbdns/resources.html
  28 http://www.fefe.de/djbdns/
  29 http://homepages.tesco.net/~J.deBoynePollard/FGA/#DNS
  30 http://binarios.com/miscnotes/djbdns.html
  31 http://web.archive.org/web/20061013054303/http://ezine.daemonnews.org/200210/ezdjbdns.html
  32
  33 Some info about the bugfixes:
  34
  35 http://www.securityfocus.com/archive/1/501294/30/0/threaded
  36 http://www.your.org/dnscache/
  37
  38 How to build
  39 ============
  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
  46
  47 If 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
  52 Once you have done a "make menuconfig;make" you can use these commands to quickly rebuild only the djbdns package.
  53
  54 Usage pointers
  55 ==============
  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 dnsroot.global, 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 local1.info.
  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. That last option is a so called set-and-forget mode which will work quite well in most home environments.
  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=127.0.0.1 . If you have dnscache listening on some other interface, you would naturally replace 127.0.0.1 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).
  68 - The ignoreip patch also has a script supplied along with it, with which you can update the ignorelist. The script contains an explanation of why you might want to do this.
  69 - The ignoreip functionality is disabled by default. If you want to activate it, you need to set the flag 'useignore' flag to '1' in the config. You might also want to check if you are really blocking what you want to block. Be careful with this feature. Think twice before using it.
  70
  71 To apply the dnsmasq patch
  72 ==========================
  73 NOTE: This patch has been incorporated into OpenWRT trunk per 20090409 as seen in https://dev.openwrt.org/ticket/4900 and https://dev.openwrt.org/changeset/15172.
  74
  75 This 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:
  76
  77 Patch the dnsmasq package source:
  78 - cd to svn/openwrt/branches/8.09/packages/dnsmasq/files
  79 - do 'patch < dnsmasq.patch
  80 - if all went well you can now compile the package as you nomally would
  81 - 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.
  82
  83 Alternatively, you can patch the dnsmasq files on the router itself:
  84 Look at the patch file and manually patch the files on the router. There are only four lines to modify, so it is not hard.
  85
  86 NOTE: 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:
  87 uci set dhcp.@dnsmasq[0].nonwildcard=1
  88 uci set dhcp.@dnsmasq[0].interfaces=br-lan
  89 uci commit
  90 This 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.
  91
  92 Assorted notes
  93 ==============
  94 - This port was put together with reasonable care. It is not a dirty hack, but that is ofcourse a very subjective statement.
  95 - 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.
  96 - 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.
  97 - The ucspi-tcp package is a requirement for installing axfrdns. If you don't user afrxdns, you won't need to install ucspi-tcp.
  98 - 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.
  99 - Among the applied patches are the latest (as of the 2nd of april 2009) notorious bug fixes for dnscache.
 100 - 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.
 101 - 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.
 102 - 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.
 103 - The dnscache package gets configured to listen to 127.0.0.1 and the lan subnet by default. See "ls /etc/dnscache/ip" and  "uci show djbdns|grep dnscache" .
 104 - 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.
 105 - 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/dnsroots.global and then copy the file dnsroots.global 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 dnsroots.global file included in this package is up to date as per the date of this writing (2nd of april 2009).
 106
 107 Testing the installation
 108 ========================
 109 The following may ease any debugging you might wish/need to do:
 110 - Set the syslog buffer to something like 64K or more and make it log to IP address localhost (reboot to activate the changes):
 111     uci set system.@system[0].log_ip=127.0.0.1
 112     uci set system.@system[0].log_size=64
 113     uci commit
 114 - Use "logread|less" to browse through the buffered syslog output.
 115 - For realtime log monitoring: Install netcat and make it listen to the syslog output:
 116     opkg install netcat
 117     netcat -ulp 514
 118
 119 This 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.
 120
 121 NOTE1: Make sure no other DNS servers are running. Check with "netstat -an|grep 53" and/or do a "killall dnsmasq" just to be sure.
 122 NOTE2: dnscache requires an active internet connection it to work
 123 NOTE3: In the following examples, the servers were running on IP address 10.1.1.2
 124 NOTE4: Most of these tests require the dnstools package to be installed
 125
 126 -dnscache
 127 session1 "DEBUG=1 /etc/init.d/dnscache start"
 128         Starting Caching nameserver: dnscachelistening on 0a010102
 129         starting
 130         <a whole truckload of log data will follow>
 131 session2 "DNSCACHEIP=$yourwanip dnsqr a example.com"  (note: you do no have to modify /etc/resolv.conf to use this command)
 132         1 example.com:
 133         45 bytes, 1+1+0+0 records, response, noerror
 134         query: 1 example.com
 135         answer: example.com 172800 A 208.77.188.166
 136 session2 "dnsip example.com" (note: /etc/resolv.conf must point to the address on which dnscache is listening)
 137         208.77.188.166
 138 session2 "nslookup example.com" (note: /etc/resolv.conf must point to the address on which dnscache is listening)
 139         Server:    10.1.1.2
 140         Address 1: 10.1.1.2
 141         Name:      example.com
 142         Address 1: 208.77.188.166 www.example.com
 143
 144 -tinydns
 145 session1 "DEBUG=1 /etc/init.d/tinydns start"
 146         Starting Authoritative nameserver: tinydnsstarting tinydns
 147         0a010102:4eee:fdd8 + 0001 example.net
 148         stats 1 1 0 0 0 0 0
 149 session2 "dnsq a example.net $yourwanip"
 150         1 example.net:
 151         79 bytes, 1+0+1+0 records, response, authoritative, noerror
 152         query: 1 example.net
 153         authority: example.net 2560 SOA ns.example.net hostmaster.example.net 1238703484 16384 2048 1048576 2560
 154
 155 -axfrdns
 156 session1 "DEBUG=1 /etc/init.d/axfrdns start"
 157         Starting Zone transfer name server: tcpservertcpserver: status: 0/10
 158         tcpserver: status: 1/10
 159         tcpserver: pid 1140 from 10.1.1.2
 160         tcpserver: ok 1140 0:10.1.1.2:53 :10.1.1.2::1034
 161         0a010102:040a:0000 0006 example.net
 162         tcpserver: end 1140 status 0
 163         tcpserver: status: 0/10
 164 session2 "tcpclient -RHl0 $yourwanip 53 axfr-get example.net /tmp/zone /tmp/zone.tmp"
 165         The file /tmp/zone should now contain the example.net zone in tinydns-data format.
 166
 167 -rbldns
 168 session1 "DEBUG=1 /etc/init.d/rbldns start"
 169         Starting Reverse DNS wall: rbldnsstarting rbldns
 170         0a010102:881d:01ca + 0010 8.4.2.1.test
 171         stats 1 1 0 0 0 0 0
 172         0a010102:674a:e70f N 0010 9.4.2.1.test
 173 session2 "dnsq txt 8.4.2.1.test $yourwanip"
 174         16 8.4.2.1.test:
 175         59 bytes, 1+1+0+0 records, response, authoritative, noerror
 176         query: 16 8.4.2.1.test
 177         answer: 8.4.2.1.test 2048 16 \020www.somesite.com
 178 session2 "dnsq txt 9.4.2.1.test $yourwanip"
 179         16 9.4.2.1.test:
 180         30 bytes, 1+0+0+0 records, response, authoritative, nxdomain
 181         query: 16 9.4.2.1.test
 182
 183 -walldns
 184 session1 "DEBUG=1 /etc/init.d/walldns start"
 185         Starting Reverse DNS wall: walldnsstarting walldns
 186         0a010102:7b76:3d97 + 0001 4.3.2.1.in-addr.arpa
 187         stats 1 1 0 0 0 0 0
 188 session2 "dnsq a 4.3.2.1.in-addr.arpa $yourwanip"
 189         1 4.3.2.1.in-addr.arpa:
 190         54 bytes, 1+1+0+0 records, response, authoritative, noerror
 191         query: 1 4.3.2.1.in-addr.arpa
 192         answer: 4.3.2.1.in-addr.arpa 655360 A 1.2.3.4
 193
 194 axfrdns defaults
 195 ================
 196 axfrdns is run using tcpserver from the ucspi-tcp package. The following parameters are used to start the tcpserver daemon (which runs as root BTW):
 197 -D: Never delay sending data; enable TCP_NODELAY.
 198 -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.
 199 -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.
 200 -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.
 201 -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.
 202 -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.
 203
 204 In debug mode and when logging is activated, the following parameter is also active:
 205 -v: Verbose. Print error messages and status messages.
 206
 207 Applied patches
 208 ===============
 209 crosscompile.patch
 210 https://dev.openwrt.org/ticket/2497
 211 Patch to make djbdns compile correctly for OpenWRT. I understand that the original patch comes from FreeWRT and was adapted for OpenWRT by Alexander Tsvyashchenko.
 212
 213 dnsroots-update.patch
 214 Update the dnsroots.global file to be current.
 215
 216 srv-records-and-axfrget.patch
 217 http://sol.truespace.ca/Files/djbdns/srv.patch
 218 Adds native support for srv records (not really necessary) and also patches axfr-get to decompose SRV and PTR records and write them out in native format, rather than opaque. This last thing is needed to fix a possible problem with tinydns-data.
 219
 220 dnscache_less_chatty_log
 221 http://sol.truespace.ca/Files/djbdns/log.patch
 222 Makes dnscache log "stat" entries no more than once per 5 seconds.
 223
 224 tinydns_mmap_leak
 225 http://marc.info/?l=djbdns&m=116399640808774&w=2
 226 This fixes the following: In the original code if cdb_read encountered an error it returned an error code and the calling function exited without closing the cdb data file resulting in an fd leak, eventually leading to a 'too many files open' error.
 227
 228 dnscache_big_udp_packets
 229 http://marc.info/?l=djbdns&m=122368590802063&w=2
 230 Patch to support oversized UDP packets up to 4096 bytes in length, while still correctly truncating responses over 512 bytes when sending them to stub resolvers.
 231
 232 dnscache_dpos_tcp_servfail
 233 http://marc.info/?l=djbdns&m=119998909915985&w=3
 234 Fixes broken tcp dns queries in certain situations. For example: A vanilla 1.05 will fail on "dnstxt aol.com aol.com".
 235
 236 dnscache-cache-negatives
 237 http://sol.truespace.ca/Files/djbdns/nxdomain.patch
 238 Add support for caching of unsuccessful lookup results.
 239
 240 tinydns_one_second
 241 http://www.tinydns.org/one-second.patch
 242 Causes tinydns to keep its mmap() of the data.cdb file open for at most one second, instead of the default one hundred queries. This improves throughput on high traffic machines.
 243
 244 dnscache-cachestats.patch
 245 http://romana.now.ie/#djbdns-cachestats
 246 This 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.
 247
 248 compiler-temporary-filename.patch
 249 http://homepages.tesco.net/~J.deBoynePollard/Softwares/djbdns/#compiler-temporary-filename
 250 A bit of a nit-picky patch that adjusts the names of generated temorary files to be more 'correct'. A bit silly really.
 251
 252 dnscache-multiple-ip.patch
 253 http://danp.net/djbdns/patches.html
 254 When 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. You can read more on that over here: http://www.faqts.com/knowledge_base/view.phtml/aid/9644/fid/699
 255
 256 dnsnamex-extra-command.patch
 257 http://homepages.tesco.net/~J.deBoynePollard/Softwares/djbdns/#dnsnamex
 258 Not 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.
 259
 260 dnscache-cname-handling.patch
 261 http://homepages.tesco.net/~J.deBoynePollard/FGA/#DNS
 262 Fixes mis-handling of client-side aliases
 263
 264 dnscache-strict-forwardonly.patch
 265 http://homepages.tesco.net/~J.deBoynePollard/Softwares/djbdns/#dnscache-strict-forwardonly
 266 This patch modifies the behaviour of dnscache such that "forwardonly" mode is fully enforced.
 267
 268 dnscacheip-space-separator.patch
 269 http://homepages.tesco.net/~J.deBoynePollard/FGA/djbdns-problems.html#dnscacheip-separator-character
 270 Patch to change the separator in ${DNSCACHEIP} to the space character
 271
 272 tinydns-data-semantic-error.patch
 273 http://homepages.tesco.net/~J.deBoynePollard/FGA/djbdns-problems.html#tinydns-data-semantic-error
 274 Fixes the fact that stock tinydns-data doesn't handle semantic errors in its input
 275
 276 tinydns-alias-chain-truncation.patch
 277 http://homepages.tesco.net/~J.deBoynePollard/FGA/djbdns-problems.html#tinydns-alias-chain-truncation
 278 Fixes truncation of alias chains by tinydns and axfrdns
 279
 280 dnscache-slogging.patch
 281 http://www.ohse.de/uwe/patches.html
 282 Patch to enable statistics logging of queried resource records.
 283 This patch is merged with the patch server-1.05-nxdomain-logging.patch that logs nxdomain queries.
 284 http://danp.net/djbdns/
 285
 286 dnsfilter-replace.patch
 287 http://www.ohse.de/uwe/patches.html
 288 This 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.
 289
 290 dnscache_sigpipe_fix
 291 http://marc.info/?l=djbdns&m=104804013229536&w=2
 292 This patch tells dnscache to ignore the SIGPIPE signal.
 293
 294 ignoreip2.patch
 295 http://tinydns.org/djbdns-1.05-ignoreip2.patch
 296 This patch change djbdns's dnscache so that it will ignore thex IP addresses given in the ignoreip file. This patch was made to boycott Verisign, amongst others, who decided to start supplying replies to non-existant and wildcard domains. NOTE: This feature is disabled in the config file by default. Be careful with this one.
 297
 298 bugfix-dnscache-dempsky-poison.patch
 299 http://www.securityfocus.com/archive/1/501294/30/0/threaded
 300 Patch 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.
 301
 302 bugfix-dnscache-merge-outgoing-requests.patch
 303 http://www.your.org/dnscache/
 304 This 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.
 305
 306 bugfix-dnscache-cache-soa-records.patch
 307 http://www.your.org/dnscache/
 308 This 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.
 309
 310 dnrqx
 311 http://homepages.tesco.net/~J.deBoynePollard/Softwares/djbdns/dnsqrx
 312 Not really a patch, but a handy script to make dnsq query a given name server instead of the one in /etc/resolv.conf.
 313
 314 Possible future enhancements to this package
 315 ============================================
 316 - add a Luci webinterface
 317 - add scripts to make the DNS daemons run using daemontools to increase the reliability of the services
 318 - ipv6 support
 319