Cleaned up and updated the yppasswdd man page to reflect FreeBSD-specific

changes and new options. (more new man pages and an NIS tutorial to follow)

1 files changed, 173 insertions, 70 deletions

diff --git a/gnu/usr.sbin/yppasswdd/yppasswdd.8 b/gnu/usr.sbin/yppasswdd/yppasswdd.8
index 24e3dda..53ac85a 100644
--- a/gnu/usr.sbin/yppasswdd/yppasswdd.8
+++ b/gnu/usr.sbin/yppasswdd/yppasswdd.8
@@ -5,88 +5,191 @@
 .\" It is provided in the hope that it is useful. However, the author
 .\" disclaims ALL WARRANTIES, expressed or implied. See the GPL for details.
 .\"
-.TH YPPASSWDD 8 "12 December 1994" "" ""
-.SH NAME
-rpc.yppasswdd \- NIS password update server
-.SH SYNOPSIS
-.B "rpc.yppasswdd [-s]"
-.SH DESCRIPTION
-\fByppasswdd\fP is the RPC server that lets users change their passwords
+.Dd 12 December 1994
+.Dt YPPASSWDD 8
+.Sh NAME
+.Nm yppasswdd
+.Nd NIS password database update server
+.Sh SYNOPSIS
+.Nm yppasswdd
+.Op Ar -m master password file
+.Op Fl s
+.Op Fl f
+.Op Fl v
+.Op Fl h
+.Sh DESCRIPTION
+.Nm yppasswdd
+is the RPC server that lets users change their passwords
 in the presence of NIS (a.k.a. YP). It must be run on the NIS master
 server for that NIS domain.
-.P
-When a \fByppasswd(1)\fP client contacts the server, it sends the old user
-password along with the new one. \fByppasswdd\fP will search the system's
-\fB/etc/passwd\fP file for the specified user name, verify that the
+.Pp
+When a
+.Xr yppasswd 1
+client contacts the server, it sends the old user
+password along with the new one.
+.Nm yppasswdd
+will search the system's
+NIS password database file for the specified user name, verify that the
 given (old) password matches, and update the entry. If the user
 specified does not exist, or if the password, UID or GID doesn't match
 the information in the password file, the update request is rejected,
 and an error returned to the client.
-.P
-After updating the \fBpasswd\fP file and returning a success notification
-to the client, \fByppasswdd\fP executes the \fBpwupdate\fP script that
-updates the NIS server's \fBpasswd.*\fP maps. This script assumes all
-NIS maps are kept in directories named 
-.BI /var/yp/< nisdomain >
-that each contain a \fBMakefile\fP customized for that NIS domain.
-.SH OPTIONS
-The following options are available with \fByppasswdd\fP:
-.IP "\-s"
-When \fByppasswdd\fP is compiled with support for John\ F. Haugh's shadow
-library, this option makes the server use the password functions from the
-\fBlibshadow\fP library instead of the standard ones. See below for a 
-brief discussion of shadow support.
-.SH MISCELLANEOUS
-.SS Shadow Passwords
-Using Shadow passwords alongside NIS does not make too much sense, because
-the supposedly inaccesible passwords now become readable through a simple
-invocation of \fBypcat(8)\fP.
-.P
-Shadow support in \fByppasswdd\fP does not mean that it offers a very
-clever solution to this problem, it simply means that it can read and write
-password entries in \fB/etc/shadow\fP.  You still have to produce a normal
-NIS map to distribute password information to your NIS clients.
-The \fByp.pwupdate\fP script supplied with
-\fByppasswdd\fP creates a standard \fB/etc/passwd\fP file from
-\fP/etc/shadow\fP using \fBpwunconv(8)\fP and produces the NIS maps from
-that.
-.SS Logging
-\fByppasswdd\fP logs all password update requests to \fBsyslogd(8)\fP's
+.Pp
+After updating the
+.Nm master.passwd
+file and returning a success
+notifications to the client,
+.Nm yppasswdd executes the
+.Nm yppwupdate
+script that updates the NIS server's
+.Nm master.passwd.*
+and
+.Nm passwd.*
+maps. This script invokes 
+.Nm /var/yp/Makefile
+to rebuild the NIS password maps (and propagate them to NIS slave
+servers if there are any in the domain).
+.Sh OPTIONS
+.Bl -tag -width Ds
+The following options are available with
+.Nm yppasswdd:
+.It Fl Ar m master password file
+.Nm yppasswdd
+server needs to know the location of the
+master.passwd file that is to be used to generate updated NIS
+password maps. This file is normally kept in
+.Nm /var/yp
+(it must be owned by root and not world readable for security reasons). 
+If you move it somewhere else you'll have to tell yppasswdd using the
+.Fl m
+option. (You'll have to change the location of master.passwd specified in
+.Nm /var/yp/Makefile
+as well.) When the server is ready to change
+a password database entry, it will modify master.passwd, then
+call the yppwupdate script, which will in turn call
+.Nm /var/yp/Makefile.
+.Pp
+Without the -m option,
+.Nm yppasswdd
+expects to use the local
+.Nm /etc/master.passwd
+file on the NIS master server as the source for 
+regenerating the password maps (the server will rebuild the local 
+password databases in this case as well).
+.Pp
+This is less secure than
+using a seperate password database to restrict access to the NIS 
+master server, but the functionality is provided in the event this 
+behavior is desired and security is not paramount (such as might be
+the case on a closed local network of trusted systems).
+Note that you will have to edit
+.Nm /var/yp/Makefile
+to use
+.Nm /etc/master.passwd
+instead of
+.Nm /var/yp/master.passwd
+if you want to use yppasswdd in this way.
+.It Fl s
+When invoked with the
+.Fl s
+flag,
+.Nm yppasswdd
+will allow users to change
+the shell field of their NIS password entry. Without it,
+.Xr yppasswd 1
+will
+appear to succeed when a user tries to change shells, but yppasswdd
+will not actually alter the password database.
+.It Fl f
+This flag works just like
+.Fl s ,
+except it applies to the GECOS or
+"fullname" field of a user's NIS password entry instead of the shell field. 
+Some sites may wish to restrict users' ability to change their shells or 
+full names for security or administrative reasons, which is why these two 
+options are provided.
+.Sh MISCELLANEOUS
+.Ss Logging
+.Nm yppasswdd
+logs all password update requests to
+.Xr syslogd 8
 auth facility. The logging information includes the originating host's
 IP address and the user name and UID contained in the request. The
 user-supplied password itself is not logged.
