   [1]D. J. Bernstein
   [2]Internet publication
   [3]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:
     * =post:new means that the host name post is replaced by new.
     * *post:new means that any name of the form prepost is replaced by
       prenew.
     * ?post:new means that any name of the form prepost, where pre does
       not contain dots or brackets, is replaced by prenew.
     * -post:new means that any name of the form prepost is replaced by
       new.

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:
     * Most programs use only /etc/resolv.conf. They don't know anything
       about /etc/dnsrewrite and $DNSREWRITEFILE.
     * Most long-running programs don't notice changes in
       /etc/resolv.conf; they read /etc/resolv.conf when they start, and
       they don't reread it until they are restarted. In contrast, the
       djbdns qualification procedure checks for changes every 10 minutes
       or 10000 uses.

   Two minor differences:
     * Some programs interpret a domain line in /etc/resolv.conf as
       specifying a search list consisting of various suffixes of the
       domain.
     * Many programs will search the local domain for names with dots.

   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

References

   1. file:///home/bruce/dev/djb.html
   2. file:///home/bruce/dev/web.html
   3. file:///home/bruce/dev/djbdns.html
