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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
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	9.2		      September	29, 1994		   FreeBSD 9.2


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

home | help