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