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