nsswitch.conf - configuration  file  for  the  name  service




     The operating system uses a number of databases of  informa-
     tion  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),
     printers                 lp(1),     lpstat(1),     cancel(1),
                              lpr(1B),      lpq(1B),     lprm(1B),
                              in.lpd(1M), lpadmin(1M),  lpget(1M),
     prof_attr                getprofname(3SECDB),
     project                  getprojent(3PROJECT),
                              inproj(3PROJECT),        newtask(1),
     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 and ipnodes.
                              Uses  the  Internet  Domain  Name
     compat                   Valid only for passwd and  group.
                              Implements   "+"   and  "-".  See
                              Interaction with +/- syntax.
     user                     Valid only for  printers.  Imple-
                              ments         support         for
     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 codes:

     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

     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>]]*
     <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  following  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

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

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

     The   default   criteria   for   all   other   sources    is
     [SUCCESS=return      NOTFOUND=continue      UNAVAIL=continue

     The default, or explicitly specified, criteria are  meaning-
     less  following  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,
     gethostbyname(3NSL),               getipnodebyname(3SOCKET),
     getservbyname(3SOCKET), and netdir_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 netconfig entries have a "-" in the last
     column for nametoaddr libraries. See the  NOTES  section  in
     gethostbyname(3NSL) and getservbyname(3SOCKET) for details.

  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"; how-
     ever, "nisplus" is recommended instead of "nis".

  Interaction with server in DNS-forwarding Mode
     The NIS (YP) server can be  run  in  "DNS-forwarding  mode",
     where  it forwards 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

     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 originating from its YP clients;
     "hosts"  policy  on  these  clients  should  be   configured

  Interaction with Password Aging
     When password aging is turned on, only a limited set of pos-
     sible  name  services are permitted for the passwd: database
     in the /etc/nsswitch.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 password aging has been turned on.
     Otherwise, you can work around incorrect  passwd:  lines  by
     using  the  -r  repository argument to the passwd(1) command
     and using passwd -r repository to override the nsswitch.conf
     settings  and  specify  in  which  name  service you want to
     modify your password.

  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 appropri-
     ate 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

  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

     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  information and try files only if
     nis is down." This, and other policies listed in the default
     configuration  above,  are identical to the hard-wired poli-
     cies 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 configuration 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 configuration 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  confi-
     guration   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
     getpwent(),  hosts  has  gethostent(), and so on. These were
     reasonable when the only source was  files  but  often  make
     little sense for hierarchically structured sources that con-
     tain large  numbers  of  entries,  much  less  for  multiple
     sources. The interfaces are still provided and the implemen-
     tations strive to provide reasonable results, but  the  data
     returned  may be incomplete (enumeration for hosts is simply
     not supported 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 con-
     secutive), or very expensive (enumerating a passwd  database
     of  5,000 users is probably a bad idea). Furthermore, multi-
     ple threads in the same process  using  the  same  reentrant
     enumeration  function (getXXXent_r() are supported beginning
     with SunOS 5.3) share the same enumeration position; if they
     interleave  calls,  they  will enumerate disjoint subsets of
     the same database.

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


     A source named SSS is implemented by a shared  object  named
     nss_SSS.so.1 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

           Sample  configuration  file  that  uses  "files"   and

           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)getgrnam(3C),
     getnetgrent(3C),         getpwnam(3C),         getspnam(3C),
     gethostbyname(3NSL), getpublickey(3NSL), getrpcbyname(3NSL),
     netdir(3NSL),     secure_rpc(3NSL),    getprojent(3PROJECT),
     getdefaultproj(3PROJECT),                  inproj(3PROJECT),
     setproject(3PROJECT),                    getauthnam(3SECDB),
     getexecprof(3SECDB), getprofnam(3SECDB), getusernam(3SECDB),
     ethers(3SOCKET),                   getipnodebyname(3SOCKET),
     getnetbyname(3SOCKET),              getprotobyname(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/nss_SSS.so.1 at run time.

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

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

     The   following   functions   do   not   use   the   switch:
     fgetgrent(3C),     fgetprojent(3PROJECT),     fgetpwent(3C),
     fgetspent(3C), getpw(3C), putpwent(3C), shadow(4).

Man(1) output converted with man2html