xref: /freebsd/share/man/man8/yp.8 (revision 39beb93c3f8bdbf72a61fda42300b5ebed7390c8)
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 April 5, 1993
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
40The
41.Nm YP
42subsystem allows network management of passwd, group, netgroup, hosts,
43services, rpc, bootparams and ethers file
44entries 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 ,
51and
52.Xr ethers 3 .
53The
54.Xr bootparamd 8
55daemon makes direct
56.Tn NIS
57library calls since there are no
58functions in the standard C library for reading bootparams.
59.Tn NIS
60support is enabled in
61.Xr nsswitch.conf 5 .
62.Pp
63The
64.Nm YP
65subsystem is started automatically in
66.Pa /etc/rc
67if it has been initialized in
68.Pa /etc/rc.conf
69and if the directory
70.Pa /var/yp
71exists (which it does in the default distribution).
72The default
73.Tn NIS
74domain must also be set with the
75.Xr domainname 1
76command, which will happen automatically at system startup if it is
77specified in
78.Pa /etc/rc.conf .
79.Pp
80.Tn NIS
81is an
82.Tn RPC Ns -based
83client/server system that allows a group of
84machines within an
85.Tn NIS
86domain to share a common set of configuration files.
87This permits a system
88administrator to set up
89.Tn NIS
90client systems with only minimal configuration
91data and add, remove or modify configuration data from a single location.
92.Pp
93The canonical copies of all
94.Tn NIS
95information are stored on a single machine
96called the
97.Tn NIS
98.Em "master server" .
99The databases used to store the information are called
100.Tn NIS
101.Em maps .
102In
103.Fx ,
104these maps are stored in
105.Pa /var/yp/ Ns Aq Ar domainname
106where
107.Aq Ar domainname
108is the name of the
109.Tn NIS
110domain being served.
111A single
112.Tn NIS
113server can
114support several domains at once, therefore it is possible to have several
115such directories, one for each supported domain.
116Each domain will have
117its own independent set of maps.
118.Pp
119In
120.Fx ,
121the
122.Tn NIS
123maps are Berkeley DB hashed database files (the
124same format used for the
125.Xr passwd 5
126database files).
127Other operating systems that support
128.Tn NIS
129use old-style
130.Nm ndbm
131databases instead (largely because Sun Microsystems originally based
132their
133.Tn NIS
134implementation on
135.Nm ndbm ,
136and other vendors have simply licensed
137Sun's code rather than design their own implementation with a different
138database format).
139On these systems, the databases are generally split
140into
141.Pa .dir
142and
143.Pa .pag
144files which the
145.Nm ndbm
146code uses to hold separate parts of the hash
147database.
148The Berkeley DB hash method instead uses a single file for
149both pieces of information.
150This means that while you may have
151.Pa passwd.byname.dir
152and
153.Pa passwd.byname.pag
154files on other operating systems (both of which are really parts of the
155same map),
156.Fx
157will have only one file called
158.Pa passwd.byname .
159The difference in format is not significant: only the
160.Tn NIS
161server,
162.Xr ypserv 8 ,
163and related tools need to know the database format of the
164.Tn NIS
165maps.
166Client
167.Tn NIS
168systems receive all
169.Tn NIS
170data in
171.Tn ASCII
172form.
173.Pp
174There are three main types of
175.Tn NIS
176systems:
177.Bl -enum
178.It
179.Tn NIS
180clients,
181which query
182.Tn NIS
183servers for information.
184.It
185.Tn NIS
186master servers,
187which maintain the canonical copies of all
188.Tn NIS
189maps.
190.It
191.Tn NIS
192slave servers,
193which maintain backup copies of
194.Tn NIS
195maps that are periodically
196updated by the master.
197.El
198.Pp
199A
200.Tn NIS
201client establishes what is called a
202.Em binding
203to a particular
204.Tn NIS
205server using the
206.Xr ypbind 8
207daemon.
208The
209.Xr ypbind 8
210utility checks the system's default domain (as set by the
211.Xr domainname 1
212command) and begins broadcasting
213.Tn RPC
214requests on the local network.
215These requests specify the name of the domain for which
216.Xr ypbind 8
217is attempting to establish a binding.
218If a server that has been
219configured to serve the requested domain receives one of the broadcasts,
220it will respond to
221.Xr ypbind 8 ,
222which will record the server's address.
223If there are several servers
224available (a master and several slaves, for example),
225.Xr ypbind 8
226will use the address of the first one to respond.
227From that point
228on, the client system will direct all of its
229.Tn NIS
230requests to that server.
231The
232.Xr ypbind 8
233utility will occasionally
234.Dq ping
235the server to make sure it is still up
236and running.
237If it fails to receive a reply to one of its pings
238within a reasonable amount of time,
239.Xr ypbind 8
240will mark the domain as unbound and begin broadcasting again in the
241hopes of locating another server.
242.Pp
243.Tn NIS
244master and slave servers handle all
245.Tn NIS
246requests with the
247.Xr ypserv 8
248daemon.
249The
250.Xr ypserv 8
251utility is responsible for receiving incoming requests from
252.Tn NIS
253clients,
254translating the requested domain and map name to a path to the
255corresponding database file and transmitting data from the database
256back to the client.
257There is a specific set of requests that
258.Xr ypserv 8
259is designed to handle, most of which are implemented as functions
260within the standard C library:
261.Bl -tag -width ".Fn yp_master"
262.It Fn yp_order
263check the creation date of a particular map
264.It Fn yp_master
265obtain the name of the
266.Tn NIS
267master server for a given
268map/domain
269.It Fn yp_match
270lookup the data corresponding to a given in key in a particular
271map/domain
272.It Fn yp_first
273obtain the first key/data pair in a particular map/domain
274.It Fn yp_next
275pass
276.Xr ypserv 8
277a key in a particular map/domain and have it return the
278key/data pair immediately following it (the functions
279.Fn yp_first
280and
281.Fn yp_next
282can be used to do a sequential search of an
283.Tn NIS
284map)
285.It Fn yp_all
286retrieve the entire contents of a map
287.El
288.Pp
289There are a few other requests which
290.Xr ypserv 8
291is capable of handling (i.e., acknowledge whether or not you can handle
292a particular domain
293.Pq Dv YPPROC_DOMAIN ,
294or acknowledge only if you can handle the domain and be silent otherwise
295.Pq Dv YPPROC_DOMAIN_NONACK )
296but
297these requests are usually generated only by
298.Xr ypbind 8
299and are not meant to be used by standard utilities.
300.Pp
301On networks with a large number of hosts, it is often a good idea to
302use a master server and several slaves rather than just a single master
303server.
304A slave server provides the exact same information as a master
305server: whenever the maps on the master server are updated, the new
306data should be propagated to the slave systems using the
307.Xr yppush 8
308command.
309The
310.Tn NIS
311.Pa Makefile
312.Pq Pa /var/yp/Makefile
313will do this automatically if the administrator comments out the
314line which says
315.Dq Li NOPUSH=true
316.Va ( NOPUSH
317is set to true by default because the default configuration is
318for a small network with only one
319.Tn NIS
320server).
321The
322.Xr yppush 8
323command will initiate a transaction between the master and slave
324during which the slave will transfer the specified maps from the
325master server using
326.Xr ypxfr 8 .
327(The slave server calls
328.Xr ypxfr 8
329automatically from within
330.Xr ypserv 8 ;
331therefore it is not usually necessary for the administrator
332to use it directly.
333It can be run manually if
334desired, however.)
335Maintaining
336slave servers helps improve
337.Tn NIS
338performance on large
339networks by:
340.Bl -bullet
341.It
342Providing backup services in the event that the
343.Tn NIS
344master crashes
345or becomes unreachable
346.It
347Spreading the client load out over several machines instead of
348causing the master to become overloaded
349.It
350Allowing a single
351.Tn NIS
352domain to extend beyond
353a local network (the
354.Xr ypbind 8
355daemon might not be able to locate a server automatically if it resides on
356a network outside the reach of its broadcasts.
357It is possible to force
358.Xr ypbind 8
359to bind to a particular server with
360.Xr ypset 8
361but this is sometimes inconvenient.
362This problem can be avoided simply by
363placing a slave server on the local network.)
364.El
365.Pp
366The
367.Fx
368.Xr ypserv 8
369is specially designed to provide enhanced security (compared to
370other
371.Tn NIS
372implementations) when used exclusively with
373.Fx
374client
375systems.
376The
377.Fx
378password database system (which is derived directly
379from
380.Bx 4.4 )
381includes support for
382.Em "shadow passwords" .
383The standard password database does not contain users' encrypted
384passwords: these are instead stored (along with other information)
385in a separate database which is accessible only by the super-user.
386If the encrypted password database were made available as an
387.Tn NIS
388map, this security feature would be totally disabled, since any user
389is allowed to retrieve
390.Tn NIS
391data.
392.Pp
393To help prevent this,
394.Fx Ns 's
395.Tn NIS
396server handles the shadow password maps
397.Pa ( master.passwd.byname
398and
399.Pa master.passwd.byuid )
400in a special way: the server will only provide access to these
401maps in response to requests that originate on privileged ports.
402Since only the super-user is allowed to bind to a privileged port,
403the server assumes that all such requests come from privileged
404users.
405All other requests are denied: requests from non-privileged
406ports will receive only an error code from the server.
407Additionally,
408.Fx Ns 's
409.Xr ypserv 8
410includes support for
411.An Wietse Venema Ns 's
412tcp wrapper package; with tcp
413wrapper support enabled, the administrator can configure
414.Xr ypserv 8
415to respond only to selected client machines.
416.Pp
417While these enhancements provide better security than stock
418.Tn NIS ,
419they are by no means 100% effective.
420It is still possible for
421someone with access to your network to spoof the server into disclosing
422the shadow password maps.
423.Pp
424On the client side,
425.Fx Ns 's
426.Xr getpwent 3
427functions will automatically search for the
428.Pa master.passwd
429maps and use them if they exist.
430If they do, they will be used, and
431all fields in these special maps (class, password age and account
432expiration) will be decoded.
433If they are not found, the standard
434.Pa passwd
435maps will be used instead.
436.Sh COMPATIBILITY
437When using a
438.No non- Ns Fx
439.Tn NIS
440server for
441.Xr passwd 5
442files, it is unlikely that the default MD5-based format that
443.Fx
444uses for passwords will be accepted by it.
445If this is the case, the value of the
446.Va passwd_format
447setting in
448.Xr login.conf 5
449should be changed to
450.Qq Li des
451for compatibility.
452.Pp
453Some systems, such as
454.Tn SunOS
4554.x, need
456.Tn NIS
457to be running in order
458for their hostname resolution functions
459.Fn ( gethostbyname ,
460.Fn gethostbyaddr ,
461etc.) to work properly.
462On these systems,
463.Xr ypserv 8
464performs
465.Tn DNS
466lookups when asked to return information about
467a host that does not exist in its
468.Pa hosts.byname
469or
470.Pa hosts.byaddr
471maps.
472.Fx Ns 's
473resolver uses
474.Tn DNS
475by default (it can be made to use
476.Tn NIS ,
477if desired), therefore its
478.Tn NIS
479server does not do
480.Tn DNS
481lookups
482by default.
483However,
484.Xr ypserv 8
485can be made to perform
486.Tn DNS
487lookups if it is started with a special
488flag.
489It can also be made to register itself as an
490.Tn NIS
491v1 server
492in order to placate certain systems that insist on the presence of
493a v1 server
494.No ( Fx
495uses only
496.Tn NIS
497v2, but many other systems,
498including
499.Tn SunOS
5004.x, search for both a v1 and v2 server when binding).
501.Fx Ns 's
502.Xr ypserv 8
503does not actually handle
504.Tn NIS
505v1 requests, but this
506.Dq "kludge mode"
507is useful for silencing stubborn systems that search for both
508a v1 and v2 server.
509.Pp
510(Please see the
511.Xr ypserv 8
512manual page for a detailed description of these special features
513and flags.)
514.Sh HISTORY
515The
516.Nm YP
517subsystem was written from the ground up by
518.An Theo de Raadt
519to be compatible to Sun's implementation.
520Bug fixes, improvements
521and
522.Tn NIS
523server support were later added by
524.An Bill Paul .
525The server-side code was originally written by
526.An Peter Eriksson
527and
528.An Tobias Reber
529and is subject to the GNU Public License.
530No Sun code was
531referenced.
532.Sh BUGS
533While
534.Fx
535now has both
536.Tn NIS
537client and server capabilities, it does not yet have support for
538.Xr ypupdated 8
539or the
540.Fn yp_update
541function.
542Both of these require secure
543.Tn RPC ,
544which
545.Fx
546does not
547support yet either.
548.Pp
549The
550.Xr getservent 3
551and
552.Xr getprotoent 3
553functions do not yet have
554.Tn NIS
555support.
556Fortunately, these files
557do not need to be updated that often.
558.Pp
559Many more manual pages should be written, especially
560.Xr ypclnt 3 .
561For the time being, seek out a local Sun machine and read the
562manuals for there.
563.Pp
564Neither Sun nor this author have found a clean way to handle
565the problems that occur when ypbind cannot find its server
566upon bootup.
567