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