1.\" $NetBSD: passwd.5,v 1.12.2.2 1999/12/17 23:14:50 he Exp $ 2.\" 3.\" Copyright (c) 1988, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" Portions Copyright (c) 1994, Jason Downs. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" From: @(#)passwd.5 8.1 (Berkeley) 6/5/93 32.\" $FreeBSD: src/share/man/man5/passwd.5,v 1.50 2007/05/08 11:00:07 yar Exp $ 33.\" $DragonFly: src/share/man/man5/passwd.5,v 1.9 2008/05/02 02:05:06 swildner Exp $ 34.\" 35.Dd May 8, 2007 36.Dt PASSWD 5 37.Os 38.Sh NAME 39.Nm passwd , 40.Nm master.passwd 41.Nd format of the password file 42.Sh DESCRIPTION 43The 44.Nm 45files are the local source of password information. 46They can be used in conjunction with the Hesiod domains 47.Sq Li passwd 48and 49.Sq Li uid , 50and the 51.Tn NIS 52maps 53.Sq Li passwd.byname , 54.Sq Li passwd.byuid , 55.Sq Li master.passwd.byname , 56and 57.Sq Li master.passwd.byuid , 58as controlled by 59.Xr nsswitch.conf 5 . 60.Pp 61For consistency, none of these files should ever be modified 62manually. 63.Pp 64The 65.Nm master.passwd 66file is readable only by root, and consists of newline separated 67records, one per user, containing ten colon 68.Pq Ql \&: 69separated 70fields. 71These fields are as follows: 72.Bl -tag -width ".Ar password" -offset indent 73.It Ar name 74User's login name. 75.It Ar password 76User's 77.Em encrypted 78password. 79.It Ar uid 80User's id. 81.It Ar gid 82User's login group id. 83.It Ar class 84User's login class. 85.It Ar change 86Password change time. 87.It Ar expire 88Account expiration time. 89.It Ar gecos 90General information about the user. 91.It Ar home_dir 92User's home directory. 93.It Ar shell 94User's login shell. 95.El 96.Pp 97The 98.Nm 99file is generated from the 100.Nm master.passwd 101file by 102.Xr pwd_mkdb 8 , 103has the 104.Ar class , 105.Ar change , 106and 107.Ar expire 108fields removed, and the 109.Ar password 110field replaced by a 111.Ql * 112character. 113.Pp 114The 115.Ar name 116field is the login used to access the computer account, and the 117.Ar uid 118field is the number associated with it. 119They should both be unique 120across the system (and often across a group of systems) since they 121control file access. 122.Pp 123While it is possible to have multiple entries with identical login names 124and/or identical user id's, it is usually a mistake to do so. 125Routines 126that manipulate these files will often return only one of the multiple 127entries, and that one by random selection. 128.Pp 129The login name must never begin with a hyphen 130.Pq Ql - ; 131also, it is strongly 132suggested that neither upper-case characters or dots 133.Pq Ql \&. 134be part 135of the name, as this tends to confuse mailers. 136No field may contain a 137colon 138.Pq Ql \&: 139as this has been used historically to separate the fields 140in the user database. 141.Pp 142In the 143.Nm master.passwd 144file, 145the 146.Ar password 147field is the 148.Em encrypted 149form of the password, see 150.Xr crypt 3 . 151If the 152.Ar password 153field is empty, no password will be required to gain access to the 154machine. 155This is almost invariably a mistake, so authentication components 156such as PAM can forcibly disallow remote access to passwordless accounts. 157Because this file contains the encrypted user passwords, it should 158not be readable by anyone without appropriate privileges. 159.Pp 160A password of 161.Ql * 162indicates that 163password authentication is disabled for that account 164(logins through other forms of 165authentication, e.g., using 166.Xr ssh 1 167keys, will still work). 168The field only contains encrypted passwords, and 169.Ql * 170can never be the result of encrypting a password. 171.Pp 172An encrypted password prefixed by 173.Ql *LOCKED* 174means that the account is temporarily locked out 175and no one can log into it using any authentication. 176For a convenient command-line interface to account locking, see 177.Xr pw 8 . 178.Pp 179The 180.Ar group 181field is the group that the user will be placed in upon login. 182Since this system supports multiple groups (see 183.Xr groups 1 ) 184this field currently has little special meaning. 185.Pp 186The 187.Ar class 188field is a key for a user's login class. 189Login classes 190are defined in 191.Xr login.conf 5 , 192which is a 193.Xr termcap 5 194style database of user attributes, accounting, resource, 195and environment settings. 196.Pp 197The 198.Ar change 199field is the number of seconds from the epoch, 200.Dv UTC , 201until the 202password for the account must be changed. 203This field may be left empty to turn off the password aging feature. 204.Pp 205The 206.Ar expire 207field is the number of seconds from the epoch, 208.Dv UTC , 209until the 210account expires. 211This field may be left empty to turn off the account aging feature. 212.Pp 213The 214.Ar gecos 215field normally contains comma 216.Pq Ql \&, 217separated subfields as follows: 218.Pp 219.Bl -tag -width ".Ar office" -offset indent -compact 220.It Ar name 221user's full name 222.It Ar office 223user's office number 224.It Ar wphone 225user's work phone number 226.It Ar hphone 227user's home phone number 228.El 229.Pp 230The full 231.Ar name 232may contain an ampersand 233.Pq Ql & 234which will be replaced by 235the capitalized login 236.Ar name 237when the 238.Ar gecos 239field is displayed or used 240by various programs such as 241.Xr finger 1 , 242.Xr sendmail 8 , 243etc. 244.Pp 245The 246.Ar office 247and phone number subfields are used by the 248.Xr finger 1 249program, and possibly other applications. 250.Pp 251The user's home directory, 252.Ar home_dir , 253is the full 254.Ux 255path name where the user 256will be placed on login. 257.Pp 258The 259.Ar shell 260field is the command interpreter the user prefers. 261If there is nothing in the 262.Ar shell 263field, the Bourne shell 264.Pq Pa /bin/sh 265is assumed. 266The conventional way to disable logging into an account once and for all, 267as it is done for system accounts, 268is to set its 269.Ar shell 270to 271.Xr nologin 8 . 272.Sh HESIOD SUPPORT 273If 274.Sq Li dns 275is specified for the 276.Sq Li passwd 277database in 278.Xr nsswitch.conf 5 , 279then 280.Nm 281lookups occur from the 282.Sq Li passwd 283Hesiod domain. 284.Sh NIS SUPPORT 285If 286.Sq Li nis 287is specified for the 288.Sq Li passwd 289database in 290.Xr nsswitch.conf 5 , 291then 292.Nm 293lookups occur from the 294.Sq Li passwd.byname , 295.Sq Li passwd.byuid , 296.Sq Li master.passwd.byname , 297and 298.Sq Li master.passwd.byuid 299.Tn NIS 300maps. 301.Sh COMPAT SUPPORT 302If 303.Sq Li compat 304is specified for the 305.Sq Li passwd 306database, and either 307.Sq Li dns 308or 309.Sq Li nis 310is specified for the 311.Sq Li passwd_compat 312database in 313.Xr nsswitch.conf 5 , 314then the 315.Nm 316file also supports standard 317.Sq Li + Ns / Ns Li - 318exclusions and inclusions, based on user names and netgroups. 319.Pp 320Lines beginning with a 321.Ql - 322(minus sign) are entries marked as being excluded 323from any following inclusions, which are marked with a 324.Ql + 325(plus sign). 326.Pp 327If the second character of the line is a 328.Ql @ 329(at sign), the operation 330involves the user fields of all entries in the netgroup specified by the 331remaining characters of the 332.Ar name 333field. 334Otherwise, the remainder of the 335.Ar name 336field is assumed to be a specific user name. 337.Pp 338The 339.Ql + 340token may also be alone in the 341.Ar name 342field, which causes all users from either the Hesiod domain 343.Nm 344(with 345.Sq Li passwd_compat: dns ) 346or 347.Sq Li passwd.byname 348and 349.Sq Li passwd.byuid 350.Tn NIS 351maps (with 352.Sq Li passwd_compat: nis ) 353to be included. 354.Pp 355If the entry contains non-empty 356.Ar uid 357or 358.Ar gid 359fields, the specified numbers will override the information retrieved 360from the Hesiod domain or the 361.Tn NIS 362maps. 363As well, if the 364.Ar gecos , 365.Ar dir 366or 367.Ar shell 368entries contain text, it will override the information included via 369Hesiod or 370.Tn NIS . 371On some systems, the 372.Ar passwd 373field may also be overridden. 374.Sh FILES 375.Bl -tag -width ".Pa /etc/master.passwd" -compact 376.It Pa /etc/passwd 377.Tn ASCII 378password file, with passwords removed 379.It Pa /etc/pwd.db 380.Xr db 3 Ns -format 381password database, with passwords removed 382.It Pa /etc/master.passwd 383.Tn ASCII 384password file, with passwords intact 385.It Pa /etc/spwd.db 386.Xr db 3 Ns -format 387password database, with passwords intact 388.El 389.Sh COMPATIBILITY 390The password file format has changed since 391.Bx 4.3 . 392The following awk script can be used to convert your old-style password 393file into a new style password file. 394The additional fields 395.Ar class , 396.Ar change 397and 398.Ar expire 399are added, but are turned off by default. 400Class is currently not implemented, but change and expire are; to set them, 401use the current day in seconds from the epoch + whatever number of seconds 402of offset you want. 403.Bd -literal -offset indent 404BEGIN { FS = ":"} 405{ print $1 ":" $2 ":" $3 ":" $4 "::0:0:" $5 ":" $6 ":" $7 } 406.Ed 407.Sh SEE ALSO 408.Xr chpass 1 , 409.Xr login 1 , 410.Xr passwd 1 , 411.Xr crypt 3 , 412.Xr getpwent 3 , 413.Xr login.conf 5 , 414.Xr netgroup 5 , 415.Xr nsswitch.conf 5 , 416.Xr adduser 8 , 417.Xr nologin 8 , 418.Xr pw 8 , 419.Xr pwd_mkdb 8 , 420.Xr vipw 8 , 421.Xr yp 8 422.Pp 423.%T "Managing NFS and NIS" 424(O'Reilly & Associates) 425.Sh HISTORY 426A 427.Nm 428file format appeared in 429.At v6 . 430.Pp 431The 432.Tn NIS 433.Nm 434file format first appeared in SunOS. 435.Pp 436The Hesiod support first appeared in 437.Fx 4.1 . 438It was imported from the 439.Nx 440Project, where it first appeared in 441.Nx 1.4 . 442.Sh BUGS 443User information should (and eventually will) be stored elsewhere. 444.Pp 445Placing 446.Sq Li compat 447exclusions in the file after any inclusions will have 448unexpected results. 449