System Administration Guide: Naming and Directory Services (FNS and NIS+)

Chapter 1 The Name Service Switch

This chapter describes the name service switch, what it does, and how clients use it to obtain naming information from one or more sources. You use the name service switch to coordinate usage of different naming services. For an overview of the Solaris naming and directory services DNS, NIS and LDAP, see “Naming and Directory Services (Overview)” in System Administration Guide: Naming and Directory Services (DNS, NIS, and LDAP).

About the Name Service Switch

The name service switch is a file named nsswitch.conf. It controls how a client machine or application obtains network information. It is used by client applications that call any of the getXbyY() interfaces such as:

Each machine has a switch file in its /etc directory. Each line of that file identifies a particular type of network information, such as host, password, and group, followed by one or more sources where the client is to look for that information.

A client can obtain naming information from one or more of the switch's sources. For example, an NIS+ client could obtain its hosts information from an NIS+ table and its password information from a local /etc file. In addition, it could specify the conditions under which the switch must use each source (see Table 1–1.

The Solaris operating environment automatically loads an nsswitch.conf file into every machine's /etc directory as part of the installation process. Four alternate (template) versions of the switch file are also loaded into /etc for LDAP, NIS, NIS+, or files. See The nsswitch.conf Template Files.

These four files are alternate default switch files. Each one is designed for a different primary naming service: /etc files, NIS, NIS+, or LDAP. When the Solaris software is first installed on a machine, the installer selects the machine's default naming service: NIS+, NIS, local files, or LDAP. During installation, the corresponding template file is copied to nsswitch.conf. For example, for a machine client using LDAP, the installation process copies nsswitch.ldap to nsswitch.conf. Unless you have an unusual namespace, the default template file as copied to nsswitch.conf should be sufficient for normal operation.

If you later change a machine's primary naming service, you copy the appropriate alternate switch file to nsswitch.conf. (See The nsswitch.conf Template Files.) You can also change the sources of particular types of network information used by the client by editing the appropriate lines of the /etc/nsswitch.conf file. The syntax for doing this is described below, and additional instructions are provided in Modifying the name service switch.

Format of the nsswitch.conf File

The nsswitch.conf file is essentially a list of 16 types of information and the sources that getXXbyYY() routines search for that information. The 16 types of information, not necessarily in this order, are:

The following table provides a description of the kind of sources that can be listed in the switch file for the information types above.

Table 1–1 Switch File Information Sources

Information Sources 

Description 

files

A file stored in the client's /etc directory. For example, /etc/passwd.

nisplus

An NIS+ table. For example, the hosts table.

nis

An NIS map. For example, the hosts map.

compat

Compat can be used for password and group information to support old-style + or - syntax in /etc/passwd, /etc/shadow, and /etc/group files.

dns

Can be used to specify that host information be obtained from DNS. 

ldap

Can be used to specify entries be obtained from the LDAP directory. 

Search Criteria

Single Source. If an information type has only one source, such as nisplus a routine using the switch searches for the information in that source only. If it finds the information, it returns a success status message. If it does not find the information, it stops searching and returns a different status message. What the routine does with the status message varies from routine to routine.

Multiple Sources. If a table has more than one source for a given information type, the switch directs the routine to start searching for the information in the first source that is listed. If it finds the information, it returns a success status message. If it does not find the information in the first source, it tries the next source. The routine will search through all of the sources until it has found the information it needs, or it is halted by encountering a return specification. If all of the listed sources are searched without finding the information, the routine stops searching and returns a non-success status message.

Switch Status Messages

If a routine finds the information, it returns a success status message. If it does not find the information for which it is looking, it returns one of three unsuccessful status messages, depending on the reason for not finding the information. Possible status messages are listed in the following table.

Table 1–2 Switch Search Status Messages

Status Message 

Meaning of Message 

SUCCESS

The requested entry was found in the specified source. 

UNAVAIL

The source is not responding or is unavailable. That is, the NIS+ table, or NIS map, or /etc file could not be found or accessed.

NOTFOUND

The source responded with "No such entry." In other words, the table, map, or file was accessed but it did not contain the needed information. 

TRYAGAIN

The source is busy; it might respond next time. In other words, the table, map, or file was found, but it could not respond to the query. 

Switch Action Options

You can instruct the switch to respond to status messages with either of these two actions shown in the following table.

Table 1–3 Responses to Switch Status Messages

Action 

Meaning 

return

Stop looking for the information. 

continue

Try the next source, if there is one. 

Default Search Criteria

The combination of nsswitch.conf file status message and action option determines what the routine does at each step. This combination of status and action is called the search criteria.

The switch's default search criteria are the same for every source. Described in terms of the status messages listed above, they are:

