D. J. Bernstein
Internet publication
djbdns

User's guide to name qualification

Qualification means conversion of a short host name that you type, such as cheetah, into a complete (``fully qualified'') domain name, such as cheetah.heaven.af.mil.

This page explains the djbdns qualification procedure. These rules are followed by the dns_ip4_qualify library routine in djbdns, and by programs that use the dns_ip4_qualify routine.

Rewriting instructions

Normally the djbdns qualification procedure follows instructions listed in /etc/dnsrewrite, a file created by your system administrator. You can override /etc/dnsrewrite by creating your own file and setting the $DNSREWRITEFILE environment variable to the name of that file.

Sample instructions:

     # anything.local -> me
     -.local:me
     # me -> 127.0.0.1
     =me:127.0.0.1
     # any.name.a -> any.name.af.mil
     *.a:.af.mil
     # any-name-without-dots -> any-name-without-dots.heaven.af.mil
     ?:.heaven.af.mil
     # remove trailing dot
     *.:

Instructions are followed in order, each at most once. There are four types of instructions:

Searching

The djbdns qualification procedure can search through DNS for several possible qualifications of a name. For example, the name
     cheetah+.heaven.af.mil+.af.mil
is qualified as cheetah.heaven.af.mil if that name has IP addresses listed in DNS, or cheetah.af.mil otherwise.

In general, x+y1+y2+y3 is qualified as xy1 if xy1 has IP addresses listed in DNS; otherwise, as xy2 if xy2 has IP addresses listed in DNS; otherwise, as xy3. You can list any number of +'s.

Searching is applied after rewriting, so you can use a rewriting instruction such as

     ?:+.heaven.af.mil+.af.mil
to have lion qualified as lion.heaven.af.mil or lion.af.mil, and tiger qualified as tiger.heaven.af.mil or tiger.af.mil, and so on.

Searching is generally not a recommended feature. If you rely on gw being qualified as gw.af.mil, and someone suddenly adds a new gw.heaven.af.mil, you'll end up talking to the wrong host. It's better to rely on syntactic rules that you control.

Compatibility mechanisms

If the rewriting-instructions file does not exist, the djbdns qualification procedure looks for a local domain name in three places:
  1. the $LOCALDOMAIN environment variable, if it is set; or
  2. the first domain or search line in /etc/resolv.conf, if /etc/resolv.conf exists and has such a line; or
  3. everything after the first dot in the system's hostname.
It then creates rewriting instructions of the form
     ?:.domain
     *.:
so that .domain is added to any name without dots or brackets.

You can specify searching in $LOCALDOMAIN by using several domain names separated by spaces. Your system administrator can specify searching in /etc/resolv.conf by putting several domains on a search line.

Compatibility notes

Different DNS client programs use different qualification procedures. Two major differences between the djbdns qualification procedure and other qualification procedures: Two minor differences: If you want the local domain searched for names with dots, you can set it up with rewriting:
     # aol.com -> aol.com or aol.com.heaven.af.mil
     *:++.heaven.af.mil
     # but skip directly to heaven.af.mil if no dots
     ?++.heaven.af.mil:.heaven.af.mil