Make your own free website on Tripod.com

SunService Tip Sheet: Sun DNS


INFODOC ID: 11975

SYNOPSIS: DNS PSD/FAQ
DETAIL DESCRIPTION:

Product Support Document (PSD) for Sun DNS

Revision 2.1
Date: September 16, 1996

Table of Contents
=================

1.0: About DNS
  1.1: DNS Definitions
  1.2: Name Service Selection
  1.3: How DNS Looks Up Records
2.0: Debugging DNS
  2.1: The Map Files
  2.2: /var/adm/messages
  2.3: nslookup
  2.4: Dumping in.named
  2.5: DNS Debug Mode
  2.6: getent
  2.7: named-xfer Debugging
3.0: Common How Tos
  3.1: Setting Up a SunOS DNS Client
  3.2: Setting Up a Solaris DNS Client
  3.3: Registering Domains
  3.4: Modifying Domains
  3.5: Getting a Root Cache File
  3.6: Setting Up a Caching Only DNS Server
  3.7: Setting Up a Primary DNS Server
  3.8: Setting Up a Secondary DNS Server
  3.9: Adding a New Record to DNS Map Files
  3.10: Setting Up Subdomains
  3.11: Setting Up a Self Contained Domain
4.0: Some Frequently Asked Questions
  4.1: Miscellaneous Questions
  4.2: Common DNS Lookup Problems
  4.3: Map Modification Problems
  4.4: SunOS Name Service Interaction
  4.5: Solaris Name Service Interaction
  4.6: nslookup Errors
  4.7: DNS Directive Problems
  4.8: Common Error Messages
5.0: Patches
  5.1: DNS Patches for SunOS
  5.2: DNS Patches for Solaris
  5.3: YP/DNS Intercompatibility Patches for SunOS
6.0: Known Bugs & RFEs
  6.1: RFEs
7.0: References
  7.1: Important Man Pages
  7.2: Sun SRDBs
  7.3: Sun Educational Services
  7.4: Solaris Documentation
  7.5: Third Party Documentation
  7.6: RFCs
8.0: Supportability
9.0: Additional Support

1.0 About DNS

 1.0: About DNS

This Tip Sheet documents a wide variety of information concerning DNS,
as implemented in the SunOS and Solaris operating systems. It is
intended as both an introduction to DNS and as a guide to the most
common problems. There are many more complete references to DNS, a few
of which are noted in section 7.0.

 1.1: DNS Definitions

The following terms are crucial to the understanding of DNS:

A RESOLVER is what runs on a client machine to initiate DNS lookups.
On Sun machines, the /etc/resolv.conf file implements this
functionality. It contains a list of nameservers to use. (See Sections
3.1 and 3.2 for information on setting up clients.)

A NAMESERVER is the program that actually does the work of looking up
names. On Sun machines, the program IN.NAMED acts as the nameserver.
There is usually one nameserver for a cluster of machines. There are
three main types of nameservers. A CACHING-ONLY nameserver does
lookups of names, but controls no name records itself. A PRIMARY
nameserver not only does lookups of names, but also owns the records
for a domain. A SECONDARY nameserver does name lookups and 
backs up a primary nameserver by providing authoritative answers for a
certain domain. Many nameservers combine Primary and Secondary
functionality for different domains. (See Sections 3.6, 3.7 and 3.8
for information on setting up servers.)

There are numerous types of records in DNS. They are all listed and
explained in the in.named man page. The most important records are
those that correlate machine names and IP addresses.

FORWARD RECORDS, or A RECORDS, are those that translate from machine
names to IP addresses. These are the most commonly used records. A
typical A record is constructed as follows:

        dns.test.com.   IN A    192.1.1.1

(this example shows an A record which correlates the machine name
dns.test.com to the IP address 192.1.1.1)

REVERSE RECORDS, or PTR RECORDS, are those which translate from IP
addresses to machine names. They are typically used for security tests
and to convert ugly IP address into names for when humans are
examining them. PTR records are constructed in an awkward manner. The
IP address of a machine is reversed, then the suffix in-addr.arpa
is appended. A typical PTR record is:

        1.1.1.192.in-addr.arpa. IN PTR  dns.test.com.

(this example shows a PTR record which correlates the IP address
192.1.1.1 to the machine name dns.test.com)

There are two very important files for DNS.

The existence of /etc/resolv.conf tells a machine that it should be a
DNS client. The resolv file lists a domain name and name servers.

The existence of /etc/named.boot tells a machine that it should be a
DNS server. The boot file lists all of the subsidiary files that are
used by a DNS servers and is typically the starting place for DNS
debugging.

 1.2: Name Service Selection

Naming services are selected in a certain order and it is important
to understand this order, to make it easier to debug DNS problems.

On SunOS machines, the client first makes naming service requests to
NIS. If the NIS server is unable to find a hostname record, the server
will then make a request to DNS. There are two important things to
note here: first, if NIS is not running, a SunOS machine will not be
able to use DNS  second, it is actually the SunOS NIS servers that do
DNS lookups, not the clients. Thus, ensure that all of your
NIS servers are set up as DNS clients (see Section 3.1).

On Solaris machines, name server selection is done based on the order
shown in the /etc/nsswitch.conf (see Section 3.2). It is always the
client which actually does the DNS lookup.

The nslookup program is a notable exception. It always goes straight
to DNS and never accesses any other naming services. This is of note
because it is the only case where a SunOS NIS client will actually do
a DNS lookup itself. For this reason, it is usually best to make sure
that all SunOS NIS clients are also set up as DNS Clients (see Section
3.1).

 1.3: How DNS Looks Up Records

Finally, it should be pointed out that DNS looks up records in a
method that might not be entirely intuitive. In your /etc/resolv.conf,
a domain is listed. Whenever a lookup occurs, DNS first examines
the hostname you requested, with the domain name tacked on. Then it examines
the hostname with a subdomain tacked on (i.e., the first
part of the domain is removed). This iterative process proceeds until
there is only one label left in the domain name (i.e., com, gov, edu).
That label is discarded rather than being looked up. Afterwards, just
the hostname is looked up.  If a lookup succeeds, the further lookups
will not be tried.

