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 $
35 .Dd September 29, 1994
40 .Nd format of the password file
44 files are files consisting of newline separated records, one per user,
47 separated fields. These fields are as
50 .Bl -tag -width password -offset indent
60 User's login group id.
66 Account expiration time.
68 General information about the user.
70 User's home directory.
75 Lines whose first non-whitespace character is a pound-sign (#)
76 are comments, and are ignored. Blank lines which consist
77 only of spaces, tabs or newlines are also ignored.
81 field is the login used to access the computer account, and the
83 field is the number associated with it. They should both be unique
84 across the system (and often across a group of systems) since they
87 While it is possible to have multiple entries with identical login names
88 and/or identical uids, it is usually a mistake to do so. Routines
89 that manipulate these files will often return only one of the multiple
90 entries, and that one by random selection.
92 The login name must never begin with a hyphen
95 suggested that neither upper-case characters nor dots
98 of the name, as this tends to confuse mailers.
100 The password field is the
102 form of the password.
105 field is empty, no password will be required to gain access to the
106 machine. This is almost invariably a mistake.
107 Because these files contain the encrypted user passwords, they should
108 not be readable by anyone without appropriate privileges.
109 Administrative accounts have a password field containing an asterisk
111 which disallows normal logins.
113 The group field is the group that the user will be placed in upon login.
114 Although this system supports multiple groups (see
116 this field indicates the user's primary group.
117 Secondary group memberships are selected in
122 field is a key for a user's login class.
123 Login classes are defined in
127 style database of user attributes, accounting, resource and
128 environment settings.
132 field is the number in seconds,
134 from the epoch, until the
135 password for the account must be changed.
136 This field may be left empty or set to 0 to turn off the
137 password aging feature.
141 field is the number in seconds,
143 from the epoch, until the
145 This field may be left empty or set to 0 to turn off the account
150 field normally contains comma
152 separated subfields as follows:
154 .Bl -bullet -compact -offset indent
158 user's office location
160 user's work phone number
162 user's home phone number
165 This information is used by the
167 program, and the first field used by the system mailer.
170 character appears within the fullname field, programs that
171 use this field will substitute it with a capitalized version
172 of the account's login name.
174 The user's home directory is the full
176 path name where the user
177 will be placed on login.
179 The shell field is the command interpreter the user prefers.
180 If there is nothing in the
182 field, the Bourne shell
185 For security reasons, if the shell is set to a script that disallows
186 access to the system (the
188 script, for example), care should be taken not to import any environment
191 this can be done by specifying the
194 Check the specific shell documentation to determine how this is
195 done with other shells.
196 .Sh YP/NIS INTERACTION
197 .Ss Enabling access to NIS passwd data
198 The system administrator can configure
201 its password information by adding special records to the
202 .Pa /etc/master.passwd
204 These entries should be added with
206 so that the changes can be properly merged with the hashed
207 password databases and the
211 should never be edited manually). Alternatively, the administrator
213 .Pa /etc/master.passwd
214 in some other way and then manually update the password databases with
217 The simplest way to activate NIS is to add an empty record
218 with only a plus sign
220 in the name field, such as this:
221 .Bd -literal -offset indent
231 standard C library to begin using the NIS passwd maps
234 Note that the entry shown above is known as a
236 entry, because it matches all users (the
238 without any other information
239 matches everybody) and allows all NIS password data to be retrieved
242 specifying a username or netgroup next to the
245 entry, the administrator can affect what data are extracted from the
246 NIS passwd maps and how it is interpreted.
247 Here are a few example
248 records that illustrate this feature (note that you can have several
249 NIS entries in a single
252 .Bd -literal -offset indent
255 +@permitted-users:::::::::
257 +ken:::::::::/bin/csh
258 +@rejected-users::32767:32767::::::/bin/false
261 Specific usernames are listed explicitly while netgroups are signified
264 In the above example, users in the
268 netgroups will have their password information
269 read from NIS and used unaltered.
270 In other words, they will be allowed
271 normal access to the machine.
277 been named explicitly rather than through a netgroup, will also have
278 their password data read from NIS,
282 will have his shell remapped to
284 This means that value for his shell specified in the NIS password map
285 will be overridden by the value specified in the special NIS entry in
291 may have been assigned the csh shell because his
292 NIS password entry specified a different shell that may not be
293 installed on the client machine for political or technical reasons.
294 Meanwhile, users in the
296 netgroup are prevented
297 from logging in because their UIDs, GIDs and shells have been overridden
302 will be be ignored entirely because his entry is
307 A minus entry can be used
308 to block out certain NIS password entries completely; users whose
309 password data has been excluded in this way are not recognized by
311 (Any overrides specified with minus entries are
312 also ignored since there is no point in processing override information
313 for a user that the system isn't going to recognize in the first place.)
314 In general, a minus entry is used to specifically exclude a user
315 who might otherwise be granted access because he happens to be a
316 member of an authorized netgroup.
322 netgroup and must, for whatever
323 the reason, be permitted to remain in that netgroup (possibly to
324 retain access to other machines within the domain), the administrator
325 can still deny him access to a particular system with a minus entry.
326 Also, it is sometimes easier to explicitly list those users who are not
327 allowed access rather than generate a possibly complicated list of
328 users who are allowed access and omit the rest.
330 Note that the plus and minus entries are evaluated in order from
331 first to last with the first match taking precedence.
333 the system will only use the first entry that matches a particular user.
334 If, using the same example, there is a user
336 who is a member of both the
340 netgroup, he will be admitted to
341 the system because the above example lists the entry for
345 If the order were reversed,
348 would be flagged as a
350 instead and denied access.
352 Lastly, any NIS password database records that do not match against
353 at least one of the users or netgroups specified by the NIS access
355 .Pa /etc/master.passwd
356 file will be ignored (along with any users specified using minus
357 entries). In our example shown above, we do not have a wildcard
358 entry at the end of the list; therefore, the system will not recognize
366 netgroup as authorized users.
370 be recognized but all members will have their shells remapped and
371 therefore be denied access.
372 All other NIS password records
374 The administrator may add a wildcard entry to the
375 end of the list such as:
376 .Bd -literal -offset indent
377 +:::::::::/sbin/nologin
380 This entry acts as a catch-all for all users that don't match against
381 any of the other entries.
382 This technique is sometimes useful when it is
383 desirable to have the system be able to recognize all users in a
384 particular NIS domain without necessarily granting them login access.
385 See the description of the shell field regarding security concerns when using
386 a shell script as the login shell.
388 The primary use of this
390 feature is to permit the administrator
391 to enforce access restrictions on NIS client systems.
393 granted access to one group of machines and denied access to other
394 machines simply by adding or removing them from a particular netgroup.
395 Since the netgroup database can also be accessed via NIS, this allows
396 access restrictions to be administered from a single location, namely
397 the NIS master server; once a host's access list has been set in
398 .Pa /etc/master.passwd ,
399 it need not be modified again unless new netgroups are created.
401 .Ss Shadow passwords through NIS
403 uses a shadow password scheme: users' encrypted passwords
405 .Pa /etc/master.passwd
408 which are readable and writable only by the superuser.
410 to prevent users from running the encrypted passwords through
411 password-guessing programs and gaining unauthorized access to
412 other users' accounts.
413 NIS does not support a standard means of
414 password shadowing, which implies that placing your password data
415 into the NIS passwd maps totally defeats the security of
417 password shadowing system.
420 provides a few special features to help get around this
422 It is possible to implement password shadowing between
429 routines will search for a
430 .Pa master.passwd.byname
432 .Pa master.passwd.byuid
433 maps which should contain the same data found in the
434 .Pa /etc/master.passwd
438 will attempt to use them for user
439 authentication instead of the standard
446 will also check client requests to make sure they originate on a
448 Since only the superuser is allowed to bind to
449 a privileged port, the server can tell if the requesting user
450 is the superuser; all requests from non-privileged users to access
453 maps will be refused.
454 Since all user authentication programs run
455 with superuser privilege, they should have the required access to
456 users' encrypted password data while normal users will only
457 be allowed access to the standard
459 maps which contain no password information.
461 Note that this feature cannot be used in an environment with
462 .No non- Ns Tn FreeBSD
464 Note also that a truly determined user with
465 unrestricted access to your network could still compromise the
468 .Ss UID and GID remapping with NIS overrides
471 and other operating systems that use Sun's NIS code,
473 allows the user to override
475 of the fields in a user's NIS
478 For example, consider the following
479 .Pa /etc/master.passwd
481 .Bd -literal -offset indent
482 +@foo-users:???:666:666:0:0:0:Bogus user:/home/bogus:/bin/bogus
485 This entry will cause all users in the `foo-users' netgroup to
488 of their password information overridden, including UIDs,
490 The result is that all `foo-users' will be
491 locked out of the system, since their passwords will be remapped
494 This is important to remember because most people are accustomed to
495 using an NIS wildcard entry that looks like this:
496 .Bd -literal -offset indent
500 This often leads to new
502 administrators choosing NIS entries for their
504 files that look like this:
505 .Bd -literal -offset indent
510 .Bd -literal -offset indent
514 .Sy DO _NOT_ PUT ENTRIES LIKE THIS IN YOUR
519 to remap all passwords to
522 will prevent anybody from logging in) and to remap all UIDs and GIDs
523 to 0 (which will make everybody appear to be the superuser). The
524 second case just maps all UIDs and GIDs to 0, which means that
525 all users will appear to be root!
527 .Ss Compatibility of NIS override evaluation
528 When Sun originally added NIS support to their
530 routines, they took into account the fact that the
539 documentation claims that
542 entry to the password file causes the contents of
543 the NIS password database to be
545 at the position in the file where the
549 administrator places a
551 entry in the middle of
553 then the entire contents of the NIS password map would appear
554 as though it had been copied into the middle of the password
556 If the administrator places
558 entries at both the middle and the end of
560 then the NIS password map would appear twice: once in the middle
561 of the file and once at the end.
562 (By using override entries
563 instead of simple wildcards, other combinations could be achieved.)
567 does not have a single
570 has a hashed password database.
571 This database does not have an
572 easily-defined beginning, middle or end, which makes it very hard
573 to design a scheme that is 100% compatible with
582 are designed to do direct queries to the
583 hash database rather than a linear search.
584 This approach is faster
585 on systems where the password database is large.
587 using direct database queries, the system does not know or care
588 about the order of the original password file, and therefore
589 it cannot easily apply the same override logic used by
594 groups all the NIS override entries together
595 and constructs a filter out of them.
596 Each NIS password entry
597 is compared against the override filter exactly once and
598 treated accordingly: if the filter allows the entry through
599 unaltered, it's treated unaltered; if the filter calls for remapping
600 of fields, then fields are remapped; if the filter calls for
601 explicit exclusion (i.e., the entry matches a
603 override), the entry is ignored; if the entry doesn't match against any
604 of the filter specifications, it's discarded.
606 Again, note that the NIS
610 entries themselves are handled in the order in which they were specified
612 .Pa /etc/master.passwd
613 file, since doing otherwise would lead to unpredictable behavior.
615 The end result is that
617 provides a very close approximation
620 behavior while maintaining the database paradigm, though the
622 functions do behave somewhat differently from their
625 The primary differences are:
626 .Bl -bullet -offset indent
628 Each NIS password map record can be mapped into the password
629 local password space only once.
631 The placement of the NIS
635 entries does not necessarily
636 affect where NIS password records will be mapped into
642 configurations, NIS client behavior will be
643 indistinguishable from that of
645 or other similar systems.
647 so, users should be aware of these architectural differences.
649 .Ss Using groups instead of netgroups for NIS overrides
651 offers the capability to do override matching based on
652 user groups rather than netgroups.
653 If, for example, an NIS entry
655 .Bd -literal -offset indent
659 the system will first try to match users against a netgroup called
663 netgroup doesn't exist, the system
664 will try to match users against the normal
667 .Ss Changes in behavior from older versions of FreeBSD
668 There have been several bug fixes and improvements in
670 NIS/YP handling, some of which have caused changes in behavior.
671 While the behavior changes are generally positive, it is important
672 that users and system administrators be aware of them:
673 .Bl -enum -offset indent
675 In versions prior to 2.0.5, reverse lookups (i.e. using
677 would not have overrides applied, which is to say that it
680 to return a login name that
683 This has been fixed: overrides specified
685 .Pa /etc/master.passwd
692 netgroup overrides did not work at
695 did not have support for reading
696 netgroups through NIS.
697 Again, this has been fixed, and
698 netgroups can be specified just as in
700 and similar NIS-capable
704 now has NIS server capabilities and supports the use
707 NIS maps in addition to the standard Sixth Edition format
710 This means that you can specify change, expiration and class
711 information through NIS, provided you use a
717 .Bl -tag -width /etc/master.passwd -compact
720 password file, with passwords removed
723 password database, with passwords removed
724 .It Pa /etc/master.passwd
726 password file, with passwords intact
729 password database, with passwords intact
736 .Xr login_getclass 3 ,
744 User information should (and eventually will) be stored elsewhere.
746 The YP/NIS password database makes encrypted passwords visible to
747 ordinary users, thus making password cracking easier unless you use
748 shadow passwords with the
758 which supports the use of
761 the YP/NIS password database will be in old-style (Sixth Edition) format,
762 which means that site-wide values for user login class, password
763 expiration date, and other fields present in the current format
764 will not be available when a
766 system is used as a client with
767 a standard NIS server.
769 The password file format has changed since
771 The following awk script can be used to convert your old-style password
772 file into a new style password file.
773 The additional fields
778 are added, but are turned off by default.
779 These fields can then be set using
783 .Bd -literal -offset indent
785 { print $1 ":" $2 ":" $3 ":" $4 "::0:0:" $5 ":" $6 ":" $7 }
790 file format appeared in
792 The YP/NIS functionality is modeled after
794 and first appeared in
796 The override capability is new in
798 The override capability was updated to properly support netgroups
801 Support for comments first appeared in