From nobody Mon Jun 29 15:52:04 2026 X-Original-To: dev-commits-src-main@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 4gprPc4SVCz6jNhl for ; Mon, 29 Jun 2026 15:52:04 +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 4gprPc3dSrz3L3G for ; Mon, 29 Jun 2026 15:52:04 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1782748324; 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=21wxucrhaCW3nD14aPsdAeYHaC+XEIPzKwpVzsXuMWs=; b=dedg4M+45hAQnUwaYLOMP6y9vexM1OKaBY758h1USJDcmowySTVLB4prCHroCZgL4dMxnC 5Fg4O/8L83Yxrz2/O+g0gSeSO2LN9eZtK2UCA4ZtNq7PYDHWTPgd+qEquGaFe7eP5xxkVQ aNRHtv7kYzTl3a0R3cZEknOaVKI1JutcnemrCfMEREEVDo4LKqXa/vrrRAMs42ies1j3zN UH+fLsMbaFuZ338YM4JAZBfKoknh+Mi9qZE3K1N8oGtwdFE0H3h5/s0AAcN4wh+K/sMY/E TlZZiJURV8Dn6ytIIvVcAXuIfjOxm5HBBH2mfoqs96N33KZZ+Ra45XigxodOyA== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1782748324; a=rsa-sha256; cv=none; b=ck8jl86DTsI09qfNV0e7jSQex2POogtExN8U1uss0VopQjIHm0CqS4ltq9tsPYqpWieSx5 QEj9XrwyuJBzUNlwjlb+J87fklz8MUUMnfJZ7jRgEipCl0bW1K9wRiKEMMxw0pONCuqU8j iwL7+nLsbhsCuc7vNSGVile1rmyryQmISlKAZkJyJS1a9F3K0y5ksBYm2T2Kx6NazfnSne jV1pyfOHN20KZzd57J+HLWIRk/EURR76VSEDvW1W7cTzabNTtx1FBY8wBGonwBIZG1ZFF8 5ulTleDypl5vaimJxQsVS/CgYVzfbC5b4jntBZtGiU5L6eI0Xtw+YZP7QJ3JCg== 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=1782748324; 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=21wxucrhaCW3nD14aPsdAeYHaC+XEIPzKwpVzsXuMWs=; b=MmXUv1UhkUXKsWNdOTAhwmzTu1qSaMX0tDP/62yNH21chl9vEqNSvkbb7PYvHURQiOQWSC +YSo6+OCGt80VbaNv4YAHEaV4RGbBV9f4veS9fhUlF+Tn0zSVEGRtv1vXuOm/oLRvMpUie pavx0xUHFPRCi+Mqj0WzakFiEOConCX8lZ33O2Y9GNV7F+412rIWV8iIEDXzf9j+b9KG+d 4vOt77uchzXWj0pGXgD236YVjxEO9Ytq42E0OXTO/4fH6kfqL5XM10REvMFnCBFAu62QtE 78VqK9ASf00DcOZyp4QgvUAuya5gd/oMO3OEswFeV9mzf9WFh0n+IuSizcRJ1g== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4gprPc2SNCz143w for ; Mon, 29 Jun 2026 15:52:04 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 3b64f by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Mon, 29 Jun 2026 15:52:04 +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: 066bef580b21 - main - resolver(5): Overhaul List-Id: Commit messages for the main branch of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-main List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-main@freebsd.org Sender: owner-dev-commits-src-main@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: 066bef580b21bed9100c727045e1dbfdeb9bf1a9 Auto-Submitted: auto-generated Date: Mon, 29 Jun 2026 15:52:04 +0000 Message-Id: <6a4294a4.3b64f.27e24c23@gitrepo.freebsd.org> The branch main has been updated by des: URL: https://cgit.FreeBSD.org/src/commit/?id=066bef580b21bed9100c727045e1dbfdeb9bf1a9 commit 066bef580b21bed9100c727045e1dbfdeb9bf1a9 Author: Dag-Erling Smørgrav AuthorDate: 2026-06-27 18:55:46 +0000 Commit: Dag-Erling Smørgrav 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