For example, assume that my domain name is corp.sun.com. If I look up
'psi', the following lookups could be done:

  psi.corp.sun.com
  psi.sun.com
  psi

In reality, since psi.corp.sun.com is an actual machine name, I will
get a success back from 'psi.corp.sun.com' and the other two lookups
will not be done.

However, if I tried to lookup 'ftp.csua.berkeley.edu', the following
lookups could be done:

  ftp.csua.berkeley.edu.corp.sun.com
  ftp.csua.berkeley.edu.sun.com
  ftp.csua.berkeley.edu

The last lookup is the correct one and so all three are done.

There is only one way to circumvent this DNS lookup order. By
appending a '.' to the end of a lookup request, you fully qualify the
name. This tells DNS not to use the search list, but just to look up the
name you typed. For example, if you did a lookup of
'ftp.csua.berkeley.edu.', the following lookups could be done:

  ftp.csua.berkeley.edu

Some bugs in DNS setups go away when a '.' is appended to the end of a
hostname. This is usually because one of the earlier entries in the
search list (incorrectly) comes back with an affirmative answer.

2.0 Debugging DNS

 2.0: Debugging DNS

A variety of DNS problems, from records simply not being displayed, to
nslookup core-dumping, can be attributed to errors in your DNS map
files. It is extremely easy to make a mistake as simple as leaving off
a '.' that can have very undesirable effects on your DNS maps.
Following are a few good methods for debugging errors in DNS map
files.

 2.1: The Map Files

The simplest method for discovering errors in your maps is 
consulting the map files themselves. Described below are the most
common DNS errors, which are all very obvious from a quick perusal of
the file.

2.1.1: Unqualified Names

If you put a machine name in a DNS map file, but do not include a '.'
at the end of the machine name, the domain of the map will
automatically be appended. For example, if I have the following
information in my named.boot:

  primary       test.com        named.test

And in the named.test file I have the following entry:

  www   IN CNAME        dns.test.com

I will get undesirable results. in.named will look at the two
hostnames, 'www' and 'test.com' and see that neither is fully
qualified because of the lack of a trailing '.' Thus, that line will
be interpreted as follows:

  www.test.com is a CNAME record to dns.test.com.test.com

The following would be correct:

  www   IN CNAME        dns.test.com.

In this case, only the www entry would get 'test.com' appended to it.
However, the next record is the preferred one, as it is totally
consistent and thus more likely to be free of errors:

  www.test.com. IN CNAME        dns.test.com.

This is particularly a problem in reverse address files. If, for
example, I had the following in my named.boot:

  primary       0.0.127.in-addr.arpa    named.local

Any unqualified hostnames in the named.local map would have
'0.0.127.in-addr.arpa' domain added on to them. So, the following
line:

  1     IN PTR  localhost

Would be interpreted as:

  1.0.0.127.in-addr.arpa is a PTR record to localhost.0.0.127.in-addr.arpa

The bottom line is: always put in the full host name within your DNS
maps and always put a '.' at the end of each record, to be sure there
are no problems.

Please note that this is only for the individual DNS map files. Names
in the resolv.conf and the named.boot should not have an appended '.'

2.1.2: Incorrect Records in Files

If you have a DNS map controlling a domain, that file can only contain
entries for machines within that domain. Nameserver records are a
distinct exception, since it is necessary that they exist to do
lookups for the domain. However, normal records (A, MX, CNAME) should
all be within the domain that is listed in your named.boot. For
example, if your named.boot lists the following:

  primary       test.com        named.test

The following record would be correct and expected:

  www.test.com. IN CNAME        dns.test.com.

As would the following:

  very.long.cname.test.com.     IN CNAME        dns.test.com.

The following would be useless:

  other-domain.com.     IN CNAME        dns.test.com.

Since our named.boot does not say that we control other-domain.com.,
queries for that domain will never get directed to us.

Again, the exception is: many NS records will have A records
associated with them, which are from outside the domain of your file.
This is necessary, so that the name servers can be found.

2.1.3: Illegal Directives

Earlier versions of DNS allowed 'domain' and 'sortlist' directives to
be put in the named.boot file. These are no longer supported and may
cause problems if you list them in your named.boot. The named.boot
file should contain only the following directives: directory, primary,
secondary, cache.

 2.2: /var/adm/messages

Whenever you restart in.named, the map files get parsed and
obvious error messages are reported to /var/adm/messages. You can
restart the named by running:

  # kill -HUP `cat /etc/named.pid`

You can then check for the named messages by running:

  %% grep named /var/adm/messages

Ignore everything but the messages that have times correlating with
your killing of the named. See just the following if the
named startup detects no errors:

  Sep  7 12:28:04 psi named[96]: reloading nameserver

However, if there are problems, errors will be displayed as well:

  Sep  7 12:28:04 psi named[96]: named.root: No such file or directory
  Sep  7 12:28:04 psi named[96]: named.local: No such file or directory

If any named messages appear in /var/adm/messages at named startup
time, they must be corrected before DNS will work correctly.

 2.3: nslookup

nslookup is a very powerful command for debugging DNS problems. When
you run it, it will start up doing lookups from the first nameserver
in your resolv.conf file:

  psi%% nslookup
  Default Server:  sun-barr.EBay.Sun.COM
  Address:  150.100.254.2

  >

By default, you can tell nslookup to check A records by
entering them on the prompt:

  > psi.corp.sun.com
  Server:  sun-barr.EBay.Sun.COM
  Address:  150.100.254.2

  Name:    psi.corp.sun.com
  Address:  150.105.16.28

  >

Note that on every lookup, nslookup repeats the server name and
address, to remind you what DNS server is answering your requests.

You can ask nslookup to verify other types of DNS records as well,
using the 'set type=' command. For example, if I wanted to examine MX
records, I would enter the following:

  > set type=mx
  > sun.com
  Server:  sun-barr.EBay.Sun.COM
  Address:  150.100.254.2

  sun.com preference = 10, mail exchanger = Sun.COM
  Sun.COM internet address = 192.9.9.1
  >

