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

FreeBSD Manual Pages


home | help
nsswitch.conf(4)					      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			getaddrinfo(3SOCKET)
       netgroup			innetgr(3C)
       netmasks			ifconfig(1M)
       networks			getnetbyname(3SOCKET)
       passwd			getpwnam(3C),  getspnam(3C), getauuser-
				nam(3BSM), getusernam(3SECDB)
       printers			lp(1), lpstat(1),  cancel(1),  lpr(1B),
				lpq(1B),  lprm(1B),  in.lpd(1M),  lpad-
				min(1M), lpget(1M), lpset(1M)
       prof_attr		getprofnam(3SECDB), getexecprof(3SECDB)
       project			getprojent(3PROJECT),	    getdefault-
				proj(3PROJECT),	 inproj(3PROJECT), new-
				task(1), setproject(3PROJECT)
       protocols		getprotobyname(3SOCKET)
       publickey		getpublickey(3NSL), secure_rpc(3NSL)
       rpc			getrpcbyname(3NSL)
       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 and ipnodes.
				Uses  the  Internet  Domain  Name
       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-

       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	 TRYAGAIN
				action	transitions  to	continue,
				until a	future request receives	a
				response,  at  which  time  TRYA-
				GAIN=n is restored.

       The complete syntax of an entry is:

       <entry>	   ::= <database> ":" [<source>	[<criteria>]]*
       <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"  is  [SUCCESS=return  NOTFOUND=continue  UNAVAIL=continue	 TRYA-

       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),  getaddrinfo(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  section in gethostbyname(3NSL) and getservbyname(3SOCKET) for  de-

   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:

       passwd:		       files

       passwd:		       files nis

       passwd:		       files nisplus

       passwd:		       files ldap

       passwd:		       compat

       passwd_compat:	       nisplus

       passwd_compat:	       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 in compat mode, for every /etc/passwd entry, there must 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:

       passwd:		       files nis

       group:		       files nis

       hosts:		       nis [NOTFOUND=return] files

       ipnodes:		       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

       services:	       files nis

       printers:	       user files nis nisplus

       auth_attr	       files nis

       prof_attr	       files nis

       project		       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:

       passwd:		       compat

       group:		       compat

       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:

       passwd:		       compat

       passwd_compat:	       nisplus OR ldap

       group:		       compat

       group_compat:	       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):

       hosts:		       nisplus dns [NOTFOUND=return] files


       hosts:		       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.

       /etc/nsswitch.conf	       Configuration file.

       /usr/lib/	       Implements "compat" source.

       /usr/lib/	       Implements "dns"	source.

       /usr/lib/	       Implements "files" source.

       /usr/lib/	       Implements "nis"	source.

       /usr/lib/       Implements "nisplus" source.

       /usr/lib/	       Implements "ldap" source.

       /usr/lib/	       Implements "user" source.

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

       /etc/nsswitch.files	       Sample  configuration  file  that  uses
				       "files" only.

       /etc/nsswitch.nis	       Sample  configuration  file  that  uses
				       "files" and "nis".

       /etc/nsswitch.nisplus	       Sample  configuration  file  that  uses
				       "files" and "nisplus".

       /etc/nsswitch.ldap	       Sample  configuration  file  that  uses
				       "files" and "ldap".

       /etc/nsswitch.dns	       Sample  configuration  file  that  uses
				       "files"	 and   "dns"   (but  only  for

       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),	getaddrinfo(3SOCKET), getnetbyname(3SOCKET), getproto-
       byname(3SOCKET),	getservbyname(3SOCKET),	netconfig(4), project(4),  re-
       solv.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.

       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),

				  25 May 2005		      nsswitch.conf(4)


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

home | help