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