dnscache

dnscache
Environment	$ROOT	Directory where dnscache runs chrooted to
	$UID	User id under which dnscache runs
	$GID	Group id under which dnscache runs
	$IP	IP address dnscache listens to (both UDP and TCP on port 53) (Typically 127.0.0.1)
	$IPSEND	IP address dnscache sends outgoing packet from (high ports) (Typically 0.0.0.0, meaning the hosts primary IP address)
	$CACHESIZE	Size of the fixed cache dnscache uses (Typically 1000000 bytes)
Files and directories	ip/1.2.3.4	If file present dnscache accepts connections from 1.2.3.4
	ip/1.2.3	If file present dnscache accepts connections from 1.2.3.x
	ip/1.2	If file present dnscache accepts connections from 1.2.x.x
	ip/1	If file present dnscache accepts connections from 1.x.x.x
	root/@	File containing the root servers IP addresses, one per line
	root/alpha.beta	File containing the "authoritative" servers for domain alpha.beta, as a list of IP addresses, one per line. dnscache answers queries for any host on that domain (machine.alpha.beta) through those servers, ignoring the root servers.
Special names	localhost	Handled internally, returning a A record of 127.0.0.1
	1.0.0.127.in-addr.arpa	Handled internally, returning a PTR record of 127.0.0.1
	1.2.3.4	Dotted-decimal domain names are handled internally, returning a A record of themselves (in the example, a A record of 1.2.3.4 is returned)

tinydns

tinydns
Environment	$ROOT	Directory where tinydns runs chrooted to
	$UID	User id under which tinydns runs
	$GID	Group id under which tinydns runs
	$IP	IP address tinydns listens to (UDP only on port 53)
Files	data.cdb	Binary data file created by tinydns-data based on which tinydns answers queries
Rejections	zone transfer requests inverse queries non-Internet-class queries truncated packets packets with anything more than a single query	tinydns rejects all of these

tinydns-data

tinydns-data
tinydns-data reads the local DNS information from the file data, in the current directory, and creates the data.cdb file required by tinydns. The data file contains a number of lines, of several types distinguished by the first character, some of which are described below. All lines include one ttl and one timestamp fields. Both can be omitted (suitable defaults will be assumed) but the : must be present. In the formats below, fqdn may be replaced by *.fqdn, which makes the record apply to any name ending in .fqdn, unless a more specific record exists.
.fqdn:ip:xyz:ttl:timestamp	Name server for the domain fqdn These lines create the following records or responses: NS record xyz.ns.fqdn is a name server for domain fqdn. If xyz contains a dot, then *that* is the name for the name server A record ip is the IP address for xyz.ns.fqdn, must be omitted if another line specifies that IP address SOA record Authority for the fqdn domain is on the xyz.ns.fqdn server (primary DNS server), and the contact address is hostmaster@fqdn. Is multiple name servers for the same domain are specified with this type of line (must have a different xyz for each) there will still be only one SOA record for the whole domain NXDOMAIN responses For any nonexistent names ending with .fqdn
&fqdn:ip:xyz:ttl:timestamp	Name server for delegated domain fqdn This creates referrals for names ending with .fqdn, and create the following records or responses: NS record xyz.ns.fqdn is a name server for delegated domain fqdn (non authoritative). If xyz contains a dot, then *that* is the name for the name server. There can be multiple name servers for a delegated domain, as long as the xyz field is different A record ip is the IP address for xyz.ns.fqdn, must be omitted if another line specifies that IP address
=fq.dn:ip:ttl:timestamp	Host fq.dn has the ip address Creates the following records or responses: A record ip is the IP address of fq.dn. Name servers must be defined for the dn domain, or this record will not be generated PTR record Assuming ip is 1.2.3.4, a PTR record is generated showing fq.dn as the name of 4.3.2.1.in-addr.arpa. Name servers must be defined for some suffix of 4.3.2.1.in-addr.arpa (for example, with ".3.2.1.in-addr.arpa:1.2.3.1:x::") or this record won't be generated
+fq.dn:ip:ttl:timestamp	fq.dn is an alias for a host Creates the following records or responses: A record ip is the IP address of fq.dn. Name servers must be defined for the dn domain, or this record will not be generated
@fqdn:ip:xyz:dist:ttl:timestamp	MX (mail exchanger) for the fqdn domain (the address answers to SMTP dialogs) Creates the following records or responses: MX record xyz.mx.fqdn is a mail exchanger for domain fqdn, at a distance dist. If xyz contains a dot, then *that* is the name for the name server. dist may be omitted, and is then presumed 0 A record ip is the IP address of xyz.mx.fqdn. Name servers must be defined for the fqdn domain, or this record will not be generated

