git: 066bef580b21 - main - resolver(5): Overhaul
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Mon, 29 Jun 2026 15:52:04 UTC
The branch main has been updated by des:
URL: https://cgit.FreeBSD.org/src/commit/?id=066bef580b21bed9100c727045e1dbfdeb9bf1a9
commit 066bef580b21bed9100c727045e1dbfdeb9bf1a9
Author: Dag-Erling Smørgrav <des@FreeBSD.org>
AuthorDate: 2026-06-27 18:55:46 +0000
Commit: Dag-Erling Smørgrav <des@FreeBSD.org>
CommitDate: 2026-06-29 13:49:18 +0000
resolver(5): Overhaul
* Modernize the markup
* Describe the comment syntax
* Drop obsolete advice
* Capitalize sentences
* Improve the language
* Replace no_tld_query with no-tld-query; both are supported, but all the
other multi-word options use hyphens rather than underscores.
* Add missing ENVIRONMENT section
* Redo the example
MFC after: 1 week
---
share/man/man5/resolver.5 | 197 +++++++++++++++++++++++-----------------------
1 file changed, 100 insertions(+), 97 deletions(-)
diff --git a/share/man/man5/resolver.5 b/share/man/man5/resolver.5
index 4dd3f8c93a99..8af69fd2dac7 100644
--- a/share/man/man5/resolver.5
+++ b/share/man/man5/resolver.5
@@ -1,5 +1,6 @@
.\" Copyright (c) 1986, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
+.\" Copyright (c) 2026 Dag-Erling Smørgrav
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
@@ -25,7 +26,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd March 15, 2026
+.Dd June 27, 2026
.Dt RESOLVER 5
.Os
.Sh NAME
@@ -40,57 +41,56 @@ is a set of routines in the C library
which provide access to the Internet Domain Name System.
The resolver configuration file contains information that is read
by the resolver routines the first time they are invoked by a process.
-The file is designed to be human readable and contains a list of
-keywords with values that provide various types of resolver information.
.Pp
-On a normally configured system, setting this file manually should not
-be necessary.
-The only name server(s) to be queried will be on the local machine
-or automatically configured using DHCP or a similar mechanism,
-the domain name is determined from the host name,
-and the domain search path is constructed from the domain name.
-.Pp
-The different configuration options are:
-.Bl -tag -width nameserver
-.It Sy nameserver
-IPv4 or IPv6 address of a name server
-that the resolver should query.
+The file is read line by line.
+Anything after a
+.Sq #
+or
+.Sq \&;
+character is considered a comment and discarded.
+Blank lines are ignored.
+The first word on each non-blank line is a keyword which determines
+how the rest of the line is interpreted.
+Available keywords are:
+.Bl -tag -width indent
+.It Cm nameserver Ar address
+IPv4 or IPv6 address of a name server that the resolver should query.
Up to
.Dv MAXNS
-(currently 3) name servers may be listed,
-one per keyword.
-If there are multiple servers,
-the resolver library queries them in the order listed.
+(currently 3) name servers may be listed on separate lines.
+If there are multiple servers, the resolver library queries them in
+the order listed, unless
+.Dv RES_ROTATE
+is in effect
+.Po
+See the
+.Cm rotate
+option below
+.Pc .
If no
-.Sy nameserver
+.Cm nameserver
entries are present,
the default is to use the name server on the local machine.
(The algorithm used is to try a name 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 Sy domain
-Local domain name.
+.It Cm domain Ar name
+Set both the local domain name and the search list to
+.Ar name .
Most queries for names within this domain can use short names
relative to the local domain.
-If no
-.Sy domain
-entry is present, the domain is determined
-from the local host name returned by
+If no domain name has been set, it is derived from the local host name
+returned by
.Xr gethostname 3 ;
the domain part is taken to be everything after the first
.Ql \&. .
Finally, if the host name does not contain a domain part, the root
domain is assumed.
-.It Sy 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
-.Sy search
-keyword with spaces or tabs separating
-the names.
+.It Cm search Ar name1 Op name2 ...
+Sets the domain search list.
+Additionally, sets the local domain to
+.Ar name1 .
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
@@ -101,7 +101,7 @@ for one of the domains.
The search list is currently limited to six domains
with a total of 256 characters.
.It Sy sortlist
-Sortlist allows addresses returned by gethostbyname to be sorted.
+Sortlist allows addresses returned by the resolver to be sorted.
A sortlist is specified by IP address netmask pairs.
If the netmask is not specified,
it defaults to the historical Class A/B/C netmask of the net;
@@ -113,26 +113,21 @@ be specified.
E.g.,
.Pp
.Dl "sortlist 10.9.1.0/255.255.240.0 10.9.0.0/255.255.0.0"
-.It Sy options
+.It Cm options Ar option1 Op Ar option2 ...
Options allows certain internal resolver variables to be modified.
-The syntax is
-.Pp
-\fBoptions\fP \fIoption\fP \fI...\fP
-.Pp
-where
-.Sy option
-is one of the following:
-.Bl -tag -width no_tld_query
-.It Sy debug
-sets
+The following options are supported:
+.Bl -tag -width indent
+.It Cm debug
+Sets
.Dv RES_DEBUG
-in _res.options.
-.It Sy usevc
-sets
+in
+.Va _res.options .
+.It Cm usevc
+Sets
.Dv RES_USEVC
to use TCP instead of UDP for queries.
-.It Sy ndots : Ns Ar n
-sets a threshold for the number of dots which must appear in a name given to
+.It Cm ndots Ns Li : 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 )
@@ -147,8 +142,8 @@ meaning that if there are 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.
-.It Sy timeout : Ns Ar n
-sets the initial amount of time the resolver will wait
+.It Cm timeout Ns Li : Ns Ar n
+Sets the initial amount of time the resolver will wait
for a response from a remote
name server before retrying the query via a different name server.
The resolver may wait longer during subsequent retries
@@ -160,8 +155,8 @@ the allowed maximum is
.Dv RES_MAXRETRANS
(see
.In resolv.h ) .
-.It Sy attempts : Ns Ar n
-sets the number of times the resolver will send a query to each of
+.It Cm attempts Ns Li : Ns Ar n
+Sets the number of times the resolver will send a query to each of
its name servers
before giving up and returning an error to the calling application.
The default is
@@ -170,118 +165,126 @@ the allowed maximum is
.Dv RES_MAXRETRY
(see
.In resolv.h ) .
-.It Sy edns0
+.It Cm edns0
Sets
.Dv RES_USE_EDNS0 .
Attach an OPT pseudo-RR for the EDNS0 extension,
as specified in RFC 2671.
This allows the resolver to advertise a larger UDP receive buffer size,
permitting responses larger than the original 512-byte limit.
-.It Sy inet6
+.It Cm inet6
Sets
.Dv RES_USE_INET6 .
-Causes
-.Xr gethostbyname 3
+Causes the resolver
to look up AAAA records before A records
and to map IPv4 responses into IPv6 addresses.
The use of this option is discouraged.
-.It Sy insecure1
+.It Cm insecure1
Sets
.Dv RES_INSECURE1 .
Disables the check that the response was received from the
same server to which the query was sent.
Use of this option is a security risk and is not recommended.
-.It Sy insecure2
+.It Cm insecure2
Sets
.Dv RES_INSECURE2 .
Disables the check that the response contains a query
matching the one that was sent.
Use of this option is a security risk and is not recommended.
-.It Sy no-check-names
+.It Cm no-check-names
Sets
.Dv RES_NOCHECKNAME .
Disables the check of incoming host names for invalid characters
such as underscore, non-ASCII, or control characters.
-.It Sy no_tld_query
+.It Cm no-tld-query
tells the resolver not to attempt to resolve a top level domain name, that
is, a name that contains no dots.
Use of this option does not prevent
the resolver from obeying the standard
-.Sy domain
+.Cm domain
and
-.Sy search
+.Cm search
rules with the given name.
-.It Sy rotate
+.It Cm rotate
Sets
.Dv RES_ROTATE .
Causes the resolver to round-robin among the configured name servers,
distributing the query load instead of always trying the first
listed server.
-.It Sy reload-period : Ns Ar n
+.It Cm reload-period Ns Li : Ns Ar n
The resolver checks the modification time of
.Pa /etc/resolv.conf
-every
+if more than
.Ar n
-seconds.
-If
-.Pa /etc/resolv.conf
-has changed, it is automatically reloaded.
+seconds have elapsed since the last check.
+If the file has changed, it is automatically reloaded.
The default for
.Ar n
is two seconds.
Setting it to zero disables the file check.
.El
.Pp
-Options may also be specified as a space or tab separated list using the
+Options may also be passed as a space- or tab-separated list in the
.Dv RES_OPTIONS
environment variable.
+This environment variable is applied after the configuration file has
+been read.
.El
.Pp
The
-.Sy domain
+.Cm domain
and
-.Sy search
+.Cm search
keywords are mutually exclusive.
If more than one instance of these keywords is present,
-the last instance will override.
+the last instance will override all previous instances.
.Pp
The keyword and value must appear on a single line, and the keyword
.Pq for example, Sy nameserver
must start the line.
The value follows the keyword, separated by white space.
+.Sh ENVIRONMENT
+.Bl -tag -width indent
+.It Dv LOCALDOMAIN
+If set, overrides the local domain and search list set in the resolver
+configuration file.
+.It Dv RES_OPTIONS
+If set, its value is split into words and interpreted as resolver
+options as described for the
+.Cm options
+keyword in the resolver configuration file.
+.El
.Sh FILES
-.Bl -tag -width /etc/resolv.conf -compact
+.Bl -tag -width indent
.It Pa /etc/resolv.conf
-The file
-.Nm resolv.conf
-resides in
-.Pa /etc .
+Resolver configuration file.
.El
.Sh EXAMPLES
-A basic resolv.conf file could be in the following form.
-.Bd -literal -offset indent
-# The domain directive is only necessary, if your local
-# router advertises something like localdomain and you have
-# set up your hostnames via an external domain.
-domain localdomain.tld
+.Bd -literal
+# Set the local domain to example.com and the search list to
+# example.com, example.net, example.org
+search example.com example.net example.org
-# In case you a running a local dns server or caching name server
-# like local-unbound(8) for example.
+# Set the local domain and search list to example.com,
+# completely overriding the previous line
+domain example.com
+
+# Use this if you are running a local caching forwarding (or
+# recursing) resolver like local-unbound(8)
nameserver 127.0.0.1
# IP address of the local or ISP name service
-nameserver 192.168.2.1
-
-# Fallback nameservers, in this case these from Google.
-nameserver 8.8.8.8
-nameserver 8.8.4.4
+nameserver 198.51.100.53
+nameserver 203.0.113.53
-# Attach an OPT pseudo-RR for the EDNS0 extension,
-# as specified in RFC 2671.
+# Enable EDNS0, which tells the name server that we are capable of
+# handling large responses. This is required for DNSSEC.
options edns0
.Ed
.Sh SEE ALSO
+.Xr getaddrinfo 3 ,
.Xr gethostbyname 3 ,
+.Xr gethostname 3 ,
.Xr resolver 3 ,
.Xr hostname 7 ,
.Xr resolvconf 8