--- /dev/null
+.TH qualification 5
+
+.SH NAME
+qualification \- User's guide to name qualification
+
+.SH OVERVIEW
+.B Qualification
+means conversion
+of a short host name that you type, such as
+.IR cheetah ,
+into a complete (``fully qualified'') domain name,
+such as
+.IR cheetah.heaven.af.mil .
+
+This page explains the djbdns qualification procedure.
+These rules are followed by the
+.I dns_ip4_qualify
+library routine in djbdns,
+and by programs that use the
+.BR dns_ip4_qualify (3)
+routine.
+
+.SH Rewriting instructions
+Normally the djbdns qualification procedure
+follows instructions listed in
+.IR /etc/dnsrewrite ,
+a file created by your system administrator.
+You can override
+.I /etc/dnsrewrite
+by creating your own file
+and setting the
+.I $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:
+.TP
+.RI = post\fR:\fInew\fR
+means that the host name
+.I post
+is replaced by
+.IR new .
+.TP
+.RI * post\fR:\fInew\fR
+means that any name of the form
+.I prepost
+is replaced by
+.IR prenew .
+.TP
+.RI ? post\fR:\fInew\fR
+means that any name of the form
+.IR prepost ,
+where
+.I pre
+does not contain dots or brackets,
+is replaced by
+.IR prenew .
+.TP
+.RI - post\fR:\fInew\fR
+means that any name of the form
+.I prepost
+is replaced by
+.IR new .
+
+.SH 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
+.I cheetah.heaven.af.mil
+if that name has IP addresses listed in DNS,
+or
+.I cheetah.af.mil
+otherwise.
+
+In general,
+.IR x +\fIy1\fR+\fIy2\fR+\fIy3\fR
+is qualified as
+.I xy1
+if
+.I xy1
+has IP addresses listed in DNS;
+otherwise, as
+.I xy2
+if
+.I xy2
+has IP addresses listed in DNS;
+otherwise, as
+.IR 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
+.I lion
+qualified as
+.I lion.heaven.af.mil
+or
+.IR lion.af.mil ,
+and
+.I tiger
+qualified as
+.I tiger.heaven.af.mil
+or
+.IR tiger.af.mil ,
+and so on.
+
+Searching is generally not a recommended feature.
+If you rely on
+.I gw
+being qualified as
+.IR gw.af.mil ,
+and someone suddenly adds a new
+.IR gw.heaven.af.mil ,
+you'll end up talking to the wrong host.
+It's better to rely on syntactic rules that you control.
+
+.SH Compatibility mechanisms
+If the rewriting-instructions file does not exist,
+the djbdns qualification procedure looks for a local domain name in three
+places:
+.TP
+1.
+the
+.I $LOCALDOMAIN
+environment variable, if it is set; or
+.TP
+2.
+the first
+.I domain
+or
+.I search
+line
+in
+.IR /etc/resolv.conf ,
+if
+.I /etc/resolv.conf
+exists and has such a line; or
+.TP
+3.
+everything after the first dot in the system's hostname.
+.P
+It then creates rewriting instructions of the form
+
+ ?:.\fIdomain\fR
+ *.:
+
+so that
+.RI . domain
+is added to any name without dots or brackets.
+
+You can specify searching in
+.I $LOCALDOMAIN
+by using several domain names separated by spaces.
+Your system administrator can specify searching in
+.I /etc/resolv.conf
+by putting several domains on a
+.I search
+line.
+
+.SH Compatibility notes
+Different DNS client programs use different qualification procedures.
+Two major differences between the djbdns qualification procedure
+and other qualification procedures:
+.IP
+Most programs use only
+.IR /etc/resolv.conf .
+They don't know anything about
+.I /etc/dnsrewrite
+and
+.IR $DNSREWRITEFILE .
+.IP
+Most long-running programs
+don't notice changes in
+.IR /etc/resolv.conf ;
+they read
+.I /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.
+.P
+Two minor differences:
+.IP
+Some programs interpret a
+.I domain
+line in
+.I /etc/resolv.conf
+as specifying a search list consisting of various suffixes of the domain.
+.IP
+Many programs will search the local domain
+for names
+.I with
+dots.
+.P
+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
+
+.SH SEE ALSO
+dnsipq(1)
+
+http://cr.yp.to/djbdns.html
HCoop / hcoop / zz_old / debian / djbdns.git / blobdiff