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