/usr.bin/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.\" 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.Pp
321.It
322.Em "Password authentication is required" .
323The
324.Nm
325utility will prompt for the user's NIS password before effecting
326any changes.
327If the password is invalid, all changes will be
328discarded.
329.Pp
330Exception: the super-user on the NIS master server is allowed to
331submit changes without supplying a password.
332(The super-user may
333choose to turn off this feature using the
334.Fl o
335flag, described below.)
336.It
337.Em "Adding new records to the local password database is discouraged" .
338The
339.Nm
340utility will allow the administrator to add new records to the
341local password database while NIS is enabled, but this can lead to
342some confusion since the new records are appended to the end of
343the master password file, usually after the special NIS '+' entries.
344The administrator should use
345.Xr vipw 8
346to modify the local password
347file when NIS is running.
348.Pp
349The super-user on the NIS master server is permitted to add new records
350to the NIS password maps, provided the
351.Xr rpc.yppasswdd 8
352server has been started with the
353.Fl a
354flag to permitted additions (it refuses them by default).
355The
356.Nm
357utility tries to update the local password database by default; to update the
358NIS maps instead, invoke chpass with the
359.Fl y
360flag.
361.It
362.Em "Password changes are not permitted".
363Users should use
364.Xr passwd 1
365or
366.Xr yppasswd 1
367to change their NIS passwords.
368The super-user is allowed to specify
369a new password (even though the
370.Dq Password:
371field does not show
372up in the editor template, the super-user may add it back by hand),
373but even the super-user must supply the user's original password
374otherwise
375.Xr rpc.yppasswdd 8
376will refuse to update the NIS maps.
377.Pp
378Exception: the super-user on the NIS master server is permitted to
379change a user's NIS password with
380.Nm .
381.El
382.Pp
383There are also a few extra option flags that are available when
384.Nm
385is compiled with NIS support:
386.Bl -tag -width indent
387.It Fl l
388Force
389.Nm
390to modify the local copy of a user's password
391information in the event that a user exists in both
392the local and NIS databases.
393.It Fl y
394Opposite effect of
395.Fl l .
396This flag is largely redundant since
397.Nm
398operates on NIS entries by default if NIS is enabled.
399.It Fl d Ar domain
400Specify a particular NIS domain.
401The
402.Nm
403utility uses the system domain name by default, as set by the
404.Xr domainname 1
405utility.
406The
407.Fl d
408option can be used to override a default, or to specify a domain
409when the system domain name is not set.
410.It Fl h Ar host
411Specify the name or address of an NIS server to query.
412Normally,
413.Nm
414will communicate with the NIS master host specified in the
415.Pa master.passwd
416or
417.Pa passwd
418maps.
419On hosts that have not been configured as NIS clients, there is
420no way for the program to determine this information unless the user
421provides the hostname of a server.
422Note that the specified hostname need
423not be that of the NIS master server; the name of any server, master or
424slave, in a given NIS domain will do.
425.Pp
426When using the
427.Fl d
428option, the hostname defaults to
429.Dq localhost .
430The
431.Fl h
432option can be used in conjunction with the
433.Fl d
434option, in which case the user-specified hostname will override
435the default.
436.Pp
437.It Fl o
438Force the use of RPC-based updates when communicating with
439.Xr rpc.yppasswdd 8
440.Pq Dq old-mode .
441When invoked by the super-user on the NIS master server,
442.Nm
443allows unrestricted changes to the NIS passwd maps using dedicated,
444non-RPC-based mechanism (in this case, a
445.Ux
446domain socket).
447The
448.Fl o
449flag can be used to force
450.Nm
451to use the standard update mechanism instead.
452This option is provided
453mainly for testing purposes.
454.El
455.Sh FILES
456.Bl -tag -width /etc/master.passwd -compact
457.It Pa /etc/master.passwd
458the user database
459.It Pa /etc/passwd
460a Version 7 format password file
461.It Pa /etc/chpass.XXXXXX
462temporary copy of the password file
463.It Pa /etc/shells
464the list of approved shells
465.El
466.Sh SEE ALSO
467.Xr finger 1 ,
468.Xr login 1 ,
469.Xr passwd 1 ,
470.Xr getusershell 3 ,
471.Xr login.conf 5 ,
472.Xr passwd 5 ,
473.Xr pw 8 ,
474.Xr pwd_mkdb 8 ,
475.Xr vipw 8
476.Rs
477.%A Robert Morris
478.%A Ken Thompson
479.%T "UNIX Password security"
480.Re
481.Sh HISTORY
482The
483.Nm
484utility appeared in
485.Bx 4.3 Reno .
486.Sh BUGS
487User information should (and eventually will) be stored elsewhere.