Date: Mon, 29 Jun 2026 15:54:31 +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: 51a4a96f63da - main - Revert "resolver(5): Overhaul" Message-ID: <6a429537.3c02d.15c10082@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=51a4a96f63dabc786abe4dd2dac74b2872165ceb commit 51a4a96f63dabc786abe4dd2dac74b2872165ceb Author: Dag-Erling Smørgrav <des@FreeBSD.org> AuthorDate: 2026-06-29 15:54:01 +0000 Commit: Dag-Erling Smørgrav <des@FreeBSD.org> CommitDate: 2026-06-29 15:54:01 +0000 Revert "resolver(5): Overhaul" This reverts commit 066bef580b21bed9100c727045e1dbfdeb9bf1a9. --- share/man/man5/resolver.5 | 197 +++++++++++++++++++++++----------------------- 1 file changed, 97 insertions(+), 100 deletions(-) diff --git a/share/man/man5/resolver.5 b/share/man/man5/resolver.5 index 8af69fd2dac7..4dd3f8c93a99 100644 --- a/share/man/man5/resolver.5 +++ b/share/man/man5/resolver.5 @@ -1,6 +1,5 @@ .\" 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 @@ -26,7 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd June 27, 2026 +.Dd March 15, 2026 .Dt RESOLVER 5 .Os .Sh NAME @@ -41,56 +40,57 @@ 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 -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. +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. Up to .Dv MAXNS -(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 . +(currently 3) name servers may be listed, +one per keyword. +If there are multiple servers, +the resolver library queries them in the order listed. If no -.Cm nameserver +.Sy 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 Cm domain Ar name -Set both the local domain name and the search list to -.Ar name . +.It Sy domain +Local domain name. Most queries for names within this domain can use short names relative to the local domain. -If no domain name has been set, it is derived from the local host name -returned by +If no +.Sy domain +entry is present, the domain is determined +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 Cm search Ar name1 Op name2 ... -Sets the domain search list. -Additionally, sets the local domain to -.Ar name1 . +.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. 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 the resolver to be sorted. +Sortlist allows addresses returned by gethostbyname 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,21 +113,26 @@ be specified. E.g., .Pp .Dl "sortlist 10.9.1.0/255.255.240.0 10.9.0.0/255.255.0.0" -.It Cm options Ar option1 Op Ar option2 ... +.It Sy options Options allows certain internal resolver variables to be modified. -The following options are supported: -.Bl -tag -width indent -.It Cm debug -Sets +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 .Dv RES_DEBUG -in -.Va _res.options . -.It Cm usevc -Sets +in _res.options. +.It Sy usevc +sets .Dv RES_USEVC to use TCP instead of UDP for queries. -.It Cm ndots Ns Li : Ns Ar n -Sets a threshold for the number of dots which must appear in a name given to +.It Sy 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 ) @@ -142,8 +147,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 Cm timeout Ns Li : Ns Ar n -Sets the initial amount of time the resolver will wait +.It Sy timeout : 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 @@ -155,8 +160,8 @@ the allowed maximum is .Dv RES_MAXRETRANS (see .In resolv.h ) . -.It Cm attempts Ns Li : Ns Ar n -Sets the number of times the resolver will send a query to each of +.It Sy attempts : 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 @@ -165,126 +170,118 @@ the allowed maximum is .Dv RES_MAXRETRY (see .In resolv.h ) . -.It Cm edns0 +.It Sy 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 Cm inet6 +.It Sy inet6 Sets .Dv RES_USE_INET6 . -Causes the resolver +Causes +.Xr gethostbyname 3 to look up AAAA records before A records and to map IPv4 responses into IPv6 addresses. The use of this option is discouraged. -.It Cm insecure1 +.It Sy 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 Cm insecure2 +.It Sy 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 Cm no-check-names +.It Sy 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 Cm no-tld-query +.It Sy 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 -.Cm domain +.Sy domain and -.Cm search +.Sy search rules with the given name. -.It Cm rotate +.It Sy 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 Cm reload-period Ns Li : Ns Ar n +.It Sy reload-period : Ns Ar n The resolver checks the modification time of .Pa /etc/resolv.conf -if more than +every .Ar n -seconds have elapsed since the last check. -If the file has changed, it is automatically reloaded. +seconds. +If +.Pa /etc/resolv.conf +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 passed as a space- or tab-separated list in the +Options may also be specified as a space or tab separated list using the .Dv RES_OPTIONS environment variable. -This environment variable is applied after the configuration file has -been read. .El .Pp The -.Cm domain +.Sy domain and -.Cm search +.Sy search keywords are mutually exclusive. If more than one instance of these keywords is present, -the last instance will override all previous instances. +the last instance will override. .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 indent +.Bl -tag -width /etc/resolv.conf -compact .It Pa /etc/resolv.conf -Resolver configuration file. +The file +.Nm resolv.conf +resides in +.Pa /etc . .El .Sh EXAMPLES -.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 +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 -# 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) +# In case you a running a local dns server or caching name server +# like local-unbound(8) for example. nameserver 127.0.0.1 # IP address of the local or ISP name service -nameserver 198.51.100.53 -nameserver 203.0.113.53 +nameserver 192.168.2.1 + +# Fallback nameservers, in this case these from Google. +nameserver 8.8.8.8 +nameserver 8.8.4.4 -# Enable EDNS0, which tells the name server that we are capable of -# handling large responses. This is required for DNSSEC. +# Attach an OPT pseudo-RR for the EDNS0 extension, +# as specified in RFC 2671. 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?6a429537.3c02d.15c10082>