Because these are the default search criteria, they are assumed. That is, you do not have to explicitly specify them in the switch file. You can change these default search criteria by explicitly specifying some other criteria using the STATUS=action syntax show above. For example, the default action for a NOTFOUND condition is to continue the search to the next source. To specify that for a particular type of information, such as networks, the search is to halt on a NOTFOUND condition, you would edit the networks line of the switch file to read:


networks: nis [NOTFOUND=return] files

The networks: nis [NOTFOUND=return] files line specifies a non-default criterion for the NOTFOUND status. Non-default criteria are delimited by square brackets.

In this example, the search routine behaves as follows:

What if the Syntax is Wrong?

Client library routines contain compiled-in default entries that are used if an entry in the nsswitch.conf file is either missing or syntactically incorrect. These entries are the same as the switch file's defaults.

The name service switch assumes that the spelling of table and source names is correct. If you misspell a table or source name, the switch uses default values.

Auto_home and Auto_master

The switch search criteria for the auto_home and auto_master tables and maps is combined into one category called automount.

Timezone and the Switch File

The timezone table does not use the switch, so it is not included in the switch file's list.

Comments in nsswitch.conf Files

Any nsswitch.conf file line beginning with a comment character (#) is interpreted as a comment line and is ignored by routines that search the file.

When a comment character (#) is included in the middle of the line, characters preceding the comment mark are interpreted by routines that search the nsswitch.conf file. Characters to the right of the comment mark are interpreted as comments and ignored.

Table 1–4 Switch File Comment Examples

Type of Line 

Example 

Comment line (not interpreted). 

# hosts: nisplus [NOTFOUND=return] files 

Fully interpreted line. 

hosts: nisplus [NOTFOUND=return] file 

Partially interpreted line (the files element not interpreted)

hosts: nisplus [NOTFOUND=return] # files 

Keyserver and publickey Entry in the Switch File


Caution – Caution –

You must restart the keyserver after you make a change to nsswitch.conf


The keyserver reads the publickey entry in the name service switch configuration file only when the keyserver is started. As a result, if you change the switch configuration file, the keyserver does not become aware of changes to the publickey entry until it is restarted.

The nsswitch.conf Template Files

Four nsswitch.conf template files are provided with the Solaris operating environment to accommodate different naming services. Each of them provides a different default set of primary and subsequent information sources.

The four template files are:

Copy the template file that most closely meets your requirements to thensswitch.conf configuration file and then modify the file as needed.

For example, to use the LDAP template file, you would type the following command:


mymachine# cp nsswitch.ldap nsswitch.conf

The Default Switch Template Files

Here are the four switch files supplied with Solaris operating environment:


Example 1–1 NIS+ Switch File Template (nsswitch.nisplus)


#
#
# /etc/nsswitch.nisplus:
#
#
# An example file that could be copied over to /etc/nsswitch.conf;
# it uses NIS+ (NIS Version 3) in conjunction with files.
#
# "hosts:" and "services:" in this file are used only if the
# /etc/netconfig file has a "-" for nametoaddr_libs of "inet"
# transports.
 
# the following two lines obviate the "+" entry in /etc/passwd 
# and /etc/group.
passwd: files nisplus
group: files nisplus
# consult /etc "files" only if nisplus is down. 
hosts: nisplus [NOTFOUND=return] files
# Uncomment the following line, and comment out the above, to use 
# both DNS and NIS+. You must also set up the /etc/resolv.conf 
# file for DNS name server lookup. See resolv.conf(4).
# hosts: nisplus dns [NOTFOUND=return] files
services: nisplus [NOTFOUND=return] files
networks: nisplus [NOTFOUND=return] files
protocols: nisplus [NOTFOUND=return] files
rpc: nisplus [NOTFOUND=return] files
ethers: nisplus [NOTFOUND=return] files
netmasks: nisplus [NOTFOUND=return] files	
bootparams: nisplus [NOTFOUND=return] files
publickey: nisplus
netgroup: nisplus
automount: files nisplus
aliases: files nisplus
sendmailvars: files nisplus


Example 1–2 NIS Switch File Template


#
# /etc/nsswitch.nis:
#
# An example file that could be copied over to /etc/nsswitch.conf;
# it uses NIS (YP) in conjunction with files.
#
# "hosts:" and "services:" in this file are used only if the
# /etc/netconfig file has a "-" for nametoaddr_libs of "inet"
# transports.
#
# the following two lines obviate the "+" entry in /etc/passwd
# and /etc/group.
passwd: files nis
group: files nis
# consult /etc "files" only if nis is down. 
hosts: nis [NOTFOUND=return] files
networks: nis [NOTFOUND=return] files
protocols: nis [NOTFOUND=return] files
rpc: nis [NOTFOUND=return] files
ethers: nis [NOTFOUND=return] files
netmasks: nis [NOTFOUND=return] files	
bootparams: nis [NOTFOUND=return] files
publickey: nis [NOTFOUND=return] files
netgroup: nis
automount: files nis
aliases: files nis
# for efficient getservbyname() avoid nis
services: files nis
sendmailvars: files


Example 1–3 Files Switch File Template


#
# /etc/nsswitch.files:
#
# An example file that could be copied over to /etc/nsswitch.conf;
# it does not use any naming service.
#
# "hosts:" and "services:" in this file are used only if the
# /etc/netconfig file has a "-" for nametoaddr_libs of "inet"
# transports.
passwd: files
group: files
hosts: files
networks: files
protocols: files
rpc: files
ethers: files
netmasks: files	
bootparams: files
publickey: files
# At present there isn't a 'files' backend for netgroup;
# the system will figure it out pretty quickly, and will notuse
# netgroups at all.
netgroup: files
automount: files
aliases: files
services: files
sendmailvars: files

The nsswitch.conf File

The default nsswitch.conf file that is installed when you install the Solaris operating environment for the first time is determined by which naming service you select during the Solaris software installation process. Each line of that file identifies a particular type of network information, such as host, password, and group, followed by one or more sources, such as NIS+ tables, NIS maps, the DNS hosts table, or local /etc, where the client is to look for that information. When you chose a naming service, the switch template file for that service is copied to create the new nsswitch.conf file. For example, if you choose NIS+, the nsswitch.nisplus file is copied to create a new nsswitch.conf file.

An /etc/nsswitch.conf file is automatically loaded into every machine's /etc directory by the Solaris 9release software, along with the following alternate (template) versions:

These alternate template files contain the default switch configurations used by the NIS+ and NIS services, local files, and LDAP. When the Solaris operating environment is first installed on a machine, the installer selects the machine's default naming service: NIS+, NIS, local files, or LDAP. During installation, the corresponding template file is copied to /etc/nsswitch.conf. For example, for a machine client using NIS+, the installation process copies nsswitch.nisplus to nsswitch.conf.

Unless you have an unusual namespace, the default template file as copied to nsswitch.confshould be sufficient for normal operation.

Selecting a Different Configuration File

When you change a machine's naming service, you need to modify that machine's switch file accordingly. For example, if you change a machine's naming service from NIS to NIS+, you need to install a switch file appropriate for NIS+. You change switch files by copying the appropriate template file to nsswitch.conf.

If you are installing NIS+ on a machine using the NIS+ installation scripts, the NIS+ template script is copied to nsswitch.conf for you. In this case, you do not have to configure the switch file unless you want to customize it.

Before proceeding to change switch files, make sure the sources listed in the file are properly set up. In other words, if you are going to select the NIS+ version, the client must eventually have access to NIS+ service; if you are going to select the local files version, those files must be properly set up on the client.

Modifying the name service switch

To change to a switch file, follow these steps:

  1. Log in to the client as superuser.

  2. Copy the alternate file appropriate for the machine's naming service over the nsswitch.conf file.

    NIS+ Version (done automatically for you by NIS+ scripts)


    client1# cd /etc
    client1# cp nsswitch.nisplus nsswitch.conf

    NIS Version


    client1# cd /etc
    client1# cp nsswitch.nis nsswitch.conf

    Local /etc Files Version


    client1# cd /etc
    client1# cp nsswitch.files nsswitch.conf
  3. Reboot the machine.

    The nscd naming service cache daemon caches switch information. Some library routines do not periodically check the nsswitch.conf file to see whether it has been changed. You must reboot the machine to make sure that the daemon and those routines have the latest information in the file.

How to Enable an NIS+ Client to Use IPv6

  1. Log in as superuser.

  2. Edit the /etc/nsswitch.conf file.

  3. Add the new ipnodes source and specify the naming service (such as ldap).


    ipnodes: ldap [NOTFOUND=return] files

    ipnodes defaults to files. During the transition from IPv4 to IPv6, where all naming services are not aware of IPv6 addresses, you should accept the files default. Otherwise, unnecessary delays might result during the resolution of addresses.

  4. Save the file and reboot the machine.

    Because the nscd daemon caches this information, which it reads at start up, you must reboot the machine now.

Ensuring Compatibility With +/- Syntax

If +/- is used in /etc/passwd, /etc/shadow, and /etc/group files, you will need to modify the nsswitch.conffile to insure compatibility.


Note –

Users working on a client machine being served by an NIS+ server running in NIS compatibility mode cannot run ypcat on the netgroup table. Doing so will give you results as if the table were empty even if it has entries.


The Switch File and Password Information


Caution – Caution –

files should be the first source in the nsswitch.conf file for passwd information. If files is not the first source, network security could be weakened and users could encounter log in difficulty.


For example, in an NIS+ environment, the passwd line of the nsswitch.conf file should look like this:


passwd: files nisplus

In an NIS environment, the passwd line of the nsswitch.conf file should look like this:


passwd: files nis