Trace Name-Service Lookups with getent

When a user, group or hostname will not resolve, getent shows you what the system itself sees, whatever your application claims. You will ask the Name Service Switch (NSS) for users, groups, hosts and services, then narrow down the problem without editing /etc/nsswitch.conf. The examples use glibc 2.39 and the Linux man-pages 6.7 installed on this machine.

Allow about fifteen minutes. You need a shell and a name-service database to inspect. The normal checks are unprivileged.

1. Check the installed command

Confirm which program runs and which glibc release supplies it:

$ command -v getent
/usr/bin/getent
$ getent --version
getent (Ubuntu GLIBC 2.39-0ubuntu8.9) 2.39

Package text differs between distributions. The fact that matters is the glibc version, because the available databases and options follow the installed implementation. This guide uses the syntax documented in the local getent(1) page, not assumptions about another operating system.

Checkpoint: If command -v getent prints nothing, stop and install the package your distribution supplies. Do not copy a binary from an unrelated host.

2. Look up a user or group

The command shape is getent database key. The key is optional for databases that support enumeration, but a key is usually safer and less noisy. Ask for the local root account and group ID 0:

$ getent passwd root
root:x:0:0:root:/root:/bin/bash
$ getent group 0
root:x:0:

These records come through the passwd and group NSS databases. Depending on the active configuration, the result may include a remote directory service as well as local files.

Tip: An x in a passwd record is not a password you can use. It normally means the password data is stored elsewhere.

Some databases treat numeric and non-numeric keys differently. For passwd, a numeric key is a user ID and a name is a user name. Group IDs and group names follow the same pattern.

3. Check host and service resolution

Use hosts for the host database and services for names such as SSH. Each database has its own output format, so do not parse every result as if it were a passwd record:

$ getent hosts localhost
::1             localhost
$ getent ahostsv4 localhost
127.0.0.1       STREAM localhost.localdomain
127.0.0.1       DGRAM
127.0.0.1       RAW
$ getent services ssh
ssh                   22/tcp

ahostsv4 asks for IPv4 addresses through getaddrinfo, and ahostsv6 does the same for IPv6. Plain hosts uses the hosts database directly. Several lines from ahosts are normal, because the command reports socket types as well as addresses.

Address-family support, local configuration and DNS all affect host results. An empty result does not prove the network is down. First establish whether the name is absent from the configured sources, then test connectivity with a tool built for that.

4. Read the NSS order first

getent follows the sources and actions in /etc/nsswitch.conf. Inspect the active lines as an ordinary user:

$ sed -n '/^[[:space:]]*[^#[:space:]]/p' /etc/nsswitch.conf
passwd:         files systemd
group:          files systemd
shadow:         files systemd
hosts:          files dns mymachines
services:       db files

Your lines will differ. On each line, the first column is the database and the remaining words are the services queried in order. A typical passwd: files systemd line tries local files first, then systemd if the first source does not return a result that stops the search.

Square-bracket actions refine that decision:

Warning: Do not edit this file just to test a theory. It controls lookup order for other programs too, and a typo can break logins, group membership, hostname resolution or service-name lookups.

5. Override a service for one test

To isolate a source, use -s or --service. A single service name overrides all databases for that one invocation:

$ getent -s files passwd root
root:x:0:0:root:/root:/bin/bash

To override only one database, use database:service, database name first:

$ getent -s passwd:files passwd root
root:x:0:0:root:/root:/bin/bash

This does not rewrite /etc/nsswitch.conf, restart a daemon or outlast the command. It is a handy way to separate a local-files problem from a remote NSS service. You can repeat the option, and the last service given for a database wins.

There is no undo step, because these examples change no state. Treat a service override as a diagnostic result, not evidence that the system-wide configuration should change. If a production service depends on the outcome, schedule any later change separately and keep a copy of the original file before editing it.

6. Read failures from the exit status

Do not rely only on whether output appeared. Save the status straight after the command:

$ getent passwd __definitely_missing__
$ status=$?
$ printf 'getent exit status: %s\n' "$status"
getent exit status: 2

The local command uses these meanings:

For example, getent ethers with no key returns status 3, because that database cannot be enumerated. Add a specific MAC address or host key when the database and local NSS service support the lookup. Likewise netgroup needs one key or three matching keys, and cannot be enumerated.

In a script, make the distinction explicit:

if getent passwd "$USER_NAME" >/dev/null; then
    printf '%s\n' 'user found'
else
    status=$?
    case "$status" in
        2) printf '%s\n' 'user not found' >&2 ;;
        *) printf 'lookup failed with status %s\n' "$status" >&2; exit "$status" ;;
    esac
fi

Replace USER_NAME with a value you have validated for your application. Quoting it stops whitespace or shell metacharacters changing the command structure.

7. Keep sensitive databases in view

The shadow database holds password ageing and related account data. Avoid broad enumeration, and do not paste its output into tickets or chat. On some systems a lookup that touches protected files needs elevated privileges:

$ getent shadow root
root:!:19778:0:99999:7:::

Warning: The exact fields and masking depend on the host. Use the least privilege that works. Do not put sudo in front of every diagnostic command, and do not read a permission error as proof that an NSS source is empty.

Enumeration can also be expensive or surprisingly broad when a remote source is configured. Prefer a named key, especially for passwd, group, hosts and netgroup. A successful lookup proves only that this query found an entry. It does not prove that every application uses the same API or configuration.

Done means