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