Finally, you can ask nslookup to use a different server for lookups,
using the 'server' command:

  > server cs.utexas.edu
  Default Server:  cs.utexas.edu
  Address:  128.83.139.9

  > sun.com
  Server:  cs.utexas.edu
  Address:  128.83.139.9

  sun.com preference = 30, mail exchanger = Sun.COM
  sun.com preference = 10, mail exchanger = mercury.Sun.COM
  sun.com preference = 20, mail exchanger = venus.Sun.COM
  Sun.COM internet address = 192.9.9.1
  mercury.Sun.COM internet address = 192.9.25.1
  venus.Sun.COM   internet address = 192.9.25.5

This is particularly useful if you are trying to check for propagation
of DNS record, or if you think that DNS records might look different
as different sites (as indeed is the case with the mx records that I
looked up for sun.com).

Later parts of this document will suggest that nslookup be used to
examine certain types of records, sometimes on certain servers. This
may be done with the 'set type=' and 'server' commands that are shown
above.

2.3.1: nslookup -debug

You can get even more information from nslookup by putting it into
debug mode. This is done by typing 'set debug' at the nslookup prompt,
and then doing a lookup, as normal. nslookup will produce a lot of
information when you do this:

  > set debug
  > sun.com
  Server:  sun-barr.EBay.Sun.COM
  Address:  150.100.254.2

  res_mkquery(0, sun.com.Corp.Sun.COM, 1, 1)
  ------------
  Got answer:
      HEADER:
          opcode = QUERY, id = 5, rcode = NXDOMAIN
          header flags:  response, auth. answer, want recursion, recursion ava
          questions = 1,  answers = 0,  authority records = 1,  additional = 0
  ...
  ------------
  res_mkquery(0, sun.com.Sun.COM, 1, 1)
  ------------
  Got answer:
      HEADER:
          opcode = QUERY, id = 6, rcode = NXDOMAIN
          header flags:  response, auth. answer, want recursion, recursion ava
          questions = 1,  answers = 0,  authority records = 1,  additional = 0
  ...
  ------------
  res_mkquery(0, sun.com, 1, 1)
  ------------
  Got answer:
      HEADER:
          opcode = QUERY, id = 7, rcode = NOERROR
          header flags:  response, auth. answer, want recursion, recursion ava
          questions = 1,  answers = 1,  authority records = 0,  additional = 0

      QUESTIONS:
          sun.com, type = A, class = IN
      ANSWERS:
      ->  sun.com
          internet address = 192.9.9.1
          ttl = 86400 (1 day)

This is very useful because it takes you through the entire lookup,
going down the whole search list. You'll note that when I look up
sun.com, because my domain is corp.sun.com, nslookup looks at
sun.com.corp.sun.com, sun.com.sun.com and sun.com, in order.

Many DNS problems are due to something in the searchlist giving an
incorrect answer (for example, if I got an answer from
sun.com.sun.com, I would never get the correct answer). This can be
clearly seen if nslookup ends earlier in the search path.

 2.4: Dumping in.named

You can force your in.named to dump, to see exactly what is in its
memory. You do this by executing the following:

  # kill -INT `cat /etc/named.pid`

This will cause all of the information stored by your in.named to be
written to /var/tmp/named_dump.db. You'll probably see lots of random
entries which your named has cached. By looking carefully through this
file, you'll be able to also pick out your own data. Via this method,
it is very easy to see problems, such as that noted in section 2.1
above.

 2.5: DNS Debug Mode

If none of the above methods clarify your DNS map errors, you can turn
DNS debugging on. This should be done on the DNS server that your
current client is referencing via its /etc/resolv.conf. The following
kill commands will turn debugging on DNS up to level two (each time
the kill signal is given, the debugging level increments by one):

  # kill -USR1 `cat /etc/named.pid`
  # kill -USR1 `cat /etc/named.pid`

This will make a debugging file appear in /var/tmp/named.run. Here is
an example of a DNS debugging file showing a DNS lookup of "sun.com"
which failed:

  Debug turned ON, Level 1
  Debug turned ON, Level 2

  datagram from 150.105.16.28 port 33446, fd 6, len 38
  req: nlookup(sun.com.Corp.Sun.COM) id 5 type=1
  req: missed 'sun.com.Corp.Sun.COM' as '' (cname=0)
  findns: No root nameservers for class 1?
  req: answer -> 150.105.16.28 6 (33446) id=5 Local

  datagram from 150.105.16.28 port 33447, fd 6, len 25
  req: nlookup(sun.com) id 6 type=1
  req: missed 'sun.com' as '' (cname=0)
  findns: No root nameservers for class 1?
  req: answer -> 150.105.16.28 6 (33447) id=6 Local

In this case, you can again note that the entire searchlist is checked.

It is evident from the 'req: missed' line that nothing was returned,
and from the next line that there is an error 'No root nameservers
for class 1?'. This makes sense, because this is from behind a firewall and so 
the DNS can't get out to look up names at the root level.

Sometimes the DNS debugging information will give this sort of clue as
to the real problem, but often it is hard to read and difficult to
interpret. Usually, it is better to use the debug mode in
nslookup, because that is a little easier to read.

To turn off named logging, execute:

  # kill -USR2 `cat /etc/named.pid`

This will return DNS debugging to level 0.

2.6: getent

Some apparent DNS problems really are not the fault of
DNS. On Solaris, this can be diagnosed via the getent command. You can
run getent with the following arguments:

  %% getent hosts machine-name

getent will look at the nsswitch.conf and look up your machine-name
according to the order listed in the hosts: line. So it might first
go to files, then to nis or nisplus before it gets to DNS. If you used
nslookup and everything looked fine, try getent next. If it
fails or gives bad information, that means that one of the other
naming services, before DNS, is misbehaving.

 2.7: named-xfer Debugging

You might find that when you are acting as a secondary name server, you
are getting errors when named-xfer runs and tries to download your
zones.

If the problem is occasional, it is extremely likely that you are
having some intermittent connectivity problem or a performance
problem. These issues are beyond the scope of this document and are
generally not issues that SunService can help with. Sections 8.0 and
9.0 explain your other alternatives.

If the problem is very consistent, download the map
with full debugging turned on. This is done by running named-xfer by
hand.

SunOS:

  # /usr/etc/in.named-xfer -z sub.test.com -f /tmp/zonefile -s 0 -d 2 dns.test.c
