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

FreeBSD Manual Pages

  
 
  

home | help
sheerdns(8)		    System Manager's Manual		   sheerdns(8)

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

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	speci-
	      fied  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 omit-
	      ted, 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  re-
       ally 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, re-
       verse, 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	.

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  en-
       tries.  These  directories  are	created	on startup.  No	errors are re-
       ported if the directories could not be created.

STANDARDS
       Start by	reading	RFC-1035.

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

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

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

				  Jul 27 2016			   sheerdns(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | WILDCARDS | EXAMPLES | ENVIRONMENT VARIABLES | CONFIGURATION FILE | BUGS | FILES | STANDARDS | AVAILABILITY | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sheerdns&sektion=8&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help