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 June 25, 2009
  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 creates
 314 .Pa /var/yp/Makefile.local
 315 and empties the
 316 .Va NOPUSH
 317 variable:
 318 .Bd -literal -offset four
 319 .Li NOPUSH=
 320 .Ed
 321 .Pp
 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 (the
 360 .Xr ypbind 8
 361 daemon might not be able to locate a server automatically if it resides on
 362 a network outside the reach of its broadcasts.
 363 It is possible to force
 364 .Xr ypbind 8
 365 to bind to a particular server with
 366 .Xr ypset 8
 367 but this is sometimes inconvenient.
 368 This problem can be avoided simply by
 369 placing a slave server on the local network.)
 370 .El
 371 .Pp
 372 The
 373 .Fx
 374 .Xr ypserv 8
 375 is specially designed to provide enhanced security (compared to
 376 other
 377 .Tn NIS
 378 implementations) when used exclusively with
 379 .Fx
 380 client
 381 systems.
 382 The
 383 .Fx
 384 password database system (which is derived directly
 385 from
 386 .Bx 4.4 )
 387 includes support for
 388 .Em "shadow passwords" .
 389 The standard password database does not contain users' encrypted
 390 passwords: these are instead stored (along with other information)
 391 in a separate database which is accessible only by the super-user.
 392 If the encrypted password database were made available as an
 393 .Tn NIS
 394 map, this security feature would be totally disabled, since any user
 395 is allowed to retrieve
 396 .Tn NIS
 397 data.
 398 .Pp
 399 To help prevent this,
 400 .Fx Ns 's
 401 .Tn NIS
 402 server handles the shadow password maps
 403 .Pa ( master.passwd.byname ,
 404 .Pa master.passwd.byuid ,
 405 .Pa shadow.byname
 406 and
 407 .Pa shadow.byuid )
 408 in a special way: the server will only provide access to these
 409 maps in response to requests that originate on privileged ports.
 410 Since only the super-user is allowed to bind to a privileged port,
 411 the server assumes that all such requests come from privileged
 412 users.
 413 All other requests are denied: requests from non-privileged
 414 ports will receive only an error code from the server.
 415 Additionally,
 416 .Fx Ns 's
 417 .Xr ypserv 8
 418 includes support for
 419 .An Wietse Venema Ns 's
 420 tcp wrapper package; with tcp
 421 wrapper support enabled, the administrator can configure
 422 .Xr ypserv 8
 423 to respond only to selected client machines.
 424 .Pp
 425 While these enhancements provide better security than stock
 426 .Tn NIS ,
 427 they are by no means 100% effective.
 428 It is still possible for
 429 someone with access to your network to spoof the server into disclosing
 430 the shadow password maps.
 431 .Pp
 432 On the client side,
 433 .Fx Ns 's
 434 .Xr getpwent 3
 435 functions will automatically search for the
 436 .Pa master.passwd
 437 maps and use them if they exist.
 438 If they do, they will be used, and
 439 all fields in these special maps (class, password age and account
 440 expiration) will be decoded.
 441 If they are not found, the standard
 442 .Pa passwd
 443 maps will be used instead.
 444 .Sh COMPATIBILITY
 445 When using a
 446 .No non- Ns Fx
 447 .Tn NIS
 448 server for
 449 .Xr passwd 5
 450 files, it is unlikely that the default MD5-based format that
 451 .Fx
 452 uses for passwords will be accepted by it.
 453 If this is the case, the value of the
 454 .Va passwd_format
 455 setting in
 456 .Xr login.conf 5
 457 should be changed to
 458 .Qq Li des
 459 for compatibility.
 460 .Pp
 461 Some systems, such as
 462 .Tn SunOS
 463 4.x, need
 464 .Tn NIS
 465 to be running in order
 466 for their hostname resolution functions
 467 .Fn ( gethostbyname ,
 468 .Fn gethostbyaddr ,
 469 etc.) to work properly.
 470 On these systems,
 471 .Xr ypserv 8
 472 performs
 473 .Tn DNS
 474 lookups when asked to return information about
 475 a host that does not exist in its
 476 .Pa hosts.byname
 477 or
 478 .Pa hosts.byaddr
 479 maps.
 480 .Fx Ns 's
 481 resolver uses
 482 .Tn DNS
 483 by default (it can be made to use
 484 .Tn NIS ,
 485 if desired), therefore its
 486 .Tn NIS
 487 server does not do
 488 .Tn DNS
 489 lookups
 490 by default.
 491 However,
 492 .Xr ypserv 8
 493 can be made to perform
 494 .Tn DNS
 495 lookups if it is started with a special
 496 flag.
 497 It can also be made to register itself as an
 498 .Tn NIS
 499 v1 server
 500 in order to placate certain systems that insist on the presence of
 501 a v1 server
 502 .No ( Fx
 503 uses only
 504 .Tn NIS
 505 v2, but many other systems,
 506 including
 507 .Tn SunOS
 508 4.x, search for both a v1 and v2 server when binding).
 509 .Fx Ns 's
 510 .Xr ypserv 8
 511 does not actually handle
 512 .Tn NIS
 513 v1 requests, but this
 514 .Dq "kludge mode"
 515 is useful for silencing stubborn systems that search for both
 516 a v1 and v2 server.
 517 .Pp
 518 (Please see the
 519 .Xr ypserv 8
 520 manual page for a detailed description of these special features
 521 and flags.)
 522 .Sh HISTORY
 523 The
 524 .Nm YP
 525 subsystem was written from the ground up by
 526 .An Theo de Raadt
 527 to be compatible to Sun's implementation.
 528 Bug fixes, improvements
 529 and
 530 .Tn NIS
 531 server support were later added by
 532 .An Bill Paul .
 533 The server-side code was originally written by
 534 .An Peter Eriksson
 535 and
 536 .An Tobias Reber
 537 and is subject to the GNU Public License.
 538 No Sun code was
 539 referenced.
 540 .Sh BUGS
 541 While
 542 .Fx
 543 now has both
 544 .Tn NIS
 545 client and server capabilities, it does not yet have support for
 546 .Xr ypupdated 8
 547 or the
 548 .Fn yp_update
 549 function.
 550 Both of these require secure
 551 .Tn RPC ,
 552 which
 553 .Fx
 554 does not
 555 support yet either.
 556 .Pp
 557 The
 558 .Xr getservent 3
 559 and
 560 .Xr getprotoent 3
 561 functions do not yet have
 562 .Tn NIS
 563 support.
 564 Fortunately, these files
 565 do not need to be updated that often.
 566 .Pp
 567 Many more manual pages should be written, especially
 568 .Xr ypclnt 3 .
 569 For the time being, seek out a local Sun machine and read the
 570 manuals for there.
 571 .Pp
 572 Neither Sun nor this author have found a clean way to handle
 573 the problems that occur when ypbind cannot find its server
 574 upon bootup.