om

Solaris:

  # /usr/sbin/named-xfer -z sub.test.com -f /tmp/zonefile -s 0 -d 2 dns.test.com

The above command downloads the zone sub.test.com from the
machine dns.test.com. When the download occurs, it will be written to
/tmp/zonefile. Debugging output will be written to
/var/tmp/xfer.ddt.*.

After you have executed named-xfer, investigate the
zonefile that was transferred and see how much of the file made it to
you. More importantly, look at the debugging output. Very
often, it lists precisely what the problem is. Usually, when
connectivity is good, if named-xfer fails it is because there is some
error in the zone files on the primary DNS server.

3.0 Common How Tos

 3.1: Setting Up a SunOS DNS Client

Edit the /etc/resolv.conf to make a machine correctly use
DNS. There should be between 2 and 4 lines in the resolver file. The
first line contains the domain for the machine, while the following
lines contain nameservers. If you list more than one nameserver, the
additional ones will be used as backups. A typical resolv.conf, for my
machine, psi.corp.sun.com, which has one nameserver, would be:

  domain corp.sun.com
  nameserver 150.100.254.2


Always use an IP address for the nameserver directive, not
a hostname.

On a SunOS machine, you will also have to run NIS for DNS to work
correctly. In addition, the NIS server must have a resolv.conf file
set up, exactly as is described above.  If this is not an option,
section 4.4 suggests unsupported alternatives.

 3.2: Setting Up a Solaris DNS Client

The resolv.conf setup for a Solaris machine is identical to what is
described in section 3.1 for SunOS.

On a Solaris machine, also add dns to the hosts: line of the
/etc/nsswitch.conf.

For example, if you are not using NIS or NIS+, the hosts: line of your
nsswitch.conf will read:

  hosts:      files

Change it to read:

  hosts:      files dns

If the phrase '[NOTFOUND=return]' appears in the hosts line, you
should either get rid of it or put the phrase dns before it,
otherwise DNS will never get consulted. For example, the standard
hosts line if you are running NIS+ reads:

  hosts:      nisplus [NOTFOUND=return] files

Change it to read:

  hosts:      nisplus dns [NOTFOUND=return] files

 3.3: Registering Domains

Before you can start offering DNS service for your domain, you must
register that domain with InterNic, the internet naming authority. To
do this, ftp to internic.net, go into the /templates directory and
retrieve the file called DOMAIN-TEMPLATE.TXT. This template can be
used to register for ORG, COM, EDU or NET domains. You will need
another template for other countries or other domains. They should
all be contained in this same directory.

After you have filled out DOMAIN-TEMPLATE.TXT, return it to
HOSTMASTER@internic.net. Complete information on this procedure will
be contained in the template file itself.

Note that you must have your primary and secondary nameservers up and
running before InterNic will register your domain name. Be aware that InterNic 
takes a few weeks to a month to complete domain registration, so put in your 
application well ahead of time.

In most cases, your internet service provider will have already taken
care of these details for you.

 3.4: Modifying Domains

If you want to modify domain information that Internic is currently
holding, use the same procedure as described in section 3.3.
Simply retrieve the DOMAIN-TEMPLATE.TXT file and send it to
HOSTMASTER@internic.net.

 3.5: Getting a Root Cache File

FTP the file /domain/named.root from rs.internic.net for the most
current Root Cache File. Your root cache file should be updated
regularly.
 In the below examples, this cache file will be installed as
/var/named/named.ca.

 3.6: Setting Up a Caching Only DNS Server

Following is a sample of how to set up a caching only name server.
This will be a name server which will cache records it looks up, but
will control no records of its own:

--start /etc/named.boot--

         named.boot file for a caching only name server

directory     /var/named
cache         .                               named.ca
 primary       0.0.127.in-addr.arpa            named.local
--end /etc/named.boot--

--start /var/named/named.local--

                   Address to host mapping for 127.0.0 net

     Note: In this and all other examples, the SOA line continues
     the following args:

    @ IN SOA controlling-machine email

     where controlling-machine is the machine which holds the primary
         records for this particular domain
     where email is an email address for the DNS administrator, with
         a '.' substituted for the '@'

@               IN       SOA    dns.test.com. administrator.test.com.
(
                  1           serial number
                  10800       refresh after 3 hours
                  3600        retry after 1 hour
                  604800      expire after 1 week
                  86400 )     minimum TTL of 1 day
                  IN      NS      dns.test.com.
1               IN      PTR     localhost.
dns.test.com.   IN      A       192.1.1.1
--end /var/named/named.local--

There must also be a /var/named/named.ca file, which should be
retrieved as described in section 3.5.

The books listed in sections 7.4 and 7.5 give a much more in-depth
description of setting up a caching only name server.

 3.7: Setting Up a Primary DNS Server

Following is a sample of how to set up a primary DNS server.  This
will be a name server that caches the records it looks up and
controls records of its own. Please note that in this example we
control both the domain test.com and a theoretical set of IP
addresses for that domain, 192.1.1.0. All DNS servers should control
both their forward and reverse address records.

--start /etc/named.boot--

         named.boot file for a caching only name server

directory     /var/named
cache         .                               named.ca
primary       0.0.127.in-addr.arpa            named.local
primary       test.com                        named.test
primary       1.1.192.in-addr.arpa            named.rev
--end /etc/named.boot--

--start /var/named/named.local--
[Identical to section 3.6 above]
--end /var/named/named.local--

--start /var/named/named.test--

                   Host to address mapping for test.com

@               IN       SOA    dns.test.com. administrator.test.com.
(
                  1           serial number
                  10800       refresh after 3 hours
                  3600        retry after 1 hour
                  604800      expire after 1 week
                  86400 )     minimum TTL of 1 day
                  IN NS         dns.test.com.
dns.test.com.   IN A          192.1.1.1
num2.test.com.  IN A          192.1.1.2
    there should be one A record as above for each machine in the
    test.com domain
--end /var/named/named.test--

--start /var/named/named.rev--

                   Address to Host mapping for test.com

@               IN       SOA    test.com. administrator.test.com.
(
                  1           serial number
                  10800       refresh after 3 hours
                  3600        retry after 1 hour
                  604800      expire after 1 week
                  86400 )     minimum TTL of 1 day
                  IN NS         dns.test.com.
