380 lines
13 KiB
Groff
380 lines
13 KiB
Groff
.\" Copyright (c) 1992/3 Theo de Raadt <deraadt@fsa.ca>
|
|
.\" 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. The name of the author may not be used to endorse or promote
|
|
.\" products derived from this software without specific prior written
|
|
.\" permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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.
|
|
.\"
|
|
.\" from: @(#)yp.8 1.0 (deraadt) 4/26/93
|
|
.\" $Id$
|
|
.\"
|
|
.Dd April 5, 1993
|
|
.Dt YP 4
|
|
.Os BSD 4.2
|
|
.Sh NAME
|
|
.Nm yp
|
|
.Nd description of the YP/NIS system
|
|
.Sh SYNOPSIS
|
|
.Nm yp
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm YP
|
|
subsystem allows network management of passwd, group, netgroup, hosts,
|
|
services, rpc, bootparams and ethers file
|
|
entries through the functions
|
|
.Xr getpwent 3 ,
|
|
.Xr getgrent 3 ,
|
|
.Xr getnetgrent 3 ,
|
|
.Xr gethostent 3 ,
|
|
.Xr getnetent 3 ,
|
|
.Xr getrpcent 3 ,
|
|
and
|
|
.Xr ethers 3 .
|
|
The
|
|
.Xr bootparamd 8
|
|
daemon makes direct NIS library calls since there are no
|
|
functions in the standard C library for reading bootparams. NIS
|
|
support for the hosts, services and rpc databases is enabled by
|
|
uncommenting the
|
|
.Pa nis
|
|
line in
|
|
.Pa /etc/host.conf.
|
|
NIS support for the remaining services is
|
|
activated by adding a special '+' entry to the appropriate file.
|
|
.Pp
|
|
The
|
|
.Nm YP
|
|
subsystem is started automatically in
|
|
.Pa /etc/rc
|
|
if it has been initialized in
|
|
.Pa /etc/sysconfig
|
|
and if the directory
|
|
.Pa /var/yp
|
|
exists (which it does in the default distribution). The default
|
|
NIS domain must also be set with the
|
|
.Xr domainname 1
|
|
command, which will happen automatically at system startup if it is
|
|
specified in
|
|
.Pa /etc/sysconfig.
|
|
.Pp
|
|
NIS is an RPC-based client/server system that allows a group of
|
|
machines within an NIS
|
|
.Em domain
|
|
to share a common set of configuration files. This permits a system
|
|
administrator to set up NIS client systems with only minimal configuration
|
|
data and add, remove or modify configuration data from a single location.
|
|
.Pp
|
|
The canonical copies of all NIS information are stored on a single machine
|
|
called the
|
|
.Pa NIS master server .
|
|
The databases used to store the information are called
|
|
.Pa NIS maps.
|
|
In FreeBSD, these maps are stored in
|
|
.Pa /var/yp/[domainname]
|
|
where
|
|
.Pa [domainname]
|
|
is the name of the NIS domain being served. A single NIS server can
|
|
support several domains at once, therefore it is possible to have several
|
|
such directories, one for each supported domain. Each domain will have
|
|
its own independent set of maps.
|
|
.Pp
|
|
In FreeBSD, the NIS maps are Berkeley DB hashed database files (the
|
|
same format used for the
|
|
.Xr passwd 5
|
|
database files). Other operating systems that support NIS use old-style
|
|
ndbm databases instead (largely because Sun Microsystems originally based
|
|
their NIS implementation on ndbm, and other vendors have simply licensed
|
|
Sun's code rather than design their own implementation with a different
|
|
database format). On these systems, the databases are generally split
|
|
into
|
|
.Em .dir
|
|
and
|
|
.Em .pag
|
|
files which the ndbm code uses to hold separate parts of the hash
|
|
database. The Berkeley DB hash method instead uses a single file for
|
|
both pieces of information. This means that while you may have
|
|
.Pa passwd.byname.dir
|
|
and
|
|
.Pa passwd.byname.pag
|
|
files on other operating systems (both of which are really parts of the
|
|
same map), FreeBSD will have only one file called
|
|
.Pa passwd.byname .
|
|
The difference in format is not significant: only the
|
|
NIS server,
|
|
.Xr ypserv 8 ,
|
|
and related tools need to know the database format of the NIS maps. Client
|
|
NIS systems receive all NIS data in ASCII form.
|
|
.Pp
|
|
There are three main types of NIS systems:
|
|
.Bl -enum -offset indent
|
|
.It
|
|
.Pa NIS clients ,
|
|
which query NIS servers for information.
|
|
.It
|
|
.Pa NIS master servers ,
|
|
which maintain the canonical copies of all NIS maps.
|
|
.It
|
|
.Pa NIS slave servers ,
|
|
which maintain backup copies of NIS maps that are periodically
|
|
updated by the master.
|
|
.El
|
|
.Pp
|
|
An NIS client establishes what is called a
|
|
.Em binding
|
|
to a particular NIS server using the
|
|
.Xr ypbind 8
|
|
daemon.
|
|
.Xr Ypbind 8
|
|
checks the system's default domain (as set by the
|
|
.Xr domainname 1
|
|
command) and begins broadcasting RPC requests on the local network.
|
|
These requests specify the name of the domain for which
|
|
.Xr ypbind 8
|
|
is attempting to establish a binding. If a server that has been
|
|
configured to serve the requested domain receives one of the broadcasts,
|
|
it will respond to
|
|
.Xr ypbind 8 ,
|
|
which will record the server's address. If there are several servers
|
|
available (a master and several slaves, for example),
|
|
.Xr ypbind 8
|
|
will use the address of the first one to respond. From that point
|
|
on, the client system will direct all of its NIS requests to that server.
|
|
.Xr Ypbind 8
|
|
will occasionally ``ping'' the server to make sure it's still up
|
|
and running. If it fails to receive a reply to one of its pings
|
|
within a reasonable amount of time,
|
|
.Xr ypbind 8
|
|
will mark the domain as unbound and begin broadcasting again in the
|
|
hopes of locating another server.
|
|
.Pp
|
|
NIS master and slave servers handle all NIS requests with the
|
|
.Xr ypserv 8
|
|
daemon.
|
|
.Xr Ypserv 8
|
|
is responsible for receiving incoming requests from NIS clients,
|
|
translating the requested domain and map name to a path to the
|
|
corresponding database file and transmitting data from the database
|
|
back to the client. There is a specific set of requests that
|
|
.Xr ypserv 8
|
|
is designed to handle, most of which are implemented as functions
|
|
within the standard C library:
|
|
.Bl -bullet -offset indent
|
|
.It
|
|
.Fn yp_order
|
|
-- check the creation date of a particular map
|
|
.It
|
|
.Fn yp_master
|
|
-- obtain the name of the NIS master server for a given
|
|
map/domain
|
|
.It
|
|
.Fn yp_match
|
|
-- lookup the data corresponding to a given in key in a particular
|
|
map/domain
|
|
.It
|
|
.Fn yp_first
|
|
-- obtain the first key/data pair in a particular map/domain
|
|
.It
|
|
.Fn yp_next
|
|
-- pass
|
|
.Xr ypserv 8
|
|
a key in a particular map/domain and have it return the
|
|
key/data pair immediately following it (the functions
|
|
.Fn yp_first
|
|
and
|
|
.Fn yp_next
|
|
can be used to do a sequential search of an NIS map)
|
|
.It
|
|
.Fn yp_all
|
|
-- retrieve the entire contents of a map
|
|
.El
|
|
.Pp
|
|
There are a few other requests which
|
|
.Xr ypserv 8
|
|
is capable of handling (i.e. acknowledge whether or not you can handle
|
|
a particular domain (YPPROC_DOMAIN), or acknowledge only if you can
|
|
handle the domain and be silent otherwise (YPPROC_DOMAIN_NONACK)) but
|
|
these requests are usually generated only by
|
|
.Xr ypbind 8
|
|
and are not meant to be used by standard utilities.
|
|
.Pp
|
|
On networks with a large number of hosts, it is often a good idea to
|
|
use a master server and several slaves rather than just a single master
|
|
server. A slave server provides the exact same information as a master
|
|
server: whenever the maps on the master server are updated, the new
|
|
data should be propagated to the slave systems using the
|
|
.Xr yppush 8
|
|
command. The NIS Makefile (
|
|
.Pa /var/yp/Makefile )
|
|
will do this automatically if the administrator comments out the
|
|
line which says
|
|
.Em NOPUSH=true
|
|
(NOPUSH is set to true by default because the default configuration is
|
|
for a small network with only one NIS server). The
|
|
.Xr yppush 8
|
|
command will initiate a transaction between the master and slave
|
|
during which the slave will transfer the specified maps from the
|
|
master server using
|
|
.Xr ypxfr 8 .
|
|
(The slave server calls
|
|
.Xr ypxfr 8
|
|
automatically from within
|
|
.Xr ypserv 8 ;
|
|
therefore it is not usually necessary for the administrator
|
|
to use it directly. It can be run manually if
|
|
desired, however.) Maintaining
|
|
slave servers helps improve NIS performance on large
|
|
networks by:
|
|
.Pp
|
|
.Bl -bullet -offset indent
|
|
.It
|
|
Providing backup services in the event that the NIS master crashes
|
|
or becomes unreachable
|
|
.It
|
|
Spreading the client load out over several machines instead of
|
|
causing the master to become overloaded
|
|
.It
|
|
Allowing a single NIS domain to extend beyond
|
|
a local network (the
|
|
.Xr ypbind 8
|
|
daemon might not be able to locate a server automatically if it resides on
|
|
a network outside the reach of its broadcasts. It is possible to force
|
|
.Xr ypbind 8
|
|
to bind to a particular server with
|
|
.Xr ypset 8
|
|
but this is sometimes inconvenient. This problem can be avoided simply by
|
|
placing a slave server on the local network.)
|
|
.El
|
|
.Pp
|
|
The FreeBSD
|
|
.Xr ypserv 8
|
|
is specially designed to provided enhanced security (compared to
|
|
other NIS implementations) when used exclusively with FreeBSD client
|
|
systems. The FreeBSD password database system (which is derived directly
|
|
from
|
|
.Bx 4.4 )
|
|
includes support for
|
|
.Em "shadow passwords" .
|
|
The standard password database does not contain users' encrypted
|
|
passwords: these are instead stored (along with other information)
|
|
is a separate database which is accessible only by the super-user.
|
|
If the encrypted password database were made available as an NIS
|
|
map, this security feature would be totally disabled, since any user
|
|
is allowed to retrieve NIS data.
|
|
.Pp
|
|
To help prevent this, FreeBSD's NIS server
|
|
handles the shadow password maps (
|
|
.Pa master.passwd.byname
|
|
and
|
|
.Pa master.passwd.byuid )
|
|
in a special way: the server will only provide access to these
|
|
maps in response to requests that originate on privileged ports.
|
|
Since only the super-user is allowed to bind to a privileged port,
|
|
the server assumes that all such requests come from privileged
|
|
users. All other requests are denied: requests from non-privileged
|
|
ports will receive only an error code from the server. Additionally,
|
|
FreeBSD's
|
|
.Xr ypserv 8
|
|
includes support for Wietse Venema's tcp wrapper package; with tcp
|
|
wrapper support enabled, the administrator can configure
|
|
.Xr ypserv 8
|
|
to respond only to selected client machines.
|
|
.Pp
|
|
While these enhancements provide better security than stock NIS,
|
|
they are by no means 100% effective. It is still possible for
|
|
someone with access to your network to spoof the server into disclosing
|
|
the shadow password maps.
|
|
.Pp
|
|
On the client side, FreeBSD's
|
|
.Fn getpwent 3
|
|
functions will automatically search for the
|
|
.Pa master.passwd
|
|
maps and use them if they exist. If they do, they will be used, and
|
|
all fields in these special maps (class, password age and account
|
|
expiration) will be decoded. If they aren't found, the standard
|
|
.Pa passwd
|
|
maps will be used instead.
|
|
.Sh COMPATIBILITY
|
|
Some systems, such as SunOS 4.x, need NIS to be running in order
|
|
for their hostname resolution functions (
|
|
.Fn gethostbyname ,
|
|
.Fn gethostbyaddr ,
|
|
etc) to work properly. On these systems,
|
|
.Xr ypserv 8
|
|
performs DNS lookups when asked to return information about
|
|
a host that doesn't exist in its
|
|
.Pa hosts.byname
|
|
or
|
|
.Pa hosts.byaddr
|
|
maps. FreeBSD's resolver uses DNS by default (it can be made to use
|
|
NIS, if desired), therefore its NIS server doesn't do DNS lookups
|
|
by default. However,
|
|
.Xr ypserv 8
|
|
can be made to perform DNS lookups if it is started with a special
|
|
flag. It can also be made to register itself as an NIS v1 server
|
|
in order to placate certain systems that insist on the presence of
|
|
a v1 server (FreeBSD uses only NIS v2, but many other systems,
|
|
including SunOS 4.x, search for both a v1 and v2 server when binding).
|
|
FreeBSD's
|
|
.Xr ypserv 8
|
|
does not actually handle NIS v1 requests, but this ``kludge mode''
|
|
is useful for silencing stubborn systems that search for both
|
|
a v1 and v2 server.
|
|
.Pp
|
|
(Please see the
|
|
.Xr ypserv 8
|
|
manual page for a detailed description of these special features
|
|
and flags.)
|
|
.Sh BUGS
|
|
While FreeBSD now has both NIS client and server capabilities,
|
|
it does not yet have support for
|
|
.Xr ypupdated 8
|
|
or the
|
|
.Fn yp_update
|
|
function. Both of these require secure RPC, which FreeBSD doesn't
|
|
support yet either.
|
|
.Pp
|
|
The
|
|
.Xr getservent 3
|
|
and
|
|
.Xr getprotoent 3
|
|
functions do not yet have NIS support. Fortunately, these files
|
|
don't need to be updated that often.
|
|
.Pp
|
|
Many more manual pages should be written, especially
|
|
.Xr ypclnt 3 .
|
|
For the time being, seek out a local Sun machine and read the
|
|
manuals for there.
|
|
.Pp
|
|
Neither Sun nor this author have found a clean way to handle
|
|
the problems that occur when ypbind cannot find its server
|
|
upon bootup.
|
|
.Sh HISTORY
|
|
The
|
|
.Nm YP
|
|
subsystem was written from the ground up by Theo de Raadt
|
|
to be compatible to Sun's implementation. Bug fixes, improvements
|
|
and NIS server support were later added by Bill Paul. The server-side
|
|
code was originally written by Peter Eriksson and Tobias Reber and
|
|
is subject to the GNU Public License. No Sun code was
|
|
referenced.
|