nscd.conf(5)

📦
version 6.18 · 10 versions
, in alpine 3.24, nixos 26.05

💅 nscd.conf — the name service cache daemon config file, explained fr

okay so bestie, gather round 🫶 this is the man page for nscd.conf — aka the name service cache daemon configuration file, and it's genuinely not that deep once you get the vibe. let's go ✨

✨ NAME ✨

nscd.conf — the config file for the name service cache daemon, no cap 🌸

🎀 SYNOPSIS 🎀

/etc/nscd.conf

💖 DESCRIPTION 💖

so the file /etc/nscd.conf gets read by nscd(8) at startup, periodt. every line in it is either an attribute + a value, or an attribute + a service + a value. the fields are separated by either SPACE or TAB characters — pick your fighter 💅. and a # (number sign) starts a comment: everything after it, all the way to the end of the line, is not interpreted by nscd. it's giving "the rest is silence" 😌

the valid services are passwd, group, hosts, services, and netgroup. those five, that's the list, memorise it 🦋

🧚 the attributes, one by one (yes, all of them)

  • logfile debug-file-name — specifies the name of the file that debug info should be written to. that's it, that's the whole thing 💜
  • debug-level value — sets how much debug tea gets spilled. 0 hides debug info entirely (mysterious, love that). 1 shows general debug info. 2 additionally shows data in cache dumps. 3 (and above, go off) shows all debug info. the default is 0 🙈
  • threads number — the initial number of threads started to sit around waiting for requests. important: at least five threads will always be created — that's a floor, not a suggestion, bestie. the number of threads may grow dynamically up to max-threads in response to client demand, but it never decreases. literally never. it's committed 🫶
  • max-threads number — the ceiling on thread count. the default is 32 🔥
  • server-user user — if you set this, nscd runs as this user instead of root. caveat time: if a separate cache for every user is being used (the -S parameter), this option is ignored. sorry babe 💀
  • stat-user user — specifies the user who's allowed to request statistics. the stats are for them and only them 👑
  • reload-count unlimited | number — sets a limit on how many times a cached entry gets reloaded without being used before it gets removed. limit can range from 0 to 254; values 255 or higher behave the same as unlimited. you can write limit values in decimal, or in hex with a 0x prefix. the special value unlimited is case-insensitive (so Unlimited slaps too). the default limit is 5. a limit of 0 turns the reloading feature off. also — go read NOTES below, the reloading discussion is required reading fr fr 🌈
  • paranoia <yes|no> — enabling paranoia mode makes nscd restart itself periodically. it's not paranoia if they're literally out to get you, bestie. the default is no 😭
  • restart-interval time — sets the restart interval to time seconds, but only if periodic restart is enabled by enabling paranoia mode. the default is 3600 ⭐
  • enable-cache service <yes|no> — turns the cache for the specified service on or off. the default is no 🙈
  • positive-time-to-live service value — sets the TTL (time-to-live) for positive entries (successful queries) in the specified cache for service. value is in seconds. bigger values mean higher cache hit rates and lower mean response times, but more cache coherence problems — it's a trade-off, everything is 💅. note that for some name services (including specifically DNS) the TTL returned from the name service is used, and this attribute is ignored entirely.
  • negative-time-to-live service value — sets the TTL (time-to-live) for negative entries (unsuccessful queries) in the specified cache for service. value is in seconds. this can give significant performance improvements if you have several files owned by UIDs (user IDs) that aren't in the system databases — for example, untarring the Linux kernel sources as root 😮‍💨 — but it should be kept small to reduce cache coherency problems. small. tiny. keep it lowkey.
  • suggested-size service value — this is the internal hash table size. value should stay a prime number for optimum efficiency like the good little prime it is. the default is 211 🍓
  • check-files service <yes|no> — enables or disables checking whether the file belonging to the specified service has changed. the files in question are /etc/passwd, /etc/group, /etc/hosts, /etc/resolv.conf, /etc/services, and /etc/netgroup. the default is yes ✨
  • persistent service <yes|no> — keeps the content of the cache for service across server restarts. useful when paranoia mode is set. the default is no 🦋
  • shared service <yes|no> — makes the memory mapping of the nscd databases for service shared with the clients, so they can search in them directly instead of asking the daemon over the socket every single time a lookup happens. the default is no. heads up though: a cache miss will still result in asking the daemon over the socket — shared doesn't save you there 🙈
  • max-db-size service bytes — the maximum allowable size, in bytes, of the database files for service. the default is 33554432 🔥
  • auto-propagate service <yes|no> — when set to no for the passwd or group service, the .byname requests are not added to the passwd.byuid or group.bygid cache. this can help with tables containing multiple records for the same ID (messy messy, we've all been there). the default is yes. this option is valid only for the services passwd and group — don't try it anywhere else, it's not for them 💀

🌸 NOTES 🌸

the default values stated in this manual page come from the source code of nscd(8) and get used if you don't override them in the config file. that said, the default values in your distribution's config file might differ — distributions love doing their own thing, iykyk 💜

🌈 Reloading

nscd(8) has a feature called reloading, and its behaviour can be, um, surprising. buckle up bestie ✨

reloading is enabled when the reload-count attribute has a non-zero value. the default value in the source code enables reloading, 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, nscd will "reload" — meaning it re-issues to the name service the exact same query that created the cached entry, to get a new value to cache. depending on /etc/nsswitch.conf, this may mean a DNS, LDAP, or NIS request gets made. if the new query succeeds, reloading repeats when the new value would expire, until reload-count reloads have happened for the entry — and only then does it actually get removed from the cache. a request from a client that hits the entry will reset the reload counter on that entry. and purging the cache using nscd -i overrides the reload logic and removes the entry, no negotiation 😌

so 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 that's a good idea on your system depends on details of your applications' behaviour, your name service, and the effective TTL values of your cache entries. also note: for some name services (DNS, for example), the effective TTL is the value returned from the name service, not the value of the positive-time-to-live attribute 🔥

please consider the following advice carefully, this is the important part:

  • if your application will make a second request for the same name, after more than 1 TTL but before reload-count TTLs, and is sensitive to the latency of a cache miss — then reloading may be a good idea for you 🎀
  • 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 😭
  • 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 💀
  • setting reload-count to unlimited is almost never a good idea, because it results in a cache that never expires entries and puts never-ending additional load on the backing name service. like, just don't 🫶

some distributions have an init script for nscd(8) with a reload command which uses nscd -i to purge the cache. that use of the word "reload" is entirely different from the "reloading" described here — same word, different vibe, don't get it twisted 🙈

🦋 SEE ALSO 🦋

nscd(8)

okay that's the whole page, you ate that bestie 👑 this gem is from Linux man-pages 6.18, dated 2026-02-08 — go forth and cache responsibly 💖✨🎀

📦 where this page comes from