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