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