1 .\" Copyright (c) 1988, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\" must display the following acknowledgement:
14 .\" This product includes software developed by the University of
15 .\" California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" From: @(#)passwd.5 8.1 (Berkeley) 6/5/93
33 .\" $FreeBSD: src/share/man/man5/passwd.5,v 1.26.2.5 2002/02/01 15:51:18 ru Exp $
34 .\" $DragonFly: src/share/man/man5/passwd.5,v 1.8 2007/07/30 22:11:33 swildner Exp $
36 .Dd September 29, 1994
42 .Nd format of the password file
46 files are files consisting of newline separated records, one per user,
49 separated fields. These fields are as
52 .Bl -tag -width password -offset indent
62 User's login group id.
68 Account expiration time.
70 General information about the user.
72 User's home directory.
77 Lines whose first non-whitespace character is a pound-sign (#)
78 are comments, and are ignored. Blank lines which consist
79 only of spaces, tabs or newlines are also ignored.
83 field is the login used to access the computer account, and the
85 field is the number associated with it. They should both be unique
86 across the system (and often across a group of systems) since they
89 While it is possible to have multiple entries with identical login names
90 and/or identical uids, it is usually a mistake to do so. Routines
91 that manipulate these files will often return only one of the multiple
92 entries, and that one by random selection.
94 The login name must never begin with a hyphen
97 suggested that neither upper-case characters nor dots
100 of the name, as this tends to confuse mailers.
102 The password field is the
104 form of the password.
107 field is empty, no password will be required to gain access to the
108 machine. This is almost invariably a mistake.
109 Because these files contain the encrypted user passwords, they should
110 not be readable by anyone without appropriate privileges.
111 Administrative accounts have a password field containing an asterisk
113 which disallows normal logins.
115 The group field is the group that the user will be placed in upon login.
116 Although this system supports multiple groups (see
118 this field indicates the user's primary group.
119 Secondary group memberships are selected in
124 field is a key for a user's login class.
125 Login classes are defined in
129 style database of user attributes, accounting, resource and
130 environment settings.
134 field is the number in seconds,
136 from the epoch, until the
137 password for the account must be changed.
138 This field may be left empty or set to 0 to turn off the
139 password aging feature.
143 field is the number in seconds,
145 from the epoch, until the
147 This field may be left empty or set to 0 to turn off the account
152 field normally contains comma
154 separated subfields as follows:
156 .Bl -bullet -compact -offset indent
160 user's office location
162 user's work phone number
164 user's home phone number
167 This information is used by the
169 program, and the first field used by the system mailer.
172 character appears within the fullname field, programs that
173 use this field will substitute it with a capitalized version
174 of the account's login name.
176 The user's home directory is the full
178 path name where the user
179 will be placed on login.
181 The shell field is the command interpreter the user prefers.
182 If there is nothing in the
184 field, the Bourne shell
187 For security reasons, if the shell is set to a script that disallows
188 access to the system (the
190 script, for example), care should be taken not to import any environment
193 this can be done by specifying the
196 Check the specific shell documentation to determine how this is
197 done with other shells.
198 .Sh YP/NIS INTERACTION
199 .Ss Enabling access to NIS passwd data
200 The system administrator can configure
203 its password information by adding special records to the
204 .Pa /etc/master.passwd
206 These entries should be added with
208 so that the changes can be properly merged with the hashed
209 password databases and the
213 should never be edited manually). Alternatively, the administrator
215 .Pa /etc/master.passwd
216 in some other way and then manually update the password databases with
219 The simplest way to activate NIS is to add an empty record
220 with only a plus sign
222 in the name field, such as this:
223 .Bd -literal -offset indent
233 standard C library to begin using the NIS passwd maps
236 Note that the entry shown above is known as a
238 entry, because it matches all users (the
240 without any other information
241 matches everybody) and allows all NIS password data to be retrieved
244 specifying a username or netgroup next to the
247 entry, the administrator can affect what data are extracted from the
248 NIS passwd maps and how it is interpreted.
249 Here are a few example
250 records that illustrate this feature (note that you can have several
251 NIS entries in a single
254 .Bd -literal -offset indent
257 +@permitted-users:::::::::
259 +ken:::::::::/bin/csh
260 +@rejected-users::32767:32767::::::/bin/false
263 Specific usernames are listed explicitly while netgroups are signified
266 In the above example, users in the
270 netgroups will have their password information
271 read from NIS and used unaltered.
272 In other words, they will be allowed
273 normal access to the machine.
279 been named explicitly rather than through a netgroup, will also have
280 their password data read from NIS,
284 will have his shell remapped to
286 This means that value for his shell specified in the NIS password map
287 will be overridden by the value specified in the special NIS entry in
293 may have been assigned the csh shell because his
294 NIS password entry specified a different shell that may not be
295 installed on the client machine for political or technical reasons.
296 Meanwhile, users in the
298 netgroup are prevented
299 from logging in because their UIDs, GIDs and shells have been overridden
304 will be be ignored entirely because his entry is
309 A minus entry can be used
310 to block out certain NIS password entries completely; users whose
311 password data has been excluded in this way are not recognized by
313 (Any overrides specified with minus entries are
314 also ignored since there is no point in processing override information
315 for a user that the system isn't going to recognize in the first place.)
316 In general, a minus entry is used to specifically exclude a user
317 who might otherwise be granted access because he happens to be a
318 member of an authorized netgroup.
324 netgroup and must, for whatever
325 the reason, be permitted to remain in that netgroup (possibly to
326 retain access to other machines within the domain), the administrator
327 can still deny him access to a particular system with a minus entry.
328 Also, it is sometimes easier to explicitly list those users who are not
329 allowed access rather than generate a possibly complicated list of
330 users who are allowed access and omit the rest.
332 Note that the plus and minus entries are evaluated in order from
333 first to last with the first match taking precedence.
335 the system will only use the first entry that matches a particular user.
336 If, using the same example, there is a user
338 who is a member of both the
342 netgroup, he will be admitted to
343 the system because the above example lists the entry for
347 If the order were reversed,
350 would be flagged as a
352 instead and denied access.
354 Lastly, any NIS password database records that do not match against
355 at least one of the users or netgroups specified by the NIS access
357 .Pa /etc/master.passwd
358 file will be ignored (along with any users specified using minus
359 entries). In our example shown above, we do not have a wildcard
360 entry at the end of the list; therefore, the system will not recognize
368 netgroup as authorized users.
372 be recognized but all members will have their shells remapped and
373 therefore be denied access.
374 All other NIS password records
376 The administrator may add a wildcard entry to the
377 end of the list such as:
378 .Bd -literal -offset indent
379 +:::::::::/sbin/nologin
382 This entry acts as a catch-all for all users that don't match against
383 any of the other entries.
384 This technique is sometimes useful when it is
385 desirable to have the system be able to recognize all users in a
386 particular NIS domain without necessarily granting them login access.
387 See the description of the shell field regarding security concerns when using
388 a shell script as the login shell.
390 The primary use of this
392 feature is to permit the administrator
393 to enforce access restrictions on NIS client systems.
395 granted access to one group of machines and denied access to other
396 machines simply by adding or removing them from a particular netgroup.
397 Since the netgroup database can also be accessed via NIS, this allows
398 access restrictions to be administered from a single location, namely
399 the NIS master server; once a host's access list has been set in
400 .Pa /etc/master.passwd ,
401 it need not be modified again unless new netgroups are created.
403 .Ss Shadow passwords through NIS
405 uses a shadow password scheme: users' encrypted passwords
407 .Pa /etc/master.passwd
410 which are readable and writable only by the superuser.
412 to prevent users from running the encrypted passwords through
413 password-guessing programs and gaining unauthorized access to
414 other users' accounts.
415 NIS does not support a standard means of
416 password shadowing, which implies that placing your password data
417 into the NIS passwd maps totally defeats the security of
419 password shadowing system.
422 provides a few special features to help get around this
424 It is possible to implement password shadowing between
431 routines will search for a
432 .Pa master.passwd.byname
434 .Pa master.passwd.byuid
435 maps which should contain the same data found in the
436 .Pa /etc/master.passwd
440 will attempt to use them for user
441 authentication instead of the standard
449 will also check client requests to make sure they originate on a
451 Since only the superuser is allowed to bind to
452 a privileged port, the server can tell if the requesting user
453 is the superuser; all requests from non-privileged users to access
456 maps will be refused.
457 Since all user authentication programs run
458 with superuser privilege, they should have the required access to
459 users' encrypted password data while normal users will only
460 be allowed access to the standard
462 maps which contain no password information.
464 Note that this feature cannot be used in an environment with
467 Note also that a truly determined user with
468 unrestricted access to your network could still compromise the
471 .Ss UID and GID remapping with NIS overrides
474 and other operating systems that use Sun's NIS code,
476 allows the user to override
478 of the fields in a user's NIS
481 For example, consider the following
482 .Pa /etc/master.passwd
484 .Bd -literal -offset indent
485 +@foo-users:???:666:666:0:0:0:Bogus user:/home/bogus:/bin/bogus
488 This entry will cause all users in the `foo-users' netgroup to
491 of their password information overridden, including UIDs,
493 The result is that all `foo-users' will be
494 locked out of the system, since their passwords will be remapped
497 This is important to remember because most people are accustomed to
498 using an NIS wildcard entry that looks like this:
499 .Bd -literal -offset indent
503 This often leads to new
505 administrators choosing NIS entries for their
507 files that look like this:
508 .Bd -literal -offset indent
513 .Bd -literal -offset indent
517 .Sy DO _NOT_ PUT ENTRIES LIKE THIS IN YOUR
522 to remap all passwords to
525 will prevent anybody from logging in) and to remap all UIDs and GIDs
526 to 0 (which will make everybody appear to be the superuser). The
527 second case just maps all UIDs and GIDs to 0, which means that
528 all users will appear to be root!
529 .Ss Compatibility of NIS override evaluation
530 When Sun originally added NIS support to their
532 routines, they took into account the fact that the
541 documentation claims that
544 entry to the password file causes the contents of
545 the NIS password database to be
547 at the position in the file where the
551 administrator places a
553 entry in the middle of
555 then the entire contents of the NIS password map would appear
556 as though it had been copied into the middle of the password
558 If the administrator places
560 entries at both the middle and the end of
562 then the NIS password map would appear twice: once in the middle
563 of the file and once at the end.
564 (By using override entries
565 instead of simple wildcards, other combinations could be achieved.)
569 does not have a single
572 has a hashed password database.
573 This database does not have an
574 easily-defined beginning, middle or end, which makes it very hard
575 to design a scheme that is 100% compatible with
584 are designed to do direct queries to the
585 hash database rather than a linear search.
586 This approach is faster
587 on systems where the password database is large.
589 using direct database queries, the system does not know or care
590 about the order of the original password file, and therefore
591 it cannot easily apply the same override logic used by
596 groups all the NIS override entries together
597 and constructs a filter out of them.
598 Each NIS password entry
599 is compared against the override filter exactly once and
600 treated accordingly: if the filter allows the entry through
601 unaltered, it's treated unaltered; if the filter calls for remapping
602 of fields, then fields are remapped; if the filter calls for
603 explicit exclusion (i.e., the entry matches a
605 override), the entry is ignored; if the entry doesn't match against any
606 of the filter specifications, it's discarded.
608 Again, note that the NIS
612 entries themselves are handled in the order in which they were specified
614 .Pa /etc/master.passwd
615 file, since doing otherwise would lead to unpredictable behavior.
617 The end result is that
619 provides a very close approximation
622 behavior while maintaining the database paradigm, though the
624 functions do behave somewhat differently from their
627 The primary differences are:
628 .Bl -bullet -offset indent
630 Each NIS password map record can be mapped into the password
631 local password space only once.
633 The placement of the NIS
637 entries does not necessarily
638 affect where NIS password records will be mapped into
644 configurations, NIS client behavior will be
645 indistinguishable from that of
647 or other similar systems.
649 so, users should be aware of these architectural differences.
650 .Ss Using groups instead of netgroups for NIS overrides
652 offers the capability to do override matching based on
653 user groups rather than netgroups.
654 If, for example, an NIS entry
656 .Bd -literal -offset indent
660 the system will first try to match users against a netgroup called
664 netgroup doesn't exist, the system
665 will try to match users against the normal
668 .Ss Changes in behavior from old versions of FreeBSD
669 There have been several bug fixes and improvements in
671 NIS/YP handling, some of which have caused changes in behavior.
672 While the behavior changes are generally positive, it is important
673 that users and system administrators be aware of them:
674 .Bl -enum -offset indent
678 versions prior to 2.0.5, reverse lookups (i.e. using
680 would not have overrides applied, which is to say that it
683 to return a login name that
686 This has been fixed: overrides specified
688 .Pa /etc/master.passwd
695 netgroup overrides did not work at
698 did not have support for reading
699 netgroups through NIS.
700 Again, this has been fixed, and
701 netgroups can be specified just as in
703 and similar NIS-capable
707 now has NIS server capabilities and supports the use
710 NIS maps in addition to the standard Sixth Edition format
713 This means that you can specify change, expiration and class
714 information through NIS, provided you use a
722 .Bl -tag -width /etc/master.passwd -compact
725 password file, with passwords removed
728 password database, with passwords removed
729 .It Pa /etc/master.passwd
731 password file, with passwords intact
734 password database, with passwords intact
737 The password file format has changed since
739 The following awk script can be used to convert your old-style password
740 file into a new style password file.
741 The additional fields
746 are added, but are turned off by default.
747 These fields can then be set using
751 .Bd -literal -offset indent
753 { print $1 ":" $2 ":" $3 ":" $4 "::0:0:" $5 ":" $6 ":" $7 }
760 .Xr login_getclass 3 ,
770 file format appeared in
772 The YP/NIS functionality is modeled after
774 and first appeared in
776 The override capability was new in
778 The override capability was updated to properly support netgroups
781 Support for comments first appeared in
784 User information should (and eventually will) be stored elsewhere.
786 The YP/NIS password database makes encrypted passwords visible to
787 ordinary users, thus making password cracking easier unless you use
788 shadow passwords with the
798 which supports the use of
801 the YP/NIS password database will be in old-style (Sixth Edition) format,
802 which means that site-wide values for user login class, password
803 expiration date, and other fields present in the current format
804 will not be available when a
806 system is used as a client with
807 a standard NIS server.