2 .\" Bill Paul <wpaul@ctr.columbia.edu>. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
31 .\" $FreeBSD: src/usr.sbin/ypserv/ypserv.8,v 1.22.2.8 2002/12/29 16:35:44 schweikh Exp $
38 .Nd NIS database server
46 is an RPC-based service designed to allow a number of UNIX-based
47 machines to share a common set of configuration files.
49 requiring a system administrator to update several copies of files
55 which tend to require frequent changes in most environments,
57 allows groups of computers to share one set of data which can be
58 updated from a single location.
62 program is the server that distributes
64 databases to client systems within an
69 domain must have its domainname set to
70 one of the domains served by
75 The clients must also run
77 in order to attach to a particular server, since it is possible to
78 have several servers within a single
82 The databases distributed by
85 .Pa /var/yp/[domainname]
88 is the name of the domain being served.
90 such directories with different domainnames, and you need only one
92 daemon to handle them all.
96 as they are often called,
99 using several system files as source.
100 The database files are in
102 format to help speed retrieval when there are many records involved.
105 the maps are always readable and writable only by root for security
107 Technically this is only necessary for the password
108 maps, but since the data in the other maps can be found in
109 other world-readable files anyway, it doesn't hurt and it's considered
110 good general practice.
114 program is started by
116 if it has been enabled in
119 There are some problems associated with distributing a
125 normally only stores encrypted passwords
127 .Pa /etc/master.passwd ,
128 which is readable and writable only by root.
132 map, this security feature would be completely defeated.
134 To make up for this, the
139 .Pa master.passwd.byname
141 .Pa master.passwd.byuid
142 maps in a special way.
143 When the server receives a request to access
144 either of these two maps, it will check the TCP port from which the
145 request originated and return an error if the port number is greater
147 Since only the superuser is allowed to bind to TCP ports
148 with values less than 1024, the server can use this test to determine
149 whether or not the access request came from a privileged user.
150 Any requests made by non-privileged users are therefore rejected.
156 standard C library will only attempt to retrieve
158 .Pa master.passwd.byname
160 .Pa master.passwd.byuid
161 maps for the superuser: if a normal user calls any of these functions,
166 maps will be accessed instead.
167 The latter two maps are constructed by
171 file and stripping out the password fields, and are therefore
172 safe to pass on to unprivileged users.
173 In this way, the shadow password
174 aspect of the protected
176 database is maintained through
179 .Ss Setting Up Master and Slave Servers
181 is a convenient script that will help setup master and slave
185 There are two problems inherent with password shadowing in
189 .Bl -enum -offset indent
192 .Sq TCP port less than 1024
193 test is trivial to defeat for users with
194 unrestricted access to machines on your network (even those machines
195 which do not run UNIX-based operating systems).
202 have no support for password shadowing (which is most of them), you
203 will have to disable the password shadowing entirely by uncommenting the
206 .Pa /var/yp/Makefile .
207 This will cause the standard
211 maps to be generated with valid encrypted password fields, which is
212 necessary in order for
214 clients to perform user
215 authentication through
220 In general, any remote user can issue an RPC to
222 and retrieve the contents of your
224 maps, provided the remote user
225 knows your domain name.
226 To prevent such unauthorized transactions,
228 supports a feature called
230 which can be used to restrict access to a given set of hosts.
233 will attempt to load the securenets information from a file
235 .Pa /var/yp/securenets .
236 (Note that this path varies depending on the path specified with
239 option, which is explained below.)
240 This file contains entries
241 that consist of a network specification and a network mask separated
245 are considered to be comments.
247 sample securenets file might look like this:
248 .Bd -unfilled -offset indent
249 # allow connections from local host -- mandatory
250 127.0.0.1 255.255.255.255
251 # allow connections from any host
252 # on the 192.168.128.0 network
253 192.168.128.0 255.255.255.0
254 # allow connections from any host
255 # between 10.0.0.0 to 10.0.15.255
256 10.0.0.0 255.255.240.0
261 receives a request from an address that matches one of these rules,
262 it will process the request normally.
263 If the address fails to match
264 a rule, the request will be ignored and a warning message will be
267 .Pa /var/yp/securenets
270 will allow connections from any host.
274 program also has support for Wietse Venema's
276 package, though it is not compiled in by default since
279 package is not distributed with
285 you can easily recompile
288 This allows the administrator to use the tcpwrapper
290 .Pa ( /etc/hosts.allow
292 .Pa /etc/hosts.deny )
293 for access control instead of
294 .Pa /var/yp/securenets .
296 Note: while both of these access control mechanisms provide some
297 security, they, like the privileged port test, are both vulnerable
302 .Ss NIS v1 compatibility
305 has some support for serving
311 implementation only uses the
313 v2 protocol, however other implementations
314 include support for the v1 protocol for backwards compatibility
318 daemons supplied with these systems will try to establish a binding
321 v1 server even though they may never actually need it (and they may
322 persist in broadcasting in search of one even after they receive a
323 response from a v2 server). Note that while
324 support for normal client calls is provided, this version of
326 does not handle v1 map transfer requests; consequently, it cannot
327 be used as a master or slave in conjunction with older
330 only support the v1 protocol.
331 Fortunately, there probably aren't any
332 such servers still in use today.
333 .Ss NIS servers that are also NIS clients
334 Care must be taken when running
336 in a multi-server domain where the server machines are also
339 It is generally a good idea to force the servers to
340 bind to themselves rather than allowing them to broadcast bind
341 requests and possibly become bound to each other: strange failure
342 modes can result if one server goes down and
343 others are dependent upon on it.
344 (Eventually all the clients will
345 time out and attempt to bind to other servers, but the delay
346 involved can be considerable and the failure mode is still present
347 since the servers might bind to each other all over again).
351 man page for details on how to force it to bind to a particular
354 The following options are supported by
358 This option affects the way
360 handles yp_match requests for the
367 can't find an entry for a given host in its hosts maps, it will
368 return an error and perform no further processing.
373 will go one step further: rather than giving up immediately, it
374 will try to resolve the hostname or address using a DNS nameserver
376 If the query is successful,
378 will construct a fake database record and return it to the client,
379 thereby making it seem as though the client's yp_match request
382 This feature is provided for compatibility with SunOS 4.1.x,
383 which has brain-damaged resolver functions in its standard C
384 library that depend on
386 for hostname and address resolution.
389 resolver can be configured to do DNS
390 queries directly, therefore it is not necessary to enable this
391 option when serving only
396 Cause the server to run in debugging mode.
399 reports only unusual errors (access violations, file access failures)
403 In debug mode, the server does not background
404 itself and prints extra status messages to stderr for each
405 request that it receives.
406 Also, while running in debug mode,
408 will not spawn any additional subprocesses as it normally does
409 when handling yp_all requests or doing DNS lookups.
411 often take a fair amount of time to complete and are therefore handled
412 in subprocesses, allowing the parent server process to go on handling
414 This makes it easier to trace the server with
421 maps are stored under
425 flag may be used to specify an alternate
428 the system administrator to move the map files to a different place
429 within the filesystem.
432 .Bl -tag -width Pa -compact
433 .It Pa /var/yp/[domainname]/[maps]
437 .It Pa /etc/host.conf
438 resolver configuration file
439 .It Pa /var/yp/securenets
440 host access control file
445 .Xr rpc.yppasswdd 8 ,
452 .An Bill Paul Aq wpaul@ctr.columbia.edu