man5/nsswitch.conf.5

   1 .\" Copyright (c) 1998, 1999 Thorsten Kukuk (kukuk@vt.uni-paderborn.de)
   2 .\" Copyright (c) 2011, Mark R. Bannister <cambridge@users.sourceforge.net>
   3 .\"
   4 .\" SPDX-License-Identifier: GPL-2.0-or-later
   5 .\"
   6 .TH NSSWITCH.CONF 5 2017-05-03 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
   7 .SH NAME
   8 nsswitch.conf \- Name Service Switch configuration file
   9 .SH DESCRIPTION
  10 The Name Service Switch (NSS) configuration file,
  11 .IR /etc/nsswitch.conf ,
  12 is used by the GNU C Library and certain other applications to determine
  13 the sources from which to obtain name-service information in
  14 a range of categories,
  15 and in what order.
  16 Each category of information is identified by a database name.
  17 .PP
  18 The file is plain ASCII text, with columns separated by spaces or tab
  19 characters.
  20 The first column specifies the database name.
  21 The remaining columns describe the order of sources to query and a
  22 limited set of actions that can be performed by lookup result.
  23 .PP
  24 The following databases are understood by the GNU C Library:
  25 .TP 12
  26 .B aliases
  27 Mail aliases, used by
  28 .BR getaliasent (3)
  29 and related functions.
  30 .TP
  31 .B ethers
  32 Ethernet numbers.
  33 .TP
  34 .B group
  35 Groups of users, used by
  36 .BR getgrent (3)
  37 and related functions.
  38 .TP
  39 .B hosts
  40 Host names and numbers, used by
  41 .BR gethostbyname (3)
  42 and related functions.
  43 .TP
  44 .B initgroups
  45 Supplementary group access list, used by
  46 .BR getgrouplist (3)
  47 function.
  48 .TP
  49 .B netgroup
  50 Network-wide list of hosts and users, used for access rules.
  51 C libraries before glibc 2.1 supported netgroups only over NIS.
  52 .TP
  53 .B networks
  54 Network names and numbers, used by
  55 .BR getnetent (3)
  56 and related functions.
  57 .TP
  58 .B passwd
  59 User passwords, used by
  60 .BR getpwent (3)
  61 and related functions.
  62 .TP
  63 .B protocols
  64 Network protocols, used by
  65 .BR getprotoent (3)
  66 and related functions.
  67 .TP
  68 .B publickey
  69 Public and secret keys for Secure_RPC used by NFS and NIS+.
  70 .TP
  71 .B rpc
  72 Remote procedure call names and numbers, used by
  73 .BR getrpcbyname (3)
  74 and related functions.
  75 .TP
  76 .B services
  77 Network services, used by
  78 .BR getservent (3)
  79 and related functions.
  80 .TP
  81 .B shadow
  82 Shadow user passwords, used by
  83 .BR getspnam (3)
  84 and related functions.
  85 .PP
  86 The GNU C Library ignores databases with unknown names.
  87 Some applications use this to implement special handling for their own
  88 databases.
  89 For example,
  90 .BR sudo (8)
  91 consults the
  92 .B sudoers
  93 database.
  94 Delegation of subordinate user/group IDs
  95 can be configured using the
  96 .B subid
  97 database.
  98 Refer to
  99 .BR subuid (5)
 100 and
 101 .BR subgid (5)
 102 for more details.
 103 .PP
 104 Here is an example
 105 .I /etc/nsswitch.conf
 106 file:
 107 .PP
 108 .in +4n
 109 .EX
 110 passwd:         compat
 111 group:          compat
 112 shadow:         compat
 113
 114 hosts:          dns [!UNAVAIL=return] files
 115 networks:       nis [NOTFOUND=return] files
 116 ethers:         nis [NOTFOUND=return] files
 117 protocols:      nis [NOTFOUND=return] files
 118 rpc:            nis [NOTFOUND=return] files
 119 services:       nis [NOTFOUND=return] files
 120 .EE
 121 .in
 122 .PP
 123 The first column is the database name.
 124 The remaining columns specify:
 125 .IP * 3
 126 One or more service specifications, for example, "files", "db", or "nis".
 127 The order of the services on the line determines the order in which
 128 those services will be queried, in turn, until a result is found.
 129 .IP *
 130 Optional actions to perform if a particular result is obtained
 131 from the preceding service, for example, "[NOTFOUND=return]".
 132 .PP
 133 The service specifications supported on your system depend on the
 134 presence of shared libraries, and are therefore extensible.
 135 Libraries called
 136 .IB /lib/libnss_SERVICE.so. X
 137 will provide the named
 138 .IR SERVICE .
 139 On a standard installation, you can use
 140 "files", "db", "nis", and "nisplus".
 141 For the
 142 .B hosts
 143 database, you can additionally specify "dns".
 144 For the
 145 .BR passwd ,
 146 .BR group ,
 147 and
 148 .B shadow
 149 databases, you can additionally specify
 150 "compat" (see
 151 .B "Compatibility mode"
 152 below).
 153 The version number
 154 .B X
 155 may be 1 for glibc 2.0, or 2 for glibc 2.1 and later.
 156 On systems with additional libraries installed, you may have access to
 157 further services such as "hesiod", "ldap", "winbind", and "wins".
 158 .PP
 159 An action may also be specified following a service specification.
 160 The action modifies the behavior following a result obtained
 161 from the preceding data source.
 162 Action items take the general form:
 163 .PP
 164 .RS 4
 165 .RI [ STATUS = ACTION ]
 166 .br
 167 .RI [! STATUS = ACTION ]
 168 .RE
 169 .PP
 170 where
 171 .PP
 172 .RS 4
 173 .I STATUS
 174 =>
 175 .B success
 176 |
 177 .B notfound
 178 |
 179 .B unavail
 180 |
 181 .B tryagain
 182 .br
 183 .I ACTION
 184 =>
 185 .B return
 186 |
 187 .B continue
 188 |
 189 .B merge
 190 .RE
 191 .PP
 192 The ! negates the test, matching all possible results except the
 193 one specified.
 194 The case of the keywords is not significant.
 195 .PP
 196 The
 197 .I STATUS
 198 value is matched against the result of the lookup function called by
 199 the preceding service specification, and can be one of:
 200 .RS 4
 201 .TP 12
 202 .B success
 203 No error occurred and the requested entry is returned.
 204 The default action for this condition is "return".
 205 .TP
 206 .B notfound
 207 The lookup succeeded, but the requested entry was not found.
 208 The default action for this condition is "continue".
 209 .TP
 210 .B unavail
 211 The service is permanently unavailable.
 212 This can mean either that the
 213 required file cannot be read, or, for network services, that the server
 214 is not available or does not allow queries.
 215 The default action for this condition is "continue".
 216 .TP
 217 .B tryagain
 218 The service is temporarily unavailable.
 219 This could mean a file is
 220 locked or a server currently cannot accept more connections.
 221 The default action for this condition is "continue".
 222 .RE
 223 .PP
 224 The
 225 .I ACTION
 226 value can be one of:
 227 .RS 4
 228 .TP 12
 229 .B return
 230 Return a result now.
 231 Do not call any further lookup functions.
 232 However, for compatibility reasons, if this is the selected action for the
 233 .B group
 234 database and the
 235 .B notfound
 236 status, and the configuration file does not contain the
 237 .B initgroups
 238 line, the next lookup function is always called,
 239 without affecting the search result.
 240 .TP
 241 .B continue
 242 Call the next lookup function.
 243 .TP
 244 .B merge
 245 .I [SUCCESS=merge]
 246 is used between two database entries.
 247 When a group is located in the first of the two group entries,
 248 processing will continue on to the next one.
 249 If the group is also found in the next entry (and the group name and GID
 250 are an exact match), the member list of the second entry will be added
 251 to the group object to be returned.
 252 Available since glibc 2.24.
 253 Note that merging will not be done for
 254 .BR getgrent (3)
 255 nor will duplicate members be pruned when they occur in both entries
 256 being merged.
 257 .RE
 258 .SS Compatibility mode (compat)
 259 The NSS "compat" service is similar to "files" except that it
 260 additionally permits special entries in corresponding files
 261 for granting users or members of netgroups access to the system.
 262 The following entries are valid in this mode:
 263 .RS 4
 264 .PP
 265 For
 266 .B passwd
 267 and
 268 .B shadow
 269 databases:
 270 .RS 4
 271 .TP 12
 272 .BI + user
 273 Include the specified
 274 .I user
 275 from the NIS passwd/shadow map.
 276 .TP
 277 .BI +@ netgroup
 278 Include all users in the given
 279 .IR netgroup .
 280 .TP
 281 .BI \- user
 282 Exclude the specified
 283 .I user
 284 from the NIS passwd/shadow map.
 285 .TP
 286 .BI \-@ netgroup
 287 Exclude all users in the given
 288 .IR netgroup .
 289 .TP
 290 .B +
 291 Include every user, except previously excluded ones, from the
 292 NIS passwd/shadow map.
 293 .RE
 294 .PP
 295 For
 296 .B group
 297 database:
 298 .RS 4
 299 .TP 12
 300 .BI + group
 301 Include the specified
 302 .I group
 303 from the NIS group map.
 304 .TP
 305 .BI \- group
 306 Exclude the specified
 307 .I group
 308 from the NIS group map.
 309 .TP
 310 .B +
 311 Include every group, except previously excluded ones, from the
 312 NIS group map.
 313 .RE
 314 .RE
 315 .PP
 316 By default, the source is "nis", but this may be
 317 overridden by specifying any NSS service except "compat" itself
 318 as the source for the pseudo-databases
 319 .BR passwd_compat ,
 320 .BR group_compat ,
 321 and
 322 .BR shadow_compat .
 323 .SH FILES
 324 A service named
 325 .I SERVICE
 326 is implemented by a shared object library named
 327 .IB libnss_SERVICE.so. X
 328 that resides in
 329 .IR /lib .
 330 .RS 4
 331 .TP 25
 332 .PD 0
 333 .I /etc/nsswitch.conf
 334 NSS configuration file.
 335 .TP
 336 .IB /lib/libnss_compat.so. X
 337 implements "compat" source.
 338 .TP
 339 .IB /lib/libnss_db.so. X
 340 implements "db" source.
 341 .TP
 342 .IB /lib/libnss_dns.so. X
 343 implements "dns" source.
 344 .TP
 345 .IB /lib/libnss_files.so. X
 346 implements "files" source.
 347 .TP
 348 .IB /lib/libnss_hesiod.so. X
 349 implements "hesiod" source.
 350 .TP
 351 .IB /lib/libnss_nis.so. X
 352 implements "nis" source.
 353 .TP
 354 .IB /lib/libnss_nisplus.so. X
 355 implements "nisplus" source.
 356 .PD
 357 .RE
 358 .PP
 359 The following files are read when "files" source is specified
 360 for respective databases:
 361 .RS 4
 362 .TP 12
 363 .PD 0
 364 .B aliases
 365 .I /etc/aliases
 366 .TP
 367 .B ethers
 368 .I /etc/ethers
 369 .TP
 370 .B group
 371 .I /etc/group
 372 .TP
 373 .B hosts
 374 .I /etc/hosts
 375 .TP
 376 .B initgroups
 377 .I /etc/group
 378 .TP
 379 .B netgroup
 380 .I /etc/netgroup
 381 .TP
 382 .B networks
 383 .I /etc/networks
 384 .TP
 385 .B passwd
 386 .I /etc/passwd
 387 .TP
 388 .B protocols
 389 .I /etc/protocols
 390 .TP
 391 .B publickey
 392 .I /etc/publickey
 393 .TP
 394 .B rpc
 395 .I /etc/rpc
 396 .TP
 397 .B services
 398 .I /etc/services
 399 .TP
 400 .B shadow
 401 .I /etc/shadow
 402 .PD
 403 .RE
 404 .SH NOTES
 405 Within each process that uses
 406 .BR nsswitch.conf ,
 407 the entire file is read only once.
 408 If the file is later changed, the
 409 process will continue using the old configuration.
 410 .PP
 411 Traditionally, there was only a single source for service information,
 412 often in the form of a single configuration
 413 file (e.g., \fI/etc/passwd\fP).
 414 However, as other name services, such as the Network Information
 415 Service (NIS) and the Domain Name Service (DNS), became popular,
 416 a method was needed
 417 that would be more flexible than fixed search orders coded into
 418 the C library.
 419 The Name Service Switch mechanism,
 420 which was based on the mechanism used by
 421 Sun Microsystems in the Solaris 2 C library,
 422 introduced a cleaner solution to the problem.
 423 .SH SEE ALSO
 424 .BR getent (1),
 425 .BR nss (5)