.\" Copyright (c) 1988, 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.
.\"
.\"     From: @(#)passwd.5	8.1 (Berkeley) 6/5/93
.\" $FreeBSD$
.\"
.Dd September 29, 1994
.Dt PASSWD 5
.Os
.Sh NAME
.Nm passwd
.Nd format of the password file
.Sh DESCRIPTION
The
.Nm passwd
files are files consisting of newline separated records, one per user,
containing ten colon (``:'') separated fields.  These fields are as
follows:
.Pp
.Bl -tag -width password -offset indent
.It name
User's login name.
.It password
User's
.Em encrypted
password.
.It uid
User's id.
.It gid
User's login group id.
.It class
User's login class.
.It change
Password change time.
.It expire
Account expiration time.
.It gecos
General information about the user.
.It home_dir
User's home directory.
.It shell
User's login shell.
.El
.Pp
Lines whose first non-whitespace character is a pound-sign (#)
are comments, and are ignored.  Blank lines which consist
only of spaces, tabs or newlines are also ignored.
.Pp
The
.Ar name
field is the login used to access the computer account, and the
.Ar uid
field is the number associated with it.  They should both be unique
across the system (and often across a group of systems) since they
control file access.
.Pp
While it is possible to have multiple entries with identical login names
and/or identical user id's, it is usually a mistake to do so.  Routines
that manipulate these files will often return only one of the multiple
entries, and that one by random selection.
.Pp
The login name must never begin with a hyphen (``-''); also, it is strongly
suggested that neither upper-case characters nor dots (``.'') be part
of the name, as this tends to confuse mailers.  No field may contain a
colon (``:'') as this has been used historically to separate the fields
in the user database.
.Pp
The password field is the
.Em encrypted
form of the password.
If the
.Ar password
field is empty, no password will be required to gain access to the
machine.  This is almost invariably a mistake.
Because these files contain the encrypted user passwords, they should
not be readable by anyone without appropriate privileges.
Administrative accounts have a password field containing an asterisk
.Ql \&*
which disallows normal logins.
.Pp
The group field is the group that the user will be placed in upon login.
Although this system supports multiple groups (see
.Xr groups 1 )
this field indicates the user's primary group.
Secondary group memberships are selected in
.Pa /etc/group .
.Pp
The
.Ar class
field is a key for a user's login class.
Login classes are defined in
.Xr login.conf 5 ,
which is a
.Xr termcap 5
style database of user attributes, accounting, resource and
environment settings.
.Pp
The
.Ar change
field is the number in seconds,
.Dv GMT ,
from the epoch, until the
password for the account must be changed.
This field may be left empty or set to 0 to turn off the
password aging feature.
.Pp
The
.Ar expire
field is the number in seconds,
.Dv GMT ,
from the epoch, until the
account expires.
This field may be left empty or set to 0 to turn off the account
aging feature.
.Pp
The
.Ar gecos
field normally contains comma (``,'') separated subfields as follows:
.Pp
.Bd -unfilled -offset indent
fullname		user's full name
office		user's office location
wphone		user's work phone number
hphone		user's home phone number
.Ed
.Pp
This information is used by the
.Xr finger 1
program, and the first field used by the system mailer.
If an ampersand
.Ql \&&
character appears within the fullname field, programs that
use this field will substitute it with a capitalized version
of the account's login name.
.Pp
The user's home directory is the full
.Tn UNIX
path name where the user
will be placed on login.
.Pp
The shell field is the command interpreter the user prefers.
If there is nothing in the
.Ar shell
field, the Bourne shell
.Pq Pa /bin/sh
is assumed.
For security reasons, if the shell is set to a script that disallows 
access to the system (the
.Xr nologin 8
script, for example), care should be taken not to import any environment 
variables.  With
.Xr sh 1 ,
this can be done by specifying the
.Fl p
flag.
Check the specific shell documentation to determine how this is 
done with other shells.
.Sh YP/NIS INTERACTION
.Ss Enabling access to NIS passwd data
The system administrator can configure
.Tn 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 (
.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
.Tn FreeBSD Ns 's
standard C library to begin using the NIS passwd maps
for lookups.
.Pp
Note that the entry shown above is known as a
.Em 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 are 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 signified
by a preceding `@'. 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 words, they will be allowed
normal access to the machine.
Users ``ken'' and ``dennis,'' who have
been 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 overridden 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 whose
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 administrator
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
the system will only use the first entry that 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 useful when it is
desirable to have the system be able to recognize all users in a
particular NIS domain without necessarily granting them login access.
See the above text on the shell field regarding security concerns when using
a shell script as the login shell.
.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
.Tn 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
.Tn FreeBSD Ns 's
password shadowing system.
.Pp
.Tn FreeBSD
provides a few special features to help get around this
problem.
It is possible to implement password shadowing between
.Tn FreeBSD
NIS clients and
.Tn 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,
.Tn FreeBSD
will attempt to use them for user
authentication instead of the standard
.Pa passwd.byname
and
.Pa passwd.byuid
maps.
.Tn FreeBSD Ns '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
.No non- Ns Tn 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
.Tn SunOS
and other operating systems that use Sun's NIS code,
.Tn 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:
.Bd -literal -offset indent
+@foo-users:???:666:666:0:0:0:Bogus user:/home/bogus:/bin/bogus

.Ed
This entry will cause all users in the `foo-users' netgroup to
have
.Pa all
of their password information overridden, 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
.Tn FreeBSD
administrators 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
.Sy DO _NOT_ PUT ENTRIES LIKE THIS IN YOUR
.Sy Pa master.passwd
.Sy FILE!!
The first tells
.Tn 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
.Tn SunOS
password
.Pa /etc/passwd
file is in plain
.Tn ASCII
format.
The
.Tn 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,
.Tn FreeBSD
does not have a single
.Tn 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
.Tn SunOS .
For example,
the
.Fn getpwnam
and
.Fn getpwuid
functions in
.Tn 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
.Tn SunOS .
.Pp
Instead,
.Tn 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 unpredictable behavior.
.Pp
The end result is that
.Tn FreeBSD Ns 's
provides a very close approximation
of
.Tn SunOS Ns 's
behavior while maintaining the database paradigm, though the
.Xr getpwent 3
functions do behave somewhat differently from their
.Tn 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
.Tn FreeBSD
configurations, NIS client behavior will be
indistinguishable from that of
.Tn SunOS
or other similar systems.
Even
so, users should be aware of these architectural differences.
.Pp
.Ss Using groups instead of netgroups for NIS overrides
.Tn 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
.Tn FreeBSD Ns '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 )
would not have overrides applied, which is to say that it
was possible for
.Fn getpwuid
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
.Fx 2.0.5 ,
netgroup overrides did not work at
all, largely because
.Tn FreeBSD
did not have support for reading
netgroups through NIS.
Again, this has been fixed, and
netgroups can be specified just as in
.Tn SunOS
and similar NIS-capable
systems.
.It
.Tn 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
.Tn FreeBSD
system as
the NIS server.
.El
.Sh FILES
.Bl -tag -width /etc/master.passwd -compact
.It Pa /etc/passwd
.Tn ASCII
password file, with passwords removed
.It Pa /etc/pwd.db
.Xr db 3 -format
password database, with passwords removed
.It Pa /etc/master.passwd
.Tn ASCII
password file, with passwords intact
.It Pa /etc/spwd.db
.Xr db 3 -format
password database, with passwords intact
.El
.Sh SEE ALSO
.Xr chpass 1 ,
.Xr login 1 ,
.Xr passwd 1 ,
.Xr getpwent 3 ,
.Xr login_getclass 3 ,
.Xr yp 4 ,
.Xr login.conf 5 ,
.Xr adduser 8 ,
.Xr pw 8 ,
.Xr pwd_mkdb 8 ,
.Xr vipw 8
.Sh BUGS
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 unless you use
shadow passwords with the
.Pa master.passwd
maps and
.Tn FreeBSD Ns 's
.Xr ypserv 8
server.
.Pp
Unless you're using
.Tn FreeBSD Ns 's
.Xr ypserv 8 ,
which supports the use of
.Pa master.passwd
type 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
.Tn FreeBSD
system is used as a client with
a standard NIS server.
.Sh COMPATIBILITY
The password file format has changed since
.Bx 4.3 .
The following awk script can be used to convert your old-style password
file into a new style password file.
The additional fields
.Dq class ,
.Dq change
and
.Dq expire
are added, but are turned off by default.
These fields can then be set using
.Xr vipw 8
or
.Xr pw 8 .
.Bd -literal -offset indent
BEGIN { FS = ":"}
{ print $1 ":" $2 ":" $3 ":" $4 "::0:0:" $5 ":" $6 ":" $7 }
.Ed
.Sh HISTORY
A
.Nm
file format appeared in
.At v6 .
The YP/NIS functionality is modeled after
.Tn SunOS
and first appeared in
.Fx 1.1
The override capability is new in
.Fx 2.0 .
The override capability was updated to properly support netgroups
in
.Fx 2.0.5 .
Support for comments first appeared in
.Fx 3.0 .