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