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