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

     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

	   fullname	  user's full name
	   office	  user's office	location
	   wphone	  user's work phone number
	   hphone	  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 ``per-
     mitted-users'' netgroups will have	their password information read	from
     NIS and used unaltered. In	other words, they will be allowed normal ac-
     cess 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 po-
     litical 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 speci-
     fied 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 (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
     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 the system	will
     only use the first	entry that matches a particular	user.  If, for in-
     stance, we	have a user ``foo'' who	is a member of both the	``staff'' net-
     group 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:


     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 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 above
     text on 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 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	re-
     fused. Since all user authentication programs run with superuser privi-
     lege, 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 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 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 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 '-'	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 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	`oper-
     ator'. 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.conf(5),
     login_getclass(3),	yp(4), login.conf(5), adduser(8), pwd_mkdb(8), pw(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