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:

- `=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