diff mbox series

nscd.conf.5: describe reloading, clarifications, v4

Message ID BL0PR2101MB13169E7F7783D74DE828D83EA1F29@BL0PR2101MB1316.namprd21.prod.outlook.com
State Not Applicable
Headers show
Series nscd.conf.5: describe reloading, clarifications, v4 | expand

Pull-request

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

Checks

Context Check Description
dj/TryBot-apply_patch fail Patch failed to apply to master at the time it was sent
dj/TryBot-32bit fail Patch series failed to apply

Commit Message

Greg Banks Aug. 5, 2021, 10:10 p.m. UTC
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.v4

for you to fetch changes up to 2cb4e042b6aee518f1673d8897fd06056bd87767:

  nscd.conf.5: describe reloading, clarifications, v4 (2021-08-05 15:07:20 -0700)

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

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

Comments

Alejandro Colomar Aug. 6, 2021, 11:11 a.m. UTC | #1
Hi Greg,

On 8/6/21 12:10 AM, 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.v4
> 
> for you to fetch changes up to 2cb4e042b6aee518f1673d8897fd06056bd87767:
> 
>    nscd.conf.5: describe reloading, clarifications, v4 (2021-08-05 15:07:20 -0700)

Thanks for the research and the patch!

Please see some comments below.

Thanks,

Alex

> 
> ----------------------------------------------------------------
> Greg Banks (1):
>        nscd.conf.5: describe reloading, clarifications, v4
> 
>   man5/nscd.conf.5 | 112 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
>   1 file changed, 109 insertions(+), 3 deletions(-)
> 
> diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5
> index 7356bf7c2..9635922fd 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,12 @@ 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 +87,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.

Only decimal or hexadecimal?

 From what you say above that values greater than 255 behave 
equivalently to 255, and also this, I suspect this is being parsed with 
strtoul(), and they also accept octal with 0... notation.

Also, I guess this behavior is common to all numeric values, so maybe 
it's a better idea to put it in a common paragraph (if you know for sure 
that this is the case).

> +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.

Apart from the comment above, I applied some minor formatting fixes to 
your text (see below; whitespace, punctuation, and a typo); could you 
include them in your next revision?

Thanks,

Alex


diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5
index 9635922fd..7534b77e6 100644
--- a/man5/nscd.conf.5
+++ b/man5/nscd.conf.5
@@ -59,7 +59,8 @@ 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.
+in response to demand from clients,
+but never decreases.
  .RE
  .PP
  .B max\-threads
@@ -259,7 +260,8 @@ 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.
+has a feature called reloading,
+whose behavior can be surprising.
  .PP
  Reloading is enabled when the
  .B reload-count
@@ -270,10 +272,11 @@ although your distribution may differ.
  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
+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,
+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
@@ -284,20 +287,20 @@ 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.
+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,
+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
@@ -308,7 +311,7 @@ attribute.
  Please consider the following advice carefully:
  .IP \(bu
  If your application will make a second request for the same name,
-after more then 1 TTL but before
+after more than 1 TTL but before
  .B reload\-count
  TTLs,
  and is sensitive to the latency of a cache miss,
@@ -330,8 +333,8 @@ Setting
  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.
+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)
Greg Banks Aug. 6, 2021, 4:39 p.m. UTC | #2
Hi Alejandro,

> +Limit values can be specified in either decimal
> +or hexadecimal with a "0x" prefix.

Only decimal or hexadecimal?

 From what you say above that values greater than 255 behave
equivalently to 255, and also this, I suspect this is being parsed with
strtoul(), and they also accept octal with 0... notation.

Your suspicion is correct, this attribute is parsed with strtoul(base=0) and any value that is accepted by that function can be used here.  That includes octal numbers with a leading 0, numbers with a leading + or -, and trailing junk characters (because the code doesn't check for that case).  Also, any string of characters that are not whitespace will result in a 0 value instead of a syntax error, because the code doesn't check for strtoul()s failure cases properly.

Some of this behavior is useful and should be documented.  Some of it is clearly just poor coding, should be fixed, and should not be documented to give wiggle room for the people fixing the code.  I made a judgement call that hexadecimal values are useful and octal values are not but I'm happy to be corrected.

Also, I guess this behavior is common to all numeric values, so maybe
it's a better idea to put it in a common paragraph (if you know for sure

No, that attribute is parsed differently from all the others, which use atoi() or atol().

Apart from the comment above, I applied some minor formatting fixes to
your text (see below; whitespace, punctuation, and a typo); could you
include them in your next revision?
Included in v5, thanks.  I'll send a new patch.
-after more then 1 TTL but before
+after more than 1 TTL but before

Woops that's embarrassing.

Greg.
diff mbox series

Patch

diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5
index 7356bf7c2..9635922fd 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,12 @@  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 +87,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 +143,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 +184,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 +213,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 +257,91 @@  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 then 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