]> git.cameronkatri.com Git - pw-darwin.git/blob - chpass/chpass.1
Sort cross references.
[pw-darwin.git] / chpass / chpass.1
1 .\" Copyright (c) 1988, 1990, 1993
2 .\" The Regents of the University of California. All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\" must display the following acknowledgement:
14 .\" This product includes software developed by the University of
15 .\" California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .\" @(#)chpass.1 8.2 (Berkeley) 12/30/93
33 .\"
34 .Dd December 30, 1993
35 .Dt CHPASS 1
36 .Os
37 .Sh NAME
38 .Nm chpass, chfn, chsh, ypchpass, ypchfn, ypchsh
39 .Nd add or change user database information
40 .Sh SYNOPSIS
41 chpass
42 .Op Fl a Ar list
43 .Op Fl p Ar encpass
44 .Op Fl s Ar newshell
45 .Op user
46 .Sh DESCRIPTION
47 The
48 .Nm chpass
49 program
50 allows editing of the user database information associated
51 with
52 .Ar user
53 or, by default, the current user.
54 The information is formatted and supplied to an editor for changes.
55 .Pp
56 Only the information that the user is allowed to change is displayed.
57 .Pp
58 The options are as follows:
59 .Bl -tag -width flag
60 .It Fl a
61 The super-user is allowed to directly supply a user database
62 entry, in the format specified by
63 .Xr passwd 5 ,
64 as an argument.
65 This argument must be a colon (``:'') separated list of all the
66 user database fields, although they may be empty.
67 .It Fl p
68 The super-user is allowed to directly supply an encrypted password field,
69 in the format used by
70 .Xr crypt 3 ,
71 as an argument.
72 .It Fl s
73 The
74 .Fl s
75 option attempts to change the user's shell to
76 .Ar newshell .
77 .El
78 .Pp
79 Possible display items are as follows:
80 .Pp
81 .Bl -tag -width "Home Directory:" -compact -offset indent
82 .It Login:
83 user's login name
84 .It Password:
85 user's encrypted password
86 .It Uid:
87 user's login
88 .It Gid:
89 user's login group
90 .It Change:
91 password change time
92 .It Expire:
93 account expiration time
94 .It Class:
95 user's general classification
96 .It Home Directory:
97 user's home directory
98 .It Shell:
99 user's login shell
100 .It Full Name:
101 user's real name
102 .It Location:
103 user's normal location
104 .It Home Phone:
105 user's home phone
106 .It Office Phone:
107 user's office phone
108 .El
109 .Pp
110 The
111 .Ar login
112 field is the user name used to access the computer account.
113 .Pp
114 The
115 .Ar password
116 field contains the encrypted form of the user's password.
117 .Pp
118 The
119 .Ar uid
120 field is the number associated with the
121 .Ar login
122 field.
123 Both of these fields should be unique across the system (and often
124 across a group of systems) as they 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. Routines
128 that manipulate these files will often return only one of the multiple
129 entries, and that one by random selection.
130 .Pp
131 The
132 .Ar group
133 field is the group that the user will be placed in at login.
134 Since BSD supports multiple groups (see
135 .Xr groups 1 )
136 this field currently has little special meaning.
137 This field may be filled in with either a number or a group name (see
138 .Xr group 5 ) .
139 .Pp
140 The
141 .Ar change
142 field is the date by which the password must be changed.
143 .Pp
144 The
145 .Ar expire
146 field is the date on which the account expires.
147 .Pp
148 Both the
149 .Ar change
150 and
151 .Ar expire
152 fields should be entered in the form ``month day year'' where
153 .Ar month
154 is the month name (the first three characters are sufficient),
155 .Ar day
156 is the day of the month, and
157 .Ar year
158 is the year.
159 .Pp
160 The
161 .Ar class
162 field is currently unused. In the near future it will be a key to
163 a
164 .Xr termcap 5
165 style database of user attributes.
166 .Pp
167 The user's
168 .Ar home directory
169 is the full UNIX path name where the user
170 will be placed at login.
171 .Pp
172 The
173 .Ar shell
174 field is the command interpreter the user prefers.
175 If the
176 .Ar shell
177 field is empty, the Bourne shell,
178 .Pa /bin/sh ,
179 is assumed.
180 When altering a login shell, and not the super-user, the user
181 may not change from a non-standard shell or to a non-standard
182 shell.
183 Non-standard is defined as a shell not found in
184 .Pa /etc/shells .
185 .Pp
186 The last four fields are for storing the user's
187 .Ar full name , office location ,
188 and
189 .Ar home
190 and
191 .Ar work telephone
192 numbers.
193 .Pp
194 Once the information has been verified,
195 .Nm chpass
196 uses
197 .Xr pwd_mkdb 8
198 to update the user database.
199 .Sh ENVIRONMENT
200 The
201 .Xr vi 1
202 editor will be used unless the environment variable EDITOR is set to
203 an alternate editor.
204 When the editor terminates, the information is re-read and used to
205 update the user database itself.
206 Only the user, or the super-user, may edit the information associated
207 with the user.
208 .Sh NIS INTERACTION
209 .Nm Chpass
210 can also be used in conjunction with NIS, however some restrictions
211 apply.
212 Currently,
213 .Nm chpass
214 can only make changes to the NIS passwd maps through
215 .Xr rpc.yppasswdd 8 ,
216 which normally only permits changes to a user's password, shell and GECOS
217 fields. Except when invoked by the super-user on the NIS master server,
218 .Nm chpass
219 (and, similarly,
220 .Xr passwd 1 )
221 can not use the
222 .Xr rpc.yppasswdd 8
223 server to change other user information or
224 add new records to the NIS passwd maps.
225 Furthermore,
226 .Xr rpc.yppasswdd 8
227 requires password authentication before it will make any
228 changes. The only user allowed to submit changes without supplying
229 a password is the super-user on the NIS master server; all other users,
230 including those with root privileges on NIS clients (and NIS slave
231 servers) must enter a password.
232 (The super-user on the NIS master is allowed to bypass these restrictions
233 largely for convenience: a user with root access
234 to the NIS master server already has the privileges required to make
235 updates to the NIS maps, but editing the map source files by hand can
236 be cumbersome.
237 .Pp
238 Note: these exceptions only apply when the NIS master server is a
239 FreeBSD system.)
240 .Pp
241 Consequently, except where noted, the following restrictions apply when
242 .Nm chpass
243 is used with NIS:
244 .Bl -enum -offset indent
245 .It
246 .Pa Only the shell and GECOS information may be changed.
247 All other
248 fields are restricted, even when
249 .Nm chpass
250 is invoked by the super-user.
251 While support for
252 changing other fields could be added, this would lead to
253 compatibility problems with other NIS-capable systems.
254 Even though the super-user may supply data for other fields
255 while editing an entry, the extra information (other than the
256 password -- see below) will be silently discarded.
257 .Pp
258 Exception: the super-user on the NIS master server is permitted to
259 change any field.
260 .Pp
261 .It
262 .Pa Password authentication is required.
263 .Nm Chpass
264 will prompt for the user's NIS password before effecting
265 any changes. If the password is invalid, all changes will be
266 discarded.
267 .Pp
268 Exception: the super-user on the NIS master server is allowed to
269 submit changes without supplying a password. (The super-user may
270 choose to turn off this feature using the
271 .Fl o
272 flag, described below.)
273 .It
274 .Pa Adding new records to the local
275 .Pa password database is discouraged.
276 .Nm Chpass
277 will allow the administrator to add new records to the
278 local password database while NIS is enabled, but this can lead to
279 some confusion since the new records are appended to the end of
280 the master password file, usually after the special NIS '+' entries.
281 The administrator should use
282 .Xr vipw 8
283 to modify the local password
284 file when NIS is running.
285 .Pp
286 The super-user on the NIS master server is permitted to add new records
287 to the NIS password maps, provided the
288 .Xr rpc.yppasswdd 8
289 server has been started with the
290 .Fl a
291 flag to permitted additions (it refuses them by default).
292 .Nm Chpass
293 tries to update the local password database by default; to update the
294 NIS maps instead, invoke chpass with the
295 .Fl y
296 flag.
297 .It
298 .Pa Password changes are not permitted.
299 Users should use
300 .Xr passwd 1
301 or
302 .Xr yppasswd 1
303 to change their NIS passwords. The super-user is allowed to specify
304 a new password (even though the ``Password:'' field does not show
305 up in the editor template, the super-user may add it back by hand),
306 but even the super-user must supply the user's original password
307 otherwise
308 .Xr rpc.yppasswdd 8
309 will refuse to update the NIS maps.
310 .Pp
311 Exception: the super-user on the NIS master server is permitted to
312 change a user's NIS password with
313 .Nm chpass .
314 .El
315 .Pp
316 There are also a few extra option flags that are available when
317 .Nm chpass
318 is compiled with NIS support:
319 .Bl -tag -width flag
320 .It Fl l
321 The
322 .Fl l
323 flag forces
324 .Nm chpass
325 to modify the local copy of a user's password
326 information in the even that a user exists in both
327 the local and NIS databases.
328 .It Fl y
329 This flag has the opposite effect of
330 .Fl l .
331 This flag is largely redundant since
332 .Nm chpass
333 operates on NIS entries by default if NIS is enabled.
334 .It Fl d Ar domain
335 Specify a particular NIS domain.
336 .Nm Chpass
337 uses the system domain name by default, as set by the
338 .Xr domainname 1
339 command. The
340 .Fl d
341 option can be used to override a default, or to specify a domain
342 when the system domain name is not set.
343 .It Fl h Ar host
344 Specify the name or address of an NIS server to query. Normally,
345 .Nm chpass
346 will communicate with the NIS master host specified in the
347 .Pa master.passwd
348 or
349 .Pa passwd
350 maps. On hosts that have not been configured as NIS clients, there is
351 no way for the program to determine this information unless the user
352 provides the hostname of a server. Note that the specified hostname need
353 not be that of the NIS master server; the name of any server, master or
354 slave, in a given NIS domain will do.
355 .Pp
356 When using the
357 .Fl d
358 option, the hostname defaults to ``localhost.'' The
359 .Fl h
360 option can be used in conjunction with the
361 .Fl d
362 option, in which case the user-specified hostname will override
363 the default.
364 .Pp
365 .It Fl o
366 Force the use of RPC-based updates when communicating with
367 .Xr rpc.yppasswdd 8
368 (``old-mode'').
369 When invoked by the super-user on the NIS master server,
370 .Nm chpass
371 allows unrestricted changes to the NIS passwd maps using dedicated,
372 non-RPC-based mechanism (in this case, a UNIX domain socket). The
373 .Fl o
374 flag can be used to force
375 .Nm chpass
376 to use the standard update mechanism instead. This option is provided
377 mainly for testing purposes.
378 .El
379 .Pp
380 .Sh FILES
381 .Bl -tag -width /etc/master.passwd -compact
382 .It Pa /etc/master.passwd
383 The user database
384 .It Pa /etc/passwd
385 A Version 7 format password file
386 .It Pa /etc/chpass.XXXXXX
387 Temporary copy of the password file
388 .It Pa /etc/shells
389 The list of approved shells
390 .El
391 .Sh SEE ALSO
392 .Xr finger 1 ,
393 .Xr login 1 ,
394 .Xr passwd 1 ,
395 .Xr getusershell 3 ,
396 .Xr passwd 5 ,
397 .Xr pwd_mkdb 8 ,
398 .Xr vipw 8
399 .Rs
400 .%A Robert Morris
401 and
402 .%A Ken Thompson
403 .%T "UNIX Password security"
404 .Re
405 .Sh NOTES
406 The
407 .Xr chfn 1 ,
408 .Xr chsh 1 ,
409 .Xr ypchpass 1 ,
410 .Xr ypchfn 1
411 and
412 .Xr ypchsh 1
413 commands are really only links to
414 .Nm chpass .
415 .Sh BUGS
416 User information should (and eventually will) be stored elsewhere.
417 .Sh HISTORY
418 The
419 .Nm
420 command appeared in
421 .Bx 4.3 Reno .