Debian Codegraph @

upstream/mageia-cauldron/man5/nscd.conf.5

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