Technotes for future me


How to use nsswitch.conf to find Linux system information

TLDR at the bottom

nsswitch.conf: Which service to look at first

Name resolving can be done with several techniques. The /etc/nsswitch.conf (name service switch configuration) file specifies the methods to use and the order in which to use them when looking for a certain type of information. You can also specify what action the system takes based on whether a method works or fails.

Each line in nsswitch.conf specifies how to search for a piece of information, such as a user’s password. A line in nsswitch.conf has the following format:

info: method [[action]] [method [[action]]]


hosts: files dns mdns4_minimal [NOTFOUND=return] resolve [!UNAVAIL=return] myhostname

info is the type of information that the line describes, method is the method used to find the information, and action is the response to the return status of the preceding method. The action is enclosed within square brackets.

How nsswitch.conf works

When called upon to supply information that nsswitch.conf describes, the system examines the line with the appropriate info field. It uses the methods specified on the line starting with the method on the left. By default, when it finds the desired information, the system stops searching. Without an action specification, when a method fails to return a result, the system tries the next method. It is possible for the search to end without finding the requested information.


The nsswitch.conf file commonly controls searches for users (in passwd), passwords (in shadow), host IP addresses, and group information. The following list describes most of the types of information (info in the format discussed earlier) that nsswitch.conf controls searches for:

  • automount Automount (/etc/auto.master and /etc/auto.misc)
  • bootparams Diskless and other booting options (See the bootparam man page.)
  • ethers MAC address
  • group Groups of users (/etc/group)
  • hosts System information (/etc/hosts)
  • netgroup Netgroup information (/etc/netgroup)
  • networks Network information (/etc/networks)
  • passwd User information (/etc/passwd)
  • protocols Protocol information (/etc/protocols)
  • publickey Used for NFS running in secure mode
  • rpc RPC names and numbers (/etc/rpc)
  • services Services information (/etc/services)
  • shadow Shadow password information (/etc/shadow)


Following is a list of the types of information that nsswitch.conf controls searches for (method). For each type of information, you can specify one or more of the following methods:

  • files Searches local files such as /etc/passwd and /etc/hosts
  • nis Searches the NIS database; yp is an alias for nis
  • dns Queries the DNS (hosts queries only)
  • compat ± syntax in passwd, group, and shadow files

Search order

The information provided by two or more methods may overlap: For example, files and nis may each provide password information for the same user. With overlapping information, you need to consider which method you want to be authoritative (take precedence) and then put that method at the left of the list of methods.

The default nsswitch.conf file lists methods without actions, assuming no overlap (which is normal). In this case, the order is not critical: When one method fails, the system goes to the next one; all that is lost is a little time. Order becomes critical when you use actions between methods or when overlapping entries differ.

The first of the following lines from nsswitch.conf causes the system to search for password information in /etc/passwd and, if that fails, to use NIS to find the information. If the user you are looking for is listed in both places, the information in the local file would be used—it would be authoritative. The second line uses NIS; if that fails, it searches /etc/hosts; if that fails, it checks with DNS to find host information.

passwd files nis

hosts nis files dns

Action items

Each method can optionally be followed by an action item that specifies what to do if the method succeeds or fails for any of a number of reasons. An action item has the following format:


where the opening and closing square brackets are part of the format and do not indicate that the contents are optional; STATUS (by convention uppercase although it is not case sensitive) is the status being tested for; and action is the action to be taken if STATUS matches the status returned by the preceding method. The leading exclamation point (!) is optional and negates the status.

STATUS may have the following values:

  • NOTFOUND The method worked but the value being searched for was not found. Default action is * continue.
  • SUCCESS The method worked and the value being searched for was found; no error was returned. * Default action is return.
  • UNAVAIL The method failed because it is permanently unavailable. For example, the required * file may not be accessible or the required server may be down. Default action is continue.
  • TRYAGAIN The method failed because it was temporarily unavailable. For example, a file may be * locked or a server overloaded. Default action is continue.

Values for action are as follows:

  • return Returns to the calling routine with or without a value.
  • continue Continues with the next method. Any returned value is overwritten by a value found by the next method.

Example: The following line from nsswitch.conf causes the system first to use DNS to search for the IP address of a given host. The action item following the DNS method tests whether the status returned by the method is not (!) UNAVAIL.

hosts dns [!UNAVAIL=return] files

The system takes the action associated with the STATUS (return) if the DNS method does not return UNAVAIL (!UNAVAIL)—that is, if DNS returns SUCCESS, NOTFOUND, or TRYAGAIN. As a consequence, the following method (files) is used only when the DNS server is unavailable: If the DNS server is not unavailable (read the two negatives as “is available”), the search returns the domain name or reports that the domain name was not found. The search uses the files method (check the local /etc/hosts file) only if the server is not available.

compat Method: ± in passwd, group, and shadow Files

You can put special codes in the /etc/passwd, /etc/group, and /etc/shadow files that cause the system, when you specify the compat method in nsswitch.conf, to combine and modify entries in the local files and the NIS maps. That is, a plus sign (+) at the beginning of a line in one of these files adds NIS information; a minus sign () removes information.

For example, to use these codes in the passwd file, specify passwd: compat in nsswitch. conf. The system then goes through the passwd file in order, adding or removing the appropriate NIS entries when it reaches each line that starts with a + or .

Although you can put a plus sign at the end of the passwd file, specify passwd: compat in nsswitch.conf to search the local passwd file, and then go through the NIS map, it is more efficient to put passwd: file nis in nsswitch.conf and not modify the passwd file.



#hosts:          files dns mdns4_minimal [NOTFOUND=return] resolve [!UNAVAIL=return]  myhostname
hosts:          files dns
  1. The files module searches /etc/hosts, then returns “not found”.
  2. Processing continues to the next module.
  3. The mdns4_minimal module searches the local LAN subnet using Multicast DNS (mDNS), then returns “not found”.
  4. [NOTFOUND=return] indicates that processing should not continue after this error; i.e. “not found” should be immediately returned to the program.

Why the extra [NOTFOUND=return]? According to various sources, it’s there to speed up unsuccessful queries and to prevent information leakage, and to reduce load on public DNS servers.

Let’s say someone’s network actually used mDNS (which is common on Linux/macOS). If the user tried to resolve “MyLittleLaptop.local” and it wasn’t found, the system would keep trying the next module (dns), and the query would be sent to the public DNS (e.g. to the school’s DNS servers, or to the coffee shop’s router).

But – according to the reservation by IETF – *.local names cannot possibly exist in public DNS, so such a query would be useless, all it does is reveal your personal information to the network admin. So the [NOTFOUND=return] tag is added to stop it from reaching DNS completely.


Last updated on 21 Oct 2021
Published on 21 Oct 2021
Edit on GitHub