1 files changed, 342 insertions, 0 deletions
diff --git a/man/man5/nscd.conf.5 b/man/man5/nscd.conf.5
new file mode 100644
index 000000000..f5c8a3940
--- /dev/null
+++ b/man/man5/nscd.conf.5
@@ -0,0 +1,342 @@
+.\" 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.
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.TH nscd.conf 5 (date) "Linux man-pages (unreleased)"
+.SH NAME
+nscd.conf \- name service cache daemon configuration file
+.SH DESCRIPTION
+The file
+.I /etc/nscd.conf
+is read from
+.BR nscd (8)
+at startup.
+Each line specifies either an attribute and a value, or an
+attribute, service, and a value.
+Fields are separated either by SPACE
+or TAB characters.
+A \[aq]#\[aq] (number sign) indicates the beginning of a
+comment; following characters, up to the end of the line,
+are not interpreted by nscd.
+.P
+Valid services are \fIpasswd\fP, \fIgroup\fP, \fIhosts\fP, \fIservices\fP,
+or \fInetgroup\fP.
+.P
+.B logfile
+.I debug-file-name
+.RS
+Specifies name of the file to which debug info should be written.
+.RE
+.P
+.B debug\-level
+.I value
+.RS
+Sets the desired debug level.
+0 hides debug info.
+1 shows general debug info.
+2 additionally shows data in cache dumps.
+3 (and above) shows all debug info.
+The default is 0.
+.RE
+.P
+.B threads
+.I number
+.RS
+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
+.P
+.B max\-threads
+.I number
+.RS
+Specifies the maximum number of threads.
+The default is 32.
+.RE
+.P
+.B server\-user
+.I user
+.RS
+If this option is set, nscd will run as this user and not as root.
+If a separate cache for every user is used (\-S parameter), this
+option is ignored.
+.RE
+.P
+.B stat\-user
+.I user
+.RS
+Specifies the user who is allowed to request statistics.
+.RE
+.P
+.B reload\-count
+unlimited |
+.I number
+.RS
+Sets a limit on the number of times a cached entry
+gets reloaded without being used
+before it gets removed.
+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
+.P
+.B paranoia
+.I <yes|no>
+.RS
+Enabling paranoia mode causes nscd to restart itself periodically.
+The default is no.
+.RE
+.P
+.B restart\-interval
+.I time
+.RS
+Sets the restart interval to
+.I time
+seconds
+if periodic restart is enabled by enabling
+.B paranoia
+mode.
+The default is 3600.
+.RE
+.P
+.B enable\-cache
+.I service
+.I <yes|no>
+.RS
+Enables or disables the specified
+.I service
+cache.
+The default is no.
+.RE
+.P
+.B positive\-time\-to\-live
+.I service
+.I value
+.RS
+Sets the TTL (time-to-live) for positive entries (successful queries)
+in the specified cache for
+.IR service .
+.I Value
+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
+.P
+.B negative\-time\-to\-live
+.I service
+.I value
+.RS
+Sets the TTL (time-to-live) for negative entries (unsuccessful queries)
+in the specified cache for
+.IR service .
+.I Value
+is in seconds.
+Can result in significant performance improvements if there
+are several files owned by UIDs (user IDs) not in system databases (for
+example untarring the Linux kernel sources as root); should be kept small
+to reduce cache coherency problems.
+.RE
+.P
+.B suggested\-size
+.I service
+.I value
+.RS
+This is the internal hash table size,
+.I value
+should remain a prime number for optimum efficiency.
+The default is 211.
+.RE
+.P
+.B check\-files
+.I service
+.I <yes|no>
+.RS
+Enables or disables checking the file belonging to the specified
+.I service
+for changes.
+The files are
+.IR /etc/passwd ,
+.IR /etc/group ,
+.IR /etc/hosts ,
+.IR /etc/resolv.conf ,
+.IR /etc/services ,
+and
+.IR /etc/netgroup .
+The default is yes.
+.RE
+.P
+.B persistent
+.I service
+.I <yes|no>
+.RS
+Keep the content of the cache for
+.I service
+over server restarts; useful when
+.B paranoia
+mode is set.
+The default is no.
+.RE
+.P
+.B shared
+.I service
+.I <yes|no>
+.RS
+The memory mapping of the nscd databases for
+.I service
+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
+.P
+.B max\-db\-size
+.I service
+.I bytes
+.RS
+The maximum allowable size, in bytes, of the database files for the
+.IR service .
+The default is 33554432.
+.RE
+.P
+.B auto\-propagate
+.I service
+.I <yes|no>
+.RS
+When set to
+.I no
+for
+.I passwd
+or
+.I group
+service, then the
+.I .byname
+requests are not added to
+.I passwd.byuid
+or
+.I group.bygid
+cache.
+This can help with tables containing multiple records for the same ID.
+The default is yes.
+This option is valid only for services
+.I passwd
+and
+.IR group .
+.RE
+.SH NOTES
+The default values stated in this manual page originate
+from the source code of
+.BR nscd (8)
+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.
+.P
+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.
+.P
+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.
+.P
+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.
+.P
+Please consider the following advice carefully:
+.IP \[bu] 3
+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.
+.P
+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
+.\" .B nscd
+.\" was written by Thorsten Kukuk and Ulrich Drepper.