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