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