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