DNS records vs. tinydns-data records

DNS record types created for each kind of tinydns-data record
Type of tinydns-data record	DNS record types created (also see QTYPE)
.	SOA,NS,A
&	NS,A
@	MX,A
=	PTR,A
+	A
'	TXT
^	PTR
C	CNAME
>	SOA
:	User defined (see QTYPE)
#	User comment, no DNS record created
%	User defined location (from djbdns >=1.04), no DNS record created
-	Ignored (from djbdns >=1.04), no DNS record created

DNS record types vs. tinydns-data record
	SOA	NS	A	MX	PTR	TXT	CNAME
.	*	*	*
&		*	*
@			*	*
=			*		*
+			*
'						*
^					*
C							*
>	*

djbdns tools

tools
dnsip fqdn	Prints the IP address for the name fqdn, or a blank line if no address is found. Exits 0 on success, 111 on failure.
dnsname a.b.c.d	Does a reverse lookup for the IP address a.b.c.d, and prints the first domain name for that address, or a blank line if no name is found. Exits 0 on success, 111 on failure.
dnsmx fqdn	Does a reverse lookup for the IP address a.b.c.d, and prints the first domain name for that address, or a blank line if no name is found. Exits 0 on success, 111 on failure (for not finding name servers, for example).
dnsq type fqdn server	Sends a query to server for records of type (usually "any") under the domain name fqdn, and prints the result in human readable format. This is the same as dig +norec using dig for non-recursive queries
dnsip fqdn	Prints the IP address for the name fqdn, or a blank line if no address is found. Exits 0 on success, 111 on failure.

Protocols accepted per program in the djbdns package

Program	Protocol listened to
	TCP	UDP
dnscache	yes	yes
tinydns	no	yes
walldns	no	yes
rbldns	no	yes
axfrdns	yes	no
pickdns	no	yes

tinydns log format

Given the following line from tinydns log file

@40000000398025cf00 7f000001:4027:0dfb + 000c ahost.com

Field	Meaning
@40000000398025cf00	TAI64N time stamp, can be converted to a more readable format by tai64nlocal
7f000001	IP address of host who queried us (convert each pair of characters from hex to decimal to get the quad-dotted format)
:	Separator
4027	Port used by the host who queried us (hexadecimal)
:	Separator
0dfb	ID field in the query packet, this comes from and is returned to the host who queried us to let it know to which query we are answering (hexadecimal)
+	Answer status Code Meaning + Success - Name not found I Not implemented / Undefined error
000c	Query type in hexadecimal, some of which are: Hex value Type of record queried Meaning 0001 A IP address 0002 NS Name server address 0005 CNAME Canonical name or alias 000c PTR Reverse IP lookup 000d HINFO Host info 000f MX Mail exchanger See DNS parameters, QTYPE, for full list
ahost.com	Name queried

A perl script to decode tinydns logs

#!/usr/bin/perl

%rtype= (
'+' => '(success)', '-' => '(not found)',
'I' => '(not implemented)', '/' => '(undefined error)',
);

%qtype= (
1 => "A", 2 => "NS", 3 => "MD", 4 => "MF",
5 => "CNAME", 6 => "SOA", 7 => "MB", 8 => "MG",
9 => "MR", 10 => "NULL", 11 => "WKS", 12 => "PTR",
13 => "HINFO", 14 => "MINFO", 15 => "MX",
16 => "TXT", 17 => "RP", 18 => "AFSDB", 19 => "X25",
20 => "ISDN", 21 => "RT", 22 => "NSAP",
23 => "NSAP-PTR", 24 => "SIG", 25 => "KEY", 26 => "PX",
27 => "GPOS", 28 => "AAAA", 29 => "LOC",
30 => "NXT", 31 => "EID", 32 => "NIMLOC", 33 => "SRV",
34 => "ATMA", 35 => "NAPTR", 36 => "KX",
37 => "CERT", 38 => "A6", 39 => "DNAME", 40 => "SINK",
41 => "OPT", 100 => "UINFO", 101 => "UID",
102 => "GID", 103 => "UNSPEC", 249 => "TKEY",
250 => "TSIG", 251 => "IXFR", 252 => "AXFR",
253 => "MAILB", 254 => "MAILA", 255 => "*",
);

