svn commit: r365391 - head/share/man/man5

[Alan Somers]

Author: asomers
Date: Sun Sep  6 20:32:13 2020
New Revision: 365391
URL: https://svnweb.freebsd.org/changeset/base/365391

Log:
  nsswitch.conf(5): recommend placing cache after files
  
  When cache precedes files, and nscd is configured to allow negative caching,
  commands like "pw groupadd" can fail. The sequence of events looks like:
  
  1. A command like pkg(8) looks up the group, and finds it absent.
  2. pkg invokes pw(8) to add the group
  3. pkg queries the group, but nscd says it doesn't exist, since it has a
     negative cache entry for that group.
  
  See also: https://lists.freebsd.org/pipermail/freebsd-current/2012-January/031595.html
  
  Reviewed by:	bcr (manpages)
  MFC after:	1 week
  Sponsored by:	Axcient
  Differential Revision:	https://reviews.freebsd.org/D26184

Modified:
  head/share/man/man5/nsswitch.conf.5

Modified: head/share/man/man5/nsswitch.conf.5
==============================================================================
--- head/share/man/man5/nsswitch.conf.5	Sun Sep  6 20:03:13 2020	(r365390)
+++ head/share/man/man5/nsswitch.conf.5	Sun Sep  6 20:32:13 2020	(r365391)
@@ -33,7 +33,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd November 10, 2018
+.Dd September 6, 2020
 .Dt NSSWITCH.CONF 5
 .Os
 .Sh NAME
@@ -224,20 +224,24 @@ and continue on anything else (i.e,
 .Ss Cache
 You can enable caching for the particular database by specifying
 .Dq cache
-as the first source in the
+in the
 .Nm
 file.
+It should come after
+.Dq files ,
+but before remote sources like
+.Dq nis .
 You should also enable caching for this database in
 .Xr nscd.conf 5 .
-If for the particular query
+If for a particular query
 .Dq cache
-source returns success, no further sources are queried.
+source returns success, then no further sources are queried.
 On the other hand, if there are no previously cached data, the
 query result will be placed into the cache right after
 all other sources are processed.
-Note, that
+Note that
 .Dq cache
-requires
+requires the
 .Xr nscd 8
 daemon to be running.
 .Ss Compat mode: +/- syntax
@@ -321,15 +325,16 @@ resides in
 .Pa /etc .
 .El
 .Sh EXAMPLES
-To lookup hosts in cache, then in
+To lookup hosts in
 .Pa /etc/hosts
+, then in cache,
 and then from the DNS, and lookup user information from
 .Tn NIS
 then files, use:
 .Pp
 .Bl -tag -width passwd: -compact
 .It hosts:
-cache files dns
+files cache dns
 .It passwd:
 nis [notfound=return] files
 .It group: