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