From nobody Mon Jun 29 15:54:31 2026 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4gprSS6zS7z6jNsl for ; Mon, 29 Jun 2026 15:54:32 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "YR1" (not verified)) by mx1.freebsd.org (Postfix) with ESMTPS id 4gprSS31dFz3Qgg for ; Mon, 29 Jun 2026 15:54:32 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1782748472; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=BFMDUqc1EF7mA3u+n+MQQt/qHjQ5neQdjPVydeW6Fzg=; b=nV9kMJsQotyJhdniBSf2sDZB+GvNtH6oXxGrXZR4g/A8EzHzcYiCmP8XckXTBOd5hIidGV 2EfNrTs3Uxda1+osGCWVTaPutInWun7gUMW3sd8ZHwqnKhnuBhyVIGUDDPzGKvHVoik6Zr /S2kZf64iD+WYQAs4mXO+Zptrq7ZlxQqkNSv6ck1i4cSBulbrf2xfOxTyLbfBetxbVCxNX OjRMnsZYYhRc2LQlujXEh9N+k6p6eja2sj0YyY8MmnWP/+wy0+LKhcqYceW06ShKhgygUX 23WoHn/klZipRgZLj0pM2h7QgdOMHnsiwZAdBkrMJ3n+Br6Hz8gS6lMPdXggKQ== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1782748472; a=rsa-sha256; cv=none; b=xnM6uKYufc3IBOT15r/08f9LR7dyWLHdlj8UzSWyJML7bRR1pibu0AjZA0TXxE5RliH7rH Cofvimu0KgiKIghgkYnNxXa0CHUzK74GRJu4nux4WIZxNIEXc3528E7faS13GCVV1PraUA h/VBjSxGZqr9Gi3kiEwNSo4aj1b5hd5wsIxgpCXqrdvppDe2er3Q39AlckYaIJwhlvXgwd lCcPX6FDv81J3n/lgnkAE5FzxewJIHrr/+VR4fda97yO9ICIfkodMD7GNCFLXzXIF0VE/+ KlUa5NBLDmYDc44c9q3Ae5Z6z/1i6K/Jtd5SJiwejekS9uywt5sWvGX1HutVRg== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1782748472; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=BFMDUqc1EF7mA3u+n+MQQt/qHjQ5neQdjPVydeW6Fzg=; b=W51gMdsmT/FBa42UchzFlWhyP/mn8CuQ2srKNGL+HY6MW15kqblvXbElavUSyiJxZGO7R1 b5d2t3OY06ibpIOIGT+EJD7ZbgDaqszxYE3sQiNeCFWltv0/5b4+fYEBJeO35Z1jgBreW8 vd+qbF6oFlpSCXWazcyRVdy2Qyu9fryqjm9naZQQ7e91sej2Gn39egsSj/0t/3mLbG813c anuTFqp4duAQbtBO5V0tNH76XigJdbl+27vVoZ1WYItsRm8RWpdadR+h4gIpxEoBoft+UT mgYPTiuAZykVDPJFdZQNcakvn1kLcNG13PCzJBbT7zTrxp51A57+7sMh1vhbrg== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4gprSR4qx4z148h for ; Mon, 29 Jun 2026 15:54:31 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 3c02d by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Mon, 29 Jun 2026 15:54:31 +0000 To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Dag-Erling=?utf-8?Q? Sm=C3=B8rg?=rav Subject: git: 51a4a96f63da - main - Revert "resolver(5): Overhaul" List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org List-Id: List-Post: List-Help: List-Subscribe: List-Unsubscribe: List-Owner: Precedence: list MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: des X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 51a4a96f63dabc786abe4dd2dac74b2872165ceb Auto-Submitted: auto-generated Date: Mon, 29 Jun 2026 15:54:31 +0000 Message-Id: <6a429537.3c02d.15c10082@gitrepo.freebsd.org> The branch main has been updated by des: URL: https://cgit.FreeBSD.org/src/commit/?id=51a4a96f63dabc786abe4dd2dac74b2872165ceb commit 51a4a96f63dabc786abe4dd2dac74b2872165ceb Author: Dag-Erling Smørgrav AuthorDate: 2026-06-29 15:54:01 +0000 Commit: Dag-Erling Smørgrav 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 8