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