Date: Mon, 29 Jun 2026 15:52:04 +0000 From: Dag-Erling=?utf-8?Q? Sm=C3=B8rg?=rav <des@FreeBSD.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org Subject: git: 066bef580b21 - main - resolver(5): Overhaul Message-ID: <6a4294a4.3b64f.27e24c23@gitrepo.freebsd.org>
index | next in thread | raw e-mail
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 8home | help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?6a4294a4.3b64f.27e24c23>