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