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 May 8, 2007 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. 207.Pp 208The 209.Ar expire 210field is the number of seconds from the epoch, 211.Dv UTC , 212until the 213account expires. 214This field may be left empty to turn off the account aging feature. 215.Pp 216The 217.Ar gecos 218field normally contains comma 219.Pq Ql \&, 220separated subfields as follows: 221.Pp 222.Bl -tag -width ".Ar office" -offset indent -compact 223.It Ar name 224user's full name 225.It Ar office 226user's office number 227.It Ar wphone 228user's work phone number 229.It Ar hphone 230user's home phone number 231.El 232.Pp 233The full 234.Ar name 235may contain a ampersand 236.Pq Ql & 237which will be replaced by 238the capitalized login 239.Ar name 240when the 241.Ar gecos 242field is displayed or used 243by various programs such as 244.Xr finger 1 , 245.Xr sendmail 8 , 246etc. 247.Pp 248The 249.Ar office 250and phone number subfields are used by the 251.Xr finger 1 252program, and possibly other applications. 253.Pp 254The user's home directory, 255.Ar home_dir , 256is the full 257.Ux 258path name where the user 259will be placed on login. 260.Pp 261The 262.Ar shell 263field is the command interpreter the user prefers. 264If there is nothing in the 265.Ar shell 266field, the Bourne shell 267.Pq Pa /bin/sh 268is assumed. 269The conventional way to disable logging into an account once and for all, 270as it is done for system accounts, 271is to set its 272.Ar shell 273to 274.Xr nologin 8 . 275.Sh HESIOD SUPPORT 276If 277.Sq Li dns 278is specified for the 279.Sq Li passwd 280database in 281.Xr nsswitch.conf 5 , 282then 283.Nm 284lookups occur from the 285.Sq Li passwd 286Hesiod domain. 287.Sh NIS SUPPORT 288If 289.Sq Li nis 290is specified for the 291.Sq Li passwd 292database in 293.Xr nsswitch.conf 5 , 294then 295.Nm 296lookups occur from the 297.Sq Li passwd.byname , 298.Sq Li passwd.byuid , 299.Sq Li master.passwd.byname , 300and 301.Sq Li master.passwd.byuid 302.Tn NIS 303maps. 304.Sh COMPAT SUPPORT 305If 306.Sq Li compat 307is specified for the 308.Sq Li passwd 309database, and either 310.Sq Li dns 311or 312.Sq Li nis 313is specified for the 314.Sq Li passwd_compat 315database in 316.Xr nsswitch.conf 5 , 317then the 318.Nm 319file also supports standard 320.Sq Li + Ns / Ns Li - 321exclusions and inclusions, based on user names and netgroups. 322.Pp 323Lines beginning with a 324.Ql - 325(minus sign) are entries marked as being excluded 326from any following inclusions, which are marked with a 327.Ql + 328(plus sign). 329.Pp 330If the second character of the line is a 331.Ql @ 332(at sign), the operation 333involves the user fields of all entries in the netgroup specified by the 334remaining characters of the 335.Ar name 336field. 337Otherwise, the remainder of the 338.Ar name 339field is assumed to be a specific user name. 340.Pp 341The 342.Ql + 343token may also be alone in the 344.Ar name 345field, which causes all users from either the Hesiod domain 346.Nm 347(with 348.Sq Li passwd_compat: dns ) 349or 350.Sq Li passwd.byname 351and 352.Sq Li passwd.byuid 353.Tn NIS 354maps (with 355.Sq Li passwd_compat: nis ) 356to be included. 357.Pp 358If the entry contains non-empty 359.Ar uid 360or 361.Ar gid 362fields, the specified numbers will override the information retrieved 363from the Hesiod domain or the 364.Tn NIS 365maps. 366As well, if the 367.Ar gecos , 368.Ar dir 369or 370.Ar shell 371entries contain text, it will override the information included via 372Hesiod or 373.Tn NIS . 374On some systems, the 375.Ar passwd 376field may also be overridden. 377.Sh FILES 378.Bl -tag -width ".Pa /etc/master.passwd" -compact 379.It Pa /etc/passwd 380.Tn ASCII 381password file, with passwords removed 382.It Pa /etc/pwd.db 383.Xr db 3 Ns -format 384password database, with passwords removed 385.It Pa /etc/master.passwd 386.Tn ASCII 387password file, with passwords intact 388.It Pa /etc/spwd.db 389.Xr db 3 Ns -format 390password database, with passwords intact 391.El 392.Sh COMPATIBILITY 393The password file format has changed since 394.Bx 4.3 . 395The following awk script can be used to convert your old-style password 396file into a new style password file. 397The additional fields 398.Ar class , 399.Ar change 400and 401.Ar expire 402are added, but are turned off by default. 403Class is currently not implemented, but change and expire are; to set them, 404use the current day in seconds from the epoch + whatever number of seconds 405of offset you want. 406.Bd -literal -offset indent 407BEGIN { FS = ":"} 408{ print $1 ":" $2 ":" $3 ":" $4 "::0:0:" $5 ":" $6 ":" $7 } 409.Ed 410.Sh SEE ALSO 411.Xr chpass 1 , 412.Xr login 1 , 413.Xr passwd 1 , 414.Xr crypt 3 , 415.Xr getpwent 3 , 416.Xr login.conf 5 , 417.Xr netgroup 5 , 418.Xr nsswitch.conf 5 , 419.Xr adduser 8 , 420.Xr nologin 8 , 421.Xr pw 8 , 422.Xr pwd_mkdb 8 , 423.Xr vipw 8 , 424.Xr yp 8 425.Pp 426.%T "Managing NFS and NIS" 427(O'Reilly & Associates) 428.Sh HISTORY 429A 430.Nm 431file format appeared in 432.At v6 . 433.Pp 434The 435.Tn NIS 436.Nm 437file format first appeared in SunOS. 438.Pp 439The Hesiod support first appeared in 440.Fx 4.1 . 441It was imported from the 442.Nx 443Project, where it first appeared in 444.Nx 1.4 . 445.Sh BUGS 446User information should (and eventually will) be stored elsewhere. 447.Pp 448Placing 449.Sq Li compat 450exclusions in the file after any inclusions will have 451unexpected results. 452