[patch] nscd.conf.5: describe reloading, clarifications, v5

[patch] nscd.conf.5: describe reloading, clarifications, v5

[Greg Banks]

The following changes since commit fbe71b1b79e72be3b9afc44b5d479e7fd84b598a:

  ioctl_tty.2: wfix (2021-07-26 01:31:54 +0200)

are available in the Git repository at:

  git@github.com:gnb/man-pages.git nscd.conf.5.v5

for you to fetch changes up to de00b682c0d2280c92c692fbcdb6cf5d4ca9bc01:

  nscd.conf.5: describe reloading, clarifications, v5 (2021-08-06 09:26:57 -0700)

----------------------------------------------------------------
Greg Banks (1):
      nscd.conf.5: describe reloading, clarifications, v5

 man5/nscd.conf.5 | 115 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 112 insertions(+), 3 deletions(-)

diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5
index 7356bf7c2..25ee4901b 100644
--- a/man5/nscd.conf.5
+++ b/man5/nscd.conf.5
@@ -1,5 +1,6 @@
 .\" Copyright (c) 1999, 2000 SuSE GmbH Nuernberg, Germany
 .\" Author: Thorsten Kukuk <kukuk@suse.de>
+.\" Updates: Greg Banks <gbanks@linkedin.com> Copyright (c) 2021 Microsoft Corp.
 .\"
 .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
 .\" This program is free software; you can redistribute it and/or
@@ -53,9 +54,13 @@ The default is 0.
 .B threads
 .I number
 .RS
-This is the number of threads that are started to wait for
+This is the initial number of threads that are started to wait for
 requests.
 At least five threads will always be created.
+The number of threads may increase dynamically up to
+.B max\-threads
+in response to demand from clients,
+but never decreases.
 .RE
 .PP
 .B max\-threads
@@ -83,9 +88,20 @@ Specifies the user who is allowed to request statistics.
 unlimited |
 .I number
 .RS
-Limit on the number of times a cached entry gets reloaded without being used
+Sets a limit on the number of times a cached entry
+gets reloaded without being used
 before it gets removed.
-The default is 5.
+The limit can take values ranging from 0 to 254;
+values 255 or higher behave the same as
+.BR unlimited .
+Limit values can be specified in either decimal
+or hexadecimal with a "0x" prefix.
+The special value
+.B unlimited
+is case-insensitive.
+The default limit is 5.
+A limit of 0 turns off the reloading feature.
+See NOTES below for further discussion of reloading.
 .RE
 .PP
 .B paranoia
@@ -128,6 +144,9 @@ in the specified cache for
 is in seconds.
 Larger values increase cache hit rates and reduce mean
 response times, but increase problems with cache coherence.
+Note that for some name services (including specifically DNS)
+the TTL returned from the name service is used and
+this attribute is ignored.
 .RE
 .PP
 .B negative\-time\-to\-live
@@ -166,6 +185,7 @@ The files are
 .IR /etc/passwd ,
 .IR /etc/group ,
 .IR /etc/hosts ,
+.IR /etc/resolv.conf ,
 .IR /etc/services ,
 and
 .IR /etc/netgroup .
@@ -194,6 +214,8 @@ is shared with the clients so
 that they can directly search in them instead of having to ask the
 daemon over the socket each time a lookup is performed.
 The default is no.
+Note that a cache miss will still result in
+asking the daemon over the socket.
 .RE
 .PP
 .B max\-db\-size
@@ -236,6 +258,93 @@ from the source code of
 and are used if not overridden in the configuration file.
 The default values used in the configuration file of
 your distribution might differ.
