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