1.\" $NetBSD: passwd.5,v 1.12.2.2 1999/12/17 23:14:50 he Exp $ 2.\" 3.\" Copyright (c) 1988, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" Portions Copyright (c) 1994, Jason Downs. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed by the University of 18.\" California, Berkeley and its contributors. 19.\" 4. Neither the name of the University nor the names of its contributors 20.\" may be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.\" From: @(#)passwd.5 8.1 (Berkeley) 6/5/93 36.\" $FreeBSD$ 37.\" 38.Dd June 23, 2012 39.Dt PASSWD 5 40.Os 41.Sh NAME 42.Nm passwd , 43.Nm master.passwd 44.Nd format of the password file 45.Sh DESCRIPTION 46The 47.Nm 48files are the local source of password information. 49They can be used in conjunction with the Hesiod domains 50.Sq Li passwd 51and 52.Sq Li uid , 53and the 54.Tn NIS 55maps 56.Sq Li passwd.byname , 57.Sq Li passwd.byuid , 58.Sq Li master.passwd.byname , 59and 60.Sq Li master.passwd.byuid , 61as controlled by 62.Xr nsswitch.conf 5 . 63.Pp 64For consistency, none of these files should ever be modified 65manually. 66.Pp 67The 68.Nm master.passwd 69file is readable only by root, and consists of newline separated 70records, one per user, containing ten colon 71.Pq Ql \&: 72separated 73fields. 74These fields are as follows: 75.Bl -tag -width ".Ar password" -offset indent 76.It Ar name 77User's login name. 78.It Ar password 79User's 80.Em encrypted 81password. 82.It Ar uid 83User's id. 84.It Ar gid 85User's login group id. 86.It Ar class 87User's login class. 88.It Ar change 89Password change time. 90.It Ar expire 91Account expiration time. 92.It Ar gecos 93General information about the user. 94.It Ar home_dir 95User's home directory. 96.It Ar shell 97User's login shell. 98.El 99.Pp 100The 101.Nm 102file is generated from the 103.Nm master.passwd 104file by 105.Xr pwd_mkdb 8 , 106has the 107.Ar class , 108.Ar change , 109and 110.Ar expire 111fields removed, and the 112.Ar password 113field replaced by a 114.Ql * 115character. 116.Pp 117The 118.Ar name 119field is the login used to access the computer account, and the 120.Ar uid 121field is the number associated with it. 122They should both be unique 123across the system (and often across a group of systems) since they 124control file access. 125.Pp 126While it is possible to have multiple entries with identical login names 127and/or identical user id's, it is usually a mistake to do so. 128Routines 129that manipulate these files will often return only one of the multiple 130entries, and that one by random selection. 131.Pp 132The login name must never begin with a hyphen 133.Pq Ql - ; 134also, it is strongly 135suggested that neither upper-case characters or dots 136.Pq Ql \&. 137be part 138of the name, as this tends to confuse mailers. 139No field may contain a 140colon 141.Pq Ql \&: 142as this has been used historically to separate the fields 143in the user database. 144.Pp 145In the 146.Nm master.passwd 147file, 148the 149.Ar password 150field is the 151.Em encrypted 152form of the password, see 153.Xr crypt 3 . 154If the 155.Ar password 156field is empty, no password will be required to gain access to the 157machine. 158This is almost invariably a mistake, so authentication components 159such as PAM can forcibly disallow remote access to passwordless accounts. 160Because this file contains the encrypted user passwords, it should 161not be readable by anyone without appropriate privileges. 162.Pp 163A password of 164.Ql * 165indicates that 166password authentication is disabled for that account 167(logins through other forms of 168authentication, e.g., using 169.Xr ssh 1 170keys, will still work). 171The field only contains encrypted passwords, and 172.Ql * 173can never be the result of encrypting a password. 174.Pp 175An encrypted password prefixed by 176.Ql *LOCKED* 177means that the account is temporarily locked out 178and no one can log into it using any authentication. 179For a convenient command-line interface to account locking, see 180.Xr pw 8 . 181.Pp 182The 183.Ar group 184field is the group that the user will be placed in upon login. 185Since this system supports multiple groups (see 186.Xr groups 1 ) 187this field currently has little special meaning. 188.Pp 189The 190.Ar class 191field is a key for a user's login class. 192Login classes 193are defined in 194.Xr login.conf 5 , 195which is a 196.Xr termcap 5 197style database of user attributes, accounting, resource, 198and environment settings. 199.Pp 200The 201.Ar change 202field is the number of seconds from the epoch, 203.Dv UTC , 204until the 205password for the account must be changed. 206This field may be left empty to turn off the password aging feature; 207a value of zero is equivalent to leaving the field empty. 208.Pp 209The 210.Ar expire 211field is the number of seconds from the epoch, 212.Dv UTC , 213until the 214account expires. 215This field may be left empty to turn off the account aging feature; 216a value of zero is equivalent to leaving the field empty. 217.Pp 218The 219.Ar gecos 220field normally contains comma 221.Pq Ql \&, 222separated subfields as follows: 223.Pp 224.Bl -tag -width ".Ar office" -offset indent -compact 225.It Ar name 226user's full name 227.It Ar office 228user's office number 229.It Ar wphone 230user's work phone number 231.It Ar hphone 232user's home phone number 233.El 234.Pp 235The full 236.Ar name 237may contain an ampersand 238.Pq Ql & 239which will be replaced by 240the capitalized login 241.Ar name 242when the 243.Ar gecos 244field is displayed or used 245by various programs such as 246.Xr finger 1 , 247.Xr sendmail 8 , 248etc. 249.Pp 250The 251.Ar office 252and phone number subfields are used by the 253.Xr finger 1 254program, and possibly other applications. 255.Pp 256The user's home directory, 257.Ar home_dir , 258is the full 259.Ux 260path name where the user 261will be placed on login. 262.Pp 263The 264.Ar shell 265field is the command interpreter the user prefers. 266If there is nothing in the 267.Ar shell 268field, the Bourne shell 269.Pq Pa /bin/sh 270is assumed. 271The conventional way to disable logging into an account once and for all, 272as it is done for system accounts, 273is to set its 274.Ar shell 275to 276.Pa /sbin/nologin 277.Pq see Xr nologin 8 . 278.Sh HESIOD SUPPORT 279If 280.Sq Li dns 281is specified for the 282.Sq Li passwd 283database in 284.Xr nsswitch.conf 5 , 285then 286.Nm 287lookups occur from the 288.Sq Li passwd 289Hesiod domain. 290.Sh NIS SUPPORT 291If 292.Sq Li nis 293is specified for the 294.Sq Li passwd 295database in 296.Xr nsswitch.conf 5 , 297then 298.Nm 299lookups occur from the 300.Sq Li passwd.byname , 301.Sq Li passwd.byuid , 302.Sq Li master.passwd.byname , 303and 304.Sq Li master.passwd.byuid 305.Tn NIS 306maps. 307.Sh COMPAT SUPPORT 308If 309.Sq Li compat 310is specified for the 311.Sq Li passwd 312database, and either 313.Sq Li dns 314or 315.Sq Li nis 316is specified for the 317.Sq Li passwd_compat 318database in 319.Xr nsswitch.conf 5 , 320then the 321.Nm 322file also supports standard 323.Sq Li + Ns / Ns Li - 324exclusions and inclusions, based on user names and netgroups. 325.Pp 326Lines beginning with a 327.Ql - 328(minus sign) are entries marked as being excluded 329from any following inclusions, which are marked with a 330.Ql + 331(plus sign). 332.Pp 333If the second character of the line is a 334.Ql @ 335(at sign), the operation 336involves the user fields of all entries in the netgroup specified by the 337remaining characters of the 338.Ar name 339field. 340Otherwise, the remainder of the 341.Ar name 342field is assumed to be a specific user name. 343.Pp 344The 345.Ql + 346token may also be alone in the 347.Ar name 348field, which causes all users from either the Hesiod domain 349.Nm 350(with 351.Sq Li passwd_compat: dns ) 352or 353.Sq Li passwd.byname 354and 355.Sq Li passwd.byuid 356.Tn NIS 357maps (with 358.Sq Li passwd_compat: nis ) 359to be included. 360.Pp 361If the entry contains non-empty 362.Ar uid 363or 364.Ar gid 365fields, the specified numbers will override the information retrieved 366from the Hesiod domain or the 367.Tn NIS 368maps. 369Likewise, if the 370.Ar gecos , 371.Ar dir 372or 373.Ar shell 374entries contain text, it will override the information included via 375Hesiod or 376.Tn NIS . 377On some systems, the 378.Ar passwd 379field may also be overridden. 380.Sh FILES 381.Bl -tag -width ".Pa /etc/master.passwd" -compact 382.It Pa /etc/passwd 383.Tn ASCII 384password file, with passwords removed 385.It Pa /etc/pwd.db 386.Xr db 3 Ns -format 387password database, with passwords removed 388.It Pa /etc/master.passwd 389.Tn ASCII 390password file, with passwords intact 391.It Pa /etc/spwd.db 392.Xr db 3 Ns -format 393password database, with passwords intact 394.El 395.Sh COMPATIBILITY 396The password file format has changed since 397.Bx 4.3 . 398The following awk script can be used to convert your old-style password 399file into a new style password file. 400The additional fields 401.Ar class , 402.Ar change 403and 404.Ar expire 405are added, but are turned off by default 406.Pq setting these fields to zero is equivalent to leaving them blank . 407Class is currently not implemented, but change and expire are; to set them, 408use the current day in seconds from the epoch + whatever number of seconds 409of offset you want. 410.Bd -literal -offset indent 411BEGIN { FS = ":"} 412{ print $1 ":" $2 ":" $3 ":" $4 "::0:0:" $5 ":" $6 ":" $7 } 413.Ed 414.Sh SEE ALSO 415.Xr chpass 1 , 416.Xr login 1 , 417.Xr passwd 1 , 418.Xr crypt 3 , 419.Xr getpwent 3 , 420.Xr login.conf 5 , 421.Xr netgroup 5 , 422.Xr nsswitch.conf 5 , 423.Xr adduser 8 , 424.Xr nologin 8 , 425.Xr pw 8 , 426.Xr pwd_mkdb 8 , 427.Xr vipw 8 , 428.Xr yp 8 429.Pp 430.%T "Managing NFS and NIS" 431(O'Reilly & Associates) 432.Sh HISTORY 433A 434.Nm 435file format appeared in 436.At v6 . 437.Pp 438The 439.Tn NIS 440.Nm 441file format first appeared in SunOS. 442.Pp 443The Hesiod support first appeared in 444.Fx 4.1 . 445It was imported from the 446.Nx 447Project, where it first appeared in 448.Nx 1.4 . 449.Sh BUGS 450User information should (and eventually will) be stored elsewhere. 451.Pp 452Placing 453.Sq Li compat 454exclusions in the file after any inclusions will have 455unexpected results. 456