GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
sheerdns(8) FreeBSD System Manager's Manual sheerdns(8)

sheerdns - master DNS server

sheerdns [-ttl seconds] [-p port] [-i iface-ip] [-d]

sheerdnshash string

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.

-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.

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.

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 intentionally 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 .

There are no applicable environment variables.

sheerdns has no configuration file. It just works.

No bugs are known at present.

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.

Start by reading RFC-1035.

http://bsdforge.com/projects/dns/sheerdns/ will always have links to the latest sheerdns-VERSION.tar.gz source file as well as this page.

	Paul Sheer <psheer@icon.co.za>
	Chris Hutchinson <portmaster bsdforge.com> (maintainer)

dig(1), nslookup(8), BIND, MyDNS, djbdns, tinydns, Dents.

Jul 27 2016

Search for    or go to Top of page |  Section 8 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.