PASSWD(5)

NAME
passwd - format of the password file

DESCRIPTION
The passwd files are files consisting of newline separated records, one per user, containing ten colon (``:'') separated fields. These fields are as follows:

name
    User's login name.

password
    User's encrypted password.

uid User's id.

gid User's login group id.

class
    User's general classification (unused).

change
    Password change time.

expire
    Account expiration time.

gecos
    General information about the user.

home_dir
    User's home directory.

shell
    User's login shell.

The name field is the login used to access the computer account, and the 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.

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.

The login name must never begin with a hyphen (``-''); also, it is strongly suggested that neither upper-case characters or 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.

The password field is the encrypted form of the password. If the 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.

The group field is the group that the user will be placed in upon login. Since this system supports multiple groups (see groups(1)) this field currently has little special meaning.

The class field is currently unused. In the near future it will be a key to a termcap(5) style database of user attributes.

The change field is the number in seconds, GMT, from the epoch, until the password for the account must be changed. This field may be left empty to turn off the password aging feature.

The expire field is the number in seconds, GMT, from the epoch, until the account expires. This field may be left empty to turn off the account aging feature.

The gecos field normally contains comma (``,'') separated subfields as follows:

    name		user's full name
    office		user's office number
    wphone		user's work phone number
    hphone		user's home phone number

This information is used by the finger(1) program.

The user's home directory is the full UNIX path name where the user will be placed on login.

The shell field is the command interpreter the user prefers. If there is nothing in the shell field, the Bourne shell (/bin/sh) is assumed.

YP/NIS INTERACTION

  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 /etc/master.passwd file. These entries should be added with vipw(8) so that the changes can be properly merged with the hashed password databases and the /etc/passwd file ( /etc/passwd should never be edited manually). Alternatively, the administrator can modify /etc/master.passwd in some other way and then manually update the password databases with pwd_mkdb(8).

The simplest way to activate NIS is to add an empty record with only a plus sign (`+') in the name field, such as this:

    +:::::::::

The `+' will tell the getpwent(3) routines in FreeBSD's standard C library to begin using the NIS passwd maps for lookups.

Note that the entry shown above is known as a 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 master.passwd file):

    -mitnick:::::::::
    +@staff:::::::::
    +@permitted-users:::::::::
    +dennis:::::::::
    +ken:::::::::/bin/csh
    +@rejected-users::32767:32767::::::/bin/false

Specific usernames are listed explicitly while netgroups are signfied 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 /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 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.

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 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.

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.

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 /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:

    +:::::::::/usr/local/bin/go_away

This entry acts as a catch-all for all users that don't match against any of the other entries. /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.

The primary use of this 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 /etc/master.passwd, it need not be modified again unless new netgroups are created.

NOTES

  Shadow passwords through NIS
FreeBSD uses a shadow password scheme: users' encrypted passwords are stored only in /etc/master.passwd and /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.

FreeBSD provides a few special features to help get around this problem. It is possible to implement password shadowing between FreeBSD NIS clients and FreeBSD NIS servers. The getpwent(3) routines will search for a master.passwd.byname and master.passwd.byuid maps which should contain the same data found in the /etc/master.passwd file. If the maps exist, FreeBSD will attempt to use them for user authentication instead of the standard passwd.byname and passwd.byuid maps. FreeBSD's 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 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 passwd maps which contain no password information.

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 master.passwd maps.

  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 all of the fields in a user's NIS passwd entry. For example, consider the following /etc/master.passwd entry:

    +@foo-users:???:666:666:0:0:0:Bogus user:/home/bogus:/bin/bogus

This entry will cause all users in the `foo-users' netgroup to have 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.

This is important to remember because most people are accustomed to using an NIS wildcard entry that looks like this:

    +:*:0:0:::

This often leads to new FreeBSD administrators choosing NIS entries for their master.passwd files that look like this:

    +:*:0:0::::::

Or worse, this

    +::0:0::::::

DO _NOT_ PUT ENTRIES LIKE THIS IN YOUR master.passwd 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 all users will appear to be root!

  Compatibility of NIS override evaluation
When Sun originally added NIS support to their getpwent(3) routines, they took into account the fact that the SunOS password /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 /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 /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.)

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 getpwnam() and 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.

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.

Again, note that the NIS '+' and '-' entries themselves are handled in the order in which they were specified in the /etc/master.passwd file since doing otherwise would lead to unpredicable behavior.

The end result is that FreeBSD's provides a very close approximation of SunOS's behavior while maintaining the database paradigm, though the getpwent(3) functions do behave somewhat differently that their SunOS counterparts. The primary differences are:

•   Each NIS password map record can be mapped into the password local password space only once.

•   The placement of the NIS '+' and '-' entries does not necessarily affect where NIS password records will be mapped into the password space.

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 architectural differences.

  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:

    +@operator:::::::::

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.

  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:

1.  In versions prior to 2.0.5, reverse lookups (i.e. using getpwuid()) would not have overrides applied, which is to say that it was possible for getpwuid() to return a login name that getpwnam() would not recognize. This has been fixed: overrides specified in /etc/master.passwd now apply to all getpwent(3) functions.

2.  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.

3.  FreeBSD now has NIS server capabilities and supports the use of master.passwd NIS maps in addition to the standard Sixth Edition format 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.

FILES
/etc/passwd
    ASCII password file, with passwords removed
/etc/pwd.db
    db(3) -format password database, with passwords removed
/etc/master.passwd
    ASCII password file, with passwords intact
/etc/spwd.db
    db(3) -format password database, with passwords intact

SEE ALSO
adduser(8), chpass(1), getpwent(3), login(1), passwd(1), pwd_mkdb(8), vipw(8), yp(4)

BUGS
User information should (and eventually will) be stored elsewhere.

The YP/NIS password database makes encrypted passwords visible to ordinary users, thus making password cracking easier unless you use shadow passwords with the master.passwd maps and FreeBSD's ypserv(8) server.

Unless you're using FreeBSD's ypserv(8), which supports the use of 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 FreeBSD system is used as a client with a standard NIS server.

COMPATIBILITY
The password file format has changed since 4.3BSD. The following awk script can be used to convert your old-style password file into a new style password file. The additional fields “class”, “change” and “expire” are added, but are turned off by default. Class is currently not implemented, but change and expire are; to set them, use the current day in seconds from the epoch + whatever number of seconds of offset you want.

    BEGIN { FS = ":"}
    { print $1 ":" $2 ":" $3 ":" $4 "::0:0:" $5 ":" $6 ":" $7 }

HISTORY
A passwd file format appeared in AT&T UNIX. The YP/NIS functionality is modeled after SunOS and first appeared in FreeBSD 1.1. The override capability is new in FreeBSD 2.0. The override capability was updated to properly support netgroups in FreeBSD 2.0.5