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