| blob | 7c9d4be066a13190ec6db90af8d39858d2b00619 |
1 .\" $NetBSD: passwd.5,v 1.27 2007/06/21 15:12:59 ginsbach Exp $
2 .\"
3 .\" Copyright (c) 1988, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" Portions Copyright (c) 1994, Jason Downs. All rights reserved.
31 .\"
32 .\" Redistribution and use in source and binary forms, with or without
33 .\" modification, are permitted provided that the following conditions
34 .\" are met:
35 .\" 1. Redistributions of source code must retain the above copyright
36 .\" notice, this list of conditions and the following disclaimer.
37 .\" 2. Redistributions in binary form must reproduce the above copyright
38 .\" notice, this list of conditions and the following disclaimer in the
39 .\" documentation and/or other materials provided with the distribution.
40 .\"
41 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS
42 .\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
43 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
44 .\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT,
45 .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
46 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
47 .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
48 .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
49 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
50 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
51 .\" SUCH DAMAGE.
52 .\"
53 .\" @(#)passwd.5 8.1 (Berkeley) 6/5/93
54 .\"
55 .Dd June 21, 2007
56 .Dt PASSWD 5
57 .Os
58 .Sh NAME
59 .Nm passwd ,
60 .Nm master.passwd
61 .Nd format of the password file
62 .Sh DESCRIPTION
63 The
64 .Nm passwd
65 files are the local source of password information.
66 They can be used in conjunction with the Hesiod domain
67 .Sq passwd
68 and the
69 .Tn NIS
70 maps
71 .Sq passwd.byname ,
72 .Sq passwd.byuid ,
73 .Sq master.passwd.byname ,
74 and
75 .Sq master.passwd.byuid ,
76 as controlled by
77 .Xr nsswitch.conf 5 .
78 .Pp
79 The
80 .Nm master.passwd
81 file is readable only by root, and consists of newline separated
82 .Tn ASCII
83 records, one per user, containing ten colon
84 .Pq Dq \&:
85 separated fields.
86 .Pp
87 Each line has the form:
88 .Dl name:password:uid:gid:class:change:expire:gecos:home_dir:shell
89 .Pp
90 These fields are as follows:
91 .Bl -tag -width password -offset indent -compact
92 .It Em name
93 User's login name.
94 .It Em password
95 User's
96 .Em encrypted
97 password.
98 .It Em uid
99 User's id.
100 .It Em gid
101 User's login group id.
102 .It Em class
103 User's login class.
104 .It Em change
105 Password change time.
106 .It Em expire
107 Account expiration time.
108 .It Em gecos
109 General information about the user.
110 .It Em home_dir
111 User's home directory.
112 .It Em shell
113 User's login shell.
114 .El
115 .Pp
116 Be aware that each line is limited to 1024 characters; longer ones will be
117 ignored.
118 This limit can be queried through
119 .Xr sysconf 3
120 by using the
121 .Li _SC_GETPW_R_SIZE_MAX
122 parameter.
123 .Pp
124 The
125 .Nm
126 file is generated from the
127 .Nm master.passwd
128 file by
129 .Xr pwd_mkdb 8 ,
130 has the
131 .Em class ,
132 .Em change ,
133 and
134 .Em expire
135 fields removed, and the
136 .Em password
137 field replaced by a
138 .Dq \&* .
139 .Pp
140 The
141 .Em name
142 field is the login used to access the computer account, and the
143 .Em uid
144 field is the number associated with it.
145 They should both be unique across the system (and often across a
146 group of systems) since they control file access.
147 .Pp
148 While it is possible to have multiple entries with identical login names
149 and/or identical user id's, it is usually a mistake to do so.
150 Routines that manipulate these files will often return only one of
151 the multiple entries, and that one by random selection.
152 .Pp
153 The login name must never begin with a hyphen
154 .Pq Dq \&- ;
155 also, it is strongly suggested that neither upper-case characters nor dots
156 .Pq Dq \&.
157 be part of the name, as this tends to confuse mailers.
158 No field may contain a colon
159 .Pq Dq \&:
160 as this has been used historically to separate the fields in the user database.
161 .Pp
162 The
163 .Em password
164 field is the
165 .Em encrypted
166 form of the password.
167 If the
168 .Em password
169 field is empty, no password will be required to gain access to the
170 machine.
171 This is almost invariably a mistake.
172 Because these files contain the encrypted user passwords, they should
173 not be readable by anyone without appropriate privileges.
174 For the possible ciphers used in this field see
175 .Xr passwd.conf 5 .
176 .Pp
177 The
178 .Em gid
179 field is the group that the user will be placed in upon login.
180 Since this system supports multiple groups (see
181 .Xr groups 1 )
182 this field currently has little special meaning.
183 .Pp
184 The
185 .Em class
186 field is a key for a user's login class.
187 Login classes are defined in
188 .Xr login.conf 5 ,
189 which is a
190 .Xr termcap 5
191 style database of user attributes, accounting, resource and
192 environment settings.
193 .Pp
194 The
195 .Em change
196 field is the number of seconds from the epoch,
197 .Dv UTC ,
198 until the
199 password for the account must be changed.
200 This field may be left empty to turn off the password aging feature.
201 If this is set to
202 .Dq -1
203 then the user will be prompted to change their password at the next
204 login.
205 .Pp
206 The
207 .Em expire
208 field is the number of seconds from the epoch,
209 .Dv UTC ,
210 until the
211 account expires.
212 This field may be left empty to turn off the account aging feature.
213 .Pp
214 If either of the
215 .Em change
216 or
217 .Em expire
218 fields are set, the system will remind the user of the impending
219 change or expiry if they login within a configurable period
220 (defaulting to 14 days) before the event.
221 .Pp
222 The
223 .Em gecos
224 field normally contains comma
225 .Pq Dq \&,
226 separated subfields as follows:
227 .Pp
228 .Bl -tag -width office -offset indent -compact
229 .It Em name
230 user's full name
231 .It Em office
232 user's office number
233 .It Em wphone
234 user's work phone number
235 .It Em hphone
236 user's home phone number
237 .El
238 .Pp
239 The full name may contain an ampersand
240 .Pq Dq \&\*[Am]
241 which will be replaced by
242 the capitalized login name when the gecos field is displayed or used
243 by various programs such as
244 .Xr finger 1 ,
245 .Xr sendmail 8 ,
246 etc.
247 .Pp
248 The office and phone number subfields are used by the
249 .Xr finger 1
250 program, and possibly other applications.
251 .Pp
252 The user's home directory is the full
253 .Ux
254 path name where the user
255 will be placed on login.
256 .Pp
257 The shell field is the command interpreter the user prefers.
258 If there is nothing in the
259 .Em shell
260 field, the Bourne shell
261 .Pq Pa /bin/sh
262 is assumed.
263 .Sh HESIOD SUPPORT
264 If
265 .Sq dns
266 is specified for the
267 .Sq passwd
268 database in
269 .Xr nsswitch.conf 5 ,
270 then
271 .Nm
272 lookups occur from the
273 .Sq passwd
274 Hesiod domain.
275 .Sh NIS SUPPORT
276 If
277 .Sq nis
278 is specified for the
279 .Sq passwd
280 database in
281 .Xr nsswitch.conf 5 ,
282 then
283 .Nm
284 lookups occur from the
285 .Sq passwd.byname ,
286 .Sq passwd.byuid ,
287 .Sq master.passwd.byname ,
288 and
289 .Sq master.passwd.byuid
290 .Tn NIS
291 maps.
292 .Sh COMPAT SUPPORT
293 If
294 .Sq compat
295 is specified for the
296 .Sq passwd
297 database, and either
298 .Sq dns
299 or
300 .Sq nis
301 is specified for the
302 .Sq passwd_compat
303 database in
304 .Xr nsswitch.conf 5 ,
305 then the
306 .Nm
307 file also supports standard
308 .Sq +/-
309 exclusions and inclusions, based on user names and netgroups.
310 .Pp
311 Lines beginning with a minus sign
312 .Pq Dq \&-
313 are entries marked as being excluded from any following inclusions,
314 which are marked with a plus sign
315 .Pq Dq \&+ .
316 .Pp
317 If the second character of the line is an at sign
318 .Pq Dq \&@ ,
319 the operation
320 involves the user fields of all entries in the netgroup specified by the
321 remaining characters of the
322 .Em name
323 field.
324 Otherwise, the remainder of the
325 .Em name
326 field is assumed to be a specific user name.
327 .Pp
328 The
329 .Dq \&+
330 token may also be alone in the
331 .Em name
332 field, which causes all users from either the Hesiod domain
333 .Nm
334 (with
335 .Sq passwd_compat: dns )
336 or
337 .Sq passwd.byname
338 and
339 .Sq passwd.byuid
340 .Tn NIS
341 maps (with
342 .Sq passwd_compat: nis )
343 to be included.
344 .Pp
345 If the entry contains non-empty
346 .Em uid
347 or
348 .Em gid
349 fields, the specified numbers will override the information retrieved
350 from the Hesiod domain or the
351 .Tn NIS
352 maps.
353 As well, if the
354 .Em gecos ,
355 .Em home_dir
356 or
357 .Em shell
358 entries contain text, it will override the information included via
359 Hesiod or
360 .Tn NIS .
361 On some systems, the
362 .Em passwd
363 field may also be overridden.
364 .Sh SEE ALSO
365 .Xr chpass 1 ,
366 .Xr login 1 ,
367 .Xr newgrp 1 ,
368 .Xr passwd 1 ,
369 .Xr pwhash 1 ,
370 .Xr getpwent 3 ,
371 .Xr login_getclass 3 ,
372 .Xr login.conf 5 ,
373 .Xr netgroup 5 ,
374 .Xr passwd.conf 5 ,
375 .Xr adduser 8 ,
376 .Xr pwd_mkdb 8 ,
377 .Xr vipw 8 ,
378 .Xr yp 8
379 .Pp
380 .%T "Managing NFS and NIS"
381 (O'Reilly \*[Am] Associates)
382 .Sh COMPATIBILITY
383 The password file format has changed since
384 .Bx 4.3 .
385 The following awk script can be used to convert your old-style password
386 file into a new style password file.
387 The additional fields
388 .Dq class ,
389 .Dq change
390 and
391 .Dq expire
392 are added, but are turned off by default.
393 To set them,
394 use the current day in seconds from the epoch + whatever number of seconds
395 of offset you want.
396 .Bd -literal -offset indent
397 BEGIN { FS = ":"}
398 { print $1 ":" $2 ":" $3 ":" $4 "::0:0:" $5 ":" $6 ":" $7 }
399 .Ed
400 .Sh HISTORY
401 A
402 .Nm
403 file format appeared in
404 .At v6 .
405 .Pp
406 The
407 .Tn NIS
408 .Nm
409 file format first appeared in SunOS.
410 .Pp
411 The Hesiod support first appeared in
412 .Nx 1.4 .
413 .Pp
414 The
415 .Xr login.conf 5
416 capability first appeared in
417 .Nx 1.5 .
418 .Sh BUGS
419 User information should (and eventually will) be stored elsewhere.
420 .Pp
421 Placing
422 .Sq compat
423 exclusions in the file after any inclusions will have
424 unexpected results.