Update this man page to reflect reality with respect to NIS and

document the proper way to set up NIS overrides in the password database.

1 files changed, 369 insertions, 38 deletions

diff --git a/share/man/man5/passwd.5 b/share/man/man5/passwd.5
index 238ae56..945a2a5 100644
--- a/share/man/man5/passwd.5
+++ b/share/man/man5/passwd.5
@@ -30,7 +30,7 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     From: @(#)passwd.5	8.1 (Berkeley) 6/5/93
-.\"	$Id$
+.\"	passwd.5,v 1.2 1994/09/20 22:44:37 wollman Exp
 .\"
 .Dd September 29, 1994
 .Dt PASSWD 5
@@ -154,44 +154,360 @@ field, the Bourne shell
 .Pq Pa /bin/sh
 is assumed.
 .Sh YP/NIS INTERACTION
-The
+.Ss Enabling access to NIS passwd data
+The system administrator can configure FreeBSD to use NIS/YP for
+its password information by adding special records to the
+.Pa /etc/master.passwd
+file. These entries should be added with
+.Xr vipw 8
+so that the changes can be properly merged with the hashed
+password databases and the
 .Pa /etc/passwd
-file can be configured to enable the YP/NIS group database.
-An entry whose
-.Ar name
-field consists of a plus sign (`+') followed by a login name, will be
-replaced internally to the C library with the YP/NIS password entry for the
-named group.  An entry whose
-.Ar name
-field consists of a single plus sign with no login name following,
-will be replaced with the entire YP/NIS
-.Dq Li passwd.byname
-map.
-.Pp
-If any fields other than the login name are left empty, they
-will be used to override the YP/NIS database's values.  So, for
-example, an
+file (
+.Pa /etc/passwd
+should never be edited manually). Alternatively, the administrator
+can modify
+.Pa /etc/master.passwd
+in some other way and then manually update the password databases with
+.Xr pwd_mkdb 8 .
+.Pp
+The simplest way to activate NIS is to add an empty record
+with only a plus sign (`+') in the name field, such as this:
+.Bd -literal -offset indent
++:::::::::
+
+.Ed
+The `+' will tell the
+.Xr getpwent 3
+routines in FreeBSD's standard C library to begin using the NIS passwd maps
+for lookups.
+.Pp
+Note that the entry shown above is known as a
+.Pa wildcard
+entry, because it matches all users (the `+' without any other information
+matches everybody) and allows all NIS password data to be retrieved
+unaltered. However, by
+specifying a username or netgroup next to the `+' in the NIS
+entry, the administrator can affect what data is extracted from the
+NIS passwd maps and how it is interpreted. Here are a few example
+records that illustrate this feature (note that you can have several
+NIS entries in a single
+.Pa master.passwd
+file):
+.Bd -literal -offset indent
+-mitnick:::::::::
++@staff:::::::::
++@permitted-users:::::::::
++dennis:::::::::
++ken:::::::::/bin/csh
++@rejected-users::32767:32767::::::/bin/false
+
+.Ed
+Specific usernames are listed explicitly while netgroups are signfied
+by a preceeding `@'. In the above example, users in the ``staff'' and
+``permitted-users'' netgroups will have their password information
+read from NIS and used unaltered. In other worrds, they will be allowed
+normal access to the machine. Users ``ken'' and ``dennis,'' who have
+beed named explicitly rather than through a netgroup, will also have
+their password data read from NIS, _except_ that user ``ken'' will
+have his shell remapped to
+.Pa /bin/csh .
+This means that value for his shell specified in the NIS password map
+will be overriden by the value specified in the special NIS entry in
+the local
+.Pa master.passwd
+file. User ``ken'' may have been assigned the csh shell because his
+NIS password entry specified a different shell that may not be
+installed on the client machine for political or technical reasons.
+Meanwhile, users in the ``rejected-users'' netgroup are prevented
+from logging in because their UIDs, GIDs and shells have been overridden
+with invalid values.
+.Pp
+User ``mitnick'' will be be ignored entirely because his entry is
+specified with a `-' instead of a `+'. A minus entry can be used
+to block out certain NIS password entries completely; users who's
+password data has been excluded in this way are not recognized by
+the system at all. (Any overrides specified with minus entries are
+also ignored since there is no point in processing override information
+for a user that the system isn't going to recognize in the first place.)
+In general, a minus entry is used to specifically exclude a user
+who might otherwise be granted access because he happens to be a
+member of an authorized netgroup. For example, if ``mitnick'' is
+a member of the ``permitted-users'' netgroup and must, for whatever
+the reason, be permitted to remain in that netgroup (possibly to
+retain access to other machines within the domain), the admistrator
+can still deny him access to a particular system with a minus entry.
+Also, it is sometimes easier to explicitly list those users who aren't
+allowed access rather than generate a possibly complicated list of
+users who are allowed access and omit the rest.
+.Pp
+Note that the plus and minus entries are evaluated in order from
+first to last with the first match taking precedence. This means
+that the system will only use the first entry which matches a particular user.
+If, for instance, we have a user ``foo'' who is a member of both the ``staff''
+netgroup and the ``rejected-users'' netgroup, he will be admitted to
+the system because the above example lists the entry for ``staff'' 
+before the entry for ``rejected-users.'' If we reversed the order,
+user ``foo'' would be flagged as a ``rejected-user'' instead and
+denied access.
+.Pp
+Lastly, any NIS password database records that do not match against
+at least one of the users or netgroups specified by the NIS access
+entries in the
+.Pa /etc/master.passwd
+file will be ignored (along with any users specified using minus
+entries). In our example shown above, we do not have a wildcard
+entry at the end of the list; therefore, the system will not recognize
+anyone except
+``ken,'' ``dennis,'' the ``staff'' netgroup and the ``permitted-users''
+netgroup as authorized users. The ``rejected-users'' netgroup will
+be recognized but all members will have their shells remapped and
+therefore be denied access.
+All other NIS password records
+will be ignored. The administrator may add a wildcard entry to the
+end of the list such as:
+.Bd -literal -offset indent
++:::::::::/usr/local/bin/go_away
+
+.Ed
+This entry acts as a catch-all for all users that don't match against
+any of the other entries.
+.Pa /usr/local/bin/go_away
+can be a short shell script or program
+that prints a message telling the user that he is not allowed access
+to the system. This technique is sometimes userful when it is
+desireable to have the system be able to recognize all users in a
+particular NIS domain without necessarily granting them login access.
+.Pp
+The primary use of this
+.Pa override
+feature is to permit the administrator
+to enforce access restrictions on NIS client systems. Users can be
+granted access to one group of machines and denied access to other
+machines simply by adding or removing them from a particular netgroup.
+Since the netgroup database can also be accessed via NIS, this allows
+access restrictions to be administered from a single location, namely
+the NIS master server; once a host's access list has been set in
+.Pa /etc/master.passwd ,
+it need not be modified again unless new netgroups are created.
+.Sh NOTES
+.Ss Shadow passwords through NIS
+FreeBSD uses a shadow password scheme: users' encrypted passwords
+are stored only in
+.Pa /etc/master.passwd
+and
+.Pa /etc/spwd.db ,
+which are readable and writable only by the superuser. This is done
+to prevent users from running the encrypted passwords through
+password-guessing programs and gaining unauthorized access to
+other users' accounts. NIS does not support a standard means of
+password shadowing, which implies that placing your password data
+into the NIS passwd maps totally defeats the security of FreeBSD's
+password shadowing system.
+.Pp
+FreeBSD provides a few special features to help get around this
+problem. It is possible to implement password shawdowing between
+FreeBSD NIS clients and FreeBSD NIS servers. The
+.Xr getpwent 3
+routines will search for a
+.Pa master.passwd.byname
+and
+.Pa master.passwd.byuid
+maps which should contain the same data found in the
+.Pa /etc/master.passwd
+file. If the maps exist, FreeBSD will attempt to use them for user
+authentication instead of the standard
+.Pa passwd.byname
+and
+.Pa passwd.byuid
+maps. FreeBSD's
+.Xr ypserv 8
+will also check client requests to make sure they originate on a
+privileged port. Since only the superuser is allowed to bind to
+a privileged port, the server can tell if the requesting user
+is the superuser; all requests from non-privileged users to access
+the
+.Pa master.passwd
+maps will be refused. Since all user authentication programs run
+with superuser privilege, they should have the required access to
+users' encrypted password data while normal users will only
+be allowed access to the standard
+.Pa passwd
+maps which contain no password information.
+.Pp
+Note that this feature cannot be used in an environment with
+non-FreeBSD systems. Note also that a truly determined user with
+unrestricted access to your network could still compromise the
+.Pa master.passwd
+maps.
+.Ss UID and GID remapping with NIS overrides
+Unlike SunOS and other operating systems that use Sun's NIS code,
+FreeBSD allows the user to override
+.Pa all
+of the fields in a user's NIS
+.Pa passwd
+entry.
+For example, consider the following
 .Pa /etc/master.passwd
-entry of:
+entry:
 .Bd -literal -offset indent
-+:::::::::/etc/noaccess
++@foo-users:???:666:666:0:0:0:Bogus user:/home/bogus:/bin/bogus
 
 .Ed
-would use the entire contents of the YP/NIS password database, but
-each entry would have its designated shell replaced by
-.Pa /etc/noaccess
-(presumably, a program to tell those users that they are not allowed to
-access the machine).
-This is the only way to specify values for the fields which are not
-present in the Sixth Edition format used by YP/NIS.
-.Pp
-If the YP/NIS password database is enabled for any reason, all reverse
-lookups (i.e.,
+This entry will cause all users in the `foo-users' netgroup to
+have
+.Pa all
+of their password information overriden, including UIDs,
+GIDs and passwords. The result is that all `foo-users' will be
+locked out of the system, since their passwords will be remapped
+to invalid values.
+.Pp
+This is important to remember because most people are accustomed to
+using an NIS wildcard entry that looks like this:
+.Bd -literal -offset indent
++:*:0:0:::
+
+.Ed
+This often leads to new FreeBSD admins choosing NIS entries for their
+.Pa master.passwd
+files that look like this:
+.Bd -literal -offset indent
++:*:0:0::::::
+
+.Ed
+Or worse, this
+.Bd -literal -offset indent
++::0:0::::::
+
+.Ed
+.Pa DO _NOT_ PUT ENTRIES LIKE THIS IN YOUR
+.Nm master.passwd
+.Pa FILE!!
+The first tells FreeBSD to remap all passwords to `*' (which
+will prevent anybody from logging in) and to remap all UIDs and GIDs
+to 0 (which will make everybody appear to be the superuser). The
+second case just maps all UIDs and GIDs to 0, which means that
+.Pa all users will appear to be root!
+.Pp
+.Ss Compatibility of NIS override evaluation
+When Sun originally added NIS support to their
+.Xr getpwent 3
+routines, they took into account the fact that the SunOS password
+.Pa /etc/passwd
+file is in plain ASCII format. The SunOS documentation claims that
+adding a '+' entry to the password file causes the contents of
+the NIS password database to be 'inserted' at the position in
+the file where the '+' entry appears. If, for example, the
+administrator places the +:::::: entry in the middle of
+.Pa /etc/passwd,
+then the entire contents of the NIS password map would appear
+as though it had been copied into the middle of the password
+file. If the administrator places the +:::::: entry at both the
+middle and the end of
+.Pa /etc/passwd ,
+then the NIS password map would appear twice: once in the middle
+of the file and once at the end. (By using override entries
+instead of simple wildcards, other combinations could be achieved.)
+.Pp
+By contrast, FreeBSD does not have a single ASCII password file: it
+has a hashed password database. This database does not have an
+easily-defined beginning, middle or end, which makes it very hard
+to design a scheme that is 100% compatible with SunOS. For example,
+the
+.Fn getpwnam
+and
+.Fn getpwuid
+functions in FreeBSD are designed to do direct queries to the
+hash database rather than a linear search. This approach is faster
+on systems where the password database is large. However, when
+using direct database queries, the system does not know or care
+about the order of the original password file, and therefore
+it cannot easily apply the same override logic used by SunOS.
+.Pp
+Instead, FreeBSD groups all the NIS override entries together
+and constructs a filter out of them. Each NIS password entry
+is compared against the override filter exactly once and 
+treated accordingly: if the filter allows the entry through
+unaltered, it's treated unaltered; if the filter calls for remapping
+of fields, then fields are remapped; if the filter calls for
+explicit exclusion (i.e. the entry matches a '-' override),
+the entry is ignored; if the entry doesn't match against any
+of the filter specifications, it's discarded.
+.Pp
+Again, note that the NIS '+' and '-' entries
+themselves are handled in the order in which they were specified
+in the
+.Pa /etc/master.passwd
+file since doing otherwise would lead to unpredicable behavior.
+.Pp
+The end result is that FreeBSD's provides a very close approximation
+of SunOS's behavior while maintaining the database paradigm, though the
+.Xr getpwent 3
+functions do behave somewhat differently that their SunOS counterparts.
+The primary differences are:
+.Bl -bullet -offset indent
+.It
+Each NIS password map record can be mapped into the password
+local password space only once.
+.It
+The placement of the NIS '+' and '-' entries does not necessarily
+affect where NIS password records will be mapped into
+the password space.
+.El
+.Pp
+In %99 of all FreeBSD configurations, NIS client behavior will be
+indistinguishable from that of SunOS or other similar systems. Even
+so, users should be aware of these architctural differences.
+.Pp
+.Ss Using groups instead of netgroups for NIS overrides
+FreeBSD offers the capability to do override matching based on
+user groups rather than netgroups. If, for example, an NIS entry
+is specified as:
+.Bd -literal -offset indent
++@operator:::::::::
+
+.Ed
+the system will first try to match users against a netgroup called
+`operator.' If an `operator' netgroup doesn't exist, the system
+will try to match users against the normal `operator' group
+instead. 
+.Ss Changes in behavior from older versions of FreeBSD
+There have been several bug fixes and improvements in FreeBSD's
+NIS/YP handling, some of which have caused changes in behavior.
+While the behavior changes are generally positive, it is important
+that users and system administrators be aware of them:
+.Bl -enum -offset indent
+.It
+In versions prior to 2.0.5, reverse lookups (i.e. using
 .Fn getpwuid )
-will use the entire database, even if only a few logins are enabled.
-Thus, the login name returned by
+would not have overrides applied, which is to say that it
+was possible for
 .Fn getpwuid
-is not guaranteed to have a valid forward mapping.
+to return a login name that
+.Fn getpwnam
+would not recognize. This has been fixed: overrides specified
+in
+.Pa /etc/master.passwd
+now apply to all
+.Xr getpwent 3
+functions.
+.It
+Prior to FreeBSD 2.0.5, netgroup overrides did not work at
+all, largely because FreeBSD did not have support for reading
+netgroups through NIS. Again, this has been fixed, and
+netgroups can be specified just as in SunOS and similar NIS-capable
+systems.
+.It
+FreeBSD now has NIS server capabilities and supports the use
+of
+.Pa master.passwd
+NIS maps in addition to the standard Sixth Edition format
+.Pa passwd
+maps.
+This means that you can specify change, expiration and class
+information through NIS, provided you use a FreeBSD system as
+the NIS server.
+.El
 .Sh FILES
 .Bl -tag -width /etc/master.passwd -compact
 .It Pa /etc/passwd
@@ -218,12 +534,23 @@ password database, with passwords intact
 User information should (and eventually will) be stored elsewhere.
 .Pp
 The YP/NIS password database makes encrypted passwords visible to
-ordinary users, thus making password cracking easier.
+ordinary users, thus making password cracking easier unless you use
+shadow passwords with the
+.Pa master.passwd
+maps and FreeBSD's
+.Xr ypserv 8
+server.
 .Pp
-The YP/NIS password database is in old-style (Sixth Edition) format,
-and so cannot specify site-wide values for user login class, password
-expiration date, and other fields present in the current format and
-not in the old.
+Unless you're using FreeBSD's
+.Xr ypserv 8 ,
+which supports the use of
+.Pa master.passwd
+stype maps,
+the YP/NIS password database will be in old-style (Sixth Edition) format,
+which means that site-wide values for user login class, password
+expiration date, and other fields present in the current format
+will not be available when a FreeBSD system is used as a client with
+a standard NIS server.
 .Sh COMPATIBILITY
 The password file format has changed since 4.3BSD.
 The following awk script can be used to convert your old-style password
@@ -252,4 +579,8 @@ and first appeared in
 .Tn FreeBSD
 1.1.  The override capability is new in
 .Tn FreeBSD
-2.0.
+2.0.  The override capability was updated to properly support netgroups
+in
+.Tn FreeBSD
+2.0.5
+