SunService Tip Sheet for Sun DNS Revision 1.01 Date: October 30, 1995 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: How to Set Up a SunOS DNS Client 3.2: How to Set Up a Solaris DNS Client 3.3: How to Register Domains 3.4: How to Modify Domains 3.5: How to Get a Root Cache File 3.6: How to Set Up a Caching Only DNS Server 3.7: How to Set Up a Primary DNS Server 3.8: How to Set Up a Secondary DNS Server 3.9: How to Add a New Record to DNS Map Files 3.10: How to Set Up Subdomains 3.11: How to Set 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 ============== 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; it also backs up a primary nameserver by providing authoritative answers for a certain domain. (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 which correlate machine names and IP addresses. FORWARD RECORDS, or A RECORDS, are those which 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 address to machine names. They are typically used for security tests, and to convert ugly ip addreses into names, for when humans are examining them. PTR records are constructed in an awkward manner. The IP address of a machine is reversed, and 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 existance 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 existance 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, you must 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 will first examine the hostname you requested, with the domain name tacked on. Then, it will examine the hostname with a subdomain tacked on (ie, the first part of the domain is removed). This iterative process proceeds until there is only one label left in the domain name(ie, 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 lookup '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 sucess 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 searchlist, but just to lookup 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 searchlist (incorrectly) comes back with an affirmative answer. 2.0: Debugging DNS ================== A variety of DNS problems, from records simply not being displayed, to nslookup coredumping, 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 simply 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 consistant 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 though: other-domain.com. IN CNAME dns.test.com. Since our named.boot does not say 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 will get parsed, and obvious error messages will be 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. You should 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 simply 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 records, or if you thinks 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 the entire searchlist is checked. I can also see from the 'req: missed' line that nothing was returned, and from the next line that I'm getting an error 'No root nameservers for class 1?'. This makes sense, as I'm behind a firewall, and so my 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, you will be better off using the debug mode in nslookup, as that is a little easier to read. When you want to turn off named logging, you should execute: # kill -USR2 `cat /etc/named.pid` This will return DNS debugging to level 0. 2.6: getent ----------- Surprisingly, 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, you should 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 may find that when you are acting as a secondary name server, you are getting errors when named-xfer runs, and trys 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 consistant, you should try and 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. com Solaris: # /usr/sbin/named-xfer -z sub.test.com -f /tmp/zonefile -s 0 -d 2 dns.test.co m The above command would download the zone sub.test.com from the machine 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, you should investigate the zonefile that was transferred, and see how much of the file made it to you. More importantly, you should look at the debugging output. Very often, it will list precisely what the problem is. Usually, if 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: How to Set Up a SunOS DNS Client ------------------------------------- You must 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 You should 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: How to Set 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, you must 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 You should 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: How to Register 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, you must 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. You should also be aware that InterNic takes a few weeks to a month to complete domain registration, and so you should 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: How to Modify Domains -------------------------- The same procedure as is described in section 3.3 should be used if you want to modify domain information that Internic is currently holding. Simply retrieve the DOMAIN-TEMPLATE.TXT file, and send it to HOSTMASTER@internic.net. 3.5: How to Get 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: How to Set 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 will also need to 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: How to Set Up a Primary DNS Server --------------------------------------- Following is a sample of how to set up a primary DNS server. This will be a name server which will cache records it looks up, and also 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 --start /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 will also need to 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: How to Set 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 also 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: How to Add 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 /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 /var/named/named.rev: 3 IN PTR newmachine.test.com. Step 3: Increment the serial numbers of every file you changed /var/named/named.test: 2 ; serial number /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: How to Set 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 seperate 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, you must 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, you must add a NS line for each of the machines that will be a name server for the subdomain, and also 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: How to Set 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 is described in Section 3.5, you will contruct 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-- You must 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, you must replace all of your root caches with a correct one from the net. In addition, you must get rid of any 'primary .' lines in your named.boot files. 4.0: Some Frequently Asked Questions & Common Problems ====================================================== 4.1: Miscellaneous Questions ---------------------------- Q: What version of BIND does Sun's in.named implement? A: 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. 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. Q: What limitations are there on domain names? A: According to RFC 924, the first character of your domain name may not be a digit (ie, 1sun.com is illegal). Though RFC 1123 does relax this limitation, Sun machines do not support this. Sun's Bind is RFC 924 compliant. 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 inadvertant 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. You should 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.named, or 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. You should 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, you should 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, or 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, you should 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, ie '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: The machine you are using 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 need to 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 may 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, and 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. In order to run DNS in a Sun-supported manner, you should setup 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= In order 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" and 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 doing 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. You should 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, you should 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, you should 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, you must 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. You should try and ping the IP address listed as your primary server (this is in the named.boot, as is described in Section 3.8). If you can not ping it, you are having 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. ie, 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 SunOS 4.1, 4.1.x: DNS doesn't work properly with secondary name Resolves a problem where zone transfers were not occuring properly between primary and secondary DNS servers, because the $ORIGIN was getting changed. 100891 SunOS 4.1.3: international libc jumbo patch 100890 SunOS 4.1.3: domestic libc jumbo patch 101558 SunOS 4.1.3_U1: international libc jumbo patch 101759 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 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 SunOS 5.3: dns fix A security patch, resolving possible DNS spoofing problems. 102479 SunOS 5.4: memory leak/mismanagement in in.named 102480 SunOS 5.4_x86: memory leak/mismanagement in in.named Cleans up a memory leak, and also gets rid of the error message, "rt_malloc: memdebug overflow" 101973 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 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 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.