1               IN PTR        dns.test.com.
2               IN PTR        num2.test.com.
dns.test.com.   IN A          192.1.1.1
    there should be one PTR record as above for each machine in the
     1.1.192.in-addr.arpa domain, that is, every machine whose network
     number starts with 192.1.1
--end /var/named/named.rev--

There must also be a /var/named/named.ca file, which should be
retrieved as described in section 3.5.

The books listed in sections 7.4 and 7.5 give a much more in-depth
description of setting up a caching only name server.

 3.8: Setting Up a Secondary DNS Server

Following is a sample of how to set up a secondary DNS server.  This
will be a name server which will cache records it looks up and
backs up records for a domain.  Please note that we secondary both the
domain test.com and a theoretical set of IP addresses for that
domain, 192.1.1.0.

--start /etc/named.boot--

         named.boot file for a caching only name server

directory     /var/named
cache         .                               named.ca
primary       0.0.127.in-addr.arpa            named.local
secondary     test.com                192.1.1.1       named.test
secondary     1.1.192.in-addr.arpa    192.1.1.1       named.rev
--end /etc/named.boot--

The IP address noted for the secondary lines (192.1.1.1 in this
example) should be the IP address of the machine that is primary for
the domain.

The named.ca file should be retrieved as described in section 3.5.

The named.local file should be created as described in section 3.6.

The named.test and named.rev files will automatically be created when
in.named is started up by downloading the information from the
primary server.

Note: although this example only shows secondary lines, machines can
actually combine primary and secondary lines in arbitrary ways. For
example, a machine could primary test.com and secondary foo.org, as a
favor to a nearby domain.

 3.9: Adding a New Record to DNS Map Files

Given below is an example of how to add a record for a new machine to
your DNS files. Steps 1 and 2 will vary if you are adding something
else, like MX or CNAME records. Steps 3 and 4 should be done whenever
a change is made to a DNS file. This outline assumes the example shown
in section 3.7 above.

Step 1: Add an A record for your new host to your forward map

In  /var/named/named.test:

newmachine.test.com.  IN A    192.1.1.3

Step 2: Add a PTR record for your new host to your reverse map

In /var/named/named.rev:

3     IN PTR  newmachine.test.com.

Step 3: Increment the serial numbers of every file you changed

In /var/named/named.test:
                  2           serial number

In /var/named/named.rev:
                  2           serial number

Step 4: Restart the named on your primary server

  # kill -HUP `cat /etc/named.pid`

--------------------------
Advanced DNS Server Setups
--------------------------

 3.10: Setting Up Subdomains

If you decide that you wish to create subdomains in your DNS zone, you
have a number of options.

The easiest method is to just include the subdomain in the same file
as your domain. For example, if you control test.com and wish to
create a subdomain called sub.test.com, you could just put entries
like the following in the file that is defined as primary for your
test.com domain:

machine.sub.test.com.  IN A          192.1.1.170

If you prefer, you could put the subdomain in a separate file. In this
case, you would modify your named.boot.

--start /etc/named.boot--

         named.boot file for a caching only name server

directory     /var/named
cache         .                               named.ca
primary       0.0.127.in-addr.arpa            named.local
primary       test.com                        named.test
primary       sub.test.com                    named.sub
primary       1.1.192.in-addr.arpa            named.rev
--end /etc/named.boot--

Afterwards, all of the machine.sub.test.com entries would go in
named.sub.

In the most complex setup, you might decide to give a subdomain away
to someone else and allow them to control it. This is called
Parenting (or Delegating) a Subdomain. To do this, edit the
file that is primary for the domain and add nameserver and A lines
for the subdomain. For example, if I wanted to give control of
sub.test.com to remote-machine.sub.test.com, I would put the following
two lines in the named.test file:

sub.test.com.                 IN NS   remote-machine.sub.test.com.
remote-machines.sub.test.com. IN A    192.1.1.160

In general, add a NS line for each of the machines that will
be a name server for the subdomain and an A record for each of
those name servers. Afterwards, the subdomain nameservers must be set
up as a normal nameserver (see Section 3.7) and changes may be made
to those files.

 3.11: Setting Up a Self Contained Domain

If you are not connected to the internet, but still want to set up
DNS, you must implement a Self Contained Domain. This is done by
defining one of your internal machines as a root name server.

On all nameservers other than your root name server, you will need to
set up a special cache file. As usual, all of you non-root name
servers will have the following line in their named.boot:

cache         .                               named.ca

However, rather than retrieving a root file as described in Section
3.5, construct it yourself. Simply create a file that includes
an NS record pointing towards your root name server and an A record, as
follows:

--start /var/named/named.ca--
.     99999999        IN NS   root.test.com.
root.test.com.        IN A    192.1.1.10
--end /var/named/named.ca--

Also, edit the files on your newly defined root server. There
should NOT be a 'cache' line in the named.boot on the root name
server. Rather, you need to insert a primary line for the root domain:

--snippet of /etc/named.boot--
primary       .       named.root
--snippet of /etc/named.boot--

The named.root file must contain nameserver records for each of your
internal domains and A records for each of them.

If section 3.7 contained my entire internal DNS domain, I would need
to create the following named.root file:

                   Internal Root db

@               IN       SOA    root.test.com. administrator.root.test.com.
(
                  1           serial number
                  10800       refresh after 3 hours
                  3600        retry after 1 hour
                  604800      expire after 1 week
                  86400 )     minimum TTL of 1 day
                  IN NS         root.test.com.
root.test.com.  IN A          192.1.1.10
     NS records for test.com.
     We have two nameservers, test.com. and num2.test.com.
test.com.       IN NS         dns.test.com.
                IN NS         num2.test.com.
     NS records for our reverse domain
     We have two nameservers, test.com. and num2.test.com.
1.1.192.in-addr.arpa  IN NS   dns.test.com.
                      IN NS   num2.test.com.
     A records for all of the nameservers listed above
dns.test.com.   IN A          192.1.1.1
num2.test.com.  IN A          192.1.1.2
root.test.com.  IN A          192.1.1.10

