| blob | e8c3beaf3c133499cd18d8fdef6c76e88f077815 |
1 .\" Copyright (c) 1995
2 .\" Bill Paul <wpaul@ctr.columbia.edu>. 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. All advertising materials mentioning features or use of this software
13 .\" must display the following acknowledgement:
14 .\" This product includes software developed by Bill Paul.
15 .\" 4. Neither the name of the author nor the names of any co-contributors
16 .\" may be used to endorse or promote products derived from this software
17 .\" without specific prior written permission.
18 .\"
19 .\" THIS SOFTWARE IS PROVIDED BY Bill Paul AND CONTRIBUTORS ``AS IS'' AND
20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 .\" ARE DISCLAIMED. IN NO EVENT SHALL Bill Paul OR CONTRIBUTORS BE LIABLE
23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29 .\" SUCH DAMAGE.
30 .\"
31 .\" $FreeBSD: src/usr.sbin/ypserv/ypserv.8,v 1.42 2008/02/03 17:39:37 matteo Exp $
32 .\" $DragonFly: src/usr.sbin/ypserv/ypserv.8,v 1.8 2007/12/16 02:55:38 thomas Exp $
33 .\"
34 .Dd February 3, 2008
35 .Dt YPSERV 8
36 .Os
37 .Sh NAME
38 .Nm ypserv
39 .Nd NIS database server
40 .Sh SYNOPSIS
41 .Nm
42 .Op Fl n
43 .Op Fl d
44 .Op Fl P Ar port
45 .Op Fl p Ar path
46 .Sh DESCRIPTION
47 .Tn NIS
48 is an RPC-based service designed to allow a number of
49 .Ux Ns -based
50 machines to share a common set of configuration files.
51 Rather than
52 requiring a system administrator to update several copies of files
53 such as
54 .Pa /etc/hosts ,
55 .Pa /etc/passwd
56 and
57 .Pa /etc/group ,
58 which tend to require frequent changes in most environments,
59 .Tn NIS
60 allows groups of computers to share one set of data which can be
61 updated from a single location.
62 .Pp
63 The
64 .Nm
65 utility is the server that distributes
66 .Tn NIS
67 databases to client systems within an
68 .Tn NIS
69 .Em domain .
70 Each client in an
71 .Tn NIS
72 domain must have its domainname set to
73 one of the domains served by
74 .Nm
75 using the
76 .Xr domainname 1
77 command.
78 The clients must also run
79 .Xr ypbind 8
80 in order to attach to a particular server, since it is possible to
81 have several servers within a single
82 .Tn NIS
83 domain.
84 .Pp
85 The databases distributed by
86 .Nm
87 are stored in
88 .Pa /var/yp/[domainname]
89 where
90 .Pa domainname
91 is the name of the domain being served.
92 There can be several
93 such directories with different domainnames, and you need only one
94 .Nm
95 daemon to handle them all.
96 .Pp
97 The databases, or
98 .Pa maps
99 as they are often called,
100 are created by
101 .Pa /var/yp/Makefile
102 using several system files as source.
103 The database files are in
104 .Xr db 3
105 format to help speed retrieval when there are many records involved.
106 In
107 .Dx ,
108 the maps are always readable and writable only by root for security
109 reasons.
110 Technically this is only necessary for the password
111 maps, but since the data in the other maps can be found in
112 other world-readable files anyway, it does not hurt and it is considered
113 good general practice.
114 .Pp
115 The
116 .Nm
117 utility is started by
118 .Pa /etc/rc.d/ypserv
119 if it has been enabled in
120 .Pa /etc/rc.conf .
121 .Sh SPECIAL FEATURES
122 There are some problems associated with distributing a
123 .Dx
124 password
125 database via
126 .Tn NIS :
127 .Dx
128 normally only stores encrypted passwords
129 in
130 .Pa /etc/master.passwd ,
131 which is readable and writable only by root.
132 By turning this file
133 into an
134 .Tn NIS
135 map, this security feature would be completely defeated.
136 .Pp
137 To make up for this, the
138 .Dx
139 version of
140 .Nm
141 handles the
142 .Pa master.passwd.byname
143 and
144 .Pa master.passwd.byuid
145 maps in a special way.
146 When the server receives a request to access
147 either of these two maps, it will check the TCP port from which the
148 request originated and return an error if the port number is greater
149 than 1023.
150 Since only the superuser is allowed to bind to TCP ports
151 with values less than 1024, the server can use this test to determine
152 whether or not the access request came from a privileged user.
153 Any requests made by non-privileged users are therefore rejected.
154 .Pp
155 Furthermore, the
156 .Xr getpwent 3
157 routines in the
158 .Dx
159 standard C library will only attempt to retrieve
160 data from the
161 .Pa master.passwd.byname
162 and
163 .Pa master.passwd.byuid
164 maps for the superuser: if a normal user calls any of these functions,
165 the standard
166 .Pa passwd.byname
167 and
168 .Pa passwd.byuid
169 maps will be accessed instead.
170 The latter two maps are constructed by
171 .Pa /var/yp/Makefile
172 by parsing the
173 .Pa master.passwd
174 file and stripping out the password fields, and are therefore
175 safe to pass on to unprivileged users.
176 In this way, the shadow password
177 aspect of the protected
178 .Pa master.passwd
179 database is maintained through
180 .Tn NIS .
181 .Sh NOTES
182 .Ss Setting Up Master and Slave Servers
183 .Xr ypinit 8
184 is a convenient script that will help setup master and slave
185 .Tn NIS
186 servers.
187 .Ss Limitations
188 There are two problems inherent with password shadowing in
189 .Tn NIS
190 that users should
191 be aware of:
192 .Bl -enum -offset indent
193 .It
194 The
195 .Sq TCP port less than 1024
196 test is trivial to defeat for users with
197 unrestricted access to machines on your network (even those machines
198 which do not run
199 .Ux Ns -based
200 operating systems).
201 .It
202 If you plan to use a
203 .Dx
204 system to serve
205 .No non- Ns Dx Ns / Ns Fx
206 clients that
207 have no support for password shadowing (which is most of them), you
208 will have to disable the password shadowing entirely by uncommenting the
209 .Em UNSECURE=True
210 entry in
211 .Pa /var/yp/Makefile .
212 This will cause the standard
213 .Pa passwd.byname
214 and
215 .Pa passwd.byuid
216 maps to be generated with valid encrypted password fields, which is
217 necessary in order for
218 .No non- Ns Dx Ns / Ns Fx
219 clients to perform user
220 authentication through
221 .Tn NIS .
222 .El
223 .Ss Security
224 In general, any remote user can issue an RPC to
225 .Nm
226 and retrieve the contents of your
227 .Tn NIS
228 maps, provided the remote user
229 knows your domain name.
230 To prevent such unauthorized transactions,
231 .Nm
232 supports a feature called
233 .Pa securenets
234 which can be used to restrict access to a given set of hosts.
235 At startup,
236 .Nm
237 will attempt to load the securenets information from a file
238 called
239 .Pa /var/yp/securenets .
240 (Note that this path varies depending on the path specified with
241 the
242 .Fl p
243 option, which is explained below.)
244 This file contains entries
245 that consist of a network specification and a network mask separated
246 by white space.
247 Lines starting with
248 .Dq \&#
249 are considered to be comments.
250 A
251 sample securenets file might look like this:
252 .Bd -unfilled -offset indent
253 # allow connections from local host -- mandatory
254 127.0.0.1 255.255.255.255
255 # allow connections from any host
256 # on the 192.168.128.0 network
257 192.168.128.0 255.255.255.0
258 # allow connections from any host
259 # between 10.0.0.0 to 10.0.15.255
260 10.0.0.0 255.255.240.0
261 .Ed
262 .Pp
263 If
264 .Nm
265 receives a request from an address that matches one of these rules,
266 it will process the request normally.
267 If the address fails to match
268 a rule, the request will be ignored and a warning message will be
269 logged.
270 If the
271 .Pa /var/yp/securenets
272 file does not exist,
273 .Nm
274 will allow connections from any host.
275 .Pp
276 The
277 .Nm
278 utility also has support for Wietse Venema's
279 .Em tcpwrapper
280 package.
281 This allows the administrator to use the tcpwrapper
282 configuration files
283 .Pa ( /etc/hosts.allow
284 and
285 .Pa /etc/hosts.deny )
286 for access control instead of
287 .Pa /var/yp/securenets .
288 .Pp
289 Note: while both of these access control mechanisms provide some
290 security, they, like the privileged port test, are both vulnerable
291 to
292 .Dq IP spoofing
293 attacks.
294 .Ss NIS v1 compatibility
295 This version of
296 .Nm
297 has some support for serving
298 .Tn NIS
299 v1 clients.
300 The
301 .Dx
302 .Tn NIS
303 implementation only uses the
304 .Tn NIS
305 v2 protocol, however other implementations
306 include support for the v1 protocol for backwards compatibility
307 with older systems.
308 The
309 .Xr ypbind 8
310 daemons supplied with these systems will try to establish a binding
311 to an
312 .Tn NIS
313 v1 server even though they may never actually need it (and they may
314 persist in broadcasting in search of one even after they receive a
315 response from a v2 server).
316 Note that while
317 support for normal client calls is provided, this version of
318 .Nm
319 does not handle v1 map transfer requests; consequently, it cannot
320 be used as a master or slave in conjunction with older
321 .Tn NIS
322 servers that
323 only support the v1 protocol.
324 Fortunately, there probably are not any
325 such servers still in use today.
326 .Ss NIS servers that are also NIS clients
327 Care must be taken when running
328 .Nm
329 in a multi-server domain where the server machines are also
330 .Tn NIS
331 clients.
332 It is generally a good idea to force the servers to
333 bind to themselves rather than allowing them to broadcast bind
334 requests and possibly become bound to each other: strange failure
335 modes can result if one server goes down and
336 others are dependent upon on it.
337 (Eventually all the clients will
338 time out and attempt to bind to other servers, but the delay
339 involved can be considerable and the failure mode is still present
340 since the servers might bind to each other all over again).
341 .Pp
342 Refer to the
343 .Xr ypbind 8
344 man page for details on how to force it to bind to a particular
345 server.
346 .Sh OPTIONS
347 The following options are supported by
348 .Nm :
349 .Bl -tag -width flag
350 .It Fl n
351 This option affects the way
352 .Nm
353 handles yp_match requests for the
354 .Pa hosts.byname
355 and
356 .Pa hosts.byaddress
357 maps.
358 By default, if
359 .Nm
360 cannot find an entry for a given host in its hosts maps, it will
361 return an error and perform no further processing.
362 With the
363 .Fl n
364 flag,
365 .Nm
366 will go one step further: rather than giving up immediately, it
367 will try to resolve the hostname or address using a DNS nameserver
368 query.
369 If the query is successful,
370 .Nm
371 will construct a fake database record and return it to the client,
372 thereby making it seem as though the client's yp_match request
373 succeeded.
374 .Pp
375 This feature is provided for compatibility with SunOS 4.1.x,
376 which has brain-damaged resolver functions in its standard C
377 library that depend on
378 .Tn NIS
379 for hostname and address resolution.
380 The
381 .Dx
382 resolver can be configured to do DNS
383 queries directly, therefore it is not necessary to enable this
384 option when serving only
385 .Dx
386 .Tn NIS
387 clients.
388 .It Fl d
389 Cause the server to run in debugging mode.
390 Normally,
391 .Nm
392 reports only unusual errors (access violations, file access failures)
393 using the
394 .Xr syslog 3
395 facility.
396 In debug mode, the server does not background
397 itself and prints extra status messages to stderr for each
398 request that it receives.
399 Also, while running in debug mode,
400 .Nm
401 will not spawn any additional subprocesses as it normally does
402 when handling yp_all requests or doing DNS lookups.
403 (These actions
404 often take a fair amount of time to complete and are therefore handled
405 in subprocesses, allowing the parent server process to go on handling
406 other requests.)
407 This makes it easier to trace the server with
408 a debugging tool.
409 .It Fl P Ar port
410 Force ypserv to bind to a specific TCP/UDP port, rather than selecting
411 its own.
412 .It Fl p Ar path
413 Normally,
414 .Nm
415 assumes that all
416 .Tn NIS
417 maps are stored under
418 .Pa /var/yp .
419 The
420 .Fl p
421 flag may be used to specify an alternate
422 .Tn NIS
423 root path, allowing
424 the system administrator to move the map files to a different place
425 within the file system.
426 .El
427 .Sh FILES
428 .Bl -tag -width Pa -compact
429 .It Pa /var/yp/[domainname]/[maps]
430 the
431 .Tn NIS
432 maps
433 .It Pa /etc/nsswitch.conf
434 name switch configuration file
435 .It Pa /var/yp/securenets
436 host access control file
437 .El
438 .Sh SEE ALSO
439 .Xr ypcat 1 ,
440 .Xr db 3 ,
441 .Xr hosts_access 5 ,
442 .Xr rc.conf 5 ,
443 .Xr rpc.yppasswdd 8 ,
444 .Xr tcpd 8 ,
445 .Xr yp 8 ,
446 .Xr ypbind 8 ,
447 .Xr ypinit 8 ,
448 .Xr yppush 8 ,
449 .Xr ypxfr 8
450 .Sh HISTORY
451 This version of
452 .Nm
453 first appeared in
454 .Fx 2.2 .
455 .Sh AUTHORS
456 .An Bill Paul Aq wpaul@ctr.columbia.edu