1nsswitch.conf(4) File Formats nsswitch.conf(4)
2
6 nsswitch.conf - configuration file for the name service switch
7
9 /etc/nsswitch.conf
10
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 The following databases use the switch file:
23 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 The following sources can be used:
60 Source Uses
65 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 Note that /etc/inet/ipnodes is a symbolic link to /etc/hosts.
91 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 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 For each status code, two actions are possible:
113 Action Meaning
118 continue Try the next source in the list.
119 return Return now.
120 Additionally, for TRYAGAIN only, the following actions are possible:
124 Action Meaning
129 forever Retry the current source forever.
130 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 The complete syntax of an entry is:
146 <entry> ::= <database> ":" [<source> [<criteria>]]*
148 <criteria> ::= "[" <criterion>+ "]"
149 <criterion> ::= <status> "=" <action>
150 <status> ::= "success" | "notfound" | "unavail" | "tryagain"
151 For every status except TRYAGAIN, the action syntax is:
155 <action> ::= "return" | "continue"
157 For the TRYAGAIN status, the action syntax is:
161 <action> ::= "return" | "continue" | "forever" | <n>
163 <n> ::= 0...MAX_INT
164 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 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 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 The default criteria for all other sources is [SUCCESS=return NOT‐
186 FOUND=continue UNAVAIL=continue TRYAGAIN=forever].
187 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 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 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 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 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 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 passwd: files
231 passwd: files nis
234 passwd: files nisplus
237 passwd: files ldap
240 passwd: compat
243 passwd_compat: nisplus
246 passwd_compat: ldap
249 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 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 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 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 Note that in compat mode, for every /etc/passwd entry, there must be a
290 corresponding entry in the /etc/shadow file.
291 The NIS/YP compatibility source also provides full +/- semantics for
294 group; the relevant pseudo-database is group_compat.
295 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 passwd: files nis
302 group: files nis
305 hosts: nis [NOTFOUND=return] files
308 ipnodes: nis [NOTFOUND=return] files
311 networks: nis [NOTFOUND=return] files
314 protocols: nis [NOTFOUND=return] files
317 rpc: nis [NOTFOUND=return] files
320 ethers: nis [NOTFOUND=return] files
323 netmasks: nis [NOTFOUND=return] files
326 bootparams: nis [NOTFOUND=return] files
329 publickey: nis [NOTFOUND=return] files
332 netgroup: nis
335 automount: files nis
338 aliases: files nis
341 services: files nis
344 printers: user files nis nisplus
347 auth_attr files nis
350 prof_attr files nis
353 project files nis
356 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 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 If compatibility with the +/- syntax for passwd and group is required,
374 simply modify the entries for passwd and group to:
375 passwd: compat
377 group: compat
380 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 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 When using Active Directory, dns is required to perform hosts resolu‐
396 tion.
397 If the use of +/- syntax is desired in conjunction with nisplus, use
400 the following four entries:
401 passwd: compat
403 passwd_compat: nisplus OR ldap
406 group: compat
409 group_compat: nisplus OR ldap
412 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 hosts: nisplus dns [NOTFOUND=return] files
421 or
425 hosts: ldap dns [NOTFOUND=return] files
427 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 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
455 A source named SSS is implemented by a shared object named nss_SSS.so.1
456 that resides in /usr/lib.
457 /etc/nsswitch.conf Configuration file.
459 /usr/lib/nss_compat.so.1 Implements compat source.
462 /usr/lib/nss_dns.so.1 Implements dns source.
465 /usr/lib/nss_files.so.1 Implements files source.
468 /usr/lib/nss_mdns.so.1 Implements mdns source.
471 /usr/lib/nss_nis.so.1 Implements nis source.
474 /usr/lib/nss_nisplus.so.1 Implements nisplus source.
477 /usr/lib/nss_ldap.so.1 Implements ldap source.
480 /usr/lib/nss_ad.so.1 Implements ad source.
483 /usr/lib/nss_user.so.1 Implements user source.
486 /etc/netconfig Configuration file for netdir(3NSL) func‐
489 tions that redirects hosts/devices policy
490 to the switch.
491 /etc/nsswitch.files Sample configuration file that uses files
494 only.
495 /etc/nsswitch.nis Sample configuration file that uses files
498 and nis.
499 /etc/nsswitch.nisplus Sample configuration file that uses files
502 and nisplus.
503 /etc/nsswitch.ldap Sample configuration file that uses files
506 and ldap.
507 /etc/nsswitch.ad Sample configuration file that uses files
510 and ad.
511 /etc/nsswitch.dns Sample configuration file that uses files,
514 dns and mdns (dns and mdns only for
515 hosts).
516
519 kpasswd(1), ldap(1), newtask(1), NIS+[22m(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
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 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 Do not use the ldap and ad keywords together when the Solaris LDAP
545 client uses schema mapping to talk to Active Directory.
546 Misspelled names of sources and databases are treated as legitimate
549 names of (most likely nonexistent) sources and databases.
550 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).
555SunOS 5.11 6 Nov 2008 nsswitch.conf(4)