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