1nsswitch.conf(4)                 File Formats                 nsswitch.conf(4)
2
3
4

NAME

6       nsswitch.conf - configuration file for the name service switch
7

SYNOPSIS

9       /etc/nsswitch.conf
10
11

DESCRIPTION

13       The  operating  system  uses a number of databases of information about
14       hosts, ipnodes, users (passwd(4),  shadow(4),  and  user_attr(4)),  and
15       groups.  Data  for  these can come from a variety of sources: hostnames
16       and host addresses, for example, can be found in /etc/hosts, NIS, NIS+,
17       LDAP,  DNS  or Multicast DNS. Zero or more sources can be used for each
18       database; the sources and their  lookup  order  are  specified  in  the
19       /etc/nsswitch.conf file.
20
21
22       The following databases use the switch file:
23
24
25
26
27              Database                          Used By
28       aliases                  sendmail(1M)
29       auth_attr                getauthnam(3SECDB)
30       automount                automount(1M)
31       bootparams               rpc.bootparamd(1M)
32       ethers                   ethers(3SOCKET)
33       group                    getgrnam(3C)
34       hosts                    gethostbyname(3NSL),             getad‐
35                                drinfo(3SOCKET). See  Interaction  with
36                                netconfig.
37       ipnodes                  Same as hosts.
38       netgroup                 innetgr(3C)
39       netmasks                 ifconfig(1M)
40       networks                 getnetbyname(3SOCKET)
41       passwd                   getpwnam(3C),  getspnam(3C), getauuser‐
42                                nam(3BSM), getusernam(3SECDB)
43       printers                 lp(1), lpstat(1),  cancel(1),  lpr(1B),
44                                lpq(1B),  lprm(1B),  in.lpd(1M),  lpad‐
45                                min(1M), lpget(1M), lpset(1M)
46       prof_attr                getprofnam(3SECDB), getexecprof(3SECDB)
47       project                  getprojent(3PROJECT),       getdefault‐
48                                proj(3PROJECT),  inproj(3PROJECT), new‐
49                                task(1), setproject(3PROJECT)
50       protocols                getprotobyname(3SOCKET)
51       publickey                getpublickey(3NSL), secure_rpc(3NSL)
52       rpc                      getrpcbyname(3NSL)
53       services                 getservbyname(3SOCKET).
54                                See Interaction with netconfig.
55       user_attr                getuserattr(3SECDB)
56
57
58
59       The following sources can be used:
60
61
62
63
64               Source                         Uses
65
66
67       files                    /etc/hosts,          /etc/passwd,
68                                /etc/inet/ipnodes,   /etc/shadow,
69                                /etc/security/auth_attr,
70                                /etc/user_attr
71       nis                      NIS(YP)
72       nisplus                  NIS+
73       ldap                     LDAP
74       ad                       Active Directory
75       dns                      Valid only for hosts and ipnodes.
76                                Uses  the  Internet  Domain  Name
77                                Service.
78       mdns                     Valid only for hosts and ipnodes.
79                                Uses the  Multicast  Domain  Name
80                                Service.
81       compat                   Valid  only for passwd and group.
82                                Implements + and -. See  Interac‐
83                                tion with +/- syntax.
84       user                     Valid  only  for printers. Imple‐
85                                ments support for ${HOME}/.print‐
86                                ers.
87
88
89
90       Note that /etc/inet/ipnodes is a symbolic link to /etc/hosts.
91
92
93       There  is  an  entry in /etc/nsswitch.conf for each database. Typically
94       these entries are simple, such as protocols: files or  networks:  files
95       nisplus.  However, when multiple sources are specified, it is sometimes
96       necessary to define precisely the circumstances under which each source
97       is tried. A source can return one of the following codes:
98
99
100
101
102               Status                         Meaning
103       SUCCESS                  Requested database entry was found.
104       UNAVAIL                  Source  is  not  configured on this
105                                system or internal failure.
106       NOTFOUND                 Source responded "no such entry"
107       TRYAGAIN                 Source is busy or  not  responding,
108                                might respond to retries.
109
110
111
112       For each status code, two actions are possible:
113
114
115
116
117               Action                        Meaning
118       continue                 Try the next source in the list.
119       return                   Return now.
120
121
122
123       Additionally, for TRYAGAIN only, the following actions are possible:
124
125
126
127
128               Action                        Meaning
129       forever                  Retry the current source forever.
130
131
132
133       n                        Retry  the  current source n more
134                                times,  where  n  is  an  integer
135                                between  0  and MAX_INT (that is,
136                                2.14 billion).  After  n  retries
137                                has  been exhausted, the TRYAGAIN
138                                action transitions  to  continue,
139                                until a future request receives a
140                                response,  at  which  time  TRYA‐
141                                GAIN=n is restored.
142
143
144
145       The complete syntax of an entry is:
146
147         <entry>     ::= <database> ":" [<source> [<criteria>]]*
148         <criteria>  ::= "[" <criterion>+ "]"
149         <criterion> ::= <status> "=" <action>
150         <status>    ::= "success" | "notfound" | "unavail" | "tryagain"
151
152
153
154       For every status except TRYAGAIN, the action syntax is:
155
156         <action>    ::= "return"  | "continue"
157
158
159
160       For the TRYAGAIN status, the action syntax is:
161
162         <action>    ::= "return"  | "continue" | "forever" | <n>
163         <n>         ::= 0...MAX_INT
164
165
166
167       Each entry occupies a single line in the file. Lines that are blank, or
168       that start with white space, are ignored. Everything on a line  follow‐
169       ing  a  # character is also ignored; the # character can begin anywhere
170       in a line, to be used to begin comments. The  <database>  and  <source>
171       names  are  case-sensitive,  but  <action> and <status> names are case-
172       insensitive.
173
174
175       The library functions contain compiled-in default entries that are used
176       if  the  appropriate  entry in nsswitch.conf is absent or syntactically
177       incorrect.
178
179
180       The default criteria for DNS and  the  NIS  server  in  "DNS-forwarding
181       mode"   is  [SUCCESS=return  NOTFOUND=continue  UNAVAIL=continue  TRYA‐
182       GAIN=3].
183
184
185       The default criteria for all  other  sources  is  [SUCCESS=return  NOT‐
186       FOUND=continue UNAVAIL=continue TRYAGAIN=forever].
187
188
189       The  default, or explicitly specified, criteria are meaningless follow‐
190       ing the last source in an entry; and they are ignored, since the action
191       is  always  to return to the caller irrespective of the status code the
192       source returns.
193
194   Interaction with netconfig
195       In order to ensure that they all return consistent results,  gethostby‐
196       name(3NSL),   getaddrinfo(3SOCKET),  getservbyname(3SOCKET),  and  net‐
197       dir_getbyname(3NSL) functions are all implemented in terms of the  same
198       internal library function. This function obtains the system-wide source
199       lookup policy for hosts, ipnodes, and services based on the inet family
200       entries in netconfig(4) and uses the switch entries only if the netcon‐
201       fig entries have a  -  (hyphen)  in  the  last  column  for  nametoaddr
202       libraries.  See the Notes section in gethostbyname(3NSL) and getservby‐
203       name(3SOCKET) for details.
204
205   YP-compatibility Mode
206       The NIS+ server can be run in YP-compatibility mode, where  it  handles
207       NIS  (YP)  requests as well as NIS+ requests. In this case, the clients
208       get much the same results (except for getspnam(3C)) from the nis source
209       as from nisplus; however, nisplus is recommended instead of nis.
210
211   Interaction with server in DNS-forwarding Mode
212       The  NIS  (YP)  server can be run in DNS-forwarding mode, where it for‐
213       wards lookup requests to DNS for host-names and -addresses that do  not
214       exist  in  its  database.  In this case, specifying nis as a source for
215       hosts is sufficient to get DNS  lookups;  dns  need  not  be  specified
216       explicitly as a source.
217
218
219       In  SunOS 5.3 (Solaris 2.3) and compatible versions, the NIS+ server in
220       NIS/YP-compatibility mode can also be run in DNS-forwarding  mode  (see
221       rpc.nisd(1M)).  Forwarding  is  effective only for requests originating
222       from its YP clients; hosts policy on these clients should be configured
223       appropriately.
224
225   Interaction with Password Aging
226       When  password  aging is turned on, only a limited set of possible name
227       services are permitted  for  the  passwd:  database  in  the  /etc/nss‐
228       witch.conf file:
229
230       passwd:           files
231
232
233       passwd:           files nis
234
235
236       passwd:           files nisplus
237
238
239       passwd:           files ldap
240
241
242       passwd:           compat
243
244
245       passwd_compat:    nisplus
246
247
248       passwd_compat:    ldap
249
250
251
252       You  can  add the ad keyword to any of the passwd configurations listed
253       above. However, you cannot use the passwd command to change  the  pass‐
254       word  of  an  Active Directory (AD) user. If the ad keyword is found in
255       the passwd entry during a password update operation, it is ignored.  To
256       update the password of an AD user, use the kpasswd(1) command.
257
258
259       Any  other  settings  causes  the  passwd(1)  command  to  fail when it
260       attempts to change the password after expiration and prevents the  user
261       from  logging  in.  These are the only permitted settings when password
262       aging has been turned on. Otherwise,  you  can  work  around  incorrect
263       passwd: lines by using the -r repository argument to the passwd(1) com‐
264       mand and using passwd -r repository to override the nsswitch.conf  set‐
265       tings  and  specify in which name service you want to modify your pass‐
266       word.
267
268   Interaction with +/- syntax
269       Releases prior to SunOS 5.0 did not have the name  service  switch  but
270       did  allow  the user some policy control. In /etc/passwd one could have
271       entries of  the  form  +user  (include  the  specified  user  from  NIS
272       passwd.byname),  -user  (exclude  the  specified  user)  and + (include
273       everything, except excluded users, from NIS passwd.byname). The desired
274       behavior  was  often  everything  in the file followed by everything in
275       NIS, expressed by a solitary + at the end of  /etc/passwd.  The  switch
276       provides an alternative for this case (passwd: files nis) that does not
277       require + entries in /etc/passwd and /etc/shadow (the latter is  a  new
278       addition to SunOS 5.0, see shadow(4)).
279
280
281       If  this  is  not  sufficient, the NIS/YP compatibility source provides
282       full +/- semantics. It reads /etc/passwd for getpwnam(3C) functions and
283       /etc/shadow  for  getspnam(3C)  functions and, if it finds +/- entries,
284       invokes an appropriate source. By default, the source is nis, but  this
285       can  be  overridden by specifying nisplus or ldap as the source for the
286       pseudo-database passwd_compat.
287
288
289       Note that in compat mode, for every /etc/passwd entry, there must be  a
290       corresponding entry in the /etc/shadow file.
291
292
293       The  NIS/YP  compatibility  source also provides full +/- semantics for
294       group; the relevant pseudo-database is group_compat.
295
296   Useful Configurations
297       The compiled-in default entries for all databases use NIS (YP)  as  the
298       enterprise level name service and are identical to those in the default
299       configuration of this file:
300
301       passwd:        files nis
302
303
304       group:         files nis
305
306
307       hosts:         nis [NOTFOUND=return] files
308
309
310       ipnodes:       nis [NOTFOUND=return] files
311
312
313       networks:      nis [NOTFOUND=return] files
314
315
316       protocols:     nis [NOTFOUND=return] files
317
318
319       rpc:           nis [NOTFOUND=return] files
320
321
322       ethers:        nis [NOTFOUND=return] files
323
324
325       netmasks:      nis [NOTFOUND=return] files
326
327
328       bootparams:    nis [NOTFOUND=return] files
329
330
331       publickey:     nis [NOTFOUND=return] files
332
333
334       netgroup:      nis
335
336
337       automount:     files nis
338
339
340       aliases:       files nis
341
342
343       services:      files nis
344
345
346       printers:      user files nis nisplus
347
348
349       auth_attr      files nis
350
351
352       prof_attr      files nis
353
354
355       project        files nis
356
357
358
359       Note that the files source for the ipnodes and hosts databases is iden‐
360       tical,  as  /etc/inet/ipnodes is a symbolic link to /etc/hosts. Because
361       other sources for the ipnodes and hosts databases are different, do not
362       remove the ipnodes line from the /etc/nsswitch.conf file.
363
364
365       The policy nis [NOTFOUND=return] files implies: if nis is UNAVAIL, con‐
366       tinue on to files, and if nis returns NOTFOUND, return to  the  caller.
367       In  other  words,  treat nis as the authoritative source of information
368       and try files only if nis is down. This, and other policies  listed  in
369       the  default configuration above, are identical to the hard-wired poli‐
370       cies in SunOS releases prior to 5.0.
371
372
373       If compatibility with the +/- syntax for passwd and group is  required,
374       simply modify the entries for passwd and group to:
375
376       passwd:    compat
377
378
379       group:     compat
380
381
382
383       If NIS+ is the enterprise level name service, the default configuration
384       should be modified to use nisplus instead of nis for every database  on
385       client  machines. The file /etc/nsswitch.nisplus contains a sample con‐
386       figuration that can be copied to /etc/nsswitch.conf to set this policy.
387
388
389       If LDAP is the enterprise level name service, the default configuration
390       should  be  modified  to  use ldap instead of nis for every database on
391       client machines. The file /etc/nsswitch.ldap contains a sample configu‐
392       ration that can be copied to /etc/nsswitch.conf to set this policy.
393
394
395       When  using  Active Directory, dns is required to perform hosts resolu‐
396       tion.
397
398
399       If the use of +/- syntax is desired in conjunction  with  nisplus,  use
400       the following four entries:
401
402       passwd:           compat
403
404
405       passwd_compat:    nisplus OR ldap
406
407
408       group:            compat
409
410
411       group_compat:     nisplus OR ldap
412
413
414
415       In  order  to get information from the Internet Domain Name Service for
416       hosts that are not listed in the enterprise level name service, NIS+ or
417       LDAP,  use  the following configuration and set up the /etc/resolv.conf
418       file (see resolv.conf(4) for more details):
419
420       hosts:    nisplus dns [NOTFOUND=return] files
421
422
423
424       or
425
426       hosts:    ldap dns [NOTFOUND=return] files
427
428
429   Enumeration - getXXXent()
430       Many of the databases have  enumeration  functions:  passwd  has  getp‐
431       went(),  hosts  has gethostent(), and so on. These were reasonable when
432       the only source was files but often make little  sense  for  hierarchi‐
433       cally  structured  sources  that contain large numbers of entries, much
434       less for multiple sources. The interfaces are still  provided  and  the
435       implementations  strive  to  provide  reasonable  results, but the data
436       returned can be incomplete (enumeration for hosts is  simply  not  sup‐
437       ported by the dns source), inconsistent (if multiple sources are used),
438       formatted in an unexpected fashion (for a host with  a  canonical  name
439       and  three  aliases, the nisplus source returns four hostents, and they
440       might not be consecutive), or  very  expensive  (enumerating  a  passwd
441       database  of 5,000 users is probably a bad idea). Furthermore, multiple
442       threads in the same process using the same reentrant enumeration  func‐
443       tion  (getXXXent_r()  are supported beginning with SunOS 5.3) share the
444       same enumeration position; if they  interleave  calls,  they  enumerate
445       disjoint subsets of the same database.
446
447
448       In  general, the use of the enumeration functions is deprecated. In the
449       case of passwd, shadow, and group, it might sometimes be appropriate to
450       use fgetgrent(), fgetpwent(), and fgetspent() (see getgrnam(3C), getpw‐
451       nam(3C), and getspnam(3C), respectively),  which  use  only  the  files
452       source.
453

