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 $
30 .\" $DragonFly: src/share/man/man8/yp.8,v 1.2 2003/06/17 04:37:01 dillon 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.
61 support for the hosts, services and rpc databases is enabled by
67 support for the remaining services is
68 activated by adding a special
70 entry to the appropriate file.
74 subsystem is started automatically in
76 if it has been initialized in
80 exists (which it does in the default distribution).
83 domain must also be set with the
85 command, which will happen automatically at system startup if it is
92 client/server system that allows a group of
95 domain to share a common set of configuration files.
97 administrator to set up
99 client systems with only minimal configuration
100 data and add, remove or modify configuration data from a single location.
102 The canonical copies of all
104 information are stored on a single machine
107 .Em "master server" .
108 The databases used to store the information are called
113 these maps are stored in
114 .Pa /var/yp/ Ns Aq Ar domainname
123 support several domains at once, therefore it is possible to have several
124 such directories, one for each supported domain.
125 Each domain will have
126 its own independent set of maps.
132 maps are Berkeley DB hashed database files (the
133 same format used for the
136 Other operating systems that support
140 databases instead (largely because Sun Microsystems originally based
145 and other vendors have simply licensed
146 Sun's code rather than design their own implementation with a different
148 On these systems, the databases are generally split
155 code uses to hold separate parts of the hash
157 The Berkeley DB hash method instead uses a single file for
158 both pieces of information.
159 This means that while you may have
160 .Pa passwd.byname.dir
162 .Pa passwd.byname.pag
163 files on other operating systems (both of which are really parts of the
166 will have only one file called
168 The difference in format is not significant: only the
172 and related tools need to know the database format of the
183 There are three main types of
192 servers for information.
196 which maintain the canonical copies of all
202 which maintain backup copies of
204 maps that are periodically
205 updated by the master.
210 client establishes what is called a
218 checks the system's default domain (as set by the
220 command) and begins broadcasting
222 requests on the local network.
223 These requests specify the name of the domain for which
225 is attempting to establish a binding.
226 If a server that has been
227 configured to serve the requested domain receives one of the broadcasts,
230 which will record the server's address.
231 If there are several servers
232 available (a master and several slaves, for example),
234 will use the address of the first one to respond.
236 on, the client system will direct all of its
238 requests to that server.
242 the server to make sure it is still up
244 If it fails to receive a reply to one of its pings
245 within a reasonable amount of time,
247 will mark the domain as unbound and begin broadcasting again in the
248 hopes of locating another server.
251 master and slave servers handle all
257 is responsible for receiving incoming requests from
260 translating the requested domain and map name to a path to the
261 corresponding database file and transmitting data from the database
263 There is a specific set of requests that
265 is designed to handle, most of which are implemented as functions
266 within the standard C library:
267 .Bl -tag -width ".Fn yp_master"
269 check the creation date of a particular map
271 obtain the name of the
273 master server for a given
276 lookup the data corresponding to a given in key in a particular
279 obtain the first key/data pair in a particular map/domain
283 a key in a particular map/domain and have it return the
284 key/data pair immediately following it (the functions
288 can be used to do a sequential search of an
292 retrieve the entire contents of a map
295 There are a few other requests which
297 is capable of handling (i.e. acknowledge whether or not you can handle
299 .Pq Dv YPPROC_DOMAIN ,
300 or acknowledge only if you can handle the domain and be silent otherwise
301 .Pq Dv YPPROC_DOMAIN_NONACK )
303 these requests are usually generated only by
305 and are not meant to be used by standard utilities.
307 On networks with a large number of hosts, it is often a good idea to
308 use a master server and several slaves rather than just a single master
310 A slave server provides the exact same information as a master
311 server: whenever the maps on the master server are updated, the new
312 data should be propagated to the slave systems using the
318 .Pq Pa /var/yp/Makefile
319 will do this automatically if the administrator comments out the
323 is set to true by default because the default configuration is
324 for a small network with only one
329 command will initiate a transaction between the master and slave
330 during which the slave will transfer the specified maps from the
333 (The slave server calls
335 automatically from within
337 therefore it is not usually necessary for the administrator
339 It can be run manually if
342 slave servers helps improve
348 Providing backup services in the event that the
351 or becomes unreachable
353 Spreading the client load out over several machines instead of
354 causing the master to become overloaded
358 domain to extend beyond
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
365 to bind to a particular server with
367 but this is sometimes inconvenient.
368 This problem can be avoided simply by
369 placing a slave server on the local network.)
375 is specially designed to provided enhanced security (compared to
378 implementations) when used exclusively with
384 password database system (which is derived directly
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
394 map, this security feature would be totally disabled, since any user
395 is allowed to retrieve
399 To help prevent this,
402 server handles the shadow password maps
403 .Pa ( master.passwd.byname
405 .Pa master.passwd.byuid )
406 in a special way: the server will only provide access to these
407 maps in response to requests that originate on privileged ports.
408 Since only the super-user is allowed to bind to a privileged port,
409 the server assumes that all such requests come from privileged
411 All other requests are denied: requests from non-privileged
412 ports will receive only an error code from the server.
417 .An Wietse Venema Ns 's
418 tcp wrapper package; with tcp
419 wrapper support enabled, the administrator can configure
421 to respond only to selected client machines.
423 While these enhancements provide better security than stock
425 they are by no means 100% effective.
426 It is still possible for
427 someone with access to your network to spoof the server into disclosing
428 the shadow password maps.
433 functions will automatically search for the
435 maps and use them if they exist.
436 If they do, they will be used, and
437 all fields in these special maps (class, password age and account
438 expiration) will be decoded.
439 If they are not found, the standard
441 maps will be used instead.
448 files, it is unlikely that the default MD5-based format that
450 uses for passwords will be accepted by it.
451 If this is the case, the value of the
459 Some systems, such as
463 to be running in order
464 for their hostname resolution functions
465 .Fn ( gethostbyname ,
467 etc.) to work properly.
472 lookups when asked to return information about
473 a host that does not exist in its
481 by default (it can be made to use
483 if desired), therefore its
491 can be made to perform
493 lookups if it is started with a special
495 It can also be made to register itself as an
498 in order to placate certain systems that insist on the presence of
503 v2, but many other systems,
506 4.x, search for both a v1 and v2 server when binding).
509 does not actually handle
511 v1 requests, but this
513 is useful for silencing stubborn systems that search for both
518 manual page for a detailed description of these special features
525 client and server capabilities, it does not yet have support for
530 Both of these require secure
541 functions do not yet have
544 Fortunately, these files
545 do not need to be updated that often.
547 Many more manual pages should be written, especially
549 For the time being, seek out a local Sun machine and read the
552 Neither Sun nor this author have found a clean way to handle
553 the problems that occur when ypbind cannot find its server
558 subsystem was written from the ground up by
560 to be compatible to Sun's implementation.
561 Bug fixes, improvements
564 server support were later added by
566 The server-side code was originally written by
570 and is subject to the GNU Public License.