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 $
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.
65 subsystem is started automatically in
67 if it has been initialized in
71 exists (which it does in the default distribution).
74 domain must also be set with the
76 command, which will happen automatically at system startup if it is
83 client/server system that allows a group of
86 domain to share a common set of configuration files.
88 administrator to set up
90 client systems with only minimal configuration
91 data and add, remove or modify configuration data from a single location.
93 The canonical copies of all
95 information are stored on a single machine
99 The databases used to store the information are called
104 these maps are stored in
105 .Pa /var/yp/ Ns Aq Ar domainname
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.
123 maps are Berkeley DB hashed database files (the
124 same format used for the
127 Other operating systems that support
131 databases instead (largely because Sun Microsystems originally based
136 and other vendors have simply licensed
137 Sun's code rather than design their own implementation with a different
139 On these systems, the databases are generally split
146 code uses to hold separate parts of the hash
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
153 .Pa passwd.byname.pag
154 files on other operating systems (both of which are really parts of the
157 will have only one file called
159 The difference in format is not significant: only the
163 and related tools need to know the database format of the
174 There are three main types of
183 servers for information.
187 which maintain the canonical copies of all
193 which maintain backup copies of
195 maps that are periodically
196 updated by the master.
201 client establishes what is called a
210 utility checks the system's default domain (as set by the
212 command) and begins broadcasting
214 requests on the local network.
215 These requests specify the name of the domain for which
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,
222 which will record the server's address.
223 If there are several servers
224 available (a master and several slaves, for example),
226 will use the address of the first one to respond.
228 on, the client system will direct all of its
230 requests to that server.
233 utility will occasionally
235 the server to make sure it is still up
237 If it fails to receive a reply to one of its pings
238 within a reasonable amount of time,
240 will mark the domain as unbound and begin broadcasting again in the
241 hopes of locating another server.
244 master and slave servers handle all
251 utility is responsible for receiving incoming requests from
254 translating the requested domain and map name to a path to the
255 corresponding database file and transmitting data from the database
257 There is a specific set of requests that
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"
263 check the creation date of a particular map
265 obtain the name of the
267 master server for a given
270 lookup the data corresponding to a given in key in a particular
273 obtain the first key/data pair in a particular map/domain
277 a key in a particular map/domain and have it return the
278 key/data pair immediately following it (the functions
282 can be used to do a sequential search of an
286 retrieve the entire contents of a map
289 There are a few other requests which
291 is capable of handling (i.e., acknowledge whether or not you can handle
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 )
297 these requests are usually generated only by
299 and are not meant to be used by standard utilities.
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
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
312 .Pq Pa /var/yp/Makefile
313 will do this automatically if the administrator comments out the
317 is set to true by default because the default configuration is
318 for a small network with only one
323 command will initiate a transaction between the master and slave
324 during which the slave will transfer the specified maps from the
327 (The slave server calls
329 automatically from within
331 therefore it is not usually necessary for the administrator
333 It can be run manually if
336 slave servers helps improve
342 Providing backup services in the event that the
345 or becomes unreachable
347 Spreading the client load out over several machines instead of
348 causing the master to become overloaded
352 domain to extend beyond
355 daemon might not be able to locate a server automatically if it resides on
356 a network outside the reach of its broadcasts.
357 It is possible to force
359 to bind to a particular server with
361 but this is sometimes inconvenient.
362 This problem can be avoided simply by
363 placing a slave server on the local network.)
369 is specially designed to provide enhanced security (compared to
372 implementations) when used exclusively with
378 password database system (which is derived directly
382 .Em "shadow passwords" .
383 The standard password database does not contain users' encrypted
384 passwords: these are instead stored (along with other information)
385 in a separate database which is accessible only by the super-user.
386 If the encrypted password database were made available as an
388 map, this security feature would be totally disabled, since any user
389 is allowed to retrieve
393 To help prevent this,
396 server handles the shadow password maps
397 .Pa ( master.passwd.byname
399 .Pa master.passwd.byuid )
400 in a special way: the server will only provide access to these
401 maps in response to requests that originate on privileged ports.
402 Since only the super-user is allowed to bind to a privileged port,
403 the server assumes that all such requests come from privileged
405 All other requests are denied: requests from non-privileged
406 ports will receive only an error code from the server.
411 .An Wietse Venema Ns 's
412 tcp wrapper package; with tcp
413 wrapper support enabled, the administrator can configure
415 to respond only to selected client machines.
417 While these enhancements provide better security than stock
419 they are by no means 100% effective.
420 It is still possible for
421 someone with access to your network to spoof the server into disclosing
422 the shadow password maps.
427 functions will automatically search for the
429 maps and use them if they exist.
430 If they do, they will be used, and
431 all fields in these special maps (class, password age and account
432 expiration) will be decoded.
433 If they are not found, the standard
435 maps will be used instead.
442 files, it is unlikely that the default MD5-based format that
444 uses for passwords will be accepted by it.
445 If this is the case, the value of the
453 Some systems, such as
457 to be running in order
458 for their hostname resolution functions
459 .Fn ( gethostbyname ,
461 etc.) to work properly.
466 lookups when asked to return information about
467 a host that does not exist in its
475 by default (it can be made to use
477 if desired), therefore its
485 can be made to perform
487 lookups if it is started with a special
489 It can also be made to register itself as an
492 in order to placate certain systems that insist on the presence of
497 v2, but many other systems,
500 4.x, search for both a v1 and v2 server when binding).
503 does not actually handle
505 v1 requests, but this
507 is useful for silencing stubborn systems that search for both
512 manual page for a detailed description of these special features
517 subsystem was written from the ground up by
519 to be compatible to Sun's implementation.
520 Bug fixes, improvements
523 server support were later added by
525 The server-side code was originally written by
529 and is subject to the GNU Public License.
537 client and server capabilities, it does not yet have support for
542 Both of these require secure
553 functions do not yet have
556 Fortunately, these files
557 do not need to be updated that often.
559 Many more manual pages should be written, especially
561 For the time being, seek out a local Sun machine and read the
564 Neither Sun nor this author have found a clean way to handle
565 the problems that occur when ypbind cannot find its server