1.\" $OpenBSD: passwd.5,v 1.41 2014/11/02 05:33:04 tedu 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: November 2 2014 $ 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 141Configuration for the cipher used to encrypt the password information 142is contained in 143.Xr login.conf 5 . 144.Pp 145The 146.Ar group 147field is the primary group that the user will be placed in upon login. 148Note that the 149.Xr group 5 150file may grant the user access to supplementary groups. 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 separated subfields as follows: 175.Pp 176.Bl -tag -width office -offset indent -compact 177.It name 178User's full name. 179.It office 180User's office location. 181.It wphone 182User's work phone number. 183.It hphone 184User's home phone number. 185.El 186.Pp 187The full name may contain an ampersand 188.Pq Ql \&& , 189which will be replaced by the capitalized login name when the gecos field 190is displayed or used by various programs such as 191.Xr finger 1 , 192.Xr sendmail 8 , 193etc. 194.Pp 195The office and phone number subfields, if they exist, are used by the 196.Xr finger 1 197program and possibly by other applications. 198.Pp 199The 200.Ar home_dir 201field is the full path name of a directory to be used as the initial 202working directory for the user's login shell. 203Usually, it is owned by the user and by the user's primary 204.Ar group . 205.Pp 206The 207.Ar shell 208field is the command interpreter the user prefers. 209If there is nothing in the 210.Ar shell 211field, the default shell 212.Pq Pa /bin/sh 213is assumed. 214Accounts that are not intended to be logged in to usually have 215a shell of 216.Pa /sbin/nologin . 217.Sh YP SUPPORT 218If YP is active, the 219.Nm passwd 220file also supports standard YP exclusions and inclusions, based on user 221names and netgroups. 222.Pp 223Lines beginning with a 224.Ql \&- 225(minus sign) are entries marked as being excluded 226from any following inclusions, which are marked with a 227.Ql + 228(plus sign). 229.Pp 230If the second character of the line is a 231.Ql @ 232(at sign), the operation involves the user fields of all entries in the 233netgroup specified by the remaining characters of the 234.Ar name 235field. 236Otherwise, the remainder of the 237.Ar name 238field is assumed to be a specific user name. 239.Pp 240The 241.Ql + 242token may also be alone in the 243.Ar name 244field, which causes all users from the 245.Pa passwd.byname 246and 247.Pa passwd.byuid 248YP maps to be included. 249.Pp 250If the entry contains non-empty 251.Ar uid 252or 253.Ar gid 254fields, the specified numbers will override the information retrieved 255from the YP maps. 256Additionally, if the 257.Ar gecos , 258.Ar dir , 259or 260.Ar shell 261entries contain text, it will override the information included via YP. 262On some systems, the 263.Ar passwd 264field may also be overridden. 265It is recommended that the standard way to enable YP passwd support in 266.Pa /etc/master.passwd 267is: 268.Pp 269+:*:::::::: 270.Pp 271which after 272.Xr pwd_mkdb 8 273will result in 274.Pa /etc/passwd 275containing: 276.Pp 277+:*:0:0::: 278.Pp 279When YP is enabled but temporarily unavailable, login becomes impossible 280for all users except those having an entry in the 281.Xr netid 5 282file. 283.Sh SEE ALSO 284.Xr chpass 1 , 285.Xr login 1 , 286.Xr passwd 1 , 287.Xr crypt 3 , 288.Xr getpwent 3 , 289.Xr login.conf 5 , 290.Xr netgroup 5 , 291.Xr netid 5 , 292.Xr adduser 8 , 293.Xr Makefile.yp 8 , 294.Xr pwd_mkdb 8 , 295.Xr vipw 8 , 296.Xr yp 8 297.Pp 298.%T "Managing NFS and NIS" 299(O'Reilly & Associates) 300.Sh HISTORY 301A 302.Nm passwd 303file format first appeared in 304.At v1 . 305The gecos field first appeared in 306.At v3 ; 307since the same version, the passwords are encrypted. 308The gid field first appeared in 309.At v5 ; 310the class, change and expire fields as well as the 311.Nm master.passwd 312file in 313.Bx 4.3 Reno . 314.Pp 315The YP file format first appeared in SunOS. 316.Sh CAVEATS 317Placing YP exclusions in the file after any inclusions does not cancel 318the earlier inclusions. 319