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 In-
				teraction 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  be-
				tween  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-in-

       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 at-
       tempts 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 ev-
       erything, 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 re-
       turned may be incomplete	(enumeration for hosts is simply not supported
       by  the	dns source), inconsistent (if multiple sources are used), for-
       matted 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	 data-
       base  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), se-
       cure_rpc(3NSL),	getprojent(3PROJECT),  getdefaultproj(3PROJECT),   in-
       proj(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  us-
       ing 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