+.SS Reloading
+.BR nscd (8)
+has a feature called reloading,
+whose behavior can be surprising.
+.PP
+Reloading is enabled when the
+.B reload-count
+attribute has a non-zero value.
+The default value in the source code enables reloading,
+although your distribution may differ.
+.PP
+When reloading is enabled,
+positive cached entries (the results of successful queries)
+do not simply expire when their TTL is up.
+Instead, at the expiry time,
+.B nscd
+will "reload",
+i.e.,
+re-issue to the name service the same query that created the cached entry,
+to get a new value to cache.
+Depending on
+.I /etc/nsswitch.conf
+this may mean that a DNS, LDAP, or NIS request is made.
+If the new query is successful,
+reloading will repeat when the new value would expire,
+until
+.B reload-count
+reloads have happened for the entry,
+and only then will it actually be removed from the cache.
+A request from a client which hits the entry will
+reset the reload counter on the entry.
+Purging the cache using
+.I nscd\~-i
+overrides the reload logic and removes the entry.
+.PP
+Reloading has the effect of extending cache entry TTLs
+without compromising on cache coherency,
+at the cost of additional load on the backing name service.
+Whether this is a good idea on your system depends on
+details of your applications' behavior,
+your name service,
+and the effective TTL values of your cache entries.
+Note that for some name services
+(for example, DNS),
+the effective TTL is the value returned from the name service and
+.I not
+the value of the
+.B positive\-time\-to\-live
+attribute.
+.PP
+Please consider the following advice carefully:
+.IP \(bu
+If your application will make a second request for the same name,
+after more than 1 TTL but before
+.B reload\-count
+TTLs,
+and is sensitive to the latency of a cache miss,
+then reloading may be a good idea for you.
+.IP \(bu
+If your name service is configured to return very short TTLs,
+and your applications only make requests rarely under normal circumstances,
+then reloading may result in additional load on your backing name service
+without any benefit to applications,
+which is probably a bad idea for you.
+.IP \(bu
+If your name service capacity is limited,
+reloading may have the surprising effect of
+increasing load on your name service instead of reducing it,
+and may be a bad idea for you.
+.IP \(bu
+Setting
+.B reload\-count
+to
+.B unlimited
+is almost never a good idea,
+as it will result in a cache that never expires entries
+and puts never-ending additional load on the backing name service.
+.PP
+Some distributions have an init script for
+.BR nscd (8)
+with a
+.I reload
+command which uses
+.I nscd\~-i
+to purge the cache.
+That use of the word "reload" is entirely different
+from the "reloading" described here.
 .SH SEE ALSO
 .BR nscd (8)
 .\" .SH AUTHOR

Re: [patch] nscd.conf.5: describe reloading, clarifications, v5

[Alejandro Colomar (man-pages)]

Hi Greg,

On 8/6/21 6:41 PM, Greg Banks wrote:
> The following changes since commit fbe71b1b79e72be3b9afc44b5d479e7fd84b598a:
> 
>    ioctl_tty.2: wfix (2021-07-26 01:31:54 +0200)
> 
> are available in the Git repository at:
> 
>    git@github.com:gnb/man-pages.git nscd.conf.5.v5
> 
> for you to fetch changes up to de00b682c0d2280c92c692fbcdb6cf5d4ca9bc01:
>  >    nscd.conf.5: describe reloading, clarifications, v5 (2021-08-06 
09:26:57 -0700)

Sorry for the delay.  Patch applied!
I also added a Signed-off-by line on your behalf.

Thanks!

Alex

> 
> ----------------------------------------------------------------
> Greg Banks (1):
>        nscd.conf.5: describe reloading, clarifications, v5
> 
>   man5/nscd.conf.5 | 115 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
>   1 file changed, 112 insertions(+), 3 deletions(-)
> 
> diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5
> index 7356bf7c2..25ee4901b 100644
> --- a/man5/nscd.conf.5
> +++ b/man5/nscd.conf.5
> @@ -1,5 +1,6 @@
>   .\" Copyright (c) 1999, 2000 SuSE GmbH Nuernberg, Germany
>   .\" Author: Thorsten Kukuk <kukuk@suse.de>
> +.\" Updates: Greg Banks <gbanks@linkedin.com> Copyright (c) 2021 Microsoft Corp.
>   .\"
>   .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
>   .\" This program is free software; you can redistribute it and/or
> @@ -53,9 +54,13 @@ The default is 0.
>   .B threads
>   .I number
>   .RS
> -This is the number of threads that are started to wait for
> +This is the initial number of threads that are started to wait for
>   requests.
>   At least five threads will always be created.
> +The number of threads may increase dynamically up to
> +.B max\-threads
> +in response to demand from clients,
> +but never decreases.
>   .RE
>   .PP
>   .B max\-threads
> @@ -83,9 +88,20 @@ Specifies the user who is allowed to request statistics.
>   unlimited |
>   .I number
>   .RS
> -Limit on the number of times a cached entry gets reloaded without being used
> +Sets a limit on the number of times a cached entry
> +gets reloaded without being used
>   before it gets removed.
> -The default is 5.
> +The limit can take values ranging from 0 to 254;
> +values 255 or higher behave the same as
> +.BR unlimited .
> +Limit values can be specified in either decimal
> +or hexadecimal with a "0x" prefix.
> +The special value
> +.B unlimited
> +is case-insensitive.
> +The default limit is 5.
> +A limit of 0 turns off the reloading feature.
> +See NOTES below for further discussion of reloading.
>   .RE
>   .PP
>   .B paranoia
> @@ -128,6 +144,9 @@ in the specified cache for
>   is in seconds.
>   Larger values increase cache hit rates and reduce mean
>   response times, but increase problems with cache coherence.
> +Note that for some name services (including specifically DNS)
> +the TTL returned from the name service is used and
> +this attribute is ignored.
>   .RE
>   .PP
>   .B negative\-time\-to\-live
> @@ -166,6 +185,7 @@ The files are
>   .IR /etc/passwd ,
>   .IR /etc/group ,
>   .IR /etc/hosts ,
> +.IR /etc/resolv.conf ,
>   .IR /etc/services ,
>   and
>   .IR /etc/netgroup .
> @@ -194,6 +214,8 @@ is shared with the clients so
>   that they can directly search in them instead of having to ask the
>   daemon over the socket each time a lookup is performed.
>   The default is no.
> +Note that a cache miss will still result in
> +asking the daemon over the socket.
>   .RE
>   .PP
>   .B max\-db\-size
> @@ -236,6 +258,93 @@ from the source code of
>   and are used if not overridden in the configuration file.
>   The default values used in the configuration file of
>   your distribution might differ.
> +.SS Reloading
> +.BR nscd (8)
> +has a feature called reloading,
> +whose behavior can be surprising.
> +.PP
> +Reloading is enabled when the
> +.B reload-count
> +attribute has a non-zero value.
> +The default value in the source code enables reloading,
> +although your distribution may differ.
> +.PP
> +When reloading is enabled,
> +positive cached entries (the results of successful queries)
> +do not simply expire when their TTL is up.
> +Instead, at the expiry time,
> +.B nscd
> +will "reload",
> +i.e.,
> +re-issue to the name service the same query that created the cached entry,
> +to get a new value to cache.
> +Depending on
> +.I /etc/nsswitch.conf
> +this may mean that a DNS, LDAP, or NIS request is made.
> +If the new query is successful,
> +reloading will repeat when the new value would expire,
> +until
> +.B reload-count
> +reloads have happened for the entry,
> +and only then will it actually be removed from the cache.
> +A request from a client which hits the entry will
> +reset the reload counter on the entry.
> +Purging the cache using
> +.I nscd\~-i
> +overrides the reload logic and removes the entry.
> +.PP
> +Reloading has the effect of extending cache entry TTLs
> +without compromising on cache coherency,
> +at the cost of additional load on the backing name service.
> +Whether this is a good idea on your system depends on
> +details of your applications' behavior,
> +your name service,
> +and the effective TTL values of your cache entries.
> +Note that for some name services
> +(for example, DNS),
> +the effective TTL is the value returned from the name service and
> +.I not
> +the value of the
> +.B positive\-time\-to\-live
> +attribute.
> +.PP
> +Please consider the following advice carefully:
> +.IP \(bu
> +If your application will make a second request for the same name,
> +after more than 1 TTL but before
> +.B reload\-count
> +TTLs,
> +and is sensitive to the latency of a cache miss,
> +then reloading may be a good idea for you.
> +.IP \(bu
> +If your name service is configured to return very short TTLs,
> +and your applications only make requests rarely under normal circumstances,
> +then reloading may result in additional load on your backing name service
> +without any benefit to applications,
> +which is probably a bad idea for you.
> +.IP \(bu
> +If your name service capacity is limited,
> +reloading may have the surprising effect of
> +increasing load on your name service instead of reducing it,
> +and may be a bad idea for you.
> +.IP \(bu
> +Setting
> +.B reload\-count
> +to
> +.B unlimited
> +is almost never a good idea,
> +as it will result in a cache that never expires entries
> +and puts never-ending additional load on the backing name service.
> +.PP
> +Some distributions have an init script for
> +.BR nscd (8)
> +with a
> +.I reload
> +command which uses
> +.I nscd\~-i
> +to purge the cache.
> +That use of the word "reload" is entirely different
> +from the "reloading" described here.
>   .SH SEE ALSO
>   .BR nscd (8)
>   .\" .SH AUTHOR
> 


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [patch] nscd.conf.5: describe reloading, clarifications, v5

[Greg Banks]

Thanks Alejandro, I really appreciate all your help 🙂

Greg.
________________________________
From: Alejandro Colomar (man-pages) <alx.manpages@gmail.com>
Sent: Friday, September 10, 2021 18:04
To: Greg Banks <gbanks@linkedin.com>
Cc: Michael Kerrisk <mtk.manpages@gmail.com>; linux-man@vger.kernel.org <linux-man@vger.kernel.org>; DJ Delorie <dj@redhat.com>; libc-alpha@sourceware.org <libc-alpha@sourceware.org>
Subject: Re: [patch] nscd.conf.5: describe reloading, clarifications, v5

Hi Greg,

On 8/6/21 6:41 PM, Greg Banks wrote:
> The following changes since commit fbe71b1b79e72be3b9afc44b5d479e7fd84b598a:
>
>    ioctl_tty.2: wfix (2021-07-26 01:31:54 +0200)
>
> are available in the Git repository at:
>
>    git@github.com:gnb/man-pages.git nscd.conf.5.v5
>
> for you to fetch changes up to de00b682c0d2280c92c692fbcdb6cf5d4ca9bc01:
>  >    nscd.conf.5: describe reloading, clarifications, v5 (2021-08-06
09:26:57 -0700)

Sorry for the delay.  Patch applied!
I also added a Signed-off-by line on your behalf.

Thanks!

Alex

>
> ----------------------------------------------------------------
> Greg Banks (1):
>        nscd.conf.5: describe reloading, clarifications, v5
>
>   man5/nscd.conf.5 | 115 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
>   1 file changed, 112 insertions(+), 3 deletions(-)
>
> diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5
> index 7356bf7c2..25ee4901b 100644
> --- a/man5/nscd.conf.5
> +++ b/man5/nscd.conf.5
> @@ -1,5 +1,6 @@
>   .\" Copyright (c) 1999, 2000 SuSE GmbH Nuernberg, Germany
>   .\" Author: Thorsten Kukuk <kukuk@suse.de>
> +.\" Updates: Greg Banks <gbanks@linkedin.com> Copyright (c) 2021 Microsoft Corp.
>   .\"
>   .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
>   .\" This program is free software; you can redistribute it and/or
> @@ -53,9 +54,13 @@ The default is 0.
>   .B threads
>   .I number
>   .RS
> -This is the number of threads that are started to wait for
> +This is the initial number of threads that are started to wait for
>   requests.
>   At least five threads will always be created.
> +The number of threads may increase dynamically up to
> +.B max\-threads
> +in response to demand from clients,
> +but never decreases.
>   .RE
>   .PP
>   .B max\-threads
> @@ -83,9 +88,20 @@ Specifies the user who is allowed to request statistics.
>   unlimited |
>   .I number
>   .RS
> -Limit on the number of times a cached entry gets reloaded without being used
> +Sets a limit on the number of times a cached entry
> +gets reloaded without being used
>   before it gets removed.
> -The default is 5.
> +The limit can take values ranging from 0 to 254;
> +values 255 or higher behave the same as
> +.BR unlimited .
> +Limit values can be specified in either decimal
> +or hexadecimal with a "0x" prefix.
> +The special value
> +.B unlimited
> +is case-insensitive.
> +The default limit is 5.
> +A limit of 0 turns off the reloading feature.
> +See NOTES below for further discussion of reloading.
>   .RE
>   .PP
>   .B paranoia
> @@ -128,6 +144,9 @@ in the specified cache for
>   is in seconds.
>   Larger values increase cache hit rates and reduce mean
>   response times, but increase problems with cache coherence.
> +Note that for some name services (including specifically DNS)
> +the TTL returned from the name service is used and
> +this attribute is ignored.
>   .RE
>   .PP
>   .B negative\-time\-to\-live
> @@ -166,6 +185,7 @@ The files are
>   .IR /etc/passwd ,
>   .IR /etc/group ,
>   .IR /etc/hosts ,
> +.IR /etc/resolv.conf ,
>   .IR /etc/services ,
>   and
>   .IR /etc/netgroup .
> @@ -194,6 +214,8 @@ is shared with the clients so
>   that they can directly search in them instead of having to ask the
>   daemon over the socket each time a lookup is performed.
>   The default is no.
> +Note that a cache miss will still result in
> +asking the daemon over the socket.
>   .RE
>   .PP
>   .B max\-db\-size
> @@ -236,6 +258,93 @@ from the source code of
>   and are used if not overridden in the configuration file.
>   The default values used in the configuration file of
>   your distribution might differ.
> +.SS Reloading
> +.BR nscd (8)
> +has a feature called reloading,
> +whose behavior can be surprising.
> +.PP
> +Reloading is enabled when the
> +.B reload-count
> +attribute has a non-zero value.
> +The default value in the source code enables reloading,
> +although your distribution may differ.
> +.PP
> +When reloading is enabled,
> +positive cached entries (the results of successful queries)
> +do not simply expire when their TTL is up.
> +Instead, at the expiry time,
> +.B nscd
> +will "reload",
> +i.e.,
> +re-issue to the name service the same query that created the cached entry,
> +to get a new value to cache.
> +Depending on
> +.I /etc/nsswitch.conf
> +this may mean that a DNS, LDAP, or NIS request is made.
> +If the new query is successful,
> +reloading will repeat when the new value would expire,
> +until
> +.B reload-count
> +reloads have happened for the entry,
> +and only then will it actually be removed from the cache.
> +A request from a client which hits the entry will
> +reset the reload counter on the entry.
> +Purging the cache using
> +.I nscd\~-i
> +overrides the reload logic and removes the entry.
> +.PP
> +Reloading has the effect of extending cache entry TTLs
> +without compromising on cache coherency,
> +at the cost of additional load on the backing name service.
> +Whether this is a good idea on your system depends on
> +details of your applications' behavior,
> +your name service,
> +and the effective TTL values of your cache entries.
> +Note that for some name services
> +(for example, DNS),
> +the effective TTL is the value returned from the name service and
> +.I not
> +the value of the
> +.B positive\-time\-to\-live
> +attribute.
> +.PP
> +Please consider the following advice carefully:
> +.IP \(bu
> +If your application will make a second request for the same name,
> +after more than 1 TTL but before
> +.B reload\-count
> +TTLs,
> +and is sensitive to the latency of a cache miss,
> +then reloading may be a good idea for you.
> +.IP \(bu
> +If your name service is configured to return very short TTLs,
> +and your applications only make requests rarely under normal circumstances,
> +then reloading may result in additional load on your backing name service
> +without any benefit to applications,
> +which is probably a bad idea for you.
> +.IP \(bu
> +If your name service capacity is limited,
> +reloading may have the surprising effect of
> +increasing load on your name service instead of reducing it,
> +and may be a bad idea for you.
> +.IP \(bu
> +Setting
> +.B reload\-count
> +to
> +.B unlimited
> +is almost never a good idea,
> +as it will result in a cache that never expires entries
> +and puts never-ending additional load on the backing name service.
> +.PP
> +Some distributions have an init script for
> +.BR nscd (8)
> +with a
> +.I reload
> +command which uses
> +.I nscd\~-i
> +to purge the cache.
> +That use of the word "reload" is entirely different
> +from the "reloading" described here.
>   .SH SEE ALSO
>   .BR nscd (8)
>   .\" .SH AUTHOR
>


--
Alejandro Colomar
Linux man-pages comaintainer; https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.kernel.org%2Fdoc%2Fman-pages%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7Cb8f528d64f7e490dcafb08d974a6fa5b%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637669083359530986%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&amp;sdata=6oUYiR6loBLnfYJG553wTkr72LjCbGpqRyW%2BzzLadSc%3D&amp;reserved=0
https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.alejandro-colomar.es%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7Cb8f528d64f7e490dcafb08d974a6fa5b%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637669083359530986%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&amp;sdata=%2B1HsWcU4Fjvnqx6Wlw7C%2BYVxdYtWj9KLeg39PhtPHms%3D&amp;reserved=0