share/man/man5/passwd.5

   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 February 8, 2005
  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
  46 The
  47 .Nm
  48 files are the local source of password information.
  49 They can be used in conjunction with the Hesiod domains
  50 .Sq passwd
  51 and
  52 .Sq uid ,
  53 and the
  54 .Tn NIS
  55 maps
  56 .Sq passwd.byname ,
  57 .Sq passwd.byuid ,
  58 .Sq master.passwd.byname ,
  59 and
  60 .Sq master.passwd.byuid ,
  61 as controlled by
  62 .Xr nsswitch.conf 5 .
  63 .Pp
  64 For consistency, none of these files should ever be modified
  65 manually.
  66 .Pp
  67 The
  68 .Nm master.passwd
  69 file is readable only by root, and consists of newline separated
  70 records, one per user, containing ten colon (``:'') separated
  71 fields.
  72 These fields are as follows:
  73 .Pp
  74 .Bl -tag -width password -offset indent
  75 .It name
  76 User's login name.
  77 .It password
  78 User's
  79 .Em encrypted
  80 password.
  81 .It uid
  82 User's id.
  83 .It gid
  84 User's login group id.
  85 .It class
  86 User's login class.
  87 .It change
  88 Password change time.
  89 .It expire
  90 Account expiration time.
  91 .It gecos
  92 General information about the user.
  93 .It home_dir
  94 User's home directory.
  95 .It shell
  96 User's login shell.
  97 .El
  98 .Pp
  99 The
 100 .Nm
 101 file is generated from the
 102 .Nm master.passwd
 103 file by
 104 .Xr pwd_mkdb 8 ,
 105 has the class, change, and expire fields removed, and the password
 106 field replaced by a
 107 .Ql *
 108 character.
 109 In the
 110 .Nm master.passwd
 111 file, a password of
 112 .Ql *
 113 is used to indicate that no one can ever log into that account
 114 using password authentication (logins through other forms of
 115 authentication, i.e.\& using
 116 .Xr ssh 1
 117 keys, will still work).
 118 The field only contains encrypted passwords, and
 119 .Ql *
 120 can never be the result of encrypting a password.
 121 .Pp
 122 The
 123 .Ar name
 124 field is the login used to access the computer account, and the
 125 .Ar uid
 126 field is the number associated with it.
 127 They should both be unique
 128 across the system (and often across a group of systems) since they
 129 control file access.
 130 .Pp
 131 While it is possible to have multiple entries with identical login names
 132 and/or identical user id's, it is usually a mistake to do so.
 133 Routines
 134 that manipulate these files will often return only one of the multiple
 135 entries, and that one by random selection.
 136 .Pp
 137 The login name must never begin with a hyphen (``-''); also, it is strongly
 138 suggested that neither upper-case characters or dots (``.'') be part
 139 of the name, as this tends to confuse mailers.
 140 No field may contain a
 141 colon (``:'') as this has been used historically to separate the fields
 142 in the user database.
 143 .Pp
 144 The password field is the
 145 .Em encrypted
 146 form of the password, see
 147 .Xr crypt 3 .
 148 If the
 149 .Ar password
 150 field is empty, no password will be required to gain access to the
 151 machine.
 152 This is almost invariably a mistake.
 153 Because these files contain the encrypted user passwords, they should
 154 not be readable by anyone without appropriate privileges.
 155 .Pp
 156 The group field is the group that the user will be placed in upon login.
 157 Since this system supports multiple groups (see
 158 .Xr groups 1 )
 159 this field currently has little special meaning.
 160 .Pp
 161 The
 162 .Ar class
 163 field is a key for a user's login class.
 164 Login classes
 165 are defined in
 166 .Xr login.conf 5 ,
 167 which is a
 168 .Xr termcap 5
 169 style database of user attributes, accounting, resource,
 170 and environment settings.
 171 .Pp
 172 The
 173 .Ar change
 174 field is the number of seconds from the epoch,
 175 .Dv UTC ,
 176 until the
 177 password for the account must be changed.
 178 This field may be left empty to turn off the password aging feature.
 179 .Pp
 180 The
 181 .Ar expire
 182 field is the number of seconds from the epoch,
 183 .Dv UTC ,
 184 until the
 185 account expires.
 186 This field may be left empty to turn off the account aging feature.
 187 .Pp
 188 The
 189 .Ar gecos
 190 field normally contains comma (``,'') separated subfields as follows:
 191 .Pp
 192 .Bl -tag -width office -offset indent -compact
 193 .It name
 194 user's full name
 195 .It office
 196 user's office number
 197 .It wphone
 198 user's work phone number
 199 .It hphone
 200 user's home phone number
 201 .El
 202 .Pp
 203 The full name may contain a ampersand (``&'') which will be replaced by
 204 the capitalized login name when the gecos field is displayed or used
 205 by various programs such as
 206 .Xr finger 1 ,
 207 .Xr sendmail 8 ,
 208 etc.
 209 .Pp
 210 The office and phone number subfields are used by the
 211 .Xr finger 1
 212 program, and possibly other applications.
 213 .Pp
 214 The user's home directory is the full
 215 .Ux
 216 path name where the user
 217 will be placed on login.
 218 .Pp
 219 The shell field is the command interpreter the user prefers.
 220 If there is nothing in the
 221 .Ar shell
 222 field, the Bourne shell
 223 .Pq Pa /bin/sh
 224 is assumed.
 225 .Sh HESIOD SUPPORT
 226 If
 227 .Sq dns
 228 is specified for the
 229 .Sq passwd
 230 database in
 231 .Xr nsswitch.conf 5 ,
 232 then
 233 .Nm
 234 lookups occur from the
 235 .Sq passwd
 236 Hesiod domain.
 237 .Sh NIS SUPPORT
 238 If
 239 .Sq nis
 240 is specified for the
 241 .Sq passwd
 242 database in
 243 .Xr nsswitch.conf 5 ,
 244 then
 245 .Nm
 246 lookups occur from the
 247 .Sq passwd.byname ,
 248 .Sq passwd.byuid ,
 249 .Sq master.passwd.byname ,
 250 and
 251 .Sq master.passwd.byuid
 252 .Tn NIS
 253 maps.
 254 .Sh COMPAT SUPPORT
 255 If
 256 .Sq compat
 257 is specified for the
 258 .Sq passwd
 259 database, and either
 260 .Sq dns
 261 or
 262 .Sq nis
 263 is specified for the
 264 .Sq passwd_compat
 265 database in
 266 .Xr nsswitch.conf 5 ,
 267 then the
 268 .Nm
 269 file also supports standard
 270 .Sq +/-
 271 exclusions and inclusions, based on user names and netgroups.
 272 .Pp
 273 Lines beginning with a ``-'' (minus sign) are entries marked as being excluded
 274 from any following inclusions, which are marked with a ``+'' (plus sign).
 275 .Pp
 276 If the second character of the line is a ``@'' (at sign), the operation
 277 involves the user fields of all entries in the netgroup specified by the
 278 remaining characters of the
 279 .Ar name
 280 field.
 281 Otherwise, the remainder of the
 282 .Ar name
 283 field is assumed to be a specific user name.
 284 .Pp
 285 The ``+'' token may also be alone in the
 286 .Ar name
 287 field, which causes all users from either the Hesiod domain
 288 .Nm
 289 (with
 290 .Sq passwd_compat: dns )
 291 or
 292 .Sq passwd.byname
 293 and
 294 .Sq passwd.byuid
 295 .Tn NIS
 296 maps (with
 297 .Sq passwd_compat: nis )
 298 to be included.
 299 .Pp
 300 If the entry contains non-empty
 301 .Ar uid
 302 or
 303 .Ar gid
 304 fields, the specified numbers will override the information retrieved
 305 from the Hesiod domain or the
 306 .Tn NIS
 307 maps.
 308 As well, if the
 309 .Ar gecos ,
 310 .Ar dir
 311 or
 312 .Ar shell
 313 entries contain text, it will override the information included via
 314 Hesiod or
 315 .Tn NIS .
 316 On some systems, the
 317 .Ar passwd
 318 field may also be overridden.
 319 .Sh FILES
 320 .Bl -tag -width ".Pa /etc/master.passwd" -compact
 321 .It Pa /etc/passwd
 322 .Tn ASCII
 323 password file, with passwords removed
 324 .It Pa /etc/pwd.db
 325 .Xr db 3 Ns -format
 326 password database, with passwords removed
 327 .It Pa /etc/master.passwd
 328 .Tn ASCII
 329 password file, with passwords intact
 330 .It Pa /etc/spwd.db
 331 .Xr db 3 Ns -format
 332 password database, with passwords intact
 333 .El
 334 .Sh COMPATIBILITY
 335 The password file format has changed since
 336 .Bx 4.3 .
 337 The following awk script can be used to convert your old-style password
 338 file into a new style password file.
 339 The additional fields
 340 .Dq class ,
 341 .Dq change
 342 and
 343 .Dq expire
 344 are added, but are turned off by default.
 345 Class is currently not implemented, but change and expire are; to set them,
 346 use the current day in seconds from the epoch + whatever number of seconds
 347 of offset you want.
 348 .Bd -literal -offset indent
 349 BEGIN { FS = ":"}
 350 { print $1 ":" $2 ":" $3 ":" $4 "::0:0:" $5 ":" $6 ":" $7 }
 351 .Ed
 352 .Sh SEE ALSO
 353 .Xr chpass 1 ,
 354 .Xr login 1 ,
 355 .Xr passwd 1 ,
 356 .Xr crypt 3 ,
 357 .Xr getpwent 3 ,
 358 .Xr login.conf 5 ,
 359 .Xr netgroup 5 ,
 360 .Xr adduser 8 ,
 361 .Xr pw 8 ,
 362 .Xr pwd_mkdb 8 ,
 363 .Xr vipw 8 ,
 364 .Xr yp 8
 365 .Pp
 366 .%T "Managing NFS and NIS"
 367 (O'Reilly & Associates)
 368 .Sh HISTORY
 369 A
 370 .Nm
 371 file format appeared in
 372 .At v6 .
 373 .Pp
 374 The
 375 .Tn NIS
 376 .Nm
 377 file format first appeared in SunOS.
 378 .Pp
 379 The Hesiod support first appeared in
 380 .Fx 4.1 .
 381 It was imported from the
 382 .Nx
 383 Project, where it first appeared in
 384 .Nx 1.4 .
 385 .Sh BUGS
 386 User information should (and eventually will) be stored elsewhere.
 387 .Pp
 388 Placing
 389 .Sq compat
 390 exclusions in the file after any inclusions will have
 391 unexpected results.