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