FILES

455       A source named SSS is implemented by a shared object named nss_SSS.so.1
456       that resides in /usr/lib.
457
458       /etc/nsswitch.conf           Configuration file.
459
460
461       /usr/lib/nss_compat.so.1     Implements compat source.
462
463
464       /usr/lib/nss_dns.so.1        Implements dns source.
465
466
467       /usr/lib/nss_files.so.1      Implements files source.
468
469
470       /usr/lib/nss_mdns.so.1       Implements mdns source.
471
472
473       /usr/lib/nss_nis.so.1        Implements nis source.
474
475
476       /usr/lib/nss_nisplus.so.1    Implements nisplus source.
477
478
479       /usr/lib/nss_ldap.so.1       Implements ldap source.
480
481
482       /usr/lib/nss_ad.so.1         Implements ad source.
483
484
485       /usr/lib/nss_user.so.1       Implements user source.
486
487
488       /etc/netconfig               Configuration file for netdir(3NSL)  func‐
489                                    tions  that redirects hosts/devices policy
490                                    to the switch.
491
492
493       /etc/nsswitch.files          Sample configuration file that uses  files
494                                    only.
495
496
497       /etc/nsswitch.nis            Sample  configuration file that uses files
498                                    and nis.
499
500
501       /etc/nsswitch.nisplus        Sample configuration file that uses  files
502                                    and nisplus.
503
504
505       /etc/nsswitch.ldap           Sample  configuration file that uses files
506                                    and ldap.
507
508
509       /etc/nsswitch.ad             Sample configuration file that uses  files
510                                    and ad.
511
512
513       /etc/nsswitch.dns            Sample configuration file that uses files,
514                                    dns  and  mdns  (dns  and  mdns  only  for
515                                    hosts).
516
517

