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