manual/LDP_man-pages/original/man5/nsswitch.conf.5

   1 .\" Copyright (c) 1998, 1999 Thorsten Kukuk (kukuk@vt.uni-paderborn.de)
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" The GNU General Public License's references to "object code"
   9 .\" and "executables" are to be interpreted as the output of any
  10 .\" document formatting or typesetting system, including
  11 .\" intermediate and printed output.
  12 .\"
  13 .\" This manual is distributed in the hope that it will be useful,
  14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 .\" GNU General Public License for more details.
  17 .\"
  18 .\" You should have received a copy of the GNU General Public
  19 .\" License along with this manual; if not, write to the Free
  20 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  21 .\" USA.
  22 .\"
  23 .\" This manual page based on the GNU C Library info pages.
  24 .\" FIXME ? The use of quotes on this page is inconsistent with the
  25 .\" rest of man-pages.
  26 .\"
  27 .TH NSSWITCH.CONF 5 1999-01-17 "Linux" "Linux Programmer's Manual"
  28 .SH NAME
  29 nsswitch.conf \- System Databases and Name Service Switch configuration file
  30 .SH DESCRIPTION
  31 Various functions in the C Library need to be configured to work
  32 correctly in the local environment.
  33 Traditionally, this was done by
  34 using files (e.g., \fI/etc/passwd\fP), but other nameservices (like the
  35 Network Information Service (NIS) and the Domain Name Service (DNS))
  36 became popular, and were hacked into the C library, usually with a fixed
  37 search order.
  38 .LP
  39 The Linux libc5 with NYS support and the GNU C Library 2.x (libc.so.6)
  40 contain a cleaner solution of this problem.
  41 It is designed after a method
  42 used by Sun Microsystems in the C library of Solaris 2.
  43 We follow their
  44 name and call this scheme "Name Service Switch" (NSS).
  45 The sources for
  46 the "databases" and their lookup order are specified in the
  47 .I /etc/nsswitch.conf
  48 file.
  49 .LP
  50 The following databases are available in the NSS:
  51 .TP
  52 .B aliases
  53 Mail aliases, used by
  54 .BR sendmail (8).
  55 Presently ignored.
  56 .TP
  57 .B ethers
  58 Ethernet numbers.
  59 .TP
  60 .B group
  61 Groups of users, used by
  62 .BR getgrent (3)
  63 functions.
  64 .TP
  65 .B hosts
  66 Host names and numbers, used by
  67 .BR gethostbyname (3)
  68 and similar functions.
  69 .TP
  70 .B netgroup
  71 Network wide list of hosts and users, used for access rules.
  72 C libraries before glibc 2.1 only support netgroups over NIS.
  73 .TP
  74 .B networks
  75 Network names and numbers, used by
  76 .BR getnetent (3)
  77 functions.
  78 .TP
  79 .B passwd
  80 User passwords, used by
  81 .BR getpwent (3)
  82 functions.
  83 .TP
  84 .B protocols
  85 Network protocols, used by
  86 .BR getprotoent (3)
  87 functions.
  88 .TP
  89 .B publickey
  90 Public and secret keys for Secure_RPC used by NFS and NIS+.
  91 .TP
  92 .B rpc
  93 Remote procedure call names and numbers, used by
  94 .BR getrpcbyname (3)
  95 and similar functions.
  96 .TP
  97 .B services
  98 Network services, used by
  99 .BR getservent (3)
 100 functions.
 101 .TP
 102 .B shadow
 103 Shadow user passwords, used by
 104 .BR getspnam (3).
 105 .LP
 106 An example
 107 .I /etc/nsswitch.conf
 108 (namely, the default used when
 109 .I /etc/nsswitch.conf
 110 is missing):
 111 .sp 1n
 112 .PD 0
 113 .TP 16
 114 passwd:
 115 compat
 116 .TP
 117 group:
 118 compat
 119 .TP
 120 shadow:
 121 compat
 122 .sp 1n
 123 .TP
 124 hosts:
 125 dns [!UNAVAIL=return] files
 126 .TP
 127 networks:
 128 nis [NOTFOUND=return] files
 129 .TP
 130 ethers:
 131 nis [NOTFOUND=return] files
 132 .TP
 133 protocols:
 134 nis [NOTFOUND=return] files
 135 .TP
 136 rpc:
 137 nis [NOTFOUND=return] files
 138 .TP
 139 services:
 140 nis [NOTFOUND=return] files
 141 .PD
 142 .LP
 143 The first column is the database.
 144 The rest of the line specifies how the lookup process works.
 145 You can specify the way it works for each database individually.
 146 .LP
 147 The configuration specification for each database can contain two
 148 different items:
 149 .PD 0
 150 .TP
 151 * The service specification like `files', `db', or `nis'.
 152 .TP
 153 * The reaction on lookup result like `[NOTFOUND=return]'.
 154 .PD
 155 .LP
 156 For libc5 with NYS, the allowed service specifications are `files', `nis',
 157 and `nisplus'.
 158 For hosts, you could specify `dns' as extra service, for
 159 passwd and group `compat', but not for shadow.
 160 .LP
 161 For glibc, you must have a file called
 162 .BI /lib/libnss_SERVICE.so. X
 163 for every SERVICE you are using.
 164 On a standard installation, you could use
 165 `files', `db', `nis', and `nisplus'.
 166 For hosts, you could specify `dns' as
 167 extra service, for passwd, group, and shadow `compat'.
 168 These services will not
 169 be used by libc5 with NYS.
 170 The version number
 171 .I X
 172 is 1 for glibc 2.0 and 2 for glibc 2.1.
 173 .LP
 174 The second item in the specification gives the user much finer
 175 control on the lookup process.
 176 Action items are placed between two
 177 service names and are written within brackets.
 178 The general form is
 179 .LP
 180 `[' ( `!'? STATUS `=' ACTION )+ `]'
 181 .LP
 182 where
 183 .sp 1n
 184 .PD 0
 185 .TP
 186 STATUS => success | notfound | unavail | tryagain
 187 .TP
 188 ACTION => return | continue
 189 .PD
 190 .LP
 191 The case of the keywords is insignificant.
 192 The STATUS values are
 193 the results of a call to a lookup function of a specific service.
 194 They mean:
 195 .TP
 196 .B success
 197 No error occurred and the wanted entry is returned.
 198 The default
 199 action for this is `return'.
 200 .TP
 201 .B notfound
 202 The lookup process works ok but the needed value was not found.
 203 The default action is `continue'.
 204 .TP
 205 .B unavail
 206 The service is permanently unavailable.
 207 This can either mean the
 208 needed file is not available, or, for DNS, the server is not
 209 available or does not allow queries.
 210 The default action is
 211 `continue'.
 212 .TP
 213 .B tryagain
 214 The service is temporarily unavailable.
 215 This could mean a file is
 216 locked or a server currently cannot accept more connections.
 217 The default action is `continue'.
 218 .SS Interaction with +/\- syntax (compat mode)
 219 Linux libc5 without NYS does not have the name service switch but does
 220 allow the user some policy control.
 221 In
 222 .I /etc/passwd
 223 you could have entries of the form +user or +@netgroup
 224 (include the specified user from the NIS passwd map),
 225 \-user or \-@netgroup (exclude the specified user),
 226 and + (include every user, except the excluded ones, from the NIS
 227 passwd map).
 228 Since most people only put a + at the end of
 229 .I /etc/passwd
 230 to include everything from NIS, the switch provides a faster
 231 alternative for this case (`passwd: files nis') which doesn't
 232 require the single + entry in
 233 .IR /etc/passwd ,
 234 .IR /etc/group ,
 235 and
 236 .IR /etc/shadow .
 237 If this is not sufficient, the NSS `compat' service provides full
 238 +/\- semantics.
 239 By default, the source is `nis', but this may be
 240 overridden by specifying `nisplus' as source for the pseudo-databases
 241 .BR passwd_compat ,
 242 .B group_compat
 243 and
 244 .BR shadow_compat .
 245 These pseudo-databases are only available in GNU C Library.
 246 .SH FILES
 247 A service named SERVICE is implemented by a shared object library named
 248 .BI libnss_SERVICE.so. X
 249 that resides in
 250 .IR /lib .
 251 .TP 25
 252 .PD 0
 253 .I /etc/nsswitch.conf
 254 configuration file
 255 .TP
 256 .BI /lib/libnss_compat.so. X
 257 implements `compat' source for glibc2
 258 .TP
 259 .BI /lib/libnss_db.so. X
 260 implements `db' source for glibc2
 261 .TP
 262 .BI /lib/libnss_dns.so. X
 263 implements `dns' source for glibc2
 264 .TP
 265 .BI /lib/libnss_files.so. X
 266 implements `files' source for glibc2
 267 .TP
 268 .BI /lib/libnss_hesiod.so. X
 269 implements `hesiod' source for glibc2
 270 .TP
 271 .BI /lib/libnss_nis.so. X
 272 implements `nis' source for glibc2
 273 .TP
 274 .I /lib/libnss_nisplus.so.2
 275 implements `nisplus' source for glibc 2.1
 276 .PD
 277 .SH NOTES
 278 Within each process that uses
 279 .BR nsswitch.conf ,
 280 the entire file is read only once; if the file is later changed, the
 281 process will continue using the old configuration.
 282 .LP
 283 With Solaris, it isn't possible to link programs using the NSS Service
 284 statically.
 285 With Linux, this is no problem.