DragonFly On-Line Manual Pages
sheerdns(1) DragonFly General Commands Manual sheerdns(1)
NAME
sheerdns - master DNS server
SYNOPSIS
sheerdns [-ttl seconds] [-p port] [-i iface-ip] [-d]
sheerdnshash string
DESCRIPTION
sheerdns is a master DNS server whose zone records are stored on a One-
Record-Per-File bases. Because of this, sheerdns is the simplest of any
DNS to configure, the easiest to update, and the most efficient for
networks that experience a lot of updates (for example master servers
for dynamic IP address ranges). You never have to restart sheerdns; any
updates are available immediately without having to notify the sheerdns
process.
sheerdns is secure. sheerdns is fast because Unix operating systems
cache small files in memory.
sheerdns is written in strict ANSI C.
sheerdnshash creates a directory /var/sheerdns/XX/string/, where XX is
a hash of the string, and outputs XX to stdout.
Note that sheerdns is not a caching nameserver for resolving queries
about the rest of the Internet. It is a master server for telling the
rest of Internet about the zones you are responsible for. No clients
anywhere should have a /etc/resolv.conf "nameserver" entry that points
to a sheerdns server.
sheerdns works by looking up queries from files of the name:
/var/sheerdns/XX/full.doma.in/query-type.
These files are created by the administrator (or one of his/her
sh/perl/python/php scripts). You can write anything to these files --
sheerdns will answer with their contents even if they are bogus. The XX
is an upper-case two character hex number of the range 00 to FF.
Each of these files contains one or more newline separated strings.
There should be no leading newlines, and zero or one trailing newline.
In the case of A records, the strings are IP addresses, for example
192.0.2.1. If there are several IP addresses in the file, they are
order-randomized before return.
In the case of PTR, MX, NS, SOA, and CNAME records, the strings are
host-names. For MX and NS you can have multiple hostnames per file, but
for PTR, SOA, and CNAME records, you must have only one entry in each
file. TXT records can contain anything---one record is returned for
each line in the file (TXT is not discussed again).
For MX records, the first entry in the file is given a priority of 10,
the second 20, and so on.
For SOA records, the modified time of the file counts as the Serial-
Number, and the contents as the name-server. The administrator email
address returned is just the name-server prepended with "hostmaster",
so you should make sure this email address exists for that domain and
is reachable. The remaining fields are hardcoded to reasonable default
values. Note that time fields for SOA records are only used for zone
transfers hence are irrelevant here.
For NS and SOA records, an entry for a domain is valid for all domains
below it. For example, if you create an NS record for the domain
test.edu, then that NS record is returned for the domain www.test.edu,
ftp.henry.test.edu, as well as user1.lab.chemistry.test.edu. On the
other hand a separate NS record can be created for
lab.chemistry.test.edu, applying to all domains
*.lab.chemistry.test.edu, *.*.lab.chemistry.test.edu etc. This works
because sheerdns searches for NS records by iteratively deleting the
text up to the front most dot until a nameserver is found. This gives
the intuitively expected behavior.
There is a special case for using sheerdns as a root nameserver. See
the example below.
sheerdns does lookups in lower case. All filenames and file contents
must be in lower case. sheerdns does no interpretation of any of the
file contents except for the characters \f\n\r\t\v and the dot
character, so it can probably manage UTF-8 domain names without a
problem.
sheerdns does not send TCP results longer than 1024 bytes, neither does
it set the TC bit if the response ought to be longer. If there are too
many records to fit in the packet, then trailing records are omitted to
keep within the 1024 byte limit. The packet format will be valid none-
the-less. Administrators should ensure that their site is not so
complex that large packets need to be sent.
OPTIONS
-ttl seconds
The Time-To-Live field to be set on outgoing packets. Records
that are likely to be fixed (not dynamic) are given a 3-day ttl.
Examples are the IP address of the NS record, and the CNAME, MX,
NS, and SOA records. All other records are given the ttl
specified in this option. The default is 86400 seconds (one
day). This option should be set to 10 seconds for dynamic IP
address ranges.
-p port
Listen port. Default is 53.
-i iface-ip
inface-ip is the network card you want to listen on. If
omitted, it defaults to 0.0.0.0 meaning all interfaces.
-d Fork twice into the background (to run as a daemon process);
otherwise sheerdns runs in the foreground.
WILDCARDS
An entry such as *.test.com will return results as expected. This means
you should
echo 192.0.2.1 > /var/sheerdns/`sheerdnshash '*'.test.com`/'*'.test.com/A
dig @localhost A lsdjkfhalsdfkjh.test.com
Note that quotes around the asterisk. This means the filename has an
asterisk in it which is never a good idea on Unix systems.
EXAMPLES
These examples assume that you have already invoked sheerdns, that you
know what kind of records are appropriate to create, that you do not
guess, and that you realize that the examples are merely shown for
demonstration and not as a recommendation for the kinds of records
really required.
Add mutiple A records for test.com for round robin sharing:
echo 192.0.2.1 > /var/sheerdns/`sheerdnshash test.com`/test.com/A
echo 192.0.2.2 >> /var/sheerdns/`sheerdnshash test.com`/test.com/A
echo 192.0.2.3 >> /var/sheerdns/`sheerdnshash test.com`/test.com/A
dig @localhost A test.com
dig @localhost A test.com
dig @localhost A test.com
Add a PTR records for test.com:
echo test.com > /var/sheerdns/`sheerdnshash 192.0.2.1`/192.0.2.1/PTR
echo test.com > /var/sheerdns/`sheerdnshash 192.0.2.2`/192.0.2.2/PTR
echo test.com > /var/sheerdns/`sheerdnshash 192.0.2.3`/192.0.2.3/PTR
echo ns.ispfortest.net > /var/sheerdns/`sheerdnshash 192.0.2`/192.0.2/NS
dig @localhost PTR 1.2.0.192.in-addr.arpa
Add an MX record for test.com with (IMPORTANT) both its forward,
reverse, and nameserver lookups:
echo mail.test.com > /var/sheerdns/`sheerdnshash test.com`/test.com/MX
echo 192.0.3.99 > /var/sheerdns/`sheerdnshash mail.test.com`/mail.test.com/A
echo mail.test.com > /var/sheerdns/`sheerdnshash 192.0.3.99`/192.0.3.99/PTR
echo ns.ispfortest.net > /var/sheerdns/`sheerdnshash test.com`/test.com/NS
dig @localhost MX test.com
Add an SOA record for test.com. Note that although SOA records are only
required for zone transfers, some institutions may demand them. The
only configurable data item in the SOA record is the authoritative
nameserver which is inserted as follows:
echo ns.ispfortest.net > /var/sheerdns/`sheerdnshash test.com`/test.com/SOA
dig @localhost SOA test.com
Add an CNAME record for www.test.com. If you use a CNAME, you should
only have one line in the CNAME file, and it should be the only file in
the domain's directory, and the CNAME should not appear anywhere as the
text of any other records. I repeat: "If you use a CNAME, you should
only have one line in the CNAME file, and it should be the only file in
the domain's directory, and the CNAME should not appear anywhere as the
text of any other records.". Do I need to say it a third time?
echo "I will not leave out the next command"
rm -f /var/sheerdns/`sheerdnshash www.test.com`/www.test.com/*
grep -w 'www[.]test[.]com' `find /var/sheerdns/ -type f` && \
echo "This DNS setup is broken"
echo "I will not leave out the previous command"
echo test.com > /var/sheerdns/`sheerdnshash www.test.com`/www.test.com/CNAME
dig @localhost A www.test.com
Using sheerdns as a root nameserver. Note that for root domains, the
hash is especially omitted:
> /var/sheerdns/NS
> /var/sheerdns/SOA
for i in \
a:198.41.0.4 h:128.63.2.53 c:192.33.4.12 g:192.112.36.4 \
f:192.5.5.241 b:128.9.0.107 j:192.58.128.30 k:193.0.14.129 \
l:198.32.64.12 m:202.12.27.33 i:192.36.148.17 e:192.203.230.10 ; do
N=`echo $i | cut -f1 -d:`.root-servers.net
echo $i | cut -f2 -d: > /var/sheerdns/`sheerdnshash $N`/$N/A
echo $N >> /var/sheerdns/NS
echo $N >> /var/sheerdns/SOA
done
dig @localhost SOA .
dig @localhost NS .
ENVIRONMENT VARIABLES
There are no applicable environment variables.
CONFIGURATION FILE
sheerdns has no configuration file. It just works.
BUGS
No bugs are known at present.
FILES
sheerdns makes use of the directory /var/sheerdns/*/* to lookup
entries. These directories are created on startup. No errors are
reported if the directories could not be created.
STANDARDS
Hmmm, more than I have time to read. Start with RFC-1035.
AVAILABILITY
http://freshmeat.net/ will always have links to the latest
sheerdns.tar.gz source file as well as this page.
AUTHOR
Paul Sheer <psheer@icon.co.za>
SEE ALSO
dig(1), nslookup(8), BIND, MyDNS, djbdns, tinydns, Dents.
Jan 11 2000 sheerdns(1)