open FOUT,"|tai64nlocal";
while(<>){
@line=split;
# $line[0]=tai timestamp
# $line[1]=ip address:port:id field of query
# $line[2]=answer status
# $line[3]=query type
# $line[4]=name queried
@q=split(/:/,$line[1]);
@ip=$q[0] =~ /(..)(..)(..)(..)/;
$ip=join('.', map (hex,@ip));
print FOUT "$line[0]  $ip ".$qtype{hex($line[3])}." $line[4] $rtype{$line[2]}\n";
}
close(FOUT);

Typical configuration for a dial-up network

Note: this is based on dnscache-0.93, changes may be required for the latest djbdns versions. The principles herein are still valid, tough.

Assume that the local network is based on a (Linux) server and one or more workstations. The network connects to the Internet trough a on demand dialing system, be it in the server or a router, and is attributed a dynamic IP address by the ISP or RAS. The purpose of this example is to allow the workstations and the local server to access the Internet DNS, and at the same time to have a fake local only domain enabling local resolution of names and reverse IP addresses. We'll also assume that the server runs a mail server such as qmail for local mail.

The local configuration is as follows:

Host	Operating system	IP address	Local DNS name
Server	Linux	192.168.1.1 (on eth0)	master.hom
Workstation 1	Linux	192.168.1.10 (on eth0)	linwks.hom
Workstation 2	Windows	192.168.1.20	noclue.hom

Therefore, the local domain will be hom. Note that the example supports any number of workstations, depending on the limits of the network configuration. The workstation IP addresses are assumed fixed, either trough hard configuration or using DHCP (with correctly configured MAC address associations).

The DNS configuration for the hosts will be, after everything is set up, as follows:

Host	Configuration
Server	Local tinydns server on 127.0.0.1 Local network dnscache on 192.168.1.1
Workstation 1	DNS server is 192.168.1.1 No local DNS cache
Workstation 2	DNS server is 192.168.1.1

Server configuration

After compiling and installing daemontools, compile the dnscache package, following the instructions up to and including the make setup check part. Also create the dnscache, dnslog and tinydns accounts, as per FAQ.

Now configure dnscache as follows:

1. dnscache-conf dnscache dnslog /etc/dnscache 192.168.1.1

   This creates the dnscache service directory and arranges for logs, etc. Also binds dnscache to answer only on the 192.168.1.1 interface

2. echo 127.0.0.1 > /etc/dnscache/root/servers/hom

   This tells dnscache to consult with 127.0.0.1 for any request on the hom domain, bypassing the root servers

3. echo 127.0.0.1 > /etc/dnscache/root/servers/1.168.192.in-addr.arpa

   This tells dnscache to consult with 127.0.0.1 for any reverse IP lookups within the 192.168.1.x network

4. touch /etc/dnscache/root/ip/192.168.1 /etc/dnscache/root/ip/127.0.0.1
   or
   touch /etc/dnscache/root/ip/192.168.1

   This tells dnscache to accept queries from any machine within the 192.168.1.x network and from the server (in the first line). The server, however, will usually make its queries from 192.168.1.1, and therefore the second line is better. Use the first as a last resort, in case some software decides to always consult via localhost, or if there are routing problems. Also see below what this does to resolv.conf

Now configure tinydns as follows:

1. tinydns-conf tinydns dnslog /etc/tinydns 127.0.0.1

   This creates the tinydns service directory, arranges for log, etc. Also binds tinydns to answer only to the 127.0.0.1 interface

2. cd /etc/tinydns/root

   The data configuration for tinydns will me made in this directory

3. ./add-ns hom 127.0.0.1

   This defines the authoritative name server for the hom domains as 127.0.0.1

4. ./add-ns 1.168.192.in-addr.arpa 127.0.0.1

   This defines the authoritative reverse IP lookup server for the 192.168.1.x network as 127.0.0.1

5. ./add-host master.hom 192.168.1.1
   ./add-host linwks.hom 192.168.1.10
   ./add-host noclue.hom 192.168.1.20

   This defines the addresses for the various hosts on the network

6. ./add-mx hom 192.168.1.1

   This defines the local MX (mail exchange) server as being on 192.168.1.1

7. make

   This creates the database for tinydns, based on the commands above.

Configure /etc/resolv.conf as follows (omit the last line if you didn't touch /etc/dnscache/root/ip/127.0.0.1 in the last step of dnscache's configuration):

search hom
nameserver 192.168.1.1
nameserver 127.0.0.1

The last thing to do is to link /etc/tinydns and /etc/dnscache into the /services directory, and both services should be working.

Linux workstation configuration

Simply configure /etc/resolv.conf as follows:

search hom
nameserver 192.168.1.1

Windows workstation configuration

Make the primary DNS server be 192.168.1.1. There are various ways of doing this, depending on the network management being made by DHCP or by hand.