FreeBSD NSS Operations: Trace getent Lookup Order Before Blaming DNS

FreeBSD applications often obtain host names, user records, groups, services, and other administrative data through the C library’s name-service switch. /etc/nsswitch.conf controls the source order for those database lookups. It is therefore possible for a program using the system lookup APIs to return a different answer from a DNS-specific diagnostic utility: the program may consult local files, a cache, NIS, or DNS in an order selected by NSS.

The distinction prevents a common troubleshooting mistake. A successful drill or host request proves that a DNS server answered that query; it does not prove that the application uses DNS first, reads the same search policy, or sees the same cached result. Conversely, getent hosts exercises the configured hosts database lookup path, but it does not prove that every application uses that API or has reloaded its resolver state.

Capture the lookup environment

Record the release, configuration file, and relevant resolver settings before editing:

freebsd-version -kru
cat /etc/nsswitch.conf
cat /etc/resolv.conf
grep -n '192.0.2.80' /etc/hosts

Use a real hostname or user database entry in place of the documentation-only address. Protect outputs if they include internal host names, account records, or search domains. Check file permissions and configuration management history before assuming a recent edit is the active file.

The NSS dispatcher reads a database-specific ordered list of sources. The hosts database concerns host name and address lookups; passwd and group are separate databases. A failure to resolve a host name and a failure to find a user are not necessarily related. Test each database explicitly rather than treating “name service” as one global switch.

Use getent to exercise the configured path

Use getent(1) to query a database through the lookup order described by nsswitch.conf:

getent hosts app01.example.invalid
getent passwd serviceuser
getent group operators
getent services https

getent returns entries in the traditional database format and is valuable because it asks libc to use the configured source order. A successful result tells you which record the lookup returned, but may not identify which source supplied it. If source attribution matters, inspect the file, cache, or NIS service separately and use controlled logging or a test host; do not infer source merely from the answer’s shape.

Compare the NSS result with a direct DNS query only as a layer-specific test:

getent hosts app01.example.invalid
drill app01.example.invalid

If getent returns an /etc/hosts mapping while drill returns a different DNS address, the tools may both be behaving correctly. Determine whether local override precedence is intended. If getent fails but drill succeeds, inspect the hosts source list, source actions, service health, and actual application API. Do not rewrite a DNS zone to compensate for a deliberate local override.

For applications, reproduce with a small command that uses the same host lookup mechanism if possible. getent is an effective test of the libc database dispatcher, but an application can use a resolver library directly, cache its own answer, or set process-specific environment. Check service documentation and configuration before assigning every discrepancy to NSS.

Understand sources and action criteria

An entry in nsswitch.conf has a database name followed by an ordered list of sources. A source can include actions for lookup statuses such as success, notfound, tryagain, and unavail; actions are continue or return. The documented default is to return on success and continue on other statuses. That distinction matters: “the record is not present here” can mean “try the next source” or “this source is authoritative; stop.”

For example, the manual demonstrates a policy similar to:

hosts: files cache dns
passwd: nis [notfound=return] files
group: nis [notfound=return] files

This is an illustration of syntax, not a recommended universal configuration. With passwd: nis [notfound=return] files, an absent record in NIS stops lookup before local files, while an unavailable NIS source can follow a different action. That might be an intentional authoritative directory policy or an outage-amplifying misconfiguration. Confirm the semantics against the installed nsswitch.conf(5) page before changing a production order.

The cache source has a dependency: the manual says it requires nscd(8) to be running and configured for that database. Adding cache without a working cache daemon does not create a cache server. Conversely, stale cached answers can make a corrected source look unchanged until cache state or the consumer process is refreshed. Check the daemon and its database policy instead of repeatedly editing hosts or DNS.

The historical compat source has special semantics for password and group information. The manual says it must appear alone for a given database to retain its compatibility behavior. Do not combine it casually with files or nis based on examples from another operating system; inspect FreeBSD syntax and migration requirements for the actual version.

Diagnose hosts lookups from the bottom up

For a hostname mismatch, inspect the local hosts file first if files appears before dns. Then verify the configured resolver and query the expected DNS server. Check the hostname’s trailing dot and search-domain behavior when comparing fully qualified names with short names. A resolver utility may apply search lists differently from a specific application call.

Review the hosts line and its status criteria. An earlier files result can shadow DNS. A cache source can return stale data. A notfound=return action can prevent a later source from being consulted. An unavailable NIS or cache service can either stop or continue depending on the configured action. Diagnose which status occurred instead of simplifying every failure to “DNS is down.”

The resolver file /etc/resolv.conf supplies resolver configuration such as nameserver addresses and search domains, but it does not replace nsswitch.conf. Local DNS service configuration is another layer: local-unbound can provide a recursive resolver while NSS still controls whether the application queries that resolver after checking files or cache.

Diagnose users, groups, and services separately

For a service that cannot resolve a user or group, test the corresponding databases:

getent passwd serviceuser
getent group appgroup
id serviceuser

getent exercises the configured database order. id shows the effective account and group view for that invocation, but a long-running daemon may have cached credentials or require restart to reload external directory state. NSS enumeration functions also have limitations when sources are distributed; the manual cautions that entries may be incomplete or duplicated when multiple sources are queried.

For a port-name mismatch, test services separately from hosts:

getent services https

Applications may use a numeric port directly or consult the services database. A stale /etc/services record does not change a port the server binds if the program has a numeric configuration, and a successful service-name lookup does not prove a listener exists. Correlate configuration, sockstat, and an end-to-end connection test.

Apply changes with process-aware validation

Before changing /etc/nsswitch.conf, save the current file, inspect it for duplicate database lines, and agree on the intended order and failure policy. Make one database change at a time. Confirm syntax with getent calls for a positive case, a known absent key, and an unavailable-source case in a test environment. A lookup policy that succeeds while every service is healthy may fail open or fail closed when a source is down.

The manual notes that each program parses nsswitch.conf only once; subsequent changes do not apply until the program is restarted. Restart only the consumer that needs to reload its policy, following its service procedure. Caches such as nscd can introduce another freshness interval. A shell command run after the edit may see the new file while a long-lived daemon still uses the old configuration.

Keep a rollback copy and an out-of-band access path when modifying host lookup policy. A bad passwd or group order can affect administrative logins and service accounts, while a bad hosts order can break remote management. Do not test a risky directory-service action on the only active root session.

Acceptance criteria

A lookup incident is resolved when the relevant database is named, its source order and actions are understood, getent produces the intended record, a direct resolver test is interpreted only as DNS evidence, and the actual application has reloaded applicable configuration. Record source health, cache state, and the exact key used in the test.

NSS is a policy dispatcher, not a DNS proxy. A clear diagnosis keeps the database, source, result status, and consumer separate. That precision avoids unnecessary resolver changes and makes a future source outage easier to explain.

Related:

Sources: