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