Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
nsswitch.conf(4)		 File Formats		      nsswitch.conf(4)

       nsswitch.conf - configuration file for the name service switch


       The  operating  system  uses a number of	databases of information about
       hosts, ipnodes, users (passwd and shadow), and groups. Data  for	 these
       can  come  from a variety of sources: hostnames and host	addresses, for
       example,	can be found in	/etc/hosts, NIS, NIS+, LDAP, or	DNS.  Zero  or
       more  sources  may  be  used  for  each database; the sources and their
       lookup order are	specified in the /etc/nsswitch.conf file.

       The following databases use the switch file:

       Database			Used By
       aliases			sendmail(1M)
       auth_attr		getauthnam(3SECDB)
       automount		automount(1M)
       bootparams		rpc.bootparamd(1M)
       ethers			ethers(3SOCKET)
       group			getgrnam(3C)
       hosts			gethostbyname(3NSL). See Interaction
				with netconfig.
       ipnodes			getipnodebyname(3SOCKET)
       netgroup			innetgr(3C)
       netmasks			ifconfig(1M)
       networks			getnetbyname(3SOCKET)
       passwd			getpwnam(3C),  getspnam(3C),  getau-
				usernam(3BSM), getusernam(3SECDB)
       printers			lp(1),	   lpstat(1),	  cancel(1),
				lpr(1B),      lpq(1B),	   lprm(1B),
				in.lpd(1M), lpadmin(1M),  lpget(1M),
       prof_attr		getprofname(3SECDB),	      getex-
       project			getprojent(3PROJECT),	 getdefault-
				proj(3PROJECT),	   inproj(3PROJECT),
				newtask(1), setproject(3PROJECT)
       protocols		getprotobyname(3SOCKET)
       publickey		getpublickey(3NSL), secure_rpc(3NSL)
       rpc			getrpcbyname(3NSL)
       sendmailvars		sendmail(1M)
       services			getservbyname(3SOCKET).
				See Interaction	with netconfig.

       The following sources may be used:

       Source			Uses
       files			/etc/hosts,	     /etc/passwd,
				/etc/inet/ipnodes, /etc/shadow
       nis			NIS(YP)
       nisplus			NIS+
       ldap			LDAP
       dns			Valid  only  for  hosts; uses the
				Internet Domain	Name Service.

       compat			Valid only for passwd and  group;
				implements   "+"   and	"-".  See
				Interaction with +/- syntax.
       user			Valid only for	printers;  imple-
				ments support for ${HOME}/.print-
       xfn			Valid only for	printers;  imple-
				ments  support	for  FNS  printer
				contexts. Provided to allow tran-
				sition away from FNS printer con-

       There is	an entry in /etc/nsswitch.conf for  each  database.  Typically
       these  entries will be simple, such as "protocols: files" or "networks:
       files nisplus". However,	when multiple sources  are  specified,	it  is
       sometimes  necessary  to	define precisely the circumstances under which
       each source will	be tried. A source can return  one  of	the  following

       Status			Meaning
       SUCCESS			Requested database entry was found.
       UNAVAIL			Source	is  not	 configured on this
				system or internal failure.
       NOTFOUND			Source responded "no such entry"
       TRYAGAIN			Source is busy or  not	responding,
				might respond to retries.

       For each	status code, two actions are possible:

       Action			Meaning
       continue			Try the	next source in the list.
       return			Return now.

       Additionally, for TRYAGAIN only,	the following actions are possible:

       Action			Meaning
       forever			Retry the current source forever.
       n			Retry  the  current source n more
				times,	where  n  is  an  integer
				between	 0  and	MAX_INT	(that is,
				2.14 billion).	After  n  retries
				has  been  exhausted,  the action
				will continue to the next source.

       The complete syntax of an entry is:

       <entry>	   ::= <database> ":" [<source>
       <criteria>  ::= "[" <criterion>+	"]"
       <criterion> ::= <status>	"=" <action>
       <status>	   ::= "success" | "notfound" |	"unavail" | "tryagain"

       For every status	except TRYAGAIN, the action syntax is:

       <action>	   ::= "return"	 | "continue"

       For the TRYAGAIN	status,	the action syntax is:

       <action>	   ::= "return"	 | "continue" |	"forever" | <n>
       <n>	   ::= 0...MAX_INT

       Each entry occupies a single line in the	file. Lines that are blank, or
       that start with white space, are	ignored. Everything on a line  follow-
       ing  a  # character is also ignored; the	# character can	begin anywhere
       in a line, to be	used to	begin comments.	The  <database>	 and  <source>
       names  are  case-sensitive,  but	 <action> and <status> names are case-

       The library functions contain compiled-in default entries that are used
       if  the	appropriate  entry in nsswitch.conf is absent or syntactically

       The default criteria for	DNS and	 the  NIS  server  in  "DNS-forwarding
       mode"  (and  DNS	server not responding or busy) is [SUCCESS=return NOT-
       FOUND=continue UNAVAIL=continue TRYAGAIN=continue].

       The default criteria for	all  other  sources  is	 [SUCCESS=return  NOT-
       FOUND=continue UNAVAIL=continue TRYAGAIN=forever].

       The  default, or	explicitly specified, criteria are meaningless follow-
       ing the last source in an entry;	and they are ignored, since the	action
       is  always  to return to	the caller irrespective	of the status code the
       source returns.

   Interaction with netconfig
       In order	to ensure that they all	return consistent results,  gethostby-
       name(3NSL),  getipnodebyname(3SOCKET), getservbyname(3SOCKET), and net-
       dir_getbyname(3NSL) functions are all implemented in terms of the  same
       internal	library	function. This function	obtains	the system-wide	source
       lookup policy for hosts,	ipnodes, and services based on the inet	family
       entries in netconfig(4) and uses	the switch entries only	if the netcon-
       fig entries have	a "-" in the last column for nametoaddr	libraries. See
       the NOTES section in gethostbyname(3NSL)	and getservbyname(3SOCKET) for

   YP-compatibility Mode
       The NIS+	server can be run in "YP-compatibility mode", where it handles
       NIS  (YP)  requests as well as NIS+ requests. In	this case, the clients
       get much	the same results (except  for  getspnam(3C))  from  the	 "nis"
       source  as from "nisplus"; however, "nisplus" is	recommended instead of

   Interaction with server in DNS-forwarding Mode
       The NIS (YP) server can be run in "DNS-forwarding mode",	where it  for-
       wards  lookup requests to DNS for host-names and	-addresses that	do not
       exist in	its database. In this case, specifying "nis" as	a  source  for
       "hosts"	is  sufficient to get DNS lookups; "dns" need not be specified
       explicitly as a source.

       In SunOS	5.3 (Solaris 2.3) and compatible versions, the NIS+ server  in
       "NIS/YP-compatibility  mode"  can  also be run in "DNS-forwarding mode"
       (see rpc.nisd(1M)). Forwarding is effective only	for requests originat-
       ing from	its YP clients;	"hosts"	policy on these	clients	should be con-
       figured appropriately.

   Interaction with Password Aging
       When password aging is turned on, only a	limited	set of	possible  name
       services	 are  permitted	 for  the  passwd:  database  in the /etc/nss-
       witch.conf file:


	     files nis

	     files nisplus

	     files ldap




       Any other settings will cause the passwd(1) command  to	fail  when  it
       attempts	 to  change the	password after expiration and will prevent the
       user from logging in. These are the only	permitted settings when	 pass-
       word aging has been turned on. Otherwise, you can work around incorrect
       passwd: lines by	using the -r repository	argument to the	passwd(1) com-
       mand  and using passwd -r repository to override	the nsswitch.conf set-
       tings and specify in which name service you want	to modify  your	 pass-

   Interaction with +/-	syntax
       Releases	 prior	to  SunOS 5.0 did not have the name service switch but
       did allow the user some policy control. In /etc/passwd one  could  have
       entries	of  the	 form  +user  (include	the  specified	user  from NIS
       passwd.byname), -user (exclude  the  specified  user)  and  +  (include
       everything, except excluded users, from NIS passwd.byname). The desired
       behavior	was often "everything in the file followed  by	everything  in
       NIS",  expressed	 by a solitary + at the	end of /etc/passwd. The	switch
       provides	an alternative for this	case ("passwd: files nis")  that  does
       not  require  + entries in /etc/passwd and /etc/shadow (the latter is a
       new addition to SunOS 5.0, see shadow(4)).

       If this is not sufficient, the  NIS/YP  compatibility  source  provides
       full +/-	semantics. It reads /etc/passwd	for getpwnam(3C) functions and
       /etc/shadow for getspnam(3C) functions and, if it  finds	 +/-  entries,
       invokes	an  appropriate	 source.  By default, the source is "nis", but
       this may	be overridden by specifying "nisplus" or "ldap"	as the	source
       for the pseudo-database passwd_compat.

       Note  that for every /etc/passwd	entry, there should be a corresponding
       entry in	the /etc/shadow	file.

       The NIS/YP compatibility	source also provides full  +/-	semantics  for
       group; the relevant pseudo-database is group_compat.

   Useful Configurations
       The  compiled-in	 default entries for all databases use NIS (YP)	as the
       enterprise level	name service and are identical to those	in the default
       configuration of	this file:

	     files nis

	     files nis

	     nis [NOTFOUND=return] files

	     nis [NOTFOUND=return] files

	     nis [NOTFOUND=return] files

	     nis [NOTFOUND=return] files

       rpc:  nis [NOTFOUND=return] files

	     nis [NOTFOUND=return] files

	     nis [NOTFOUND=return] files

	     nis [NOTFOUND=return] files

	     nis [NOTFOUND=return] files


	     files nis

	     files nis

	     files nis


	     user files	nis nisplus xfn

	     files nis

	     files nis

	     files nis

       The  policy  "nis  [NOTFOUND=return] files" implies "if nis is UNAVAIL,
       continue	on to files, and  if  nis  returns  NOTFOUND,  return  to  the
       caller; in other	words, treat nis as the	authoritative source of	infor-
       mation and try files only if nis	is down."  This,  and  other  policies
       listed  in  the default configuration above, are	identical to the hard-
       wired policies in SunOS releases	prior to 5.0.

       If compatibility	with the +/- syntax for	passwd and group is  required,
       simply modify the entries for passwd and	group to:



       If NIS+ is the enterprise level name service, the default configuration
       should be modified to use nisplus instead of nis	for every database  on
       client  machines. The file /etc/nsswitch.nisplus	contains a sample con-
       figuration that can be copied to	/etc/nsswitch.conf to set this policy.

       If LDAP is the enterprise level name service, the default configuration
       should be modified to use ldap instead of nis  for  every  database  on
       client machines.	The file /etc/nsswitch.ldap contains a sample configu-
       ration that can be copied to /etc/nsswitch.conf to set this policy.

       If the use of +/- syntax	is desired in conjunction  with	 nisplus,  use
       the following four entries:


	     nisplus OR	ldap


	     nisplus OR	ldap

       In  order  to get information from the Internet Domain Name Service for
       hosts that are not listed in the	enterprise level name service, NIS+ or
       LDAP,  use  the following configuration and set up the /etc/resolv.conf
       file (see resolv.conf(4)	for more details):

	     nisplus dns [NOTFOUND=return] files


	     ldap dns [NOTFOUND=return]	files

   Enumeration - getXXXent()
       Many of the databases have  enumeration	functions:  passwd  has	 getp-
       went(),	hosts  has gethostent(), and so	on. These were reasonable when
       the only	source was files but often make	little	sense  for  hierarchi-
       cally  structured  sources  that	contain	large numbers of entries, much
       less for	multiple sources. The interfaces are still  provided  and  the
       implementations	strive	to  provide  reasonable	 results, but the data
       returned	may be incomplete (enumeration for hosts is  simply  not  sup-
       ported by the dns source), inconsistent (if multiple sources are	used),
       formatted in an unexpected fashion (for a host with  a  canonical  name
       and  three  aliases,  the nisplus source	will return four hostents, and
       they may	not be consecutive), or	very expensive (enumerating  a	passwd
       database	 of 5,000 users	is probably a bad idea). Furthermore, multiple
       threads in the same process using the same reentrant enumeration	 func-
       tion  (getXXXent_r()  are supported beginning with SunOS	5.3) share the
       same enumeration	position; if they interleave calls, they will  enumer-
       ate disjoint subsets of the same	database.

       In  general, the	use of the enumeration functions is deprecated.	In the
       case of passwd, shadow, and group, it may sometimes be  appropriate  to
       use fgetgrent(),	fgetpwent(), and fgetspent() (see getgrnam(3C),	getpw-
       nam(3C),	and getspnam(3C), respectively),  which	 use  only  the	 files

       A source	named SSS is implemented by a shared object named
       that resides in /usr/lib.

	     Configuration file.

	     Implements	"compat" source.

	     Implements	"dns" source.

	     Implements	"files"	source.

	     Implements	"nis" source.

	     Implements	"nisplus" source.

	     Implements	"ldap" source.

	     Implements	"user" source.

	     Implements	"xfn" source.

	     Configuration file	 for  netdir(3NSL)  functions  that  redirects
	     hosts/devices policy to the switch.

	     Sample configuration file that uses "files" only.

	     Sample configuration file that uses "files" and "nis".

	     Sample configuration file that uses "files" and "nisplus".

	     Sample configuration file that uses "files" and "ldap".

	     Sample  configuration  file that uses "files" and "dns" (but only
	     for hosts:).

       ldap(1),	newtask(1), nis+(1), passwd(1),	 automount(1M),	 ifconfig(1M),
       rpc.bootparamd(1M),  rpc.nisd(1M), sendmail(1M),	getauusernam(3BSM)get-
       grnam(3C),  getnetgrent(3C),  getpwnam(3C),  getspnam(3C),   gethostby-
       name(3NSL),   getpublickey(3NSL),   getrpcbyname(3NSL),	 netdir(3NSL),
       secure_rpc(3NSL),    getprojent(3PROJECT),    getdefaultproj(3PROJECT),
       inproj(3PROJECT),   setproject(3PROJECT),   getauthnam(3SECDB),	getex-
       ecprof(3SECDB),	       getprofnam(3SECDB),	   getusernam(3SECDB),
       ethers(3SOCKET),	 getipnodebyname(3SOCKET), getnetbyname(3SOCKET), get-
       protobyname(3SOCKET), getservbyname(3SOCKET), netconfig(4), project(4),
       resolv.conf(4), ypfiles(4)

       Within  each  process  that uses	nsswitch.conf, the entire file is read
       only once; if the file is later	changed,  the  process	will  continue
       using the old configuration.

       Programs	that use the getXXbyYY() functions cannot be linked statically
       since the implementation	of these  functions  requires  dynamic	linker
       functionality to	access the shared objects /usr/lib/	at run

       The use of both nis and nisplus as sources for  the  same  database  is
       strongly	discouraged since both the name	services are expected to store
       similar information and the lookups on the database may yield different
       results	depending  on which name service is operational	at the time of
       the request. The	same applies for using ldap along with nis or nisplus.

       Misspelled names	of sources and databases will be treated as legitimate
       names of	(most likely nonexistent) sources and databases.

       The following functions do not use the switch: fgetgrent(3C),  fgetpro-
       jent(3PROJECT),	fgetpwent(3C), fgetspent(3C), getpw(3C), putpwent(3C),

SunOS 5.9			  10 Jul 2001		      nsswitch.conf(4)


Want to link to this manual page? Use this URL:

home | help