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