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

FreeBSD Manual Pages


home | help
PASSWD(5)		    BSD	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 en-
     tries, 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 se-
     lected in /etc/group.

     The class field is	a key for a user's login class.	 Login classes are de-
     fined in login.conf(5), which is a	termcap(5) style database of user at-
     tributes, 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	li-
     brary 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 en-
     try, 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 ex-
     plicitly 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 techni-
     cal reasons.  Meanwhile, users in the "rejected-users" netgroup are pre-
     vented 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 cer-
     tain NIS password entries completely; users whose password	data has been
     excluded in this way are not recognized by	the system at all.  (Any over-
     rides 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 (possi-
     bly to retain access to other machines within the domain),	the adminis-
     trator can	still deny him access to a particular system with a minus en-
     try.  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 admitted 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	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:


     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 de-
     sirable to	have the system	be able	to recognize all users in a particular
     NIS domain	without	necessarily granting them login	access.	 See the de-
     scription 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	ma-
     chines simply by adding or	removing them from a particular	netgroup.
     Since the netgroup	database can also be accessed via NIS, this allows ac-
     cess 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 ex-
     ist, 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 en-
     try.  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 ev-
     erybody 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 `+' en-
     try 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 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 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 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 be-
     havior 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 re-
     /etc/master.passwd	 ASCII password	file, with passwords intact
     /etc/spwd.db	 db(3) -format password	database, with passwords in-

     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.

BSD			      September	29, 1994			   BSD


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

home | help