Name Service Switch

The GNU C Library’s Name Service Switch (NSS) separates an application’s lookup API from the data source that answers it. Code calls getpwnam(3), getgrnam(3), getaddrinfo(3), or getservbyname(3); glibc selects and combines services according to /etc/nsswitch.conf. Consequently, a local file, DNS server, directory service, or system service can provide the same category of information without changing callers.

Database Families #

glibc recognizes databases including passwd, group, shadow, hosts, networks, protocols, services, rpc, ethers, netgroup, aliases, publickey, and initgroups. Each has its own libc interfaces and record shape.

Enumeration interfaces follow the same policy. For example, setpwent, getpwent, and endpwent enumerate the effective passwd database, not necessarily /etc/passwd. Enumeration can therefore contact a directory server and can return a larger or changing set than a local-file reader would.

Use the reentrant interfaces in concurrent code. getpwnam_r and peers receive caller-owned result and character buffers, return an error number, and report absence through a null result pointer rather than treating it as a successful record. The exact result convention is interface-specific; check the relevant manual rather than reducing every failure to errno. Non-reentrant legacy interfaces commonly return pointers to storage that later calls overwrite.

Configuring Search Order #

Every non-comment entry names a database, a colon, and an ordered list of services:

passwd:   files systemd sss
group:    files systemd sss
shadow:   files sss
hosts:    files resolve [!UNAVAIL=return] dns
services: files

files reads the corresponding local database. dns is meaningful for host lookup. resolve and mymachines are systemd-provided host services on installations that ship them. sss, ldap, winbind, and mdns come from separately installed providers. A configured service that is unavailable is part of the operational behavior, not a declaration that its library must exist.

Each service returns one of four NSS statuses:

Bracketed criteria override the default for the preceding service:

hosts: files [NOTFOUND=return] dns

That configuration deliberately makes a negative /etc/hosts lookup final. [!UNAVAIL=return] matches every status except unavail. merge has narrowly defined support: glibc uses [SUCCESS=merge] to merge matching group entries, and it does not apply to arbitrary databases or getgrent enumeration.

Run getent when testing the configured behavior because it uses NSS rather than reading a local file directly:

getent passwd root
getent hosts example.com
getent services https

Module Boundary #

For a service named SERVICE, traditional glibc NSS modules are shared objects named libnss_SERVICE.so.2, loaded through the dynamic loader when a configured database needs them. A module exports database- and operation-specific symbols such as _nss_files_getpwnam_r; it returns an internal NSS status, while glibc applies nsswitch.conf actions.

The module ABI is deliberately lower level than the public lookup API. A reentrant lookup entry point must fill caller-provided objects and buffers, distinguish not-found from an unavailable backend, and set error outputs as that database contract requires. Module authors must match the glibc NSS interface for the target release and architecture; exporting a similarly named public libc function does not create an NSS backend.

NSS is not a universal configuration language. glibc ignores database names it does not implement, while applications may define and parse their own names; sudoers and subid are examples. Therefore, identify both the consumer and its module ABI before modifying a nonstandard entry.

Resolver and Directory-Service Operations #

Host resolution can pass through files, resolve, and dns, while identity resolution can pass through local files, systemd’s dynamic-user service, SSSD, LDAP, or Active Directory adapters. A lookup may thus block on IPC or a network round trip. Service order, negative-result actions, daemon availability, directory timeouts, and caching must be designed together because they affect login latency and failure behavior.

The glibc NSS documentation and nsswitch.conf(5) define the configuration and libc-facing behavior.