1 .\" Copyright (c) 1992/3 Theo de Raadt <deraadt@fsa.ca>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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
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
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 $
37 .Nd description of the YP/NIS system
43 subsystem allows network management of passwd, group, netgroup, hosts,
44 services, rpc, bootparams and ethers file
45 entries through the functions
58 library calls since there are no
59 functions in the standard C library for reading bootparams.
66 subsystem is started automatically in
68 if it has been initialized in
72 exists (which it does in the default distribution).
75 domain must also be set with the
77 command, which will happen automatically at system startup if it is
84 client/server system that allows a group of
87 domain to share a common set of configuration files.
89 administrator to set up
91 client systems with only minimal configuration
92 data and add, remove or modify configuration data from a single location.
94 The canonical copies of all
96 information are stored on a single machine
100 The databases used to store the information are called
105 these maps are stored in
106 .Pa /var/yp/ Ns Aq Ar domainname
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.
124 maps are Berkeley DB hashed database files (the
125 same format used for the
128 Other operating systems that support
132 databases instead (largely because Sun Microsystems originally based
137 and other vendors have simply licensed
138 Sun's code rather than design their own implementation with a different
140 On these systems, the databases are generally split
147 code uses to hold separate parts of the hash
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
154 .Pa passwd.byname.pag
155 files on other operating systems (both of which are really parts of the
158 will have only one file called
160 The difference in format is not significant: only the
164 and related tools need to know the database format of the
175 There are three main types of
184 servers for information.
188 which maintain the canonical copies of all
194 which maintain backup copies of
196 maps that are periodically
197 updated by the master.
202 client establishes what is called a
211 utility checks the system's default domain (as set by the
213 command) and begins broadcasting
215 requests on the local network.
216 These requests specify the name of the domain for which
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,
223 which will record the server's address.
224 If there are several servers
225 available (a master and several slaves, for example),
227 will use the address of the first one to respond.
229 on, the client system will direct all of its
231 requests to that server.
234 utility will occasionally
236 the server to make sure it is still up
238 If it fails to receive a reply to one of its pings
239 within a reasonable amount of time,
241 will mark the domain as unbound and begin broadcasting again in the
242 hopes of locating another server.
245 master and slave servers handle all
252 utility is responsible for receiving incoming requests from
255 translating the requested domain and map name to a path to the
256 corresponding database file and transmitting data from the database
258 There is a specific set of requests that
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"
264 check the creation date of a particular map
266 obtain the name of the
268 master server for a given
271 lookup the data corresponding to a given in key in a particular
274 obtain the first key/data pair in a particular map/domain
278 a key in a particular map/domain and have it return the
279 key/data pair immediately following it (the functions
283 can be used to do a sequential search of an
287 retrieve the entire contents of a map
290 There are a few other requests which
292 is capable of handling (i.e., acknowledge whether or not you can handle
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 )
298 these requests are usually generated only by
300 and are not meant to be used by standard utilities.
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
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
313 .Pq Pa /var/yp/Makefile
314 will do this automatically if the administrator comments out the
318 is set to true by default because the default configuration is
319 for a small network with only one
324 command will initiate a transaction between the master and slave
325 during which the slave will transfer the specified maps from the
328 (The slave server calls
330 automatically from within
332 therefore it is not usually necessary for the administrator
334 It can be run manually if
337 slave servers helps improve
343 Providing backup services in the event that the
346 or becomes unreachable
348 Spreading the client load out over several machines instead of
349 causing the master to become overloaded
353 domain to extend beyond
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
362 to bind to a particular server with
364 but this is sometimes inconvenient.
365 This problem can be avoided simply by
366 placing a slave server on the local network.
373 is specially designed to provide enhanced security
379 when used exclusively with
387 password database system (which is derived directly
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
397 map, this security feature would be totally disabled, since any user
398 is allowed to retrieve
402 To help prevent this,
405 server handles the shadow password maps
406 .Pa ( master.passwd.byname
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
414 All other requests are denied: requests from non-privileged
415 ports will receive only an error code from the server.
420 .An Wietse Venema Ns 's
421 tcp wrapper package; with tcp
422 wrapper support enabled, the administrator can configure
424 to respond only to selected client machines.
426 While these enhancements provide better security than stock
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.
436 functions will automatically search for the
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
444 maps will be used instead.
447 .No non- Ns Dx Ns / Ns Fx
451 files, it is unlikely that the default MD5-based format that
453 uses for passwords will be accepted by it.
454 If this is the case, the value of the
462 Some systems, such as
466 to be running in order
467 for their hostname resolution functions
468 .Fn ( gethostbyname ,
470 etc.) to work properly.
475 lookups when asked to return information about
476 a host that does not exist in its
484 by default (it can be made to use
486 if desired), therefore its
494 can be made to perform
496 lookups if it is started with a special
498 It can also be made to register itself as an
501 in order to placate certain systems that insist on the presence of
506 v2, but many other systems,
509 4.x, search for both a v1 and v2 server when binding).
512 does not actually handle
514 v1 requests, but this
516 is useful for silencing stubborn systems that search for both
521 manual page for a detailed description of these special features
526 subsystem was written from the ground up by
528 to be compatible to Sun's implementation.
529 Bug fixes, improvements
532 server support were later added by
534 The server-side code was originally written by
538 and is subject to the GNU Public License.
546 client and server capabilities, it does not yet have support for
551 Both of these require secure
562 functions do not yet have
565 Fortunately, these files
566 do not need to be updated that often.
568 Many more manual pages should be written, especially
570 For the time being, seek out a local Sun machine and read the
573 Neither Sun nor this author have found a clean way to handle
574 the problems that occur when ypbind cannot find its server