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.9 2008/05/02 02:05:06 swildner Exp $ 35.\" 36.Dd September 29, 1994 37.Dt PASSWD 5 38.Os 39.Sh NAME 40.Nm passwd , 41.Nm master.passwd 42.Nd format of the password file 43.Sh DESCRIPTION 44The 45.Nm 46files are files consisting of newline separated records, one per user, 47containing ten colon 48.Pq Ql \&: 49separated fields. These fields are as 50follows: 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.Ux 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.Dx 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.Dx Ap 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.Dx 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.Dx Ap s 418password shadowing system. 419.Pp 420.Dx 421provides a few special features to help get around this 422problem. 423It is possible to implement password shadowing between 424.Dx 425NIS clients and 426.Dx 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.Dx 439will attempt to use them for user 440authentication instead of the standard 441.Pa passwd.byname 442and 443.Pa passwd.byuid 444maps. 445The 446.Dx 447.Xr ypserv 8 448will also check client requests to make sure they originate on a 449privileged port. 450Since only the superuser is allowed to bind to 451a privileged port, the server can tell if the requesting user 452is the superuser; all requests from non-privileged users to access 453the 454.Pa master.passwd 455maps will be refused. 456Since all user authentication programs run 457with superuser privilege, they should have the required access to 458users' encrypted password data while normal users will only 459be allowed access to the standard 460.Pa passwd 461maps which contain no password information. 462.Pp 463Note that this feature cannot be used in an environment with 464.No non- Ns Tn Dx 465systems. 466Note also that a truly determined user with 467unrestricted access to your network could still compromise the 468.Pa master.passwd 469maps. 470.Ss UID and GID remapping with NIS overrides 471Unlike 472.Tn SunOS 473and other operating systems that use Sun's NIS code, 474.Dx 475allows the user to override 476.Pa all 477of the fields in a user's NIS 478.Pa passwd 479entry. 480For example, consider the following 481.Pa /etc/master.passwd 482entry: 483.Bd -literal -offset indent 484+@foo-users:???:666:666:0:0:0:Bogus user:/home/bogus:/bin/bogus 485 486.Ed 487This entry will cause all users in the `foo-users' netgroup to 488have 489.Pa all 490of their password information overridden, including UIDs, 491GIDs and passwords. 492The result is that all `foo-users' will be 493locked out of the system, since their passwords will be remapped 494to invalid values. 495.Pp 496This is important to remember because most people are accustomed to 497using an NIS wildcard entry that looks like this: 498.Bd -literal -offset indent 499+:*:0:0::: 500 501.Ed 502This often leads to new 503.Dx 504administrators choosing NIS entries for their 505.Pa master.passwd 506files that look like this: 507.Bd -literal -offset indent 508+:*:0:0:::::: 509 510.Ed 511Or worse, this 512.Bd -literal -offset indent 513+::0:0:::::: 514 515.Ed 516.Sy DO _NOT_ PUT ENTRIES LIKE THIS IN YOUR 517.Pa master.passwd 518.Sy FILE!! 519The first tells 520.Dx 521to remap all passwords to 522.Ql \&* 523(which 524will prevent anybody from logging in) and to remap all UIDs and GIDs 525to 0 (which will make everybody appear to be the superuser). The 526second case just maps all UIDs and GIDs to 0, which means that 527all users will appear to be root! 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.Dx 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.Dx 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.Dx 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.Dx 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.Dx 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.Ss Using groups instead of netgroups for NIS overrides 650.Dx 651offers the capability to do override matching based on 652user groups rather than netgroups. 653If, for example, an NIS entry 654is specified as: 655.Bd -literal -offset indent 656+@operator::::::::: 657 658.Ed 659the system will first try to match users against a netgroup called 660.Ql operator . 661If an 662.Ql operator 663netgroup doesn't exist, the system 664will try to match users against the normal 665.Ql operator 666group instead. 667.Ss Changes in behavior from old versions of FreeBSD 668There have been several bug fixes and improvements in 669.Fx Ap s 670NIS/YP handling, some of which have caused changes in behavior. 671While the behavior changes are generally positive, it is important 672that users and system administrators be aware of them: 673.Bl -enum -offset indent 674.It 675In 676.Fx 677versions 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.Fx 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.Fx 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 COMPATIBILITY 736The password file format has changed since 737.Bx 4.3 . 738The following awk script can be used to convert your old-style password 739file into a new style password file. 740The additional fields 741.Dq class , 742.Dq change 743and 744.Dq expire 745are added, but are turned off by default. 746These fields can then be set using 747.Xr vipw 8 748or 749.Xr pw 8 . 750.Bd -literal -offset indent 751BEGIN { FS = ":"} 752{ print $1 ":" $2 ":" $3 ":" $4 "::0:0:" $5 ":" $6 ":" $7 } 753.Ed 754.Sh SEE ALSO 755.Xr chpass 1 , 756.Xr login 1 , 757.Xr passwd 1 , 758.Xr getpwent 3 , 759.Xr login_getclass 3 , 760.Xr login.conf 5 , 761.Xr adduser 8 , 762.Xr pw 8 , 763.Xr pwd_mkdb 8 , 764.Xr vipw 8 , 765.Xr yp 8 766.Sh HISTORY 767A 768.Nm 769file format appeared in 770.At v6 . 771The YP/NIS functionality is modeled after 772.Tn SunOS 773and first appeared in 774.Fx 1.1 . 775The override capability was new in 776.Fx 2.0 . 777The override capability was updated to properly support netgroups 778in 779.Fx 2.0.5 . 780Support for comments first appeared in 781.Fx 3.0 . 782.Sh BUGS 783User information should (and eventually will) be stored elsewhere. 784.Pp 785The YP/NIS password database makes encrypted passwords visible to 786ordinary users, thus making password cracking easier unless you use 787shadow passwords with the 788.Pa master.passwd 789maps and 790.Dx Ns 's 791.Xr ypserv 8 792server. 793.Pp 794Unless you're using 795.Dx Ns 's 796.Xr ypserv 8 , 797which supports the use of 798.Pa master.passwd 799type maps, 800the YP/NIS password database will be in old-style (Sixth Edition) format, 801which means that site-wide values for user login class, password 802expiration date, and other fields present in the current format 803will not be available when a 804.Dx 805system is used as a client with 806a standard NIS server. 807