1.\" $NetBSD: passwd.5,v 1.23 2003/10/13 15:36:34 agc 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 November 17, 2000 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 116The 117.Nm 118file is generated from the 119.Nm master.passwd 120file by 121.Xr pwd_mkdb 8 , 122has the 123.Em class , 124.Em change , 125and 126.Em expire 127fields removed, and the 128.Em password 129field replaced by a 130.Dq \&* . 131.Pp 132The 133.Em name 134field is the login used to access the computer account, and the 135.Em uid 136field is the number associated with it. They should both be unique 137across the system (and often across a group of systems) since they 138control file access. 139.Pp 140While it is possible to have multiple entries with identical login names 141and/or identical user id's, it is usually a mistake to do so. Routines 142that manipulate these files will often return only one of the multiple 143entries, and that one by random selection. 144.Pp 145The login name must never begin with a hyphen 146.Pq Dq \&- ; 147also, it is strongly suggested that neither upper-case characters nor dots 148.Pq Dq \&. 149be part of the name, as this tends to confuse mailers. 150No field may contain a colon 151.Pq Dq \&: 152as this has been used historically to separate the fields in the user database. 153.Pp 154The 155.Em password 156field is the 157.Em encrypted 158form of the password. 159If the 160.Em password 161field is empty, no password will be required to gain access to the 162machine. This is almost invariably a mistake. 163Because these files contain the encrypted user passwords, they should 164not be readable by anyone without appropriate privileges. 165For the possible ciphers used in this field see 166.Xr passwd.conf 5 . 167.Pp 168The 169.Em gid 170field is the group that the user will be placed in upon login. 171Since this system supports multiple groups (see 172.Xr groups 1 ) 173this field currently has little special meaning. 174.Pp 175The 176.Em class 177field is a key for a user's login class. 178Login classes are defined in 179.Xr login.conf 5 , 180which is a 181.Xr termcap 5 182style database of user attributes, accounting, resource and 183environment settings. 184.Pp 185The 186.Em change 187field is the number of seconds from the epoch, 188.Dv UTC , 189until the 190password for the account must be changed. 191This field may be left empty to turn off the password aging feature. 192If this is set to 193.Dq -1 194then the user will be prompted to change their password at the next 195login. 196.Pp 197The 198.Em expire 199field is the number of seconds from the epoch, 200.Dv UTC , 201until the 202account expires. 203This field may be left empty to turn off the account aging feature. 204.Pp 205If either of the 206.Em change 207or 208.Em expire 209fields are set, the system will remind the user of the impending 210change or expiry if they login within a configurable period 211(defaulting to 14 days) before the event. 212.Pp 213The 214.Em gecos 215field normally contains comma 216.Pq Dq \&, 217separated subfields as follows: 218.Pp 219.Bl -tag -width office -offset indent -compact 220.It Em name 221user's full name 222.It Em office 223user's office number 224.It Em wphone 225user's work phone number 226.It Em hphone 227user's home phone number 228.El 229.Pp 230The full name may contain an ampersand 231.Pq Dq \&\*[Am] 232which will be replaced by 233the capitalized login name when the gecos field is displayed or used 234by various programs such as 235.Xr finger 1 , 236.Xr sendmail 8 , 237etc. 238.Pp 239The office and phone number subfields are used by the 240.Xr finger 1 241program, and possibly other applications. 242.Pp 243The user's home directory is the full 244.Ux 245path name where the user 246will be placed on login. 247.Pp 248The shell field is the command interpreter the user prefers. 249If there is nothing in the 250.Em shell 251field, the Bourne shell 252.Pq Pa /bin/sh 253is assumed. 254.Sh HESIOD SUPPORT 255If 256.Sq dns 257is specified for the 258.Sq passwd 259database in 260.Xr nsswitch.conf 5 , 261then 262.Nm 263lookups occur from the 264.Sq passwd 265Hesiod domain. 266.Sh NIS SUPPORT 267If 268.Sq nis 269is specified for the 270.Sq passwd 271database in 272.Xr nsswitch.conf 5 , 273then 274.Nm 275lookups occur from the 276.Sq passwd.byname , 277.Sq passwd.byuid , 278.Sq master.passwd.byname , 279and 280.Sq master.passwd.byuid 281.Tn NIS 282maps. 283.Sh COMPAT SUPPORT 284If 285.Sq compat 286is specified for the 287.Sq passwd 288database, and either 289.Sq dns 290or 291.Sq nis 292is specified for the 293.Sq passwd_compat 294database in 295.Xr nsswitch.conf 5 , 296then the 297.Nm 298file also supports standard 299.Sq +/- 300exclusions and inclusions, based on user names and netgroups. 301.Pp 302Lines beginning with a minus sign 303.Pq Dq \&- 304are entries marked as being excluded from any following inclusions, 305which are marked with a plus sign 306.Pq Dq \&+ . 307.Pp 308If the second character of the line is an at sign 309.Pq Dq \&@ , 310the operation 311involves the user fields of all entries in the netgroup specified by the 312remaining characters of the 313.Em name 314field. 315Otherwise, the remainder of the 316.Em name 317field is assumed to be a specific user name. 318.Pp 319The 320.Dq \&+ 321token may also be alone in the 322.Em name 323field, which causes all users from either the Hesiod domain 324.Nm 325(with 326.Sq passwd_compat: dns ) 327or 328.Sq passwd.byname 329and 330.Sq passwd.byuid 331.Tn NIS 332maps (with 333.Sq passwd_compat: nis ) 334to be included. 335.Pp 336If the entry contains non-empty 337.Em uid 338or 339.Em gid 340fields, the specified numbers will override the information retrieved 341from the Hesiod domain or the 342.Tn NIS 343maps. As well, if the 344.Em gecos , 345.Em home_dir 346or 347.Em shell 348entries contain text, it will override the information included via 349Hesiod or 350.Tn NIS . 351On some systems, the 352.Em passwd 353field may also be overridden. 354.Sh SEE ALSO 355.Xr chpass 1 , 356.Xr login 1 , 357.Xr passwd 1 , 358.Xr getpwent 3 , 359.Xr login_getclass 3 , 360.Xr login.conf 5 , 361.Xr netgroup 5 , 362.Xr passwd.conf 5 , 363.Xr adduser 8 , 364.Xr pwd_mkdb 8 , 365.Xr vipw 8 , 366.Xr yp 8 367.Pp 368.%T "Managing NFS and NIS" 369(O'Reilly \*[Am] Associates) 370.Sh BUGS 371User information should (and eventually will) be stored elsewhere. 372.Pp 373Placing 374.Sq compat 375exclusions in the file after any inclusions will have 376unexpected results. 377.Sh COMPATIBILITY 378The password file format has changed since 379.Bx 4.3 . 380The following awk script can be used to convert your old-style password 381file into a new style password file. 382The additional fields 383.Dq class , 384.Dq change 385and 386.Dq expire 387are added, but are turned off by default. 388To set them, 389use the current day in seconds from the epoch + whatever number of seconds 390of offset you want. 391.Bd -literal -offset indent 392BEGIN { FS = ":"} 393{ print $1 ":" $2 ":" $3 ":" $4 "::0:0:" $5 ":" $6 ":" $7 } 394.Ed 395.Sh HISTORY 396A 397.Nm 398file format appeared in 399.At v6 . 400.Pp 401The 402.Tn NIS 403.Nm 404file format first appeared in SunOS. 405.Pp 406The Hesiod support first appeared in 407.Nx 1.4 . 408.Pp 409The 410.Xr login.conf 5 411capability first appeared in 412.Nx 1.5 . 413