diff options
author | wpaul <wpaul@FreeBSD.org> | 1995-09-02 04:20:01 +0000 |
---|---|---|
committer | wpaul <wpaul@FreeBSD.org> | 1995-09-02 04:20:01 +0000 |
commit | 13cf8d48fa2648e2416aeb724f6f05eed9431204 (patch) | |
tree | d44ea3a27bce6101bc8451102af082d8ea62ad99 /share/man | |
parent | 0863217995c71be6cbd89180d178bdc0653dc6bb (diff) | |
download | FreeBSD-src-13cf8d48fa2648e2416aeb724f6f05eed9431204.zip FreeBSD-src-13cf8d48fa2648e2416aeb724f6f05eed9431204.tar.gz |
Update this man page to reflect reality.
Diffstat (limited to 'share/man')
-rw-r--r-- | share/man/man4/yp.4 | 338 | ||||
-rw-r--r-- | share/man/man8/yp.8 | 338 |
2 files changed, 642 insertions, 34 deletions
diff --git a/share/man/man4/yp.4 b/share/man/man4/yp.4 index f444316..441efeb 100644 --- a/share/man/man4/yp.4 +++ b/share/man/man4/yp.4 @@ -26,42 +26,343 @@ .\" SUCH DAMAGE. .\" .\" from: @(#)yp.8 1.0 (deraadt) 4/26/93 -.\" $Id: yp.4,v 1.2 1995/03/23 01:49:15 jkh Exp $ +.\" $Id: yp.4,v 1.3 1995/03/23 06:05:04 jkh Exp $ .\" .Dd April 5, 1993 .Dt YP 4 .Os BSD 4.2 .Sh NAME .Nm yp -.Nd description of the YP system +.Nd description of the YP/NIS system .Sh SYNOPSIS .Nm yp .Sh DESCRIPTION The .Nm YP -subsystem allows network management of passwd and group file -entries through the functions getpwent(3) and getgrent(3). +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 +.Nm bootparamd +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 -.Nm /etc/netstart -if the directory +.Pa /etc/rc +if it has been initialized in +.Pa /etc/sysconfig +and if the directory .Nm /var/yp -exists. +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 +.Nm 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 +.Nm .dir +and +.Nm .pag +files which the ndbm code uses to hold seperate 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 +.Nm 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 +withing 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 +.Nm yp_order() +-- check the creation date of a particular map +.It +.Nm yp_master() +-- obtain the name of the NIS master server for a given +map/domain +.It +.Nm yp_match() +-- lookup the data corresponding to a given in key in a particular +map/domain +.It +.Nm yp_first() +-- obtain the first key/data pair in a particular map/domain +.It +.Nm yp_next() +-- pass +.Xr ypserv 8 +a key in a particular map/domain and have it return the +key/data pair immediately following it (yp_first() and yp_next() +can be used to do a sequential search of an NIS map) +.It +.Nm yp_all() +-- retreive the entire contents of a map +.El +.Pp +There are a few other requests which +.Xr ypserv +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 +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 +.Nm 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 unreachanble +.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 +form 4.4BSD) includes support for +.Nm shadow passwords . +The standard password database does not contain users' encrpyted +passwords: these are instead stored (along with other information) +is a seperate database which is accesible 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 -Only -.Nm YP -client functionality exists -- the server code has not yet been -written. Brave folk can contact the author. - -.Nm /etc/passwd +While FreeBSD now has both NIS client and server capabilities, +it does not yet have support for +.Nm ypupdated +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 -.Nm /etc/group only supports "+" entries. - +.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 ypclnt(3). For the time being, seek out a local Sun machine and read the manuals for there. - +.Pp +FreeBSD's server-side support is based on GPL'ed code originally +written for Linux. It really needs its own implementation that is not +subject to the GPL. +.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. @@ -69,5 +370,8 @@ upon bootup. The .Nm YP subsystem was written from the ground up by Theo de Raadt -to be compatible to Sun's implimentation. No Sun code was +to be compatible to Sun's implimentation. 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. diff --git a/share/man/man8/yp.8 b/share/man/man8/yp.8 index f444316..441efeb 100644 --- a/share/man/man8/yp.8 +++ b/share/man/man8/yp.8 @@ -26,42 +26,343 @@ .\" SUCH DAMAGE. .\" .\" from: @(#)yp.8 1.0 (deraadt) 4/26/93 -.\" $Id: yp.4,v 1.2 1995/03/23 01:49:15 jkh Exp $ +.\" $Id: yp.4,v 1.3 1995/03/23 06:05:04 jkh Exp $ .\" .Dd April 5, 1993 .Dt YP 4 .Os BSD 4.2 .Sh NAME .Nm yp -.Nd description of the YP system +.Nd description of the YP/NIS system .Sh SYNOPSIS .Nm yp .Sh DESCRIPTION The .Nm YP -subsystem allows network management of passwd and group file -entries through the functions getpwent(3) and getgrent(3). +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 +.Nm bootparamd +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 -.Nm /etc/netstart -if the directory +.Pa /etc/rc +if it has been initialized in +.Pa /etc/sysconfig +and if the directory .Nm /var/yp -exists. +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 +.Nm 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 +.Nm .dir +and +.Nm .pag +files which the ndbm code uses to hold seperate 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 +.Nm 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 +withing 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 +.Nm yp_order() +-- check the creation date of a particular map +.It +.Nm yp_master() +-- obtain the name of the NIS master server for a given +map/domain +.It +.Nm yp_match() +-- lookup the data corresponding to a given in key in a particular +map/domain +.It +.Nm yp_first() +-- obtain the first key/data pair in a particular map/domain +.It +.Nm yp_next() +-- pass +.Xr ypserv 8 +a key in a particular map/domain and have it return the +key/data pair immediately following it (yp_first() and yp_next() +can be used to do a sequential search of an NIS map) +.It +.Nm yp_all() +-- retreive the entire contents of a map +.El +.Pp +There are a few other requests which +.Xr ypserv +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 +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 +.Nm 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 unreachanble +.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 +form 4.4BSD) includes support for +.Nm shadow passwords . +The standard password database does not contain users' encrpyted +passwords: these are instead stored (along with other information) +is a seperate database which is accesible 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 -Only -.Nm YP -client functionality exists -- the server code has not yet been -written. Brave folk can contact the author. - -.Nm /etc/passwd +While FreeBSD now has both NIS client and server capabilities, +it does not yet have support for +.Nm ypupdated +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 -.Nm /etc/group only supports "+" entries. - +.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 ypclnt(3). For the time being, seek out a local Sun machine and read the manuals for there. - +.Pp +FreeBSD's server-side support is based on GPL'ed code originally +written for Linux. It really needs its own implementation that is not +subject to the GPL. +.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. @@ -69,5 +370,8 @@ upon bootup. The .Nm YP subsystem was written from the ground up by Theo de Raadt -to be compatible to Sun's implimentation. No Sun code was +to be compatible to Sun's implimentation. 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. |