man/man5/nscd.conf.5

   1 .\" Copyright (c) 1999, 2000 SuSE GmbH Nuernberg, Germany
   2 .\" Author: Thorsten Kukuk <kukuk@suse.de>
   3 .\" Updates: Greg Banks <gbanks@linkedin.com> Copyright (c) 2021 Microsoft Corp.
   4 .\"
   5 .\" SPDX-License-Identifier: GPL-2.0-or-later
   6 .\"
   7 .TH nscd.conf 5 (date) "Linux man-pages (unreleased)"
   8 .SH NAME
   9 nscd.conf \- name service cache daemon configuration file
  10 .SH DESCRIPTION
  11 The file
  12 .I /etc/nscd.conf
  13 is read from
  14 .BR nscd (8)
  15 at startup.
  16 Each line specifies either an attribute and a value, or an
  17 attribute, service, and a value.
  18 Fields are separated either by SPACE
  19 or TAB characters.
  20 A \[aq]#\[aq] (number sign) indicates the beginning of a
  21 comment; following characters, up to the end of the line,
  22 are not interpreted by nscd.
  23 .P
  24 Valid services are \fIpasswd\fP, \fIgroup\fP, \fIhosts\fP, \fIservices\fP,
  25 or \fInetgroup\fP.
  26 .P
  27 .B logfile
  28 .I debug-file-name
  29 .RS
  30 Specifies name of the file to which debug info should be written.
  31 .RE
  32 .P
  33 .B debug\-level
  34 .I value
  35 .RS
  36 Sets the desired debug level.
  37 0 hides debug info.
  38 1 shows general debug info.
  39 2 additionally shows data in cache dumps.
  40 3 (and above) shows all debug info.
  41 The default is 0.
  42 .RE
  43 .P
  44 .B threads
  45 .I number
  46 .RS
  47 This is the initial number of threads that are started to wait for
  48 requests.
  49 At least five threads will always be created.
  50 The number of threads may increase dynamically up to
  51 .B max\-threads
  52 in response to demand from clients,
  53 but never decreases.
  54 .RE
  55 .P
  56 .B max\-threads
  57 .I number
  58 .RS
  59 Specifies the maximum number of threads.
  60 The default is 32.
  61 .RE
  62 .P
  63 .B server\-user
  64 .I user
  65 .RS
  66 If this option is set, nscd will run as this user and not as root.
  67 If a separate cache for every user is used (\-S parameter), this
  68 option is ignored.
  69 .RE
  70 .P
  71 .B stat\-user
  72 .I user
  73 .RS
  74 Specifies the user who is allowed to request statistics.
  75 .RE
  76 .P
  77 .B reload\-count
  78 unlimited |
  79 .I number
  80 .RS
  81 Sets a limit on the number of times a cached entry
  82 gets reloaded without being used
  83 before it gets removed.
  84 The limit can take values ranging from 0 to 254;
  85 values 255 or higher behave the same as
  86 .BR unlimited .
  87 Limit values can be specified in either decimal
  88 or hexadecimal with a "0x" prefix.
  89 The special value
  90 .B unlimited
  91 is case-insensitive.
  92 The default limit is 5.
  93 A limit of 0 turns off the reloading feature.
  94 See NOTES below for further discussion of reloading.
  95 .RE
  96 .P
  97 .B paranoia
  98 .I <yes|no>
  99 .RS
 100 Enabling paranoia mode causes nscd to restart itself periodically.
 101 The default is no.
 102 .RE
 103 .P
 104 .B restart\-interval
 105 .I time
 106 .RS
 107 Sets the restart interval to
 108 .I time
 109 seconds
 110 if periodic restart is enabled by enabling
 111 .B paranoia
 112 mode.
 113 The default is 3600.
 114 .RE
 115 .P
 116 .B enable\-cache
 117 .I service
 118 .I <yes|no>
 119 .RS
 120 Enables or disables the specified
 121 .I service
 122 cache.
 123 The default is no.
 124 .RE
 125 .P
 126 .B positive\-time\-to\-live
 127 .I service
 128 .I value
 129 .RS
 130 Sets the TTL (time-to-live) for positive entries (successful queries)
 131 in the specified cache for
 132 .IR service .
 133 .I Value
 134 is in seconds.
 135 Larger values increase cache hit rates and reduce mean
 136 response times, but increase problems with cache coherence.
 137 Note that for some name services (including specifically DNS)
 138 the TTL returned from the name service is used and
 139 this attribute is ignored.
 140 .RE
 141 .P
 142 .B negative\-time\-to\-live
 143 .I service
 144 .I value
 145 .RS
 146 Sets the TTL (time-to-live) for negative entries (unsuccessful queries)
 147 in the specified cache for
 148 .IR service .
 149 .I Value
 150 is in seconds.
 151 Can result in significant performance improvements if there
 152 are several files owned by UIDs (user IDs) not in system databases (for
 153 example untarring the Linux kernel sources as root); should be kept small
 154 to reduce cache coherency problems.
 155 .RE
 156 .P
 157 .B suggested\-size
 158 .I service
 159 .I value
 160 .RS
 161 This is the internal hash table size,
 162 .I value
 163 should remain a prime number for optimum efficiency.
 164 The default is 211.
 165 .RE
 166 .P
 167 .B check\-files
 168 .I service
 169 .I <yes|no>
 170 .RS
 171 Enables or disables checking the file belonging to the specified
 172 .I service
 173 for changes.
 174 The files are
 175 .IR /etc/passwd ,
 176 .IR /etc/group ,
 177 .IR /etc/hosts ,
 178 .IR /etc/resolv.conf ,
 179 .IR /etc/services ,
 180 and
 181 .IR /etc/netgroup .
 182 The default is yes.
 183 .RE
 184 .P
 185 .B persistent
 186 .I service
 187 .I <yes|no>
 188 .RS
 189 Keep the content of the cache for
 190 .I service
 191 over server restarts; useful when
 192 .B paranoia
 193 mode is set.
 194 The default is no.
 195 .RE
 196 .P
 197 .B shared
 198 .I service
 199 .I <yes|no>
 200 .RS
 201 The memory mapping of the nscd databases for
 202 .I service
 203 is shared with the clients so
 204 that they can directly search in them instead of having to ask the
 205 daemon over the socket each time a lookup is performed.
 206 The default is no.
 207 Note that a cache miss will still result in
 208 asking the daemon over the socket.
 209 .RE
 210 .P
 211 .B max\-db\-size
 212 .I service
 213 .I bytes
 214 .RS
 215 The maximum allowable size, in bytes, of the database files for the
 216 .IR service .
 217 The default is 33554432.
 218 .RE
 219 .P
 220 .B auto\-propagate
 221 .I service
 222 .I <yes|no>
 223 .RS
 224 When set to
 225 .I no
 226 for
 227 .I passwd
 228 or
 229 .I group
 230 service, then the
 231 .I .byname
 232 requests are not added to
 233 .I passwd.byuid
 234 or
 235 .I group.bygid
 236 cache.
 237 This can help with tables containing multiple records for the same ID.
 238 The default is yes.
 239 This option is valid only for services
 240 .I passwd
 241 and
 242 .IR group .
 243 .RE
 244 .SH NOTES
 245 The default values stated in this manual page originate
 246 from the source code of
 247 .BR nscd (8)
 248 and are used if not overridden in the configuration file.
 249 The default values used in the configuration file of
 250 your distribution might differ.
 251 .SS Reloading
 252 .BR nscd (8)
 253 has a feature called reloading,
 254 whose behavior can be surprising.
 255 .P
 256 Reloading is enabled when the
 257 .B reload-count
 258 attribute has a non-zero value.
 259 The default value in the source code enables reloading,
 260 although your distribution may differ.
 261 .P
 262 When reloading is enabled,
 263 positive cached entries (the results of successful queries)
 264 do not simply expire when their TTL is up.
 265 Instead, at the expiry time,
 266 .B nscd
 267 will "reload",
 268 i.e.,
 269 re-issue to the name service the same query that created the cached entry,
 270 to get a new value to cache.
 271 Depending on
 272 .I /etc/nsswitch.conf
 273 this may mean that a DNS, LDAP, or NIS request is made.
 274 If the new query is successful,
 275 reloading will repeat when the new value would expire,
 276 until
 277 .B reload-count
 278 reloads have happened for the entry,
 279 and only then will it actually be removed from the cache.
 280 A request from a client which hits the entry will
 281 reset the reload counter on the entry.
 282 Purging the cache using
 283 .I nscd\~-i
 284 overrides the reload logic and removes the entry.
 285 .P
 286 Reloading has the effect of extending cache entry TTLs
 287 without compromising on cache coherency,
 288 at the cost of additional load on the backing name service.
 289 Whether this is a good idea on your system depends on
 290 details of your applications' behavior,
 291 your name service,
 292 and the effective TTL values of your cache entries.
 293 Note that for some name services
 294 (for example, DNS),
 295 the effective TTL is the value returned from the name service and
 296 .I not
 297 the value of the
 298 .B positive\-time\-to\-live
 299 attribute.
 300 .P
 301 Please consider the following advice carefully:
 302 .IP \[bu] 3
 303 If your application will make a second request for the same name,
 304 after more than 1 TTL but before
 305 .B reload\-count
 306 TTLs,
 307 and is sensitive to the latency of a cache miss,
 308 then reloading may be a good idea for you.
 309 .IP \[bu]
 310 If your name service is configured to return very short TTLs,
 311 and your applications only make requests rarely under normal circumstances,
 312 then reloading may result in additional load on your backing name service
 313 without any benefit to applications,
 314 which is probably a bad idea for you.
 315 .IP \[bu]
 316 If your name service capacity is limited,
 317 reloading may have the surprising effect of
 318 increasing load on your name service instead of reducing it,
 319 and may be a bad idea for you.
 320 .IP \[bu]
 321 Setting
 322 .B reload\-count
 323 to
 324 .B unlimited
 325 is almost never a good idea,
 326 as it will result in a cache that never expires entries
 327 and puts never-ending additional load on the backing name service.
 328 .P
 329 Some distributions have an init script for
 330 .BR nscd (8)
 331 with a
 332 .I reload
 333 command which uses
 334 .I nscd\~-i
 335 to purge the cache.
 336 That use of the word "reload" is entirely different
 337 from the "reloading" described here.
 338 .SH SEE ALSO
 339 .BR nscd (8)
 340 .\" .SH AUTHOR
 341 .\" .B nscd
 342 .\" was written by Thorsten Kukuk and Ulrich Drepper.