/share/man/man8/yp.8

  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 December 14, 2011
 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 creates
314.Pa /var/yp/Makefile.local
315and empties the
316.Va NOPUSH
317variable:
318.Bd -literal -offset four
319.Li NOPUSH=
320.Ed
321.Pp
322.Va ( NOPUSH
323is set to true by default because the default configuration is
324for a small network with only one
325.Tn NIS
326server).
327The
328.Xr yppush 8
329command will initiate a transaction between the master and slave
330during which the slave will transfer the specified maps from the
331master server using
332.Xr ypxfr 8 .
333(The slave server calls
334.Xr ypxfr 8
335automatically from within
336.Xr ypserv 8 ;
337therefore it is not usually necessary for the administrator
338to use it directly.
339It can be run manually if
340desired, however.)
341Maintaining
342slave servers helps improve
343.Tn NIS
344performance on large
345networks by:
346.Bl -bullet
347.It
348Providing backup services in the event that the
349.Tn NIS
350master crashes
351or becomes unreachable
352.It
353Spreading the client load out over several machines instead of
354causing the master to become overloaded
355.It
356Allowing a single
357.Tn NIS
358domain to extend beyond
359a local network (the
360.Xr ypbind 8
361daemon might not be able to locate a server automatically if it resides on
362a network outside the reach of its broadcasts.
363It is possible to force
364.Xr ypbind 8
365to bind to a particular server with
366.Xr ypset 8
367but this is sometimes inconvenient.
368This problem can be avoided simply by
369placing a slave server on the local network.)
370.El
371.Pp
372The
373.Fx
374.Xr ypserv 8
375is specially designed to provide enhanced security (compared to
376other
377.Tn NIS
378implementations) when used exclusively with
379.Fx
380client
381systems.
382The
383.Fx
384password database system (which is derived directly
385from
386.Bx 4.4 )
387includes support for
388.Em "shadow passwords" .
389The standard password database does not contain users' encrypted
390passwords: these are instead stored (along with other information)
391in a separate database which is accessible only by the super-user.
392If the encrypted password database were made available as an
393.Tn NIS
394map, this security feature would be totally disabled, since any user
395is allowed to retrieve
396.Tn NIS
397data.
398.Pp
399To help prevent this,
400.Fx Ns 's
401.Tn NIS
402server handles the shadow password maps
403.Pa ( master.passwd.byname ,
404.Pa master.passwd.byuid ,
405.Pa shadow.byname
406and
407.Pa shadow.byuid )
408in a special way: the server will only provide access to these
409maps in response to requests that originate on privileged ports.
410Since only the super-user is allowed to bind to a privileged port,
411the server assumes that all such requests come from privileged
412users.
413All other requests are denied: requests from non-privileged
414ports will receive only an error code from the server.
415Additionally,
416.Fx Ns 's
417.Xr ypserv 8
418includes support for
419.An Wietse Venema Ns 's
420tcp wrapper package; with tcp
421wrapper support enabled, the administrator can configure
422.Xr ypserv 8
423to respond only to selected client machines.
424.Pp
425While these enhancements provide better security than stock
426.Tn NIS ,
427they are by no means 100% effective.
428It is still possible for
429someone with access to your network to spoof the server into disclosing
430the shadow password maps.
431.Pp
432On the client side,
433.Fx Ns 's
434.Xr getpwent 3
435functions will automatically search for the
436.Pa master.passwd
437maps and use them if they exist.
438If they do, they will be used, and
439all fields in these special maps (class, password age and account
440expiration) will be decoded.
441If they are not found, the standard
442.Pa passwd
443maps will be used instead.
444.Sh COMPATIBILITY
445When using a
446.No non- Ns Fx
447.Tn NIS
448server for
449.Xr passwd 5
450files, it is unlikely that the default MD5-based format that
451.Fx
452uses for passwords will be accepted by it.
453If this is the case, the value of the
454.Va passwd_format
455setting in
456.Xr login.conf 5
457should be changed to
458.Qq Li des
459for compatibility.
460.Pp
461Some systems, such as
462.Tn SunOS
4634.x, need
464.Tn NIS
465to be running in order
466for their hostname resolution functions
467.Fn ( gethostbyname ,
468.Fn gethostbyaddr ,
469etc.) to work properly.
470On these systems,
471.Xr ypserv 8
472performs
473.Tn DNS
474lookups when asked to return information about
475a host that does not exist in its
476.Pa hosts.byname
477or
478.Pa hosts.byaddr
479maps.
480.Fx Ns 's
481resolver uses
482.Tn DNS
483by default (it can be made to use
484.Tn NIS ,
485if desired), therefore its
486.Tn NIS
487server does not do
488.Tn DNS
489lookups
490by default.
491However,
492.Xr ypserv 8
493can be made to perform
494.Tn DNS
495lookups if it is started with a special
496flag.
497It can also be made to register itself as an
498.Tn NIS
499v1 server
500in order to placate certain systems that insist on the presence of
501a v1 server
502.No ( Fx
503uses only
504.Tn NIS
505v2, but many other systems,
506including
507.Tn SunOS
5084.x, search for both a v1 and v2 server when binding).
509.Fx Ns 's
510.Xr ypserv 8
511does not actually handle
512.Tn NIS
513v1 requests, but this
514.Dq "kludge mode"
515is useful for silencing stubborn systems that search for both
516a v1 and v2 server.
517.Pp
518(Please see the
519.Xr ypserv 8
520manual page for a detailed description of these special features
521and flags.)
522.Sh SEE ALSO
523.Xr domainname 1 ,
524.Xr ypcat 1 ,
525.Xr ypmatch 1 ,
526.Xr ypwhich 1 ,
527.Xr nsswitch.conf 5 ,
528.Xr yp_mkdb 8 ,
529.Xr ypbind 8 ,
530.Xr ypinit 8 ,
531.Xr yppoll 8 ,
532.Xr yppush 8 ,
533.Xr ypserv 8 ,
534.Xr ypset 8 ,
535.Xr ypxfr 8
536.Sh HISTORY
537The
538.Nm YP
539subsystem was written from the ground up by
540.An Theo de Raadt
541to be compatible to Sun's implementation.
542Bug fixes, improvements
543and
544.Tn NIS
545server support were later added by
546.An Bill Paul .
547The server-side code was originally written by
548.An Peter Eriksson
549and
550.An Tobias Reber
551and is subject to the GNU Public License.
552No Sun code was
553referenced.
554.Sh BUGS
555While
556.Fx
557now has both
558.Tn NIS
559client and server capabilities, it does not yet have support for
560.Xr ypupdated 8
561or the
562.Fn yp_update
563function.
564Both of these require secure
565.Tn RPC ,
566which
567.Fx
568does not
569support yet either.
570.Pp
571The
572.Xr getservent 3
573and
574.Xr getprotoent 3
575functions do not yet have
576.Tn NIS
577support.
578Fortunately, these files
579do not need to be updated that often.
580.Pp
581Many more manual pages should be written, especially
582.Xr ypclnt 3 .
583For the time being, seek out a local Sun machine and read the
584manuals for there.
585.Pp
586Neither Sun nor this author have found a clean way to handle
587the problems that occur when ypbind cannot find its server
588upon bootup.