original/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 2013-02-12 "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 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 .LP
  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 .LP
  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 .LP
 105 Here is an example
 106 .I /etc/nsswitch.conf
 107 file:
 108 .LP
 109 .RS 4
 110 .PD 0
 111 .TP 16
 112 passwd:
 113 compat
 114 .TP
 115 group:
 116 compat
 117 .TP
 118 shadow:
 119 compat
 120 .sp 1n
 121 .TP
 122 hosts:
 123 dns [!UNAVAIL=return] files
 124 .TP
 125 networks:
 126 nis [NOTFOUND=return] files
 127 .TP
 128 ethers:
 129 nis [NOTFOUND=return] files
 130 .TP
 131 protocols:
 132 nis [NOTFOUND=return] files
 133 .TP
 134 rpc:
 135 nis [NOTFOUND=return] files
 136 .TP
 137 services:
 138 nis [NOTFOUND=return] files
 139 .PD
 140 .RE
 141 .LP
 142 The first column is the database name.
 143 The remaining columns specify:
 144 .IP * 3
 145 One or more service specifications, for example, "files", "db", or "nis".
 146 The order of the services on the line determines the order in which
 147 those services will be queried, in turn, until a result is found.
 148 .IP *
 149 Optional actions to perform if a particular result is obtained
 150 from the preceding service, for example, "[NOTFOUND=return]".
 151 .LP
 152 The service specifications supported on your system depend on the
 153 presence of shared libraries, and are therefore extensible.
 154 Libraries called
 155 .IB /lib/libnss_SERVICE.so. X
 156 will provide the named
 157 .IR SERVICE .
 158 On a standard installation, you can use
 159 "files", "db", "nis", and "nisplus".
 160 For the
 161 .B hosts
 162 database, you can additionally specify "dns".
 163 For the
 164 .BR passwd ,
 165 .BR group ,
 166 and
 167 .BR shadow
 168 databases, you can additionally specify
 169 "compat" (see
 170 .B "Compatibility mode"
 171 below).
 172 The version number
 173 .B X
 174 may be 1 for glibc 2.0, or 2 for glibc 2.1 and later.
 175 On systems with additional libraries installed, you may have access to
 176 further services such as "hesiod", "ldap", "winbind" and "wins".
 177 .LP
 178 An action may also be specified following a service specification.
 179 The action modifies the behavior following a result obtained
 180 from the preceding data source.
 181 Action items take the general form:
 182 .LP
 183 .RS 4
 184 .RI [ STATUS = ACTION ]
 185 .br
 186 .RI [! STATUS = ACTION ]
 187 .RE
 188 .LP
 189 where
 190 .LP
 191 .RS 4
 192 .I STATUS
 193 =>
 194 .B success
 195 |
 196 .B notfound
 197 |
 198 .B unavail
 199 |
 200 .B tryagain
 201 .br
 202 .I ACTION
 203 =>
 204 .B return
 205 |
 206 .B continue
 207 .RE
 208 .LP
 209 The ! negates the test, matching all possible results except the
 210 one specified.
 211 The case of the keywords is not significant.
 212 .LP
 213 The
 214 .I STATUS
 215 value is matched against the result of the lookup function called by
 216 the preceding service specification, and can be one of:
 217 .RS 4
 218 .TP 12
 219 .B success
 220 No error occurred and the requested entry is returned.
 221 The default action for this condition is "return".
 222 .TP
 223 .B notfound
 224 The lookup succeeded, but the requested entry was not found.
 225 The default action for this condition is "continue".
 226 .TP
 227 .B unavail
 228 The service is permanently unavailable.
 229 This can mean either that the
 230 required file cannot be read, or, for network services, that the server
 231 is not available or does not allow queries.
 232 The default action for this condition is "continue".
 233 .TP
 234 .B tryagain
 235 The service is temporarily unavailable.
 236 This could mean a file is
 237 locked or a server currently cannot accept more connections.
 238 The default action for this condition is "continue".
 239 .RE
 240 .LP
 241 The
 242 .I ACTION
 243 value can be one of:
 244 .RS 4
 245 .TP 12
 246 .B return
 247 Return a result now.
 248 Do not call any further lookup functions.
 249 However, for compatibility reasons, if this is the selected action for the
 250 .B group
 251 database and the
 252 .B notfound
 253 status, and the configuration file does not contain the
 254 .B initgroups
 255 line, the next lookup function is always called,
 256 without affecting the search result.
 257 .TP
 258 .B continue
 259 Call the next lookup function.
 260 .RE
 261 .SS Compatibility mode (compat)
 262 The NSS "compat" service is similar to "files" except that it
 263 additionally permits special entries in
 264 .I /etc/passwd
 265 for granting users or members of netgroups access to the system.
 266 The following entries are valid in this mode:
 267 .RS 4
 268 .TP 12
 269 .BI + user
 270 Include the specified
 271 .I user
 272 from the NIS passwd map.
 273 .TP
 274 .BI +@ netgroup
 275 Include all users in the given
 276 .IR netgroup .
 277 .TP
 278 .BI \- user
 279 Exclude the specified
 280 .I user
 281 from the NIS passwd map.
 282 .TP
 283 .BI \-@ netgroup
 284 Exclude all users in the given
 285 .IR netgroup .
 286 .TP
 287 .B +
 288 Include every user, except previously excluded ones, from the
 289 NIS passwd map.
 290 .RE
 291 .LP
 292 By default the source is "nis", but this may be
 293 overridden by specifying "nisplus" as the source for the pseudo-databases
 294 .BR passwd_compat ,
 295 .BR group_compat ,
 296 and
 297 .BR shadow_compat .
 298 .SH FILES
 299 A service named
 300 .I SERVICE
 301 is implemented by a shared object library named
 302 .IB libnss_SERVICE.so. X
 303 that resides in
 304 .IR /lib .
 305 .RS 4
 306 .TP 25
 307 .PD 0
 308 .I /etc/nsswitch.conf
 309 NSS configuration file.
 310 .TP
 311 .IB /lib/libnss_compat.so. X
 312 implements "compat" source.
 313 .TP
 314 .IB /lib/libnss_db.so. X
 315 implements "db" source.
 316 .TP
 317 .IB /lib/libnss_dns.so. X
 318 implements "dns" source.
 319 .TP
 320 .IB /lib/libnss_files.so. X
 321 implements "files" source.
 322 .TP
 323 .IB /lib/libnss_hesiod.so. X
 324 implements "hesiod" source.
 325 .TP
 326 .IB /lib/libnss_nis.so. X
 327 implements "nis" source.
 328 .TP
 329 .IB /lib/libnss_nisplus.so. X
 330 implements "nisplus" source.
 331 .PD
 332 .RE
 333 .SH NOTES
 334 Within each process that uses
 335 .BR nsswitch.conf ,
 336 the entire file is read only once.
 337 If the file is later changed, the
 338 process will continue using the old configuration.
 339 .LP
 340 Traditionally, there was only a single source for service information,
 341 often in the form of a single configuration
 342 file (e.g., \fI/etc/passwd\fP).
 343 However, as other name services, such as the Network Information
 344 Service (NIS) and the Domain Name Service (DNS), became popular,
 345 a method was needed
 346 that would be more flexible than fixed search orders coded into
 347 the C library.
 348 The Name Service Switch mechanism,
 349 which was based on the mechanism used by
 350 Sun Microsystems in the Solaris 2 C library,
 351 introduced a cleaner solution to the problem.
 352 .SH SEE ALSO
 353 .BR getent (1),
 354 .BR nss (5)
 355 .SH COLOPHON
 356 This page is part of release 3.79 of the Linux
 357 .I man-pages
 358 project.
 359 A description of the project,
 360 information about reporting bugs,
 361 and the latest version of this page,
 362 can be found at
 363 \%http://www.kernel.org/doc/man\-pages/.