freebsd-dev/gnu/usr.sbin/ypserv/ypserv.8

.\" Copyright (c) 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	$Id$
.\"
.Dd February 4, 1995
.Dt YPSERV 8
.Os
.Sh NAME
.Nm ypserv
.Nd "NIS database server"
.Sh SYNOPSIS
.Nm ypserv
.Op Fl dns
.Op Fl debug
.Op Fl p Ar port
.Sh DESCRIPTION
.Nm NIS
is an RPC-based service designed to allow a number of UNIX-based
machines to share a common set of configuration files. Rather than
requiring a system administrator to update several copies of files
such as
.Pa /etc/hosts ,
.Pa /etc/passwd
and
.Pa /etc/group ,
which tend to require frequent changes in most environments, NIS
allows groups of computers to share one set of data which can be
updated from a single location.
.Pp
.Nm ypserv
is the server that distributes NIS databases
to client systems within an NIS
.Nm domain.
Each client in an NIS domain must have its domainname set to
one of the domains served by
.Nm ypserv
using the
.Xr domainname 2
command. The clients must also run
.Xr ypbind 8
in order to attach to a particular server, since it is possible to
have serveral servers within a single NIS domain.
.Pp
The databases distributed by
.Nm ypserv
are stored in
.Pa /var/yp/[domainname]
where
.Pa domainname
is the name of the domain being served. There can be several
such directories with different domainnames, and
.Nm ypserv
cam handle them all.
.Pp
The databases, or
.Pa maps
as they are often called,
are created by
.Nm /var/yp/Makefile
using several system files as source. The database files are in
.Xr db 3
format to help speed retrieval when there are many records involved.
In FreeBSD, the
maps are always readable and writable only by root for security
reasons. Technically this is only necessary for the password
maps, but since the data in the other maps can be found in
other world-readable files anyway, it doesn't hurt and it's considered
good general practice.
.Pp
.Nm ypserv
is started by
.Nm /etc/rc.local
if it has been enabled in
.Nm /etc/netstart.
.Sh SPECIAL FEATURES
There are some problems associated with distributing FreeBSD's password
database via NIS: FreeBSD normally only stores encrypted passwords
in
.Pa /etc/master.passwd ,
which is readable and writable only by root. By turning this file
into an NIS map, this security feature would be completely defeated.
.Pp
To make up for this, the FreeBSD version of
.Nm ypserv
handles the
.Pa master.passwd.byname
and
.Pa master.basswd.byuid
maps in a special way. When the server receives a request to access
either of these two maps, it will check the TCP port from which the
request originated and return an error if the port number is greater
than 1023. Since only the superuser is allowed to bind to TCP ports
with values less than 1024, the server can use this test to determine
whether or not the access request came from a privileged user.
Any requests made by non-privileged users are therefore rejected.
.Pp
Furthermore, the
.Xr getpwent 3
routines in FreeBSD's standard C libarary will only attempt to retrieve
data from the
.Pa master.passwd.byname
and
.Pa master.passwd.byuid
maps for the superuser: if a normal user calls any of these functions,
the standard
.Pa passwd.byname
and
.Pa passwd.byuid
maps will be accessed instead. The latter two maps are constructed by
.Nm /var/yp/Makefile
by parsing the
.Pa master.passwd
file and stripping out the password fields, and are therefore
safe to pass on to unprivileged users. In this way, the shadow password
aspect of the protected
.Pa master.passwd
database is maintained through NIS.
.Pp
.Sh NOTES
.Ss Limitations
There are two problems inherent with password shadowing in NIS
that users should
be aware of:
.Bl -enum -offset indent
.It
The 'TCP port less than 1024' test is trivial to defeat for users with
unrestricted access to machines on your network (even those machines
which do not run UNIX-based operating systems).
.It
If you plan to use a FreeBSD system to serve non-FreeBSD clients that
have no support for password shadowing (which is most of them), you
will have to disable the password shadowing entirely by uncommenting the
.Nm UNSECURE=True
entry in
.Nm /var/yp/Makefile .
This will cause the standard
.Pa passwd.byname
and
.Pa passwd.byuid
maps to be generated with valid encrypted password fields, which is
neccesary in order for non-FreeBSD clients to perform user
authentication through NIS.
.El
.Pp
.Ss Security
.Nm ypserv
has support for Wietse Venema's
.Pa tcpwrapper
package built in, though it is not compiled in by default since
the
.Pa tcpwrapper
package is not distributed with FreeBSD. However, if you have
.Nm libwrap.a
and
.Nm tcpd.h ,
you can easily recompile
.Nm ypserv
with them, thereby enabling its 'securenets' features: you can
configure
.Nm ypserv
to only handle resquests from machines listed
in the
.Pa tcpwrapper
configuration files, which would help limit vulnerability to the
first limitation listed above.
.Pp
.Ss NIS servers that are also NIS clients
Care must be taken when running
.Nm ypserv
in a multi-server domain where the server machines are also
NIS clients. It is generally a good idea to force the servers to
bind to themselves rather than allowing them to broadcast bind
requests and possibly become bound to each other: strange failure
modes can result if one server goes down and
others are dependent upon on it. (Eventually all the clients will
time out and attempt to bind to other servers, but the delay
involved can be considerable and the failure mode is still present
since the servers might bind to each other all over again).
.Pp
Refer to the
.Xr ypbind 8
man page for details on how to force it to bind to a particular
server.
.Sh OPTIONS
The following options are supported by
.Nm ypserv :
.Bl -tag -width flag
.It Fl dns
This option affects the way
.Nm ypserv
handles yp_match requests for the
.Pa hosts.byname
and
.Pa hosts.byaddress
maps. By default, if
.Nm ypserv
can't find an entry for a given host in its hosts maps, it will
return an error and perform no further processing. With the
.Fl dns
flag,
.Nm ypserv
will go one step further: rather than giving up immediately, it
will try to resolve the hostname or address using a DNS query.
If the query is successful,
.Nm ypserv
will construct a fake database record and return it to the client,
thereby making it seem as though the client's yp_match request
succeeded.
.Pp
This functionality is provided for compatiblity with SunOS 4.1.x,
which has brain-damaged resolver functions in its standard C
library that depend on NIS for hostname and address resolution.
FreeBSD's resolver can be configured to do DNS
queries directly, therefore it is not necessary to enable this
option when serving only FreeBSD NIS clients.
.It Fl debug
Run the server in debugging mode: the server does not background
itself and prints copious debugging output to stderr for
each
request that it revceives.
.It Fl p Ar port
Normally,
.Nm ypserv
will bind itself to a randomly chosen TCP port when it is first
started. This option can be used to force the server to bind to
a particular port instead.
.El
.Sh FILES
.Bl -tag -width Pa -compact
.It Pa /var/yp/[domainname]/[maps]
The NIS maps.
.It Pa /etc/host.conf
Resolver configuration file.
.El
.Sh SEE ALSO
.Xr ypbind 8 ,
.Xr yppasswdd 8 ,
.Xr yppush 8 ,
.Xr ypxfr 8 ,
.Xr ypcat 1 ,
.Xr yp 8 ,
.Xr db 3
.Sh LICENSE
This program is covered by the GNU Public License version 2.
.Sh AUTHOR
Peter Eriksson <pem@signum.se> (original Linux version)
.br
Bill Paul <wpaul@ctr.columbia.edu> (port to FreeBSD and various
changes)