nis.subproj/yp.8

   1 .\" Copyright (c) 1992/3 Theo de Raadt <deraadt@fsa.ca>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. The name of the author may not be used to endorse or promote
  13 .\"    products derived from this software without specific prior written
  14 .\"    permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
  17 .\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  18 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
  20 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     from: @(#)yp.8  1.0 (deraadt) 4/26/93
  29 .\" $FreeBSD: src/share/man/man8/yp.8,v 1.36 2005/01/21 08:36:40 ru Exp $
  30 .\"
  31 .Dd April 5, 1993
  32 .Dt YP 8
  33 .Os
  34 .Sh NAME
  35 .Nm yp
  36 .Nd description of the YP/NIS system
  37 .Sh SYNOPSIS
  38 .Nm
  39 .Sh DESCRIPTION
  40 The
  41 .Nm YP
  42 subsystem allows network management of passwd, group, netgroup, hosts,
  43 services, rpc, bootparams and ethers file
  44 entries through the functions
  45 .Xr getpwent 3 ,
  46 .Xr getgrent 3 ,
  47 .Xr getnetgrent 3 ,
  48 .Xr gethostent 3 ,
  49 .Xr getnetent 3 ,
  50 .Xr getrpcent 3 ,
  51 and
  52 .Xr ethers 3 .
  53 The
  54 .Xr bootparamd 8
  55 daemon makes direct
  56 .Tn NIS
  57 library calls since there are no
  58 functions in the standard C library for reading bootparams.
  59 .Tn NIS
  60 support is enabled in
  61 .Xr nsswitch.conf 5 .
  62 .Pp
  63 The
  64 .Nm YP
  65 subsystem is started automatically by
  66 .Xr launchd 8
  67 if an
  68 .Tn NIS
  69 domain is specified in the
  70 .Pa /etc/defaultdomain
  71 configuration file,
  72 and if the directory
  73 .Pa /var/yp
  74 exists (which it does in the default distribution).
  75 .Pp
  76 .Tn NIS
  77 is an
  78 .Tn RPC Ns -based
  79 client/server system that allows a group of
  80 machines within an
  81 .Tn NIS
  82 domain to share a common set of configuration files.
  83 This permits a system
  84 administrator to set up
  85 .Tn NIS
  86 client systems with only minimal configuration
  87 data and add, remove or modify configuration data from a single location.
  88 .Pp
  89 The canonical copies of all
  90 .Tn NIS
  91 information are stored on a single machine
  92 called the
  93 .Tn NIS
  94 .Em "master server" .
  95 The databases used to store the information are called
  96 .Tn NIS
  97 .Em maps .
  98 In
  99 .Fx ,
 100 these maps are stored in
 101 .Pa /var/yp/ Ns Aq Ar domainname
 102 where
 103 .Aq Ar domainname
 104 is the name of the
 105 .Tn NIS
 106 domain being served.
 107 A single
 108 .Tn NIS
 109 server can
 110 support several domains at once, therefore it is possible to have several
 111 such directories, one for each supported domain.
 112 Each domain will have
 113 its own independent set of maps.
 114 .Pp
 115 In
 116 .Fx ,
 117 the
 118 .Tn NIS
 119 maps are Berkeley DB hashed database files (the
 120 same format used for the
 121 .Xr passwd 5
 122 database files).
 123 Other operating systems that support
 124 .Tn NIS
 125 use old-style
 126 .Nm ndbm
 127 databases instead (largely because Sun Microsystems originally based
 128 their
 129 .Tn NIS
 130 implementation on
 131 .Nm ndbm ,
 132 and other vendors have simply licensed
 133 Sun's code rather than design their own implementation with a different
 134 database format).
 135 On these systems, the databases are generally split
 136 into
 137 .Pa .dir
 138 and
 139 .Pa .pag
 140 files which the
 141 .Nm ndbm
 142 code uses to hold separate parts of the hash
 143 database.
 144 The Berkeley DB hash method instead uses a single file for
 145 both pieces of information.
 146 This means that while you may have
 147 .Pa passwd.byname.dir
 148 and
 149 .Pa passwd.byname.pag
 150 files on other operating systems (both of which are really parts of the
 151 same map),
 152 .Fx
 153 will have only one file called
 154 .Pa passwd.byname .
 155 The difference in format is not significant: only the
 156 .Tn NIS
 157 server,
 158 .Xr ypserv 8 ,
 159 and related tools need to know the database format of the
 160 .Tn NIS
 161 maps.
 162 Client
 163 .Tn NIS
 164 systems receive all
 165 .Tn NIS
 166 data in
 167 .Tn ASCII
 168 form.
 169 .Pp
 170 There are three main types of
 171 .Tn NIS
 172 systems:
 173 .Bl -enum
 174 .It
 175 .Tn NIS
 176 clients,
 177 which query
 178 .Tn NIS
 179 servers for information.
 180 .It
 181 .Tn NIS
 182 master servers,
 183 which maintain the canonical copies of all
 184 .Tn NIS
 185 maps.
 186 .It
 187 .Tn NIS
 188 slave servers,
 189 which maintain backup copies of
 190 .Tn NIS
 191 maps that are periodically
 192 updated by the master.
 193 .El
 194 .Pp
 195 A
 196 .Tn NIS
 197 client establishes what is called a
 198 .Em binding
 199 to a particular
 200 .Tn NIS
 201 server using the
 202 .Xr ypbind 8
 203 daemon.
 204 The
 205 .Xr ypbind 8
 206 utility checks the system's default domain (as set by the
 207 .Xr domainname 1
 208 command) and begins broadcasting
 209 .Tn RPC
 210 requests on the local network.
 211 These requests specify the name of the domain for which
 212 .Xr ypbind 8
 213 is attempting to establish a binding.
 214 If a server that has been
 215 configured to serve the requested domain receives one of the broadcasts,
 216 it will respond to
 217 .Xr ypbind 8 ,
 218 which will record the server's address.
 219 If there are several servers
 220 available (a master and several slaves, for example),
 221 .Xr ypbind 8
 222 will use the address of the first one to respond.
 223 From that point
 224 on, the client system will direct all of its
 225 .Tn NIS
 226 requests to that server.
 227 The
 228 .Xr ypbind 8
 229 utility will occasionally
 230 .Dq ping
 231 the server to make sure it is still up
 232 and running.
 233 If it fails to receive a reply to one of its pings
 234 within a reasonable amount of time,
 235 .Xr ypbind 8
 236 will mark the domain as unbound and begin broadcasting again in the
 237 hopes of locating another server.
 238 .Pp
 239 .Tn NIS
 240 master and slave servers handle all
 241 .Tn NIS
 242 requests with the
 243 .Xr ypserv 8
 244 daemon.
 245 The
 246 .Xr ypserv 8
 247 utility is responsible for receiving incoming requests from
 248 .Tn NIS
 249 clients,
 250 translating the requested domain and map name to a path to the
 251 corresponding database file and transmitting data from the database
 252 back to the client.
 253 There is a specific set of requests that
 254 .Xr ypserv 8
 255 is designed to handle, most of which are implemented as functions
 256 within the standard C library:
 257 .Bl -tag -width ".Fn yp_master"
 258 .It Fn yp_order
 259 check the creation date of a particular map
 260 .It Fn yp_master
 261 obtain the name of the
 262 .Tn NIS
 263 master server for a given
 264 map/domain
 265 .It Fn yp_match
 266 lookup the data corresponding to a given in key in a particular
 267 map/domain
 268 .It Fn yp_first
 269 obtain the first key/data pair in a particular map/domain
 270 .It Fn yp_next
 271 pass
 272 .Xr ypserv 8
 273 a key in a particular map/domain and have it return the
 274 key/data pair immediately following it (the functions
 275 .Fn yp_first
 276 and
 277 .Fn yp_next
 278 can be used to do a sequential search of an
 279 .Tn NIS
 280 map)
 281 .It Fn yp_all
 282 retrieve the entire contents of a map
 283 .El
 284 .Pp
 285 There are a few other requests which
 286 .Xr ypserv 8
 287 is capable of handling (i.e., acknowledge whether or not you can handle
 288 a particular domain
 289 .Pq Dv YPPROC_DOMAIN ,
 290 or acknowledge only if you can handle the domain and be silent otherwise
 291 .Pq Dv YPPROC_DOMAIN_NONACK )
 292 but
 293 these requests are usually generated only by
 294 .Xr ypbind 8
 295 and are not meant to be used by standard utilities.
 296 .Pp
 297 On networks with a large number of hosts, it is often a good idea to
 298 use a master server and several slaves rather than just a single master
 299 server.
 300 A slave server provides the exact same information as a master
 301 server: whenever the maps on the master server are updated, the new
 302 data should be propagated to the slave systems using the
 303 .Xr yppush 8
 304 command.
 305 The
 306 .Tn NIS
 307 .Pa Makefile
 308 .Pq Pa /var/yp/Makefile
 309 will do this automatically if the administrator comments out the
 310 line which says
 311 .Dq Li NOPUSH=true
 312 .Va ( NOPUSH
 313 is set to true by default because the default configuration is
 314 for a small network with only one
 315 .Tn NIS
 316 server).
 317 The
 318 .Xr yppush 8
 319 command will initiate a transaction between the master and slave
 320 during which the slave will transfer the specified maps from the
 321 master server using
 322 .Xr ypxfr 8 .
 323 (The slave server calls
 324 .Xr ypxfr 8
 325 automatically from within
 326 .Xr ypserv 8 ;
 327 therefore it is not usually necessary for the administrator
 328 to use it directly.
 329 It can be run manually if
 330 desired, however.)
 331 Maintaining
 332 slave servers helps improve
 333 .Tn NIS
 334 performance on large
 335 networks by:
 336 .Bl -bullet
 337 .It
 338 Providing backup services in the event that the
 339 .Tn NIS
 340 master crashes
 341 or becomes unreachable
 342 .It
 343 Spreading the client load out over several machines instead of
 344 causing the master to become overloaded
 345 .It
 346 Allowing a single
 347 .Tn NIS
 348 domain to extend beyond
 349 a local network (the
 350 .Xr ypbind 8
 351 daemon might not be able to locate a server automatically if it resides on
 352 a network outside the reach of its broadcasts.
 353 It is possible to force
 354 .Xr ypbind 8
 355 to bind to a particular server with
 356 .Xr ypset 8
 357 but this is sometimes inconvenient.
 358 This problem can be avoided simply by
 359 placing a slave server on the local network.)
 360 .El
 361 .Pp
 362 The
 363 .Fx
 364 .Xr ypserv 8
 365 is specially designed to provide enhanced security (compared to
 366 other
 367 .Tn NIS
 368 implementations) when used exclusively with
 369 .Fx
 370 client
 371 systems.
 372 The
 373 .Fx
 374 password database system (which is derived directly
 375 from
 376 .Bx 4.4 )
 377 includes support for
 378 .Em "shadow passwords" .
 379 The standard password database does not contain users' encrypted
 380 passwords: these are instead stored (along with other information)
 381 in a separate database which is accessible only by the super-user.
 382 If the encrypted password database were made available as an
 383 .Tn NIS
 384 map, this security feature would be totally disabled, since any user
 385 is allowed to retrieve
 386 .Tn NIS
 387 data.
 388 .Pp
 389 To help prevent this,
 390 .Fx Ns 's
 391 .Tn NIS
 392 server handles the shadow password maps
 393 .Pa ( master.passwd.byname
 394 and
 395 .Pa master.passwd.byuid )
 396 in a special way: the server will only provide access to these
 397 maps in response to requests that originate on privileged ports.
 398 Since only the super-user is allowed to bind to a privileged port,
 399 the server assumes that all such requests come from privileged
 400 users.
 401 All other requests are denied: requests from non-privileged
 402 ports will receive only an error code from the server.
 403 Additionally,
 404 .Fx Ns 's
 405 .Xr ypserv 8
 406 includes support for
 407 .An Wietse Venema Ns 's
 408 tcp wrapper package; with tcp
 409 wrapper support enabled, the administrator can configure
 410 .Xr ypserv 8
 411 to respond only to selected client machines.
 412 .Pp
 413 While these enhancements provide better security than stock
 414 .Tn NIS ,
 415 they are by no means 100% effective.
 416 It is still possible for
 417 someone with access to your network to spoof the server into disclosing
 418 the shadow password maps.
 419 .Pp
 420 On the client side,
 421 .Fx Ns 's
 422 .Xr getpwent 3
 423 functions will automatically search for the
 424 .Pa master.passwd
 425 maps and use them if they exist.
 426 If they do, they will be used, and
 427 all fields in these special maps (class, password age and account
 428 expiration) will be decoded.
 429 If they are not found, the standard
 430 .Pa passwd
 431 maps will be used instead.
 432 .Sh COMPATIBILITY
 433 When using a
 434 .No non- Ns Fx
 435 .Tn NIS
 436 server for
 437 .Xr passwd 5
 438 files, it is unlikely that the default MD5-based format that
 439 .Fx
 440 uses for passwords will be accepted by it.
 441 If this is the case, the value of the
 442 .Va passwd_format
 443 setting in
 444 .Xr login.conf 5
 445 should be changed to
 446 .Qq Li des
 447 for compatibility.
 448 .Pp
 449 Some systems, such as
 450 .Tn SunOS
 451 4.x, need
 452 .Tn NIS
 453 to be running in order
 454 for their hostname resolution functions
 455 .Fn ( gethostbyname ,
 456 .Fn gethostbyaddr ,
 457 etc.) to work properly.
 458 On these systems,
 459 .Xr ypserv 8
 460 performs
 461 .Tn DNS
 462 lookups when asked to return information about
 463 a host that does not exist in its
 464 .Pa hosts.byname
 465 or
 466 .Pa hosts.byaddr
 467 maps.
 468 .Fx Ns 's
 469 resolver uses
 470 .Tn DNS
 471 by default (it can be made to use
 472 .Tn NIS ,
 473 if desired), therefore its
 474 .Tn NIS
 475 server does not do
 476 .Tn DNS
 477 lookups
 478 by default.
 479 However,
 480 .Xr ypserv 8
 481 can be made to perform
 482 .Tn DNS
 483 lookups if it is started with a special
 484 flag.
 485 It can also be made to register itself as an
 486 .Tn NIS
 487 v1 server
 488 in order to placate certain systems that insist on the presence of
 489 a v1 server
 490 .No ( Fx
 491 uses only
 492 .Tn NIS
 493 v2, but many other systems,
 494 including
 495 .Tn SunOS
 496 4.x, search for both a v1 and v2 server when binding).
 497 .Fx Ns 's
 498 .Xr ypserv 8
 499 does not actually handle
 500 .Tn NIS
 501 v1 requests, but this
 502 .Dq "kludge mode"
 503 is useful for silencing stubborn systems that search for both
 504 a v1 and v2 server.
 505 .Pp
 506 (Please see the
 507 .Xr ypserv 8
 508 manual page for a detailed description of these special features
 509 and flags.)
 510 .Sh HISTORY
 511 The
 512 .Nm YP
 513 subsystem was written from the ground up by
 514 .An Theo de Raadt
 515 to be compatible to Sun's implementation.
 516 Bug fixes, improvements
 517 and
 518 .Tn NIS
 519 server support were later added by
 520 .An Bill Paul .
 521 The server-side code was originally written by
 522 .An Peter Eriksson
 523 and
 524 .An Tobias Reber
 525 and is subject to the GNU Public License.
 526 No Sun code was
 527 referenced.
 528 .Sh BUGS
 529 While
 530 .Fx
 531 now has both
 532 .Tn NIS
 533 client and server capabilities, it does not yet have support for
 534 .Xr ypupdated 8
 535 or the
 536 .Fn yp_update
 537 function.
 538 Both of these require secure
 539 .Tn RPC ,
 540 which
 541 .Fx
 542 does not
 543 support yet either.
 544 .Pp
 545 The
 546 .Xr getservent 3
 547 and
 548 .Xr getprotoent 3
 549 functions do not yet have
 550 .Tn NIS
 551 support.
 552 Fortunately, these files
 553 do not need to be updated that often.
 554 .Pp
 555 Many more manual pages should be written, especially
 556 .Xr ypclnt 3 .
 557 For the time being, seek out a local Sun machine and read the
 558 manuals for there.
 559 .Pp
 560 Neither Sun nor this author have found a clean way to handle
 561 the problems that occur when ypbind cannot find its server
 562 upon bootup.