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