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