1.\" $OpenBSD: passwd.5,v 1.35 2009/03/27 12:31:31 schwarze 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 $Mdocdate: March 27 2009 $ 35.Dt PASSWD 5 36.Os 37.Sh NAME 38.Nm passwd , 39.Nm master.passwd 40.Nd format of the password file 41.Sh DESCRIPTION 42The 43.Nm master.passwd 44file, readable only by root, consists of newline-separated records, 45one per user, containing ten colon 46.Pq Ql \&: 47separated fields. 48These fields are as follows: 49.Pp 50.Bl -tag -width password -offset indent -compact 51.It name 52User's login name. 53.It password 54User's 55.Em encrypted 56password. 57.It uid 58User's login user ID. 59.It gid 60User's login group ID. 61.It class 62User's general classification (see 63.Xr login.conf 5 ) . 64.It change 65Password change time. 66.It expire 67Account expiration time. 68.It gecos 69General information about the user. 70.It home_dir 71User's home directory. 72.It shell 73User's login shell. 74.El 75.Pp 76The publicly-readable 77.Nm passwd 78file is generated from the 79.Nm master.passwd 80file by 81.Xr pwd_mkdb 8 82and has the class, change, and expire fields removed. 83Also, the encrypted password field is replaced by an asterisk 84.Pq Ql \&* . 85.Pp 86The password files should never be edited by hand; 87.Xr vipw 8 88should be used instead. 89.Pp 90The 91.Ar name 92field is the login used to access the computer account, and the 93.Ar uid 94field is the number associated with it. 95They should both be unique across the system (and often across a group of 96systems) since they control file access. 97.Pp 98While it is possible to have multiple entries with identical login names 99and/or identical user IDs, it is usually a mistake to do so. 100Routines that manipulate these files will often return only one of the 101multiple entries, and that one by random selection. 102.Pp 103The login name may be up to 31 characters long. 104For compatibility with legacy software, a login name should start 105with a letter and consist solely of letters, numbers, dashes and 106underscores. 107The login name must never begin with a hyphen 108.Pq Ql \&- ; 109also, it is strongly 110suggested that neither uppercase characters nor dots 111.Pq Ql \&. 112be part of the name, as this tends to confuse mailers. 113No field may contain a colon 114as this has been used historically to separate the fields 115in the user database. 116.Pp 117The password field is the 118.Em encrypted 119form of the password. 120If the 121.Ar password 122field is empty, no password will be required to gain access to the machine. 123This is almost invariably a mistake. 124By convention, accounts that are not intended to be logged in to 125(e.g. bin, daemon, sshd) have a star 126.Pq Ql * 127in the 128.Ar password 129field. 130Note that there is nothing special about 131.Ql * , 132it is just one of many strings that is not a valid encrypted password 133(see 134.Xr crypt 3 ) . 135Because 136.Nm master.passwd 137contains the encrypted user passwords, it should not be readable by anyone 138without appropriate privileges. 139.Pp 140Which type of cipher is used to encrypt the password information 141depends on the configuration in 142.Xr login.conf 5 . 143It can be different for local and YP passwords. 144.Pp 145The 146.Ar group 147field is the group that the user will be placed in upon login. 148Since this system supports multiple groups (see 149.Xr groups 1 ) 150this field currently has little special meaning. 151.Pp 152The 153.Ar class 154field is used by 155.Xr login 1 156and other programs to determine which entry in the 157.Xr login.conf 5 158database should be used. 159.Pp 160The 161.Ar change 162field is the number in seconds, GMT, from the Epoch, until the 163password for the account must be changed. 164This field may be left empty to turn off the password aging feature. 165.Pp 166The 167.Ar expire 168field is the number in seconds, GMT, from the Epoch, until the 169account expires. 170This field may be left empty to turn off the account aging feature. 171.Pp 172The 173.Ar gecos 174field normally contains comma 175.Pq Ql \&, 176separated subfields as follows: 177.Pp 178.Bl -tag -width office -offset indent -compact 179.It name 180User's full name. 181.It office 182User's office location. 183.It wphone 184User's work phone number. 185.It hphone 186User's home phone number. 187.El 188.Pp 189The full name may contain an ampersand 190.Pq Ql \&& , 191which will be replaced by the capitalized login name when the gecos field 192is displayed or used by various programs such as 193.Xr finger 1 , 194.Xr sendmail 8 , 195etc. 196.Pp 197The office and phone number subfields, if they exist, are used by the 198.Xr finger 1 199program and possibly by other applications. 200.Pp 201The 202.Ar home_dir 203field 204(the user's home directory) 205is the full 206.Tn UNIX 207pathname where the user will be placed on login. 208.Pp 209The 210.Ar shell 211field is the command interpreter the user prefers. 212If there is nothing in the 213.Ar shell 214field, the Bourne shell 215.Pq Pa /bin/sh 216is assumed. 217Accounts that are not intended to be logged in to usually have 218a shell of 219.Pa /sbin/nologin . 220.Sh YP SUPPORT 221If YP is active, the 222.Nm passwd 223file also supports standard YP exclusions and inclusions, based on user 224names and netgroups. 225.Pp 226Lines beginning with a 227.Ql \&- 228(minus sign) are entries marked as being excluded 229from any following inclusions, which are marked with a 230.Ql + 231(plus sign). 232.Pp 233If the second character of the line is a 234.Ql @ 235(at sign), the operation involves the user fields of all entries in the 236netgroup specified by the remaining characters of the 237.Ar name 238field. 239Otherwise, the remainder of the 240.Ar name 241field is assumed to be a specific user name. 242.Pp 243The 244.Ql + 245token may also be alone in the 246.Ar name 247field, which causes all users from the 248.Pa passwd.byname 249and 250.Pa passwd.byuid 251YP maps to be included. 252.Pp 253If the entry contains non-empty 254.Ar uid 255or 256.Ar gid 257fields, the specified numbers will override the information retrieved 258from the YP maps. 259Additionally, if the 260.Ar gecos , 261.Ar dir , 262or 263.Ar shell 264entries contain text, it will override the information included via YP. 265On some systems, the 266.Ar passwd 267field may also be overridden. 268It is recommended that the standard way to enable YP passwd support in 269.Pa /etc/master.passwd 270is: 271.Pp 272+:*:::::::: 273.Pp 274which after 275.Xr pwd_mkdb 8 276will result in 277.Pa /etc/passwd 278containing: 279.Pp 280+:*:0:0::: 281.Pp 282When YP is enabled but temporarily unavailable, login becomes impossible 283for all users except those having an entry in the 284.Xr netid 5 285file. 286.Sh SEE ALSO 287.Xr chpass 1 , 288.Xr login 1 , 289.Xr passwd 1 , 290.Xr crypt 3 , 291.Xr getpwent 3 , 292.Xr login.conf 5 , 293.Xr netgroup 5 , 294.Xr netid 5 , 295.Xr adduser 8 , 296.Xr Makefile.yp 8 , 297.Xr pwd_mkdb 8 , 298.Xr vipw 8 , 299.Xr yp 8 300.Pp 301.%T "Managing NFS and NIS" 302(O'Reilly & Associates) 303.Sh STANDARDS 304The password file format has changed since 305.Bx 4.3 . 306The following 307.Xr awk 1 308script can be used to convert your old-style password 309file into a new style password file. 310The additional fields 311.Dq class , 312.Dq change , 313and 314.Dq expire 315are added, but are turned off by default. 316To set 317.Ar change 318and 319.Ar expire 320use the current day in seconds from the Epoch plus the number of seconds 321of offset desired. 322.Bd -literal -offset indent 323BEGIN { FS = ":"} 324{ print $1 ":" $2 ":" $3 ":" $4 "::0:0:" $5 ":" $6 ":" $7 } 325.Ed 326.Sh HISTORY 327A 328.Nm passwd 329file format appeared in 330.At v3 . 331.Pp 332The YP file format first appeared in SunOS. 333.Sh BUGS 334User information should (and eventually will) be stored elsewhere. 335.Pp 336Placing YP exclusions in the file after any inclusions will have 337unexpected results. 338