1.\" Copyright (c) 1988, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 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. 19.\" 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 30.\" SUCH DAMAGE. 31.\" 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.3 2004/03/11 12:28:56 hmp Exp $ 35.\" 36.Dd September 29, 1994 37.Dt PASSWD 5 38.Os 39.Sh NAME 40.Nm passwd 41.Nd format of the password file 42.Sh DESCRIPTION 43The 44.Nm 45files are files consisting of newline separated records, one per user, 46containing ten colon 47.Pq Ql \&: 48separated fields. These fields are as 49follows: 50.Pp 51.Bl -tag -width password -offset indent 52.It name 53User's login name. 54.It password 55User's 56.Em encrypted 57password. 58.It uid 59User's id. 60.It gid 61User's login group id. 62.It class 63User's login class. 64.It change 65Password change time. 66.It expire 67Account expiration time. 68.It gecos 69General information about the user. 70.It home_dir 71User's home directory. 72.It shell 73User's login shell. 74.El 75.Pp 76Lines whose first non-whitespace character is a pound-sign (#) 77are comments, and are ignored. Blank lines which consist 78only of spaces, tabs or newlines are also ignored. 79.Pp 80The 81.Ar name 82field is the login used to access the computer account, and the 83.Ar uid 84field is the number associated with it. They should both be unique 85across the system (and often across a group of systems) since they 86control file access. 87.Pp 88While it is possible to have multiple entries with identical login names 89and/or identical uids, it is usually a mistake to do so. Routines 90that manipulate these files will often return only one of the multiple 91entries, and that one by random selection. 92.Pp 93The login name must never begin with a hyphen 94.Pq Ql \&- ; 95also, it is strongly 96suggested that neither upper-case characters nor dots 97.Pq Ql \&. 98be part 99of the name, as this tends to confuse mailers. 100.Pp 101The password field is the 102.Em encrypted 103form of the password. 104If the 105.Ar password 106field is empty, no password will be required to gain access to the 107machine. This is almost invariably a mistake. 108Because these files contain the encrypted user passwords, they should 109not be readable by anyone without appropriate privileges. 110Administrative accounts have a password field containing an asterisk 111.Ql \&* 112which disallows normal logins. 113.Pp 114The group field is the group that the user will be placed in upon login. 115Although this system supports multiple groups (see 116.Xr groups 1 ) 117this field indicates the user's primary group. 118Secondary group memberships are selected in 119.Pa /etc/group . 120.Pp 121The 122.Ar class 123field is a key for a user's login class. 124Login classes are defined in 125.Xr login.conf 5 , 126which is a 127.Xr termcap 5 128style database of user attributes, accounting, resource and 129environment settings. 130.Pp 131The 132.Ar change 133field is the number in seconds, 134.Dv GMT , 135from the epoch, until the 136password for the account must be changed. 137This field may be left empty or set to 0 to turn off the 138password aging feature. 139.Pp 140The 141.Ar expire 142field is the number in seconds, 143.Dv GMT , 144from the epoch, until the 145account expires. 146This field may be left empty or set to 0 to turn off the account 147aging feature. 148.Pp 149The 150.Ar gecos 151field normally contains comma 152.Pq Ql \&, 153separated subfields as follows: 154.Pp 155.Bl -bullet -compact -offset indent 156.It 157user's full name 158.It 159user's office location 160.It 161user's work phone number 162.It 163user's home phone number 164.El 165.Pp 166This information is used by the 167.Xr finger 1 168program, and the first field used by the system mailer. 169If an ampersand 170.Pq Ql \&& 171character appears within the fullname field, programs that 172use this field will substitute it with a capitalized version 173of the account's login name. 174.Pp 175The user's home directory is the full 176.Tn UNIX 177path name where the user 178will be placed on login. 179.Pp 180The shell field is the command interpreter the user prefers. 181If there is nothing in the 182.Ar shell 183field, the Bourne shell 184.Pq Pa /bin/sh 185is assumed. 186For security reasons, if the shell is set to a script that disallows 187access to the system (the 188.Xr nologin 8 189script, for example), care should be taken not to import any environment 190variables. With 191.Xr sh 1 , 192this can be done by specifying the 193.Fl p 194flag. 195Check the specific shell documentation to determine how this is 196done with other shells. 197.Sh YP/NIS INTERACTION 198.Ss Enabling access to NIS passwd data 199The system administrator can configure 200.Tn FreeBSD 201to use NIS/YP for 202its password information by adding special records to the 203.Pa /etc/master.passwd 204file. 205These entries should be added with 206.Xr vipw 8 207so that the changes can be properly merged with the hashed 208password databases and the 209.Pa /etc/passwd 210file ( 211.Pa /etc/passwd 212should never be edited manually). Alternatively, the administrator 213can modify 214.Pa /etc/master.passwd 215in some other way and then manually update the password databases with 216.Xr pwd_mkdb 8 . 217.Pp 218The simplest way to activate NIS is to add an empty record 219with only a plus sign 220.Pq Ql \&+ 221in the name field, such as this: 222.Bd -literal -offset indent 223+::::::::: 224 225.Ed 226The 227.Ql \&+ 228will tell the 229.Xr getpwent 3 230routines in 231.Tn FreeBSD Ns 's 232standard C library to begin using the NIS passwd maps 233for lookups. 234.Pp 235Note that the entry shown above is known as a 236.Em wildcard 237entry, because it matches all users (the 238.Ql \&+ 239without any other information 240matches everybody) and allows all NIS password data to be retrieved 241unaltered. 242However, by 243specifying a username or netgroup next to the 244.Ql \&+ 245in the NIS 246entry, the administrator can affect what data are extracted from the 247NIS passwd maps and how it is interpreted. 248Here are a few example 249records that illustrate this feature (note that you can have several 250NIS entries in a single 251.Pa master.passwd 252file): 253.Bd -literal -offset indent 254-mitnick::::::::: 255+@staff::::::::: 256+@permitted-users::::::::: 257+dennis::::::::: 258+ken:::::::::/bin/csh 259+@rejected-users::32767:32767::::::/bin/false 260 261.Ed 262Specific usernames are listed explicitly while netgroups are signified 263by a preceding 264.Ql \&@ . 265In the above example, users in the 266.Dq staff 267and 268.Dq permitted-users 269netgroups will have their password information 270read from NIS and used unaltered. 271In other words, they will be allowed 272normal access to the machine. 273Users 274.Dq ken 275and 276.Dq dennis , 277who have 278been named explicitly rather than through a netgroup, will also have 279their password data read from NIS, 280.Em except 281that user 282.Dq ken 283will have his shell remapped to 284.Pa /bin/csh . 285This means that value for his shell specified in the NIS password map 286will be overridden by the value specified in the special NIS entry in 287the local 288.Pa master.passwd 289file. 290User 291.Dq ken 292may have been assigned the csh shell because his 293NIS password entry specified a different shell that may not be 294installed on the client machine for political or technical reasons. 295Meanwhile, users in the 296.Dq rejected-users 297netgroup are prevented 298from logging in because their UIDs, GIDs and shells have been overridden 299with invalid values. 300.Pp 301User 302.Dq mitnick 303will be be ignored entirely because his entry is 304specified with a 305.Ql \&- 306instead of a 307.Ql \&+ . 308A minus entry can be used 309to block out certain NIS password entries completely; users whose 310password data has been excluded in this way are not recognized by 311the system at all. 312(Any overrides specified with minus entries are 313also ignored since there is no point in processing override information 314for a user that the system isn't going to recognize in the first place.) 315In general, a minus entry is used to specifically exclude a user 316who might otherwise be granted access because he happens to be a 317member of an authorized netgroup. 318For example, if 319.Dq mitnick 320is 321a member of the 322.Dq permitted-users 323netgroup and must, for whatever 324the reason, be permitted to remain in that netgroup (possibly to 325retain access to other machines within the domain), the administrator 326can still deny him access to a particular system with a minus entry. 327Also, it is sometimes easier to explicitly list those users who are not 328allowed access rather than generate a possibly complicated list of 329users who are allowed access and omit the rest. 330.Pp 331Note that the plus and minus entries are evaluated in order from 332first to last with the first match taking precedence. 333This means 334the system will only use the first entry that matches a particular user. 335If, using the same example, there is a user 336.Dq foo 337who is a member of both the 338.Dq staff 339netgroup and the 340.Dq rejected-users 341netgroup, he will be admitted to 342the system because the above example lists the entry for 343.Dq staff 344before the entry for 345.Dq rejected-users . 346If the order were reversed, 347user 348.Dq foo 349would be flagged as a 350.Dq rejected-user 351instead and denied access. 352.Pp 353Lastly, any NIS password database records that do not match against 354at least one of the users or netgroups specified by the NIS access 355entries in the 356.Pa /etc/master.passwd 357file will be ignored (along with any users specified using minus 358entries). In our example shown above, we do not have a wildcard 359entry at the end of the list; therefore, the system will not recognize 360anyone except 361.Dq ken , 362.Dq dennis , 363the 364.Dq staff 365netgroup, and the 366.Dq permitted-users 367netgroup as authorized users. 368The 369.Dq rejected-users 370netgroup will 371be recognized but all members will have their shells remapped and 372therefore be denied access. 373All other NIS password records 374will be ignored. 375The administrator may add a wildcard entry to the 376end of the list such as: 377.Bd -literal -offset indent 378+:::::::::/sbin/nologin 379 380.Ed 381This entry acts as a catch-all for all users that don't match against 382any of the other entries. 383This technique is sometimes useful when it is 384desirable to have the system be able to recognize all users in a 385particular NIS domain without necessarily granting them login access. 386See the description of the shell field regarding security concerns when using 387a shell script as the login shell. 388.Pp 389The primary use of this 390.Pa override 391feature is to permit the administrator 392to enforce access restrictions on NIS client systems. 393Users can be 394granted access to one group of machines and denied access to other 395machines simply by adding or removing them from a particular netgroup. 396Since the netgroup database can also be accessed via NIS, this allows 397access restrictions to be administered from a single location, namely 398the NIS master server; once a host's access list has been set in 399.Pa /etc/master.passwd , 400it need not be modified again unless new netgroups are created. 401.Sh NOTES 402.Ss Shadow passwords through NIS 403.Tn FreeBSD 404uses a shadow password scheme: users' encrypted passwords 405are stored only in 406.Pa /etc/master.passwd 407and 408.Pa /etc/spwd.db , 409which are readable and writable only by the superuser. 410This is done 411to prevent users from running the encrypted passwords through 412password-guessing programs and gaining unauthorized access to 413other users' accounts. 414NIS does not support a standard means of 415password shadowing, which implies that placing your password data 416into the NIS passwd maps totally defeats the security of 417.Tn FreeBSD Ns 's 418password shadowing system. 419.Pp 420.Tn FreeBSD 421provides a few special features to help get around this 422problem. 423It is possible to implement password shadowing between 424.Tn FreeBSD 425NIS clients and 426.Tn FreeBSD 427NIS servers. 428The 429.Xr getpwent 3 430routines will search for a 431.Pa master.passwd.byname 432and 433.Pa master.passwd.byuid 434maps which should contain the same data found in the 435.Pa /etc/master.passwd 436file. 437If the maps exist, 438.Tn FreeBSD 439will attempt to use them for user 440authentication instead of the standard 441.Pa passwd.byname 442and 443.Pa passwd.byuid 444maps. 445.Tn FreeBSD Ns 's 446.Xr ypserv 8 447will also check client requests to make sure they originate on a 448privileged port. 449Since only the superuser is allowed to bind to 450a privileged port, the server can tell if the requesting user 451is the superuser; all requests from non-privileged users to access 452the 453.Pa master.passwd 454maps will be refused. 455Since all user authentication programs run 456with superuser privilege, they should have the required access to 457users' encrypted password data while normal users will only 458be allowed access to the standard 459.Pa passwd 460maps which contain no password information. 461.Pp 462Note that this feature cannot be used in an environment with 463.No non- Ns Tn FreeBSD 464systems. 465Note also that a truly determined user with 466unrestricted access to your network could still compromise the 467.Pa master.passwd 468maps. 469.Ss UID and GID remapping with NIS overrides 470Unlike 471.Tn SunOS 472and other operating systems that use Sun's NIS code, 473.Tn FreeBSD 474allows the user to override 475.Pa all 476of the fields in a user's NIS 477.Pa passwd 478entry. 479For example, consider the following 480.Pa /etc/master.passwd 481entry: 482.Bd -literal -offset indent 483+@foo-users:???:666:666:0:0:0:Bogus user:/home/bogus:/bin/bogus 484 485.Ed 486This entry will cause all users in the `foo-users' netgroup to 487have 488.Pa all 489of their password information overridden, including UIDs, 490GIDs and passwords. 491The result is that all `foo-users' will be 492locked out of the system, since their passwords will be remapped 493to invalid values. 494.Pp 495This is important to remember because most people are accustomed to 496using an NIS wildcard entry that looks like this: 497.Bd -literal -offset indent 498+:*:0:0::: 499 500.Ed 501This often leads to new 502.Tn FreeBSD 503administrators choosing NIS entries for their 504.Pa master.passwd 505files that look like this: 506.Bd -literal -offset indent 507+:*:0:0:::::: 508 509.Ed 510Or worse, this 511.Bd -literal -offset indent 512+::0:0:::::: 513 514.Ed 515.Sy DO _NOT_ PUT ENTRIES LIKE THIS IN YOUR 516.Pa master.passwd 517.Sy FILE!! 518The first tells 519.Tn FreeBSD 520to remap all passwords to 521.Ql \&* 522(which 523will prevent anybody from logging in) and to remap all UIDs and GIDs 524to 0 (which will make everybody appear to be the superuser). The 525second case just maps all UIDs and GIDs to 0, which means that 526all users will appear to be root! 527.Pp 528.Ss Compatibility of NIS override evaluation 529When Sun originally added NIS support to their 530.Xr getpwent 3 531routines, they took into account the fact that the 532.Tn SunOS 533password 534.Pa /etc/passwd 535file is in plain 536.Tn ASCII 537format. 538The 539.Tn SunOS 540documentation claims that 541adding a 542.Ql \&+ 543entry to the password file causes the contents of 544the NIS password database to be 545.Dq inserted 546at the position in the file where the 547.Ql \&+ 548entry appears. 549If, for example, the 550administrator places a 551.Ql \&+:::::: 552entry in the middle of 553.Pa /etc/passwd , 554then the entire contents of the NIS password map would appear 555as though it had been copied into the middle of the password 556file. 557If the administrator places 558.Ql \&+:::::: 559entries at both the middle and the end of 560.Pa /etc/passwd , 561then the NIS password map would appear twice: once in the middle 562of the file and once at the end. 563(By using override entries 564instead of simple wildcards, other combinations could be achieved.) 565.Pp 566By contrast, 567.Fx 568does not have a single 569.Tn ASCII 570password file: it 571has a hashed password database. 572This database does not have an 573easily-defined beginning, middle or end, which makes it very hard 574to design a scheme that is 100% compatible with 575.Tn SunOS . 576For example, 577the 578.Fn getpwnam 579and 580.Fn getpwuid 581functions in 582.Tn FreeBSD 583are designed to do direct queries to the 584hash database rather than a linear search. 585This approach is faster 586on systems where the password database is large. 587However, when 588using direct database queries, the system does not know or care 589about the order of the original password file, and therefore 590it cannot easily apply the same override logic used by 591.Tn SunOS . 592.Pp 593Instead, 594.Tn FreeBSD 595groups all the NIS override entries together 596and constructs a filter out of them. 597Each NIS password entry 598is compared against the override filter exactly once and 599treated accordingly: if the filter allows the entry through 600unaltered, it's treated unaltered; if the filter calls for remapping 601of fields, then fields are remapped; if the filter calls for 602explicit exclusion (i.e., the entry matches a 603.Ql \&- 604override), the entry is ignored; if the entry doesn't match against any 605of the filter specifications, it's discarded. 606.Pp 607Again, note that the NIS 608.Ql \&+ 609and 610.Ql \&- 611entries themselves are handled in the order in which they were specified 612in the 613.Pa /etc/master.passwd 614file, since doing otherwise would lead to unpredictable behavior. 615.Pp 616The end result is that 617.Tn FreeBSD Ns 's 618provides a very close approximation 619of 620.Tn SunOS Ns 's 621behavior while maintaining the database paradigm, though the 622.Xr getpwent 3 623functions do behave somewhat differently from their 624.Tn SunOS 625counterparts. 626The primary differences are: 627.Bl -bullet -offset indent 628.It 629Each NIS password map record can be mapped into the password 630local password space only once. 631.It 632The placement of the NIS 633.Ql \&+ 634and 635.Ql \&- 636entries does not necessarily 637affect where NIS password records will be mapped into 638the password space. 639.El 640.Pp 641In 99% of all 642.Tn FreeBSD 643configurations, NIS client behavior will be 644indistinguishable from that of 645.Tn SunOS 646or other similar systems. 647Even 648so, users should be aware of these architectural differences. 649.Pp 650.Ss Using groups instead of netgroups for NIS overrides 651.Tn FreeBSD 652offers the capability to do override matching based on 653user groups rather than netgroups. 654If, for example, an NIS entry 655is specified as: 656.Bd -literal -offset indent 657+@operator::::::::: 658 659.Ed 660the system will first try to match users against a netgroup called 661.Ql operator . 662If an 663.Ql operator 664netgroup doesn't exist, the system 665will try to match users against the normal 666.Ql operator 667group instead. 668.Ss Changes in behavior from older versions of 669.Dx 670There have been several bug fixes and improvements in 671.Dx Ns 's 672NIS/YP handling, some of which have caused changes in behavior. 673While the behavior changes are generally positive, it is important 674that users and system administrators be aware of them: 675.Bl -enum -offset indent 676.It 677In versions prior to 2.0.5, reverse lookups (i.e. using 678.Fn getpwuid ) 679would not have overrides applied, which is to say that it 680was possible for 681.Fn getpwuid 682to return a login name that 683.Fn getpwnam 684would not recognize. 685This has been fixed: overrides specified 686in 687.Pa /etc/master.passwd 688now apply to all 689.Xr getpwent 3 690functions. 691.It 692Prior to 693.Fx 2.0.5 , 694netgroup overrides did not work at 695all, largely because 696.Tn FreeBSD 697did not have support for reading 698netgroups through NIS. 699Again, this has been fixed, and 700netgroups can be specified just as in 701.Tn SunOS 702and similar NIS-capable 703systems. 704.It 705.Dx 706now has NIS server capabilities and supports the use 707of 708.Pa master.passwd 709NIS maps in addition to the standard Sixth Edition format 710.Pa passwd 711maps. 712This means that you can specify change, expiration and class 713information through NIS, provided you use a 714.Dx 715or 716.Fx 717system as 718the NIS server. 719.El 720.Sh FILES 721.Bl -tag -width /etc/master.passwd -compact 722.It Pa /etc/passwd 723.Tn ASCII 724password file, with passwords removed 725.It Pa /etc/pwd.db 726.Xr db 3 -format 727password database, with passwords removed 728.It Pa /etc/master.passwd 729.Tn ASCII 730password file, with passwords intact 731.It Pa /etc/spwd.db 732.Xr db 3 -format 733password database, with passwords intact 734.El 735.Sh SEE ALSO 736.Xr chpass 1 , 737.Xr login 1 , 738.Xr passwd 1 , 739.Xr getpwent 3 , 740.Xr login_getclass 3 , 741.Xr login.conf 5 , 742.Xr adduser 8 , 743.Xr pw 8 , 744.Xr pwd_mkdb 8 , 745.Xr vipw 8 , 746.Xr yp 8 747.Sh BUGS 748User information should (and eventually will) be stored elsewhere. 749.Pp 750The YP/NIS password database makes encrypted passwords visible to 751ordinary users, thus making password cracking easier unless you use 752shadow passwords with the 753.Pa master.passwd 754maps and 755.Dx Ns 's 756.Xr ypserv 8 757server. 758.Pp 759Unless you're using 760.Dx Ns 's 761.Xr ypserv 8 , 762which supports the use of 763.Pa master.passwd 764type maps, 765the YP/NIS password database will be in old-style (Sixth Edition) format, 766which means that site-wide values for user login class, password 767expiration date, and other fields present in the current format 768will not be available when a 769.Dx 770system is used as a client with 771a standard NIS server. 772.Sh COMPATIBILITY 773The password file format has changed since 774.Bx 4.3 . 775The following awk script can be used to convert your old-style password 776file into a new style password file. 777The additional fields 778.Dq class , 779.Dq change 780and 781.Dq expire 782are added, but are turned off by default. 783These fields can then be set using 784.Xr vipw 8 785or 786.Xr pw 8 . 787.Bd -literal -offset indent 788BEGIN { FS = ":"} 789{ print $1 ":" $2 ":" $3 ":" $4 "::0:0:" $5 ":" $6 ":" $7 } 790.Ed 791.Sh HISTORY 792A 793.Nm 794file format appeared in 795.At v6 . 796The YP/NIS functionality is modeled after 797.Tn SunOS 798and first appeared in 799.Fx 1.1 800The override capability is new in 801.Fx 2.0 . 802The override capability was updated to properly support netgroups 803in 804.Fx 2.0.5 . 805Support for comments first appeared in 806.Fx 3.0 . 807