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