1.\" $OpenBSD: passwd.5,v 1.19 2001/06/24 07:30:29 pvalchev Exp $ 2.\" $NetBSD: passwd.5,v 1.4 1995/07/28 06:46:05 phil Exp $ 3.\" 4.\" Copyright (c) 1988, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" Portions Copyright (c) 1994, Jason Downs. All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. All advertising materials mentioning features or use of this software 17.\" must display the following acknowledgement: 18.\" This product includes software developed by the University of 19.\" California, Berkeley and its contributors. 20.\" 4. Neither the name of the University nor the names of its contributors 21.\" may be used to endorse or promote products derived from this software 22.\" without specific prior written permission. 23.\" 24.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 25.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 26.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 27.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 28.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 29.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 30.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 31.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 32.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 33.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 34.\" SUCH DAMAGE. 35.\" 36.\" @(#)passwd.5 8.1 (Berkeley) 6/5/93 37.\" 38.Dd July 18, 1995 39.Dt PASSWD 5 40.Os 41.Sh NAME 42.Nm passwd 43.Nd format of the password file 44.Sh DESCRIPTION 45The 46.Nm master.passwd 47file, readable only by root, consists of newline-separated records, 48one per user, containing ten colon 49.Pq Ql \&: 50separated fields. 51These fields are as follows: 52.Pp 53.Bl -tag -width password -offset indent -compact 54.It name 55User's login name. 56.It password 57User's 58.Em encrypted 59password. 60.It uid 61User's login user ID. 62.It gid 63User's login group ID. 64.It class 65User's general classification (see 66.Xr login.conf 5 ). 67.It change 68Password change time. 69.It expire 70Account expiration time. 71.It gecos 72General information about the user. 73.It home_dir 74User's home directory. 75.It shell 76User's login shell. 77.El 78.Pp 79The publicly-readable 80.Nm passwd 81file is generated from the 82.Nm master.passwd 83file by 84.Xr pwd_mkdb 8 85and has the class, change, and expire fields removed. 86Also, the encrypted password field is replaced by an asterisk 87.Pq Ql \&* . 88.Pp 89The 90.Ar name 91field is the login used to access the computer account, and the 92.Ar uid 93field is the number associated with it. 94They should both be unique across the system (and often across a group of 95systems) since they control file access. 96.Pp 97While it is possible to have multiple entries with identical login names 98and/or identical user IDs, it is usually a mistake to do so. 99Routines that manipulate these files will often return only one of the 100multiple entries, and that one by random selection. 101.Pp 102The login name must never begin with a hyphen 103.Pq Ql \&- ; 104also, it is strongly 105suggested that neither uppercase characters nor dots 106.Pq Ql \&. 107be part 108of the name, as this tends to confuse mailers. 109No field may contain a colon 110as this has been used historically to separate the fields 111in the user database. 112.Pp 113The password field is the 114.Em encrypted 115form of the password. 116If the 117.Ar password 118field is empty, no password will be required to gain access to the machine. 119This is almost invariably a mistake. 120Because 121.Nm master.passwd 122contains the encrypted user passwords, it should not be readable by anyone 123without appropriate privileges. 124.Pp 125Which type of cipher is used to encrypt the password information 126depends on the configuration in 127.Xr passwd.conf 5 . 128It can be different for local and YP passwords. 129.Pp 130The 131.Ar group 132field is the group that the user will be placed in upon login. 133Since this system supports multiple groups (see 134.Xr groups 1 ) 135this field currently has little special meaning. 136.Pp 137The 138.Ar class 139field is used by 140.Xr login 1 141and other programs to determine which entry in the 142.Xr login.conf 5 143database should be used. 144.Pp 145The 146.Ar change 147field is the number in seconds, GMT, from the epoch, until the 148password for the account must be changed. 149This field may be left empty to turn off the password aging feature. 150.Pp 151The 152.Ar expire 153field is the number in seconds, GMT, from the epoch, until the 154account expires. 155This field may be left empty to turn off the account aging feature. 156.Pp 157The 158.Ar gecos 159field normally contains comma 160.Pq Ql \&, 161separated subfields as follows: 162.Pp 163.Bl -tag -width office -offset indent -compact 164.It name 165User's full name. 166.It office 167User's office location. 168.It wphone 169User's work phone number. 170.It hphone 171User's home phone number. 172.El 173.Pp 174The full name may contain an ampersand 175.Pq Ql \&& , 176which will be replaced by the capitalized login name when the gecos field 177is displayed or used by various programs such as 178.Xr finger 1 , 179.Xr sendmail 8 , 180etc. 181.Pp 182The office and phone number subfields, if they exist, are used by the 183.Xr finger 1 184program and possibly by other applications. 185.Pp 186The user's home directory is the full 187.Tn UNIX 188path name where the user will be placed on login. 189.Pp 190The 191.Ar shell 192field is the command interpreter the user prefers. 193If there is nothing in the 194.Ar shell 195field, the Bourne shell 196.Pq Pa /bin/sh 197is assumed. 198.Sh YP SUPPORT 199If YP is active, the 200.Nm passwd 201file also supports standard YP exclusions and inclusions, based on user 202names and netgroups. 203.Pp 204Lines beginning with a 205.Ql \&- 206(minus sign) are entries marked as being excluded 207from any following inclusions, which are marked with a 208.Ql + 209(plus sign). 210.Pp 211If the second character of the line is a 212.Ql @ 213(at sign), the operation involves the user fields of all entries in the 214netgroup specified by the remaining characters of the 215.Ar name 216field. 217Otherwise, the remainder of the 218.Ar name 219field is assumed to be a specific user name. 220.Pp 221The 222.Ql + 223token may also be alone in the 224.Ar name 225field, which causes all users from the 226.Pa passwd.byname 227and 228.Pa passwd.byuid 229YP maps to be included. 230.Pp 231If the entry contains non-empty 232.Ar uid 233or 234.Ar gid 235fields, the specified numbers will override the information retrieved 236from the YP maps. 237As well, if the 238.Ar gecos , 239.Ar dir , 240or 241.Ar shell 242entries contain text, it will override the information included via YP. 243On some systems, the 244.Ar passwd 245field may also be overridden. 246It is recommended that the standard way to enable YP passwd support in 247.Pa /etc/master.passwd 248is: 249.Pp 250+:*:::::::: 251.Pp 252which after 253.Xr pwd_mkdb 8 254will result in 255.Pa /etc/passwd 256containing: 257.Pp 258+:*:0:0::: 259.Sh SEE ALSO 260.Xr chpass 1 , 261.Xr login 1 , 262.Xr passwd 1 , 263.Xr getpwent 3 , 264.Xr netgroup 5 , 265.Xr passwd.conf 5 , 266.Xr adduser 8 , 267.Xr pwd_mkdb 8 , 268.Xr vipw 8 , 269.Xr yp 8 270.Pp 271.%T "Managing NFS and NIS" 272(O'Reilly & Associates) 273.Sh BUGS 274User information should (and eventually will) be stored elsewhere. 275.Pp 276Placing YP exclusions in the file after any inclusions will have 277unexpected results. 278.Sh COMPATIBILITY 279The password file format has changed since 280.Bx 4.3 . 281The following 282.Xr awk 283script can be used to convert your old-style password 284file into a new style password file. 285The additional fields 286.Dq class , 287.Dq change , 288and 289.Dq expire 290are added, but are turned off by default. 291To set 292.Ar change 293and 294.Ar expire 295use the current day in seconds from the epoch plus the number of seconds 296of offset desired. 297.Bd -literal -offset indent 298BEGIN { FS = ":"} 299{ print $1 ":" $2 ":" $3 ":" $4 "::0:0:" $5 ":" $6 ":" $7 } 300.Ed 301.Sh HISTORY 302A 303.Nm passwd 304file format appeared in 305.At v6 . 306.Pp 307The YP file format first appeared in SunOS. 308