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