Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PASSWD(5)                 FreeBSD File Formats Manual                PASSWD(5)

     passwd -- format of the password file

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

           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.

     Lines whose first non-whitespace character is a pound-sign (#) are com-
     ments, and are ignored.  Blank lines which consist only of spaces, tabs
     or newlines are also ignored.

     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 con-
     trol file access.

     While it is possible to have multiple entries with identical login names
     and/or identical uids, 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 nor dots (`.') be part of
     the name, as this tends to confuse mailers.

     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 any-
     one without appropriate privileges.  Administrative accounts have a pass-
     word field containing an asterisk `*' which disallows normal logins.

     The group field is the group that the user will be placed in upon login.
     Although this system supports multiple groups (see groups(1)) this field
     indicates the user's primary group.  Secondary group memberships are
     selected in /etc/group.

     The class field is a key for a user's login class.  Login classes are
     defined in login.conf(5), which is a termcap(5) style database of user
     attributes, accounting, resource and environment settings.

     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
     or set to 0 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 or set to 0 to turn off
     the account aging feature.

     The gecos field normally contains comma (`,') separated subfields as fol-

           +o   user's full name
           +o   user's office location
           +o   user's work phone number
           +o   user's home phone number

     This information is used by the finger(1) program, and the first field
     used by the system mailer.  If an ampersand (`&') character appears
     within the fullname field, programs that use this field will substitute
     it with a capitalized version of the account's login name.

     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.  For
     security reasons, if the shell is set to a script that disallows access
     to the system (the nologin(8) script, for example), care should be taken
     not to import any environment variables.  With sh(1), this can be done by
     specifying the -p flag.  Check the specific shell documentation to deter-
     mine how this is done with other shells.

   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 every-
     body) and allows all NIS password data to be retrieved unaltered.  How-
     ever, 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 master.passwd file):


     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 /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 differ-
     ent shell that may not be installed on the client machine for political
     or technical reasons.  Meanwhile, users in the ``rejected-users'' net-
     group 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 speci-
     fied 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 exam-
     ple, 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 are not 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 the system will
     only use the first entry that matches a particular user.  If, using the
     same example, there is a user ``foo'' who is a member of both the
     ``staff'' netgroup and the ``rejected-users'' netgroup, he will be admit-
     ted to the system because the above example lists the entry for ``staff''
     before the entry for ``rejected-users''.  If the order were reversed,
     user ``foo'' would be flagged as a ``rejected-user'' instead and denied

     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:


     This entry acts as a catch-all for all users that don't match against any
     of the other entries.  This technique is sometimes useful when it is
     desirable to have the system be able to recognize all users in a particu-
     lar NIS domain without necessarily granting them login access.  See the
     description of the shell field regarding security concerns when using a
     shell script as the login shell.

     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.

   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 sup-
     port 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 con-
     tain 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 privi-
     leged 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 pass-
     word 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 pass-
     words.  The result is that all `foo-users' will be locked out of the sys-
     tem, 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:


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


     Or worse, this


     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 data-
     base to be ``inserted'' at the position in the file where the `+' entry
     appears.  If, for example, the administrator places a `+::::::' 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 `+::::::' entries 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

     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 con-
     structs 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 `-' over-
     ride), 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 unpredictable 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 from their SunOS
     counterparts.  The primary differences are:

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

           +o   The placement of the NIS `+' and `-' entries does not necessar-
               ily affect where NIS password records will be mapped into the
               password space.

     In 99% of all FreeBSD configurations, NIS client behavior will be indis-
     tinguishable 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


     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 net-
                groups can be specified just as in SunOS and similar NIS-capa-
                ble 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.

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

     chpass(1), login(1), passwd(1), getpwent(3), login_getclass(3),
     login.conf(5), adduser(8), pw(8), pwd_mkdb(8), vipw(8), yp(8)

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

     The YP/NIS password database makes encrypted passwords visible to ordi-
     nary 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.

     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.  These fields can
     then be set using vipw(8) or pw(8).

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

     A passwd file format appeared in Version 6 AT&T UNIX.  The YP/NIS func-
     tionality 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.  Support for com-
     ments first appeared in FreeBSD 3.0.

FreeBSD 4.10                  September 29, 1994                  FreeBSD 4.10


Want to link to this manual page? Use this URL:

home | help