A self-contained domain should never be set up if you are directly
connected to the internet. If you do become connected to the internet
at a later time, replace all of your root caches with a
correct one from the net. In addition, get rid of any
'primary .' lines in your named.boot files.

4.0 Frequently Asked Questions

 4.1: Miscellaneous Questions

Q1: What version of BIND does Sun's in.named implement?

A1: SunOS implements Bind 4.8.1. This means that some newer directives
such as 'search' will not be available.

Solaris implements Bind 4.8.3 in the "as-supplied" OS thru 2.5.1.
A patch is needed to update Solaris to BIND 4.9.3. See the Solaris
Patch list in Section 5.2.  More details on BIND 4.9.3 are
supplied in the Patches.

An RFE does exist to upgrade the Solaris in.named to the newest
version of Bind, which is 4.9.3. See Section 6.1.

Q2: What limitations are there on domain names?

A2: According to RFC 924, the first character of your domain name may
not be a digit (i.e., 1sun.com is illegal). Though RFC 1123 does relax
this limitation, Sun machines do not support this. Sun's Bind is RFC
924 compliant.

Q3: Why do some of my host names appear as 255.255.255.255 or
    as a different number?

A3: The cause of this is use of leading zeros in the DNS database
    files for the "A" records.  If you put in a leading zero,
    named assumes the number is octal.  Because 8 and 9 are illegal
    numbers in octal, the 255.255.255.255 entry goes in the database.
    Also an entry such as 192.1.1.032 translates the 032 to 26 decimal.

 4.2: Common DNS Lookup Problems

Q: Why does name resolution immediately fail?

A1: An intercompatibility problem may exist with other naming
services, such as NIS or NIS+. Run 'nslookup' and see if you can use
that to lookup the record that you were trying to access. If
'nslookup' works, DNS is ok, but may not be integrated into your
naming services. Consult section 4.4 or 4.5 below.

A2: Your resolv.conf may be set up incorrectly. Reference section 3.1
for the correct way to set up your resolver. Verify the spelling of
the various directives (domain, nameserver) to make sure that there
were no inadvertent typos.

A3: On a SunOS system, you may be trying to run DNS without NIS. This
is unsupported. Section 4.4 explains your options.

A4: On a 5.3 system, you may have a comment in the middle of the hosts
line in your /etc/nsswitch.conf, as follows:

  hosts: file dns # changes made by me

On 5.3 machines, comments in the nsswitch.conf must begin at the start
of a line  if they are in the middle of a line, that line will not be
correctly read.

Q: Why does name resolution hang for a minute before failing?

A: If name resolution is hanging for an extended time before failing,
this means that your DNS server is not responding. Verify
that you have a good route to your DNS server with the ping command.
If your route seems sound, then either the server is not running
in.namedor the server is having an error of its own. Either continue
debugging the error on the server or choose another machine to be
your name server and adjust your resolv.conf appropriately.

Q: Why does name resolution hang for half a minute before returning an
answer?

A: This typically means that you have multiple name servers in you
resolv.conf and the first one or two failed, as in the question
above. Your resolver is eventually falling back to a good name server
later in your resolv.conf. Comment out the first nameserver
listed in your resolv.conf and see if that improves the situation. If
you have three nameservers listed, you may end up commenting out the
first two. Afterwards, investigate the server to see what
might have been causing the problem.

Q: Why can I not look up names outside of my domain?

A1: You do not have a named.ca file on your DNS server, it is out
of date, or it contains incorrect information. Section 3.5 shows how
to get a new one.

A2: Your DNS server is unable to contact the root servers. You can
verify this by pinging the root servers listed in your cache file. If
this seems to be the case, examine your routing,
particularly to see if anything is purposefully blocking packets.

Q: Why can I only sometimes look up names outside of my domain?

A: Your named.ca file is out of date. Section 3.5 explains how to get
a new one.

4.2.1: ping/telnet/rlogin Problems Related to Name Lookup

Q: Why can I only ping/telnet/rlogin if I put a '.' after the machine
name, i.e. 'ping sun.com.'?

A: There is in an error in one of the DNS maps on the nameserver
listed in your resolv.conf. Consult section 2.0 for hints on how to
track down a map error. Adjusting your resolv.conf to look at a
different DNS server will fix your client, but not the basic error
which exists in one of your DNS maps.

Q: Why does ping/telnet/rlogin core dump on my SunOS system when I try
and connect to a system with multiple A records?

A: This is a known bug. It is fixed in the libc patch for 4.1.3 and
4.1.3_u1. See section 5.1 below.

Q: Why do some sites refuse to let me ftp/rlogin to them, complaining
that they can't lookup my server name?

A: Your machine is failing a security test because it does not have a
PTR record in the reverse map. Consult section 3.9 above, for how to
create both an A record and a PTR record for a machine.

 4.3: Map Modification Problems

Q: Why don't my modifications to the DNS maps show up after I make
them?

A1: It could be that you are not following the proper procedure to
make changes. First, you always must increment the serial number of
each and every map that you are modifying. All that is required is
that the number be increased. Second, you always need to deliver a
-HUP signal to the in.named process on your main server. See section
3.9 above for the proper procedure to add entries to DNS maps.

A2: DNS changes do take a measurable time to be propagated. Depending
on your exact setup, it can be two or more days before all sites on
the internet see modifications that you make.  The only machine that
is guaranteed to have your new records, after you have followed the
proper procedure noted in section 3.9 to add entries, is your primary
nameserver. You can check that they are there by running nslookup,
setting your server to be your primary DNS server, then looking up
the record. See section 2.3 for a brief introduction on running
nslookup. If you are able to lookup DNS records on your primary DNS
server, wait a few days after you have made the change. It is probable
that the changes will get propagated out to the net in due time.

A3: If you have followed the proper procedure to add entries to your
DNS map, but you are unable to look them up on the primary name
server, it is likely that you made an error in your entry. Examine
your maps carefully. You will also want to check the /var/adm/messages
file, as noted in section 2.2.

Q: Why do my modifications never appear anywhere outside my domain?

