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