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