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.2 2003/06/17 04:37:00 dillon Exp $
36 .Dd September 29, 1994
41 .Nd format of the password file
45 files are files consisting of newline separated records, one per user,
48 separated fields. These fields are as
51 .Bl -tag -width password -offset indent
61 User's login group id.
67 Account expiration time.
69 General information about the user.
71 User's home directory.
76 Lines whose first non-whitespace character is a pound-sign (#)
77 are comments, and are ignored. Blank lines which consist
78 only of spaces, tabs or newlines are also ignored.
82 field is the login used to access the computer account, and the
84 field is the number associated with it. They should both be unique
85 across the system (and often across a group of systems) since they
88 While it is possible to have multiple entries with identical login names
89 and/or identical uids, it is usually a mistake to do so. Routines
90 that manipulate these files will often return only one of the multiple
91 entries, and that one by random selection.
93 The login name must never begin with a hyphen
96 suggested that neither upper-case characters nor dots
99 of the name, as this tends to confuse mailers.
101 The password field is the
103 form of the password.
106 field is empty, no password will be required to gain access to the
107 machine. This is almost invariably a mistake.
108 Because these files contain the encrypted user passwords, they should
109 not be readable by anyone without appropriate privileges.
110 Administrative accounts have a password field containing an asterisk
112 which disallows normal logins.
114 The group field is the group that the user will be placed in upon login.
115 Although this system supports multiple groups (see
117 this field indicates the user's primary group.
118 Secondary group memberships are selected in
123 field is a key for a user's login class.
124 Login classes are defined in
128 style database of user attributes, accounting, resource and
129 environment settings.
133 field is the number in seconds,
135 from the epoch, until the
136 password for the account must be changed.
137 This field may be left empty or set to 0 to turn off the
138 password aging feature.
142 field is the number in seconds,
144 from the epoch, until the
146 This field may be left empty or set to 0 to turn off the account
151 field normally contains comma
153 separated subfields as follows:
155 .Bl -bullet -compact -offset indent
159 user's office location
161 user's work phone number
163 user's home phone number
166 This information is used by the
168 program, and the first field used by the system mailer.
171 character appears within the fullname field, programs that
172 use this field will substitute it with a capitalized version
173 of the account's login name.
175 The user's home directory is the full
177 path name where the user
178 will be placed on login.
180 The shell field is the command interpreter the user prefers.
181 If there is nothing in the
183 field, the Bourne shell
186 For security reasons, if the shell is set to a script that disallows
187 access to the system (the
189 script, for example), care should be taken not to import any environment
192 this can be done by specifying the
195 Check the specific shell documentation to determine how this is
196 done with other shells.
197 .Sh YP/NIS INTERACTION
198 .Ss Enabling access to NIS passwd data
199 The system administrator can configure
202 its password information by adding special records to the
203 .Pa /etc/master.passwd
205 These entries should be added with
207 so that the changes can be properly merged with the hashed
208 password databases and the
212 should never be edited manually). Alternatively, the administrator
214 .Pa /etc/master.passwd
215 in some other way and then manually update the password databases with
218 The simplest way to activate NIS is to add an empty record
219 with only a plus sign
221 in the name field, such as this:
222 .Bd -literal -offset indent
232 standard C library to begin using the NIS passwd maps
235 Note that the entry shown above is known as a
237 entry, because it matches all users (the
239 without any other information
240 matches everybody) and allows all NIS password data to be retrieved
243 specifying a username or netgroup next to the
246 entry, the administrator can affect what data are extracted from the
247 NIS passwd maps and how it is interpreted.
248 Here are a few example
249 records that illustrate this feature (note that you can have several
250 NIS entries in a single
253 .Bd -literal -offset indent
256 +@permitted-users:::::::::
258 +ken:::::::::/bin/csh
259 +@rejected-users::32767:32767::::::/bin/false
262 Specific usernames are listed explicitly while netgroups are signified
265 In the above example, users in the
269 netgroups will have their password information
270 read from NIS and used unaltered.
271 In other words, they will be allowed
272 normal access to the machine.
278 been named explicitly rather than through a netgroup, will also have
279 their password data read from NIS,
283 will have his shell remapped to
285 This means that value for his shell specified in the NIS password map
286 will be overridden by the value specified in the special NIS entry in
292 may have been assigned the csh shell because his
293 NIS password entry specified a different shell that may not be
294 installed on the client machine for political or technical reasons.
295 Meanwhile, users in the
297 netgroup are prevented
298 from logging in because their UIDs, GIDs and shells have been overridden
303 will be be ignored entirely because his entry is
308 A minus entry can be used
309 to block out certain NIS password entries completely; users whose
310 password data has been excluded in this way are not recognized by
312 (Any overrides specified with minus entries are
313 also ignored since there is no point in processing override information
314 for a user that the system isn't going to recognize in the first place.)
315 In general, a minus entry is used to specifically exclude a user
316 who might otherwise be granted access because he happens to be a
317 member of an authorized netgroup.
323 netgroup and must, for whatever
324 the reason, be permitted to remain in that netgroup (possibly to
325 retain access to other machines within the domain), the administrator
326 can still deny him access to a particular system with a minus entry.
327 Also, it is sometimes easier to explicitly list those users who are not
328 allowed access rather than generate a possibly complicated list of
329 users who are allowed access and omit the rest.
331 Note that the plus and minus entries are evaluated in order from
332 first to last with the first match taking precedence.
334 the system will only use the first entry that matches a particular user.
335 If, using the same example, there is a user
337 who is a member of both the
341 netgroup, he will be admitted to
342 the system because the above example lists the entry for
346 If the order were reversed,
349 would be flagged as a
351 instead and denied access.
353 Lastly, any NIS password database records that do not match against
354 at least one of the users or netgroups specified by the NIS access
356 .Pa /etc/master.passwd
357 file will be ignored (along with any users specified using minus
358 entries). In our example shown above, we do not have a wildcard
359 entry at the end of the list; therefore, the system will not recognize
367 netgroup as authorized users.
371 be recognized but all members will have their shells remapped and
372 therefore be denied access.
373 All other NIS password records
375 The administrator may add a wildcard entry to the
376 end of the list such as:
377 .Bd -literal -offset indent
378 +:::::::::/sbin/nologin
381 This entry acts as a catch-all for all users that don't match against
382 any of the other entries.
383 This technique is sometimes useful when it is
384 desirable to have the system be able to recognize all users in a
385 particular NIS domain without necessarily granting them login access.
386 See the description of the shell field regarding security concerns when using
387 a shell script as the login shell.
389 The primary use of this
391 feature is to permit the administrator
392 to enforce access restrictions on NIS client systems.
394 granted access to one group of machines and denied access to other
395 machines simply by adding or removing them from a particular netgroup.
396 Since the netgroup database can also be accessed via NIS, this allows
397 access restrictions to be administered from a single location, namely
398 the NIS master server; once a host's access list has been set in
399 .Pa /etc/master.passwd ,
400 it need not be modified again unless new netgroups are created.
402 .Ss Shadow passwords through NIS
404 uses a shadow password scheme: users' encrypted passwords
406 .Pa /etc/master.passwd
409 which are readable and writable only by the superuser.
411 to prevent users from running the encrypted passwords through
412 password-guessing programs and gaining unauthorized access to
413 other users' accounts.
414 NIS does not support a standard means of
415 password shadowing, which implies that placing your password data
416 into the NIS passwd maps totally defeats the security of
418 password shadowing system.
421 provides a few special features to help get around this
423 It is possible to implement password shadowing between
430 routines will search for a
431 .Pa master.passwd.byname
433 .Pa master.passwd.byuid
434 maps which should contain the same data found in the
435 .Pa /etc/master.passwd
439 will attempt to use them for user
440 authentication instead of the standard
447 will also check client requests to make sure they originate on a
449 Since only the superuser is allowed to bind to
450 a privileged port, the server can tell if the requesting user
451 is the superuser; all requests from non-privileged users to access
454 maps will be refused.
455 Since all user authentication programs run
456 with superuser privilege, they should have the required access to
457 users' encrypted password data while normal users will only
458 be allowed access to the standard
460 maps which contain no password information.
462 Note that this feature cannot be used in an environment with
463 .No non- Ns Tn FreeBSD
465 Note also that a truly determined user with
466 unrestricted access to your network could still compromise the
469 .Ss UID and GID remapping with NIS overrides
472 and other operating systems that use Sun's NIS code,
474 allows the user to override
476 of the fields in a user's NIS
479 For example, consider the following
480 .Pa /etc/master.passwd
482 .Bd -literal -offset indent
483 +@foo-users:???:666:666:0:0:0:Bogus user:/home/bogus:/bin/bogus
486 This entry will cause all users in the `foo-users' netgroup to
489 of their password information overridden, including UIDs,
491 The result is that all `foo-users' will be
492 locked out of the system, since their passwords will be remapped
495 This is important to remember because most people are accustomed to
496 using an NIS wildcard entry that looks like this:
497 .Bd -literal -offset indent
501 This often leads to new
503 administrators choosing NIS entries for their
505 files that look like this:
506 .Bd -literal -offset indent
511 .Bd -literal -offset indent
515 .Sy DO _NOT_ PUT ENTRIES LIKE THIS IN YOUR
520 to remap all passwords to
523 will prevent anybody from logging in) and to remap all UIDs and GIDs
524 to 0 (which will make everybody appear to be the superuser). The
525 second case just maps all UIDs and GIDs to 0, which means that
526 all users will appear to be root!
528 .Ss Compatibility of NIS override evaluation
529 When Sun originally added NIS support to their
531 routines, they took into account the fact that the
540 documentation claims that
543 entry to the password file causes the contents of
544 the NIS password database to be
546 at the position in the file where the
550 administrator places a
552 entry in the middle of
554 then the entire contents of the NIS password map would appear
555 as though it had been copied into the middle of the password
557 If the administrator places
559 entries at both the middle and the end of
561 then the NIS password map would appear twice: once in the middle
562 of the file and once at the end.
563 (By using override entries
564 instead of simple wildcards, other combinations could be achieved.)
568 does not have a single
571 has a hashed password database.
572 This database does not have an
573 easily-defined beginning, middle or end, which makes it very hard
574 to design a scheme that is 100% compatible with
583 are designed to do direct queries to the
584 hash database rather than a linear search.
585 This approach is faster
586 on systems where the password database is large.
588 using direct database queries, the system does not know or care
589 about the order of the original password file, and therefore
590 it cannot easily apply the same override logic used by
595 groups all the NIS override entries together
596 and constructs a filter out of them.
597 Each NIS password entry
598 is compared against the override filter exactly once and
599 treated accordingly: if the filter allows the entry through
600 unaltered, it's treated unaltered; if the filter calls for remapping
601 of fields, then fields are remapped; if the filter calls for
602 explicit exclusion (i.e., the entry matches a
604 override), the entry is ignored; if the entry doesn't match against any
605 of the filter specifications, it's discarded.
607 Again, note that the NIS
611 entries themselves are handled in the order in which they were specified
613 .Pa /etc/master.passwd
614 file, since doing otherwise would lead to unpredictable behavior.
616 The end result is that
618 provides a very close approximation
621 behavior while maintaining the database paradigm, though the
623 functions do behave somewhat differently from their
626 The primary differences are:
627 .Bl -bullet -offset indent
629 Each NIS password map record can be mapped into the password
630 local password space only once.
632 The placement of the NIS
636 entries does not necessarily
637 affect where NIS password records will be mapped into
643 configurations, NIS client behavior will be
644 indistinguishable from that of
646 or other similar systems.
648 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 older 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
676 In versions prior to 2.0.5, reverse lookups (i.e. using
678 would not have overrides applied, which is to say that it
681 to return a login name that
684 This has been fixed: overrides specified
686 .Pa /etc/master.passwd
693 netgroup overrides did not work at
696 did not have support for reading
697 netgroups through NIS.
698 Again, this has been fixed, and
699 netgroups can be specified just as in
701 and similar NIS-capable
705 now has NIS server capabilities and supports the use
708 NIS maps in addition to the standard Sixth Edition format
711 This means that you can specify change, expiration and class
712 information through NIS, provided you use a
718 .Bl -tag -width /etc/master.passwd -compact
721 password file, with passwords removed
724 password database, with passwords removed
725 .It Pa /etc/master.passwd
727 password file, with passwords intact
730 password database, with passwords intact
737 .Xr login_getclass 3 ,
745 User information should (and eventually will) be stored elsewhere.
747 The YP/NIS password database makes encrypted passwords visible to
748 ordinary users, thus making password cracking easier unless you use
749 shadow passwords with the
759 which supports the use of
762 the YP/NIS password database will be in old-style (Sixth Edition) format,
763 which means that site-wide values for user login class, password
764 expiration date, and other fields present in the current format
765 will not be available when a
767 system is used as a client with
768 a standard NIS server.
770 The password file format has changed since
772 The following awk script can be used to convert your old-style password
773 file into a new style password file.
774 The additional fields
779 are added, but are turned off by default.
780 These fields can then be set using
784 .Bd -literal -offset indent
786 { print $1 ":" $2 ":" $3 ":" $4 "::0:0:" $5 ":" $6 ":" $7 }
791 file format appeared in
793 The YP/NIS functionality is modeled after
795 and first appeared in
797 The override capability is new in
799 The override capability was updated to properly support netgroups
802 Support for comments first appeared in
projects / dragonfly.git / blob