A: If you can see modifications on your primary DNS server, but not
anywhere else, and several days have passed since the change was made,
it is likely that your primary server is not registered with InterNic
as such. You can verify this by running nslookup, setting your server
to something other than your primary (or secondary) DNS server and
then looking up the NS records for your domain. The best server to use
for this lookup is your parent domain. That is, if you control
sub.test.com, use the name server for test.com. If you control
test.com or some other top level domain, use one of the root name
servers listed in your cache file. Section 2.3 gives a brief
introduction to running nslookup.

 4.4: SunOS Name Server Interaction

Q: How do I use DNS without NIS?

A: You really can't, at least not in a supported manner. If you are
running DNS on a SunOS machine, without NIS, you will find that it
will react in a very erratic and unexpected manner. Lookups might not
go to DNS at all or they might go to DNS only in some specific cases.
To run DNS in a Sun-supported manner, set up at
least a minimal NIS configuration.

If you are unwilling to do this, Sun SRDB #3886 explains how to modify
your libc to remove any NIS dependencies. This procedure does work,
but SunService is unable to support DNS on sites which use this
configuration.

Q: Why are my hostname lookups never checking DNS if NIS fails?

A1: In order for hostname lookups to get passed on to DNS, if NIS
lookups fail, you must build your DNS maps with a special "-b" flag.
If you consult your /var/yp/Makefile on your NIS master, near the top,
you will see four lines as follows:

  # Set the following variable to "-b" to have NIS servers use the domain name
  # resolver for hosts not in the current domain.
  #B=-b
  B=

For DNS to work with NIS, you must change the last two lines:

  B=-b
  #B=

Afterwards make a new map with the correct flags on it:

  # touch /etc/hosts
  # cd /var/yp
  # make

A2: When NIS fails to lookup a host and the request gets passed on to
DNS, it is actually the yp server that does the DNS lookup, not your
client. Check what your current ypserver is by executing:

  %% ypwhich

then log on to that server and verify that DNS works correctly from
that machine with the command:

  %% nslookup

See Section 2.3 for a description of the nslookup command.

A3: You could be running into a bug where NIS gives up if the first
DNS server does not respond. See section 5.1 for a description of the
patches that resolve this bug.

A4: It appears that ypserv can incorrectly cache information that says
that a DNS server is down. When this occurs, NIS decides that DNS is
down and never forwards requests. This seems to occur most often when
DNS has just been set up for the first time. After determining which
yp server you are bound to, via the ypwhich command, try logging on to
that machine, killing the ypserv daemon and restarting it. In many
cases, this will cause DNS lookup to start working.

Q: Why are my hostname lookups never checking DNS if NIS+, running in
YP compatibility mode, fails?

A1: If you are running NIS+ in YP compatibility mode and have SunOS
clients, your rpc.nisd must be run with the flags -Y and -B. Change
the following line:

                       EMULYP="-Y"

in the file /etc/init.d/rpc to read:

                       EMULYP="-Y -B"

then reboot your machine. Alternatively, you can find the rpc.nisd
process in the process table, kill it and restart it with the -Y and
-B flags. In this case, you will still need to change the
/etc/init.d/rpc file, however, in order to make rpc.nisd come up
correctly after the next reboot.

A2: When NIS+ fails to lookup a host and the request gets passed on
to DNS, it is actually the NIS+ server that does the DNS lookup, not
your client. Go to each of your NIS+ servers and verify that DNS
works correctly from that machine with the command:

  %% nslookup

See Section 2.3 for a description of the nslookup command.

If DNS is intermittently not getting used, it is quite possible that
one of your NIS+ servers is not running DNS, since each NIS+ request
gets handled by an arbitrary machine.

 4.5: Solaris Name Server Interaction

Q: Why isn't DNS being used for name lookups?

A: On Solaris machines, the file /etc/nsswitch.conf controls what is
used for hostname lookups. Consult the hosts: line of that
file and verify that it includes dns. See section 3.2 for the correct
method for adjusting the /etc/nsswitch.conf.

 4.6: nslookup Problems

Q: Why can't nslookup look up an IP address, such as 127.0.0.1?

A: Some versions of nslookup will let you type an IP address, such as
127.0.0.1, directly at the prompt and then automatically do the
reversal and lookup for you. This works, for example, under Solaris'
nslookup. This is not true of older versions of nslookup on SunOS
machines which will give you the following result:

  > 127.0.0.1
  Server:  sun-barr.EBay.Sun.COM
  Address:  150.100.254.2

  Name:    [127.0.0.1]
  Address:  127.0.0.1

For SunOS machines, request a PTR record and reverse the
address:

  > set type=ptr
  > 1.0.0.127.in-addr.arpa
  Server:  sun-barr.EBay.Sun.COM
  Address:  150.100.254.2

  1.0.0.127.in-addr.arpa  host name = localhost.Sun.COM

Q: Why does nslookup fail with the message "Can't find server name for
address XXX.XXX.XXX.XXX"?

A1: This typically means that a PTR record does not exist for the
nameserver listed first in your resolv.conf. Section 3.9 explains how
to correctly set up the reverse address records for a machine. You can
check and see if the reverse address records exist for a machine by
going to someplace where nslookup works, then telling it to look up
the PTR record for that machine, as is described above.

A2: This seems to occur in some instances where the server that you
are connecting to is running the public domain 4.9.3 BIND. If your
server's reverse address records are set up correctly, you should
determine if your server is running the public domain version of BIND.
If it is, and you can not work around it by using another server, you
should talk to a SunService Engineer and let them know that you would
like to help supply information to get a Bug filed on this.

Q: Why does nslookup core dump when I run it?

A: nslookup is very picky and will coredump if it is given incorrect
input. If nslookup core dumps when you start it up, check
your /etc/resolv.conf and all of your map files on your server
(especially recently modified ones). Section 3.1 explains how a
resolv.conf file should look. Section 2.0 gives hints on debugging bad
map files.

 4.7: DNS Directive Problems

Q: Why is my 'search' directive not being used?

A: The search directive is not supported under SunOS. If you wish to
use the search directive, upgrade to Solaris or use a
public-domain version of BIND.

Q: Why is my 'sortlist' directive not being used?

A: sortlist is not supported on any of the current versions of Sun's
DNS.

 4.8: Common Error Messages
 
The following errors are generated from in.named, usually to the
/var/adm/messages file.
 
