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