SEE ALSO

519       kpasswd(1),  ldap(1),  newtask(1),  NIS+(1),  passwd(1), automount(1M),
520       ifconfig(1M),  mdnsd(1M),   rpc.bootparamd(1M),   rpc.nisd(1M),   send‐
521       mail(1M),  getauusernam(3BSM),  getgrnam(3C),  getnetgrent(3C),  getpw‐
522       nam(3C), getspnam(3C), gethostbyname(3NSL),  getpublickey(3NSL),  getr‐
523       pcbyname(3NSL),  netdir(3NSL),  secure_rpc(3NSL), getprojent(3PROJECT),
524       getdefaultproj(3PROJECT),    inproj(3PROJECT),    setproject(3PROJECT),
525       getauthnam(3SECDB),  getexecprof(3SECDB),  getprofnam(3SECDB), getuser‐
526       attr(3SECDB),     getusernam(3SECDB),      ethers(3SOCKET),      getad‐
527       drinfo(3SOCKET),  getnetbyname(3SOCKET),  getprotobyname(3SOCKET), get‐
528       servbyname(3SOCKET), auth_attr(4), hosts(4), netconfig(4),  project(4),
529       resolv.conf(4), user_attr(4), ypfiles(4), ad(5)
530

NOTES

532       Within  each  process  that uses nsswitch.conf, the entire file is read
533       only once; if the file is later changed, the  process  continues  using
534       the old configuration.
535
536
537       The  use  of  both  nis and nisplus as sources for the same database is
538       strongly discouraged since both the name services are expected to store
539       similar information and the lookups on the database can yield different
540       results depending on which name service is operational at the  time  of
541       the request. The same applies for using ldap along with nis or nisplus.
542
543
544       Do  not  use  the  ldap  and ad keywords together when the Solaris LDAP
545       client uses schema mapping to talk to Active Directory.
546
547
548       Misspelled names of sources and databases  are  treated  as  legitimate
549       names of (most likely nonexistent) sources and databases.
550
551
552       The  following functions do not use the switch: fgetgrent(3C), fgetpro‐
553       jent(3PROJECT), fgetpwent(3C), fgetspent(3C), getpw(3C),  putpwent(3C),
554       shadow(4).
555
556
557
558SunOS 5.11                        6 Nov 2008                  nsswitch.conf(4)
Impressum