From fa263add26a4e1e848c5274b9dda20c09e50711b Mon Sep 17 00:00:00 2001 From: Jim Reid Date: Sun, 3 Sep 2000 20:45:58 +0000 Subject: [PATCH] First draft of resolver(5) man page --- doc/man/bin/resolver.5 | 215 +++++++++++++++++++++++++++++++++++++++ doc/man/lwres/resolver.5 | 215 +++++++++++++++++++++++++++++++++++++++ lib/lwres/man/resolver.5 | 215 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 645 insertions(+) create mode 100644 doc/man/bin/resolver.5 create mode 100644 doc/man/lwres/resolver.5 create mode 100644 lib/lwres/man/resolver.5 diff --git a/doc/man/bin/resolver.5 b/doc/man/bin/resolver.5 new file mode 100644 index 0000000000..01ec255d18 --- /dev/null +++ b/doc/man/bin/resolver.5 @@ -0,0 +1,215 @@ +.\" Copyright (C) @YEARS@ Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: resolver.5,v 1.1 2000/09/03 20:45:58 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt RESOLVER 5 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm resolver +.Nd resolver configuration file +.Sh SYNOPSIS +.Pa /etc/resolv.conf +.Sh DESCRIPTION +The +.Nm resolver +and +.Nm "BIND9 lightwreight resolver" +are sets of routines in the C library and BIND9 library respectively +that provide access to the Internet Domain Name System. +The resolver configuration file, +.Pa /etc/resolv.conf , +is normally gets read +by the resolver and lightweight resolver +routines to initialise low-level resolver data structures the first time +that a process invokes those routines. +The file contains a list of +keywords with values that provide various types of +information, such as the IP addresses of the servers that should be +used when making lookup requests. +.Pp +Each keyword and value must appear on a single line. +The value follows the keyword, separated by white space. +The hash character '#' or semi-colon ';' introduce comments. +Anything from either of these characters to the end of the line +is treated as a comment and ignored. +.\" XXXJR - Don't think the next para is relevant. Not every host will run +.\" a name server or lightweight resolver. Those that don't will need +.\" a resolv.conf so they can send their lookups somewhere sensible. +.\".Pp +.\"On a normally configured system, this file should not be necessary. +.\"The only name server to be queried will be on the local machine, +.\"the domain name is determined from the host name, +.\"and the domain search path is constructed from the domain name. +.Pp +The available configuration directives are: +.Bl -tag -width "nameserver" +.It Li nameserver +Internet address of a name server that the resolver should query. +The IP address of the server can be supplied in the usual notation: +either in dotted-decimal form for an IPv4 addess or in double colon +form described in RFC1884 for an IPv6 address. +Up to three nameserver directives can be listed. +See +.Dv LWRES_CONFMAXNAMESERVERS +in +.Pa . +If more than +.Dv LWRES_CONFMAXNAMESERVERS +nameserver directives are present in the file, +only the first three are used. +Any others are ignored. +.Pp +When there are multiple servers, the resolver +library queries them in the order listed. +If no +.Li nameserver +entries are present, the default is to attempt to use the name server or +lightweight resolver daemon on the local machine. +The algorithm used is to try a server, and if the query times out, +try the next, until out of name servers, +then repeat trying all the name servers +until a maximum number of retries are made. +.It Li domain +Local domain name. +Most queries for names within this domain can use short names +relative to the local domain. +When no +.Li domain +entry is present, the domain is determined from the local host name returned by +.Xr gethostname 2 ; +the domain part is taken to be everything after the first +.Sq \&. . +Finally, if the host name does not contain a domain part, the root +domain is assumed. +.It Li search +Search list for host-name lookup. +The search list is normally determined from the local domain name; +by default, it contains only the local domain name. +This may be changed by listing the desired domain search path +following the +.Li search +keyword with spaces or tabs separating the names. +Most resolver +queries will be attempted using each component +of the search path in turn until a match is found. +Note that this process may be slow and will generate a lot of network +traffic if the servers for the listed domains are not local, +and that queries will time out if no server is available +for one of the domains. +.Pp +The search list is currently limited to eight domains +with a total of 256 characters. +See +.Dv LWRES_CONFMAXSEARCH +and +.Dv LWRES_CONFMAXLINELEN +in +.Pa lwres/lwres.h . +.It Li sortlist +Allows addresses returned by gethostbyname to be sorted. +A +.Li sortlist +is specified by IP address netmask pairs. +The netmask is optional and defaults to the natural netmask of the net. +The IP address and optional network pairs are separated by slashes. +Up to 10 pairs may be specified. +For example: +.Bd -literal -offset indent +sortlist 130.155.160.0/255.255.240.0 130.155.0.0 +.Ed +.It Li options +Allows certain internal +.Nm resolver +variables to be modified. +The syntax is +.D1 Li options Ar option ... +where +.Ar option +is one of the following: +.Bl -tag -width "no_tld_query" +.It Li ndots: Ns Ar n +sets a threshold for the number of dots which +must appear in a name given to +.Fn res_query +(see +.Xr resolver 3 ) +before an +.Em initial absolute query +will be made. +The default for +.Ar n +is +.Dq 1 , +meaning that if there are +.Em any +dots in a name, the name will be tried first as an absolute name before any +.Em search list +elements are appended to it. +Acceptable values of +.Ar n +are between 0 and 255 inclusive. +.It debug +enables debugging traces for the resolver +XXXJR if anything actually looked at +.Dv confdata->resdebug . +At present the option is just recognised but not used by +the BIND9 implementation. +.It no_tld_query +tells the resolver not to attempt to resolve a +top level domain name, i.e. a name containing no dots. +Use of this option does not prevent the resolver from obeying the +standard +.Ar domain +and +.Ar search +rules with the given name. +XXXJR At present this option is recognised but is otherwise unused +in BIND9. +.It missing +XXXJR what about the other BIND8 resolver options like rotate and +timeout? Shouldn't these be provided for backwards compatibility? +.El +.El +.Pp +The +.Li domain +and +.Li search +keywords are mutually exclusive. +If more than one instance of these keywords is present, +the last instance wins. +.Sh FILES +.Pa /etc/resolv.conf +.Pa +.Sh SEE ALSO +.Xr gethostbyname 3 , +.Xr lwres_config 3 , +.Xr lwres 3 , +.Xr resolver 3 , +.Xr hostname 7 , +.Xr lwresd 8 , +.Xr named 8 , +"BIND9 Administrators Manual". +.Sh BUGS +Unrecognised directives and syntax errors in +.Pa /etc/resolv.conf +are usually silently ignored, though +.Er LWRES_R_FAILURE +can be returned by the lightweight resolver functions described in +.Xr lwres_config 3 +which parse this file. diff --git a/doc/man/lwres/resolver.5 b/doc/man/lwres/resolver.5 new file mode 100644 index 0000000000..01ec255d18 --- /dev/null +++ b/doc/man/lwres/resolver.5 @@ -0,0 +1,215 @@ +.\" Copyright (C) @YEARS@ Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: resolver.5,v 1.1 2000/09/03 20:45:58 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt RESOLVER 5 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm resolver +.Nd resolver configuration file +.Sh SYNOPSIS +.Pa /etc/resolv.conf +.Sh DESCRIPTION +The +.Nm resolver +and +.Nm "BIND9 lightwreight resolver" +are sets of routines in the C library and BIND9 library respectively +that provide access to the Internet Domain Name System. +The resolver configuration file, +.Pa /etc/resolv.conf , +is normally gets read +by the resolver and lightweight resolver +routines to initialise low-level resolver data structures the first time +that a process invokes those routines. +The file contains a list of +keywords with values that provide various types of +information, such as the IP addresses of the servers that should be +used when making lookup requests. +.Pp +Each keyword and value must appear on a single line. +The value follows the keyword, separated by white space. +The hash character '#' or semi-colon ';' introduce comments. +Anything from either of these characters to the end of the line +is treated as a comment and ignored. +.\" XXXJR - Don't think the next para is relevant. Not every host will run +.\" a name server or lightweight resolver. Those that don't will need +.\" a resolv.conf so they can send their lookups somewhere sensible. +.\".Pp +.\"On a normally configured system, this file should not be necessary. +.\"The only name server to be queried will be on the local machine, +.\"the domain name is determined from the host name, +.\"and the domain search path is constructed from the domain name. +.Pp +The available configuration directives are: +.Bl -tag -width "nameserver" +.It Li nameserver +Internet address of a name server that the resolver should query. +The IP address of the server can be supplied in the usual notation: +either in dotted-decimal form for an IPv4 addess or in double colon +form described in RFC1884 for an IPv6 address. +Up to three nameserver directives can be listed. +See +.Dv LWRES_CONFMAXNAMESERVERS +in +.Pa . +If more than +.Dv LWRES_CONFMAXNAMESERVERS +nameserver directives are present in the file, +only the first three are used. +Any others are ignored. +.Pp +When there are multiple servers, the resolver +library queries them in the order listed. +If no +.Li nameserver +entries are present, the default is to attempt to use the name server or +lightweight resolver daemon on the local machine. +The algorithm used is to try a server, and if the query times out, +try the next, until out of name servers, +then repeat trying all the name servers +until a maximum number of retries are made. +.It Li domain +Local domain name. +Most queries for names within this domain can use short names +relative to the local domain. +When no +.Li domain +entry is present, the domain is determined from the local host name returned by +.Xr gethostname 2 ; +the domain part is taken to be everything after the first +.Sq \&. . +Finally, if the host name does not contain a domain part, the root +domain is assumed. +.It Li search +Search list for host-name lookup. +The search list is normally determined from the local domain name; +by default, it contains only the local domain name. +This may be changed by listing the desired domain search path +following the +.Li search +keyword with spaces or tabs separating the names. +Most resolver +queries will be attempted using each component +of the search path in turn until a match is found. +Note that this process may be slow and will generate a lot of network +traffic if the servers for the listed domains are not local, +and that queries will time out if no server is available +for one of the domains. +.Pp +The search list is currently limited to eight domains +with a total of 256 characters. +See +.Dv LWRES_CONFMAXSEARCH +and +.Dv LWRES_CONFMAXLINELEN +in +.Pa lwres/lwres.h . +.It Li sortlist +Allows addresses returned by gethostbyname to be sorted. +A +.Li sortlist +is specified by IP address netmask pairs. +The netmask is optional and defaults to the natural netmask of the net. +The IP address and optional network pairs are separated by slashes. +Up to 10 pairs may be specified. +For example: +.Bd -literal -offset indent +sortlist 130.155.160.0/255.255.240.0 130.155.0.0 +.Ed +.It Li options +Allows certain internal +.Nm resolver +variables to be modified. +The syntax is +.D1 Li options Ar option ... +where +.Ar option +is one of the following: +.Bl -tag -width "no_tld_query" +.It Li ndots: Ns Ar n +sets a threshold for the number of dots which +must appear in a name given to +.Fn res_query +(see +.Xr resolver 3 ) +before an +.Em initial absolute query +will be made. +The default for +.Ar n +is +.Dq 1 , +meaning that if there are +.Em any +dots in a name, the name will be tried first as an absolute name before any +.Em search list +elements are appended to it. +Acceptable values of +.Ar n +are between 0 and 255 inclusive. +.It debug +enables debugging traces for the resolver +XXXJR if anything actually looked at +.Dv confdata->resdebug . +At present the option is just recognised but not used by +the BIND9 implementation. +.It no_tld_query +tells the resolver not to attempt to resolve a +top level domain name, i.e. a name containing no dots. +Use of this option does not prevent the resolver from obeying the +standard +.Ar domain +and +.Ar search +rules with the given name. +XXXJR At present this option is recognised but is otherwise unused +in BIND9. +.It missing +XXXJR what about the other BIND8 resolver options like rotate and +timeout? Shouldn't these be provided for backwards compatibility? +.El +.El +.Pp +The +.Li domain +and +.Li search +keywords are mutually exclusive. +If more than one instance of these keywords is present, +the last instance wins. +.Sh FILES +.Pa /etc/resolv.conf +.Pa +.Sh SEE ALSO +.Xr gethostbyname 3 , +.Xr lwres_config 3 , +.Xr lwres 3 , +.Xr resolver 3 , +.Xr hostname 7 , +.Xr lwresd 8 , +.Xr named 8 , +"BIND9 Administrators Manual". +.Sh BUGS +Unrecognised directives and syntax errors in +.Pa /etc/resolv.conf +are usually silently ignored, though +.Er LWRES_R_FAILURE +can be returned by the lightweight resolver functions described in +.Xr lwres_config 3 +which parse this file. diff --git a/lib/lwres/man/resolver.5 b/lib/lwres/man/resolver.5 new file mode 100644 index 0000000000..01ec255d18 --- /dev/null +++ b/lib/lwres/man/resolver.5 @@ -0,0 +1,215 @@ +.\" Copyright (C) @YEARS@ Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: resolver.5,v 1.1 2000/09/03 20:45:58 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt RESOLVER 5 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm resolver +.Nd resolver configuration file +.Sh SYNOPSIS +.Pa /etc/resolv.conf +.Sh DESCRIPTION +The +.Nm resolver +and +.Nm "BIND9 lightwreight resolver" +are sets of routines in the C library and BIND9 library respectively +that provide access to the Internet Domain Name System. +The resolver configuration file, +.Pa /etc/resolv.conf , +is normally gets read +by the resolver and lightweight resolver +routines to initialise low-level resolver data structures the first time +that a process invokes those routines. +The file contains a list of +keywords with values that provide various types of +information, such as the IP addresses of the servers that should be +used when making lookup requests. +.Pp +Each keyword and value must appear on a single line. +The value follows the keyword, separated by white space. +The hash character '#' or semi-colon ';' introduce comments. +Anything from either of these characters to the end of the line +is treated as a comment and ignored. +.\" XXXJR - Don't think the next para is relevant. Not every host will run +.\" a name server or lightweight resolver. Those that don't will need +.\" a resolv.conf so they can send their lookups somewhere sensible. +.\".Pp +.\"On a normally configured system, this file should not be necessary. +.\"The only name server to be queried will be on the local machine, +.\"the domain name is determined from the host name, +.\"and the domain search path is constructed from the domain name. +.Pp +The available configuration directives are: +.Bl -tag -width "nameserver" +.It Li nameserver +Internet address of a name server that the resolver should query. +The IP address of the server can be supplied in the usual notation: +either in dotted-decimal form for an IPv4 addess or in double colon +form described in RFC1884 for an IPv6 address. +Up to three nameserver directives can be listed. +See +.Dv LWRES_CONFMAXNAMESERVERS +in +.Pa . +If more than +.Dv LWRES_CONFMAXNAMESERVERS +nameserver directives are present in the file, +only the first three are used. +Any others are ignored. +.Pp +When there are multiple servers, the resolver +library queries them in the order listed. +If no +.Li nameserver +entries are present, the default is to attempt to use the name server or +lightweight resolver daemon on the local machine. +The algorithm used is to try a server, and if the query times out, +try the next, until out of name servers, +then repeat trying all the name servers +until a maximum number of retries are made. +.It Li domain +Local domain name. +Most queries for names within this domain can use short names +relative to the local domain. +When no +.Li domain +entry is present, the domain is determined from the local host name returned by +.Xr gethostname 2 ; +the domain part is taken to be everything after the first +.Sq \&. . +Finally, if the host name does not contain a domain part, the root +domain is assumed. +.It Li search +Search list for host-name lookup. +The search list is normally determined from the local domain name; +by default, it contains only the local domain name. +This may be changed by listing the desired domain search path +following the +.Li search +keyword with spaces or tabs separating the names. +Most resolver +queries will be attempted using each component +of the search path in turn until a match is found. +Note that this process may be slow and will generate a lot of network +traffic if the servers for the listed domains are not local, +and that queries will time out if no server is available +for one of the domains. +.Pp +The search list is currently limited to eight domains +with a total of 256 characters. +See +.Dv LWRES_CONFMAXSEARCH +and +.Dv LWRES_CONFMAXLINELEN +in +.Pa lwres/lwres.h . +.It Li sortlist +Allows addresses returned by gethostbyname to be sorted. +A +.Li sortlist +is specified by IP address netmask pairs. +The netmask is optional and defaults to the natural netmask of the net. +The IP address and optional network pairs are separated by slashes. +Up to 10 pairs may be specified. +For example: +.Bd -literal -offset indent +sortlist 130.155.160.0/255.255.240.0 130.155.0.0 +.Ed +.It Li options +Allows certain internal +.Nm resolver +variables to be modified. +The syntax is +.D1 Li options Ar option ... +where +.Ar option +is one of the following: +.Bl -tag -width "no_tld_query" +.It Li ndots: Ns Ar n +sets a threshold for the number of dots which +must appear in a name given to +.Fn res_query +(see +.Xr resolver 3 ) +before an +.Em initial absolute query +will be made. +The default for +.Ar n +is +.Dq 1 , +meaning that if there are +.Em any +dots in a name, the name will be tried first as an absolute name before any +.Em search list +elements are appended to it. +Acceptable values of +.Ar n +are between 0 and 255 inclusive. +.It debug +enables debugging traces for the resolver +XXXJR if anything actually looked at +.Dv confdata->resdebug . +At present the option is just recognised but not used by +the BIND9 implementation. +.It no_tld_query +tells the resolver not to attempt to resolve a +top level domain name, i.e. a name containing no dots. +Use of this option does not prevent the resolver from obeying the +standard +.Ar domain +and +.Ar search +rules with the given name. +XXXJR At present this option is recognised but is otherwise unused +in BIND9. +.It missing +XXXJR what about the other BIND8 resolver options like rotate and +timeout? Shouldn't these be provided for backwards compatibility? +.El +.El +.Pp +The +.Li domain +and +.Li search +keywords are mutually exclusive. +If more than one instance of these keywords is present, +the last instance wins. +.Sh FILES +.Pa /etc/resolv.conf +.Pa +.Sh SEE ALSO +.Xr gethostbyname 3 , +.Xr lwres_config 3 , +.Xr lwres 3 , +.Xr resolver 3 , +.Xr hostname 7 , +.Xr lwresd 8 , +.Xr named 8 , +"BIND9 Administrators Manual". +.Sh BUGS +Unrecognised directives and syntax errors in +.Pa /etc/resolv.conf +are usually silently ignored, though +.Er LWRES_R_FAILURE +can be returned by the lightweight resolver functions described in +.Xr lwres_config 3 +which parse this file.