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