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.30.2.2 2002/09/30 08:19:41 max Exp $
36 .Nd description of the YP/NIS system
42 subsystem allows network management of passwd, group, netgroup, hosts,
43 services, rpc, bootparams and ethers file
44 entries through the functions
57 library calls since there are no
58 functions in the standard C library for reading bootparams.
60 support for the hosts, services and rpc databases is enabled by
66 support for the remaining services is
67 activated by adding a special
69 entry to the appropriate file.
73 subsystem is started automatically in
75 if it has been initialized in
79 exists (which it does in the default distribution).
82 domain must also be set with the
84 command, which will happen automatically at system startup if it is
91 client/server system that allows a group of
94 domain to share a common set of configuration files.
96 administrator to set up
98 client systems with only minimal configuration
99 data and add, remove or modify configuration data from a single location.
101 The canonical copies of all
103 information are stored on a single machine
106 .Em "master server" .
107 The databases used to store the information are called
112 these maps are stored in
113 .Pa /var/yp/ Ns Aq Ar domainname
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.
131 maps are Berkeley DB hashed database files (the
132 same format used for the
135 Other operating systems that support
139 databases instead (largely because Sun Microsystems originally based
144 and other vendors have simply licensed
145 Sun's code rather than design their own implementation with a different
147 On these systems, the databases are generally split
154 code uses to hold separate parts of the hash
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
161 .Pa passwd.byname.pag
162 files on other operating systems (both of which are really parts of the
165 will have only one file called
167 The difference in format is not significant: only the
171 and related tools need to know the database format of the
182 There are three main types of
191 servers for information.
195 which maintain the canonical copies of all
201 which maintain backup copies of
203 maps that are periodically
204 updated by the master.
209 client establishes what is called a
217 checks the system's default domain (as set by the
219 command) and begins broadcasting
221 requests on the local network.
222 These requests specify the name of the domain for which
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,
229 which will record the server's address.
230 If there are several servers
231 available (a master and several slaves, for example),
233 will use the address of the first one to respond.
235 on, the client system will direct all of its
237 requests to that server.
241 the server to make sure it is still up
243 If it fails to receive a reply to one of its pings
244 within a reasonable amount of time,
246 will mark the domain as unbound and begin broadcasting again in the
247 hopes of locating another server.
250 master and slave servers handle all
256 is responsible for receiving incoming requests from
259 translating the requested domain and map name to a path to the
260 corresponding database file and transmitting data from the database
262 There is a specific set of requests that
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"
268 check the creation date of a particular map
270 obtain the name of the
272 master server for a given
275 lookup the data corresponding to a given in key in a particular
278 obtain the first key/data pair in a particular map/domain
282 a key in a particular map/domain and have it return the
283 key/data pair immediately following it (the functions
287 can be used to do a sequential search of an
291 retrieve the entire contents of a map
294 There are a few other requests which
296 is capable of handling (i.e. acknowledge whether or not you can handle
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 )
302 these requests are usually generated only by
304 and are not meant to be used by standard utilities.
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
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
317 .Pq Pa /var/yp/Makefile
318 will do this automatically if the administrator comments out the
322 is set to true by default because the default configuration is
323 for a small network with only one
328 command will initiate a transaction between the master and slave
329 during which the slave will transfer the specified maps from the
332 (The slave server calls
334 automatically from within
336 therefore it is not usually necessary for the administrator
338 It can be run manually if
341 slave servers helps improve
347 Providing backup services in the event that the
350 or becomes unreachable
352 Spreading the client load out over several machines instead of
353 causing the master to become overloaded
357 domain to extend beyond
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
364 to bind to a particular server with
366 but this is sometimes inconvenient.
367 This problem can be avoided simply by
368 placing a slave server on the local network.)
374 is specially designed to provided enhanced security (compared to
377 implementations) when used exclusively with
383 password database system (which is derived directly
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
393 map, this security feature would be totally disabled, since any user
394 is allowed to retrieve
398 To help prevent this,
401 server handles the shadow password maps
402 .Pa ( master.passwd.byname
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
410 All other requests are denied: requests from non-privileged
411 ports will receive only an error code from the server.
416 .An Wietse Venema Ns 's
417 tcp wrapper package; with tcp
418 wrapper support enabled, the administrator can configure
420 to respond only to selected client machines.
422 While these enhancements provide better security than stock
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.
432 functions will automatically search for the
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
440 maps will be used instead.
447 files, it is unlikely that the default MD5-based format that
449 uses for passwords will be accepted by it.
450 If this is the case, the value of the
458 Some systems, such as
462 to be running in order
463 for their hostname resolution functions
464 .Fn ( gethostbyname ,
466 etc.) to work properly.
471 lookups when asked to return information about
472 a host that does not exist in its
480 by default (it can be made to use
482 if desired), therefore its
490 can be made to perform
492 lookups if it is started with a special
494 It can also be made to register itself as an
497 in order to placate certain systems that insist on the presence of
502 v2, but many other systems,
505 4.x, search for both a v1 and v2 server when binding).
508 does not actually handle
510 v1 requests, but this
512 is useful for silencing stubborn systems that search for both
517 manual page for a detailed description of these special features
524 client and server capabilities, it does not yet have support for
529 Both of these require secure
540 functions do not yet have
543 Fortunately, these files
544 do not need to be updated that often.
546 Many more manual pages should be written, especially
548 For the time being, seek out a local Sun machine and read the
551 Neither Sun nor this author have found a clean way to handle
552 the problems that occur when ypbind cannot find its server
557 subsystem was written from the ground up by
559 to be compatible to Sun's implementation.
560 Bug fixes, improvements
563 server support were later added by
565 The server-side code was originally written by
569 and is subject to the GNU Public License.