Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
sheerdns(8)		    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

       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:


       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  If there are	several	IP addresses in	the file, they are or-
       der-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,  then that NS record is returned for the domain,, as well  as  On  the
       other   hand  a	separate  NS  record  can  be  created	for  lab.chem-,	applying  to  all  domains   *,
       *.*  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

       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 charac-
       ter, 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  com-
       plex 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	speci-
	      fied  in	this  option.  The default is 86400 seconds (one day).
	      This option should be set	to 10 seconds for dynamic  IP  address

       -p port
	      Listen port. Default is 53.

       -i iface-ip
	      inface-ip	 is  the network card you want to listen on.  If omit-
	      ted, it defaults to 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	* will	return results as expected. This means
       you should

	      echo > /var/sheerdns/`sheerdnshash '*'`/'*'
	      dig @localhost A

       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  re-
       ally required.

       Add mutiple A records for for round robin sharing:

	      echo > /var/sheerdns/`sheerdnshash`/
	      echo >>	/var/sheerdns/`sheerdnshash`/
	      echo >>	/var/sheerdns/`sheerdnshash`/
	      dig @localhost A
	      dig @localhost A
	      dig @localhost A

       Add a PTR records for

	      echo > /var/sheerdns/`sheerdnshash`/
	      echo > /var/sheerdns/`sheerdnshash`/
	      echo > /var/sheerdns/`sheerdnshash`/
	      echo > /var/sheerdns/`sheerdnshash 192.0.2`/192.0.2/NS
	      dig @localhost PTR

       Add  an	MX  record for	with (IMPORTANT) both its forward, re-
       verse, and nameserver lookups:

	      echo > /var/sheerdns/`sheerdnshash`/
	      echo >	/var/sheerdns/`sheerdnshash`/
	      echo > /var/sheerdns/`sheerdnshash`/
	      echo > /var/sheerdns/`sheerdnshash`/
	      dig @localhost MX

       Add an SOA record for 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 > /var/sheerdns/`sheerdnshash`/
	      dig @localhost SOA

       Add  an	CNAME  record for	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`/*
	      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 > /var/sheerdns/`sheerdnshash`/
	      dig @localhost A

       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:	h:	  c:	    g:    \
	       f:	b:	  j:   k:    \
	       l:	m:	  i:   e:  ;	do
		  N=`echo $i | cut -f1 -d:`
		  echo $i | cut	-f2 -d:	> /var/sheerdns/`sheerdnshash $N`/$N/A
		  echo $N >> /var/sheerdns/NS
		  echo $N >> /var/sheerdns/SOA
	      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  en-
       tries.  These  directories  are	created	on startup.  No	errors are re-
       ported if the directories could not be created.

       Start by	reading	RFC-1035.

AVAILABILITY will always  have  links  to
       the latest sheerdns-VERSION.tar.gz source file as well as this page.

	    Paul Sheer <>
	    Chris Hutchinson <portmaster> (maintainer)

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

				  Jul 27 2016			   sheerdns(8)


Want to link to this manual page? Use this URL:

home | help