-.SS Security
+.Ss Security
 Unless I've screwed up completely (as I did with versions prior to
-version\ 0.5), \fByppasswdd\fP should be as secure or insecure as any
+version 0.5),
+.Nm yppasswdd
+should be as secure or insecure as any
 program relying on simple password authentication.  If you feel that
-this is not enough, you may want to protect \fByppasswdd\fP from outside
-access by using the `securenets' feature of the new \fBportmap(8)\fP
-version\ 3.  Better still, use Kerberos.
-.SH COPYRIGHT
-\fByppasswdd\fP is copyright (C) Olaf Kirch. You can use and distribute it
-under the GNU General Public License Version 2. Note that it does \fInot\fP
-contain any code from the shadow password suite. This means that as long as
-you don't use shadow passwords, you won't be affected by the ``no commercial
-use'' policy of the shadow suite.
-.SH FILES
-\fB/usr/sbin/rpc.yppasswdd\fP
+this is not enough, you may want to protect
+.Nm yppasswdd
+from outside
+access by using the 'securenets' feature of
+.Xr portmap 8
+version 3.  Better still, use Kerberos.
+.Sh NOTES
+.Ss FreeBSD changes
+Unlike the original
+.Nm yppasswdd ,
+the FreeBSD version has no support for 
+John F. Haugh II's shadow password suite. It doesn't need it: 4.4BSD's
+password database system already implements shadow passwords.
+.Ss Using the yppasswdd server with non-FreeBSD clients
+FreeBSD's
+.Nm yppasswdd
+should work equally well with non-FreeBSD client machines provided a
+few small changes are made to
+.Nm /var/yp/Makefile.
+FreeBSD's passwd.byname and passwd.byuid maps do not contain actual
+encrypted passwords (just like FreeBSD's /etc/passwd file): the real
+encrypted passwords are kept in master.passwd.byname and
+master.passwd.byuid, which FreeBSD's NIS server will only serve to
+the superuser on FreeBSD NIS clients (non-privileged users are not
+permitted to access these maps). Non-FreeBSD clients will not function
+properly in this situation, since they require the password fields in
+the passwd.* maps to be valid.
+.Pp
+To use
+.Nm yppasswdd
+with non-FreeBSD clients, you will need to edit
+.Nm /var/yp/Makefile
+and uncomment the line that says 'UNSECURE=True' and run
+.Xr make 1 .
+This will cause
+.Nm /var/yp/Makefile
+to generate passwd.* maps with real passwords in them instead of
+stripping them out as it does normally.
+.Sh FILES
+.Bl -tag -width /usr/libexec/yppwupdate -compact
+.It Pa /usr/sbin/yppasswdd
+The yppasswdd daemon
+.It Pa /usr/libexec/yppwupdate
+The NIS map update script
+.It Pa /var/yp/master.passwd
+NIS password map source file
+.It Pa /etc/master.passwd
+Raw local password database (only used when
+.Fl m
+option isn't supplied)
+.Sh SEE ALSO
+.Xr passwd 5 ,
+.Xr passwd 1 ,
+.Xr portmap 8 ,
+.Xr pwunconv 8 ,
+.Xr yppasswd 1 ,
+.Xr ypchsh 1 ,
+.Xr ypchfn 1 ,
+.Xr ypserv 8 ,
+.Xr ypcat 8 .
+.Sh COPYRIGHT
+.Nm yppasswdd
+is copyright (C) Olaf Kirch. You can use and distribute it
+under the GNU General Public License Version 2.
+.Sh AUTHOR(S)
 .br
-\fB/usr/lib/yp/pwupdate\fP
-.br
-\fB/etc/passwd\fP
-.br
-\fB/etc/shadow\fP
-.SH SEE ALSO
-.IR passwd(5) ,
-.IR passwd(8) ,
-.IR portmap(8) ,
-.IR pwunconv(8) ,
-.IR yppasswd(1) ,
-.IR ypchsh(1) ,
-.IR ypchfn(1) ,
-.IR ypserv(8) ,
-.IR ypcat(8) .
-.SH AUTHOR
 Olaf Kirch, <okir@monad.swb.de>
 .br
 Charles Lopez, <tjarls@infm.ulst.ac.uk> (shadow support)
+.br
+Bill Paul, <wpaul@ctr.columbia.edu> (port to FreeBSD, various small changes)