Q: What does "named-xfer exited with signal 1" mean?
 
A: named-xfer is the program that secondary name servers use to load
the zone maps from primary name servers. If you see an error like the
above, it usually means that named-xfer failed. 
ping the IP address listed as your primary server (this is in the
named.boot, as is described in Section 3.8). If you cannot ping it,
you have an connectivity problem.
 
Other named-xfer problems may be diagnosed by running named-xfer by
hand. This is described in Section 2.7.
 
Q: What does "rt_malloc: memdebug overflow" mean?
 
A: This is an error in the DNS implementation in Solaris 2.4. Apply
patch 102479. See Section 5.2.
 
Q: What does "too many zones (MAXZONES=128)" mean?
 
A: Under SunOS, in.named has a limit of 128 zones  this means that
there may not be more than 128 primary/secondary lines in the
named.boot. If you are hitting this limit, you will have to combine
several subdomains into one domain file. i.e., just list:
 
  primary       test.com        named.test
 
Rather than:
 
  primary       test.com        named.test
  primary       sub.test.com    named.sub
  primary       sub2.test.com   named.sub2
  ...
 
Under Solaris, this limitation does not exist.
 
5.0: Patches

The following is the list of all of the DNS related patches for 4.1.3,
4.1.3_u1, 4.1.4, 5.3 and 5.4. If you are having DNS problems,
installing the patches is a good place to start, especially if you
recognize the general symptoms noted below.
 
In order for a machine to be stable, all of the recommended patches
should be installed as well. The list of recommended patches for your
operating system is available from sunsolve1.sun.com.
 
5.1 DNS Patches For SunOS
 
100390-01 SunOS 4.1, 4.1.x: DNS doesn't work properly with secondary name  
 
  Resolves a problem where zone transfers were not occurring properly
  between primary and secondary DNS servers, because the $ORIGIN was
  getting changed.
 
100891-13 SunOS 4.1.3: international libc jumbo patch  
100890-12 SunOS 4.1.3: domestic libc jumbo patch  
101558-07 SunOS 4.1.3_U1: international libc jumbo patch  
101759-03 SunOS 4.1.3_U1: domestic libc jumbo patch  
 
  Correct a problem where ftp, ping and other internet connection
  programs coredump if they try and connect to a machine with multiple
  A records. Please be sure to install the domestic version and not
  the international version, if you are in the US, because the
  international version does not include encryption, which is
  necessary for login to work correctly.
 
101838-01 SunOS 4.1.3_U1: in.named core dumps in 4.1.x  
 
  Fixes a number of problems which caused in.named to core dump.
 
5.2: DNS Patches for Solaris
 
102167-02 SunOS 5.3: DNS fix  
 
  A security patch, resolving possible DNS spoofing problems.
 
102479-01 SunOS 5.4: memory leak/mismanagement in in.named  
102480-01 SunOS 5.4_x86: memory leak/mismanagement in in.named  
 
  Cleans up a memory leak and gets rid of the error message,
  "rt_malloc: memdebug overflow"
 
101973-14 SunOS 5.4: fixes for libnsl and ypbind  
 
  Fixes certain name server library bugs, including one which could
  cause DNS to incorrectly arrange the IP addresses of a multi-homed
  host.

5.3 YP/DNS Intercompatibility Patches for SunOS
 
100482-07 SunOS 4.1 4.1.1 4.1.2 4.1.3: ypserv and ypxfrd Jumbo Patch  
 
  Fixes a number of incompatibilities between DNS & YP, including the
  one noted in 101435, below.
 
101435-01 SunOS 4.1.3_U1: ypserv fix  
 
  Resolves a problem where DNS would fail if the first name server was
  down, even if others when up, if YP was also involved.
6.0: Known Bugs & RFES
 
6.1 RFEs
 
1178513   Solaris DNS in.named et al. requires upgrade to latest version
 
  Requests that in.named be upgraded to the current version of Bind,
  which is 4.9.3
7.0: References
 
Although this document tries to give an overview of the most common
DNS issues, it is by no means comprehensive. The following resources
should be used to supplement the information that is contained herein.
 
7.1: Important Man Pages
 
  in.named
  nslookup
  resolver
  resolv.conf
 
7.2: Sun SRDBs
 
3886    Using DNS without NIS
4619    How to set up NIS/YP to use DNS?
5113    How to set up reverse address in server
 
7.3: Sun Educational Services

[pending]
 
7.4: Solaris Documentation
 
_Name Services Configuration Guide_, Part #801-6635-10
 
  Basic information on how to set up the various DNS files on a
  Solaris machine.

7.5 Third Party Documentation
 
_DNS and Bind_, by Paul Albitz & Cricket Liu, published by O'Reilly &
Associates, Inc., ISBN #1-56592-010-4
 
  The definitive source on administering DNS. Gives in-depth
  information on DNS setup, administration and debugging. A necessity
  for anyone controlling a large DNS domain.
 
7.6: RFCs

 
RFCs are the internet-written documents that define the specifications
of many common networking programs. RFCs can be retrieved from
nic.ddn.mil, in the /rfc directory or through WWW at
http://www.cis.ohio-state.edu/hypertext/information/rfc.html
 
1032    Domain Administrators Guide
1033    Domain Administrators Operations Guide
1034    Domain Names - Concepts and Facilities
1035    Domain Names - Implementation and Specification
 
  Together, these four documents form the official specs for the
  Domain Naming Service that underlies BIND.


 
8.0: Supportability
 
SunService is not responsible for the initial configuration of your
DNS, nor for answering basic questions about how to put such a DNS
configuration together.
 
We can help resolve problems where DNS is not behaving correctly, but
in such cases the contact must be a system administrator who has a
good understanding of the syntax and rules of DNS maps.
9.0: Additional Support
 
For initial configuration or DNS setup, please contact your local
SunService office for possible consulting offerings. Sun's Customer
Relations organization can put you in touch with your local
SunIntegration or Sales office. You can reach Customer Relations at
800-821-4643.

PATCH ID: n/a
PRODUCT AREA: Gen. Network
PRODUCT: DNS
SUNOS RELEASE: any
UNBUNDLED RELEASE: n/a
HARDWARE: any