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