Annotation of src/usr.bin/chpass/chpass.1, Revision 1.27
1.27 ! mpech 1: .\" $OpenBSD: chpass.1,v 1.26 2001/08/27 02:57:07 millert Exp $
1.2 deraadt 2: .\" $NetBSD: chpass.1,v 1.7 1996/05/15 21:50:40 jtc Exp $
1.1 deraadt 3: .\"
4: .\" Copyright (c) 1988, 1990, 1993
5: .\" The Regents of the University of California. 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. All advertising materials mentioning features or use of this software
16: .\" must display the following acknowledgement:
17: .\" This product includes software developed by the University of
18: .\" California, Berkeley and its contributors.
19: .\" 4. Neither the name of the University nor the names of its contributors
20: .\" may be used to endorse or promote products derived from this software
21: .\" without specific prior written permission.
22: .\"
23: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33: .\" SUCH DAMAGE.
34: .\"
35: .\" @(#)chpass.1 8.2 (Berkeley) 12/30/93
36: .\"
37: .Dd December 30, 1993
38: .Dt CHPASS 1
39: .Os
40: .Sh NAME
1.16 aaron 41: .Nm chpass ,
42: .Nm chfn ,
43: .Nm chsh
1.1 deraadt 44: .Nd add or change user database information
45: .Sh SYNOPSIS
46: .Nm chpass
1.13 niklas 47: .Op Fl ly
1.1 deraadt 48: .Op Fl a Ar list
49: .Op Fl s Ar newshell
1.9 aaron 50: .Op Ar user
1.1 deraadt 51: .Sh DESCRIPTION
1.16 aaron 52: .Nm chpass
1.1 deraadt 53: allows editing of the user database information associated
54: with
1.9 aaron 55: .Ar user ,
1.1 deraadt 56: or, by default, the current user.
57: The information is formatted and supplied to an editor for changes.
58: .Pp
59: Only the information that the user is allowed to change is displayed.
60: .Pp
1.24 millert 61: If YP is enabled change requests are first tried in the local database,
1.13 niklas 62: and then in the YP database, if there was no entry to change locally.
1.16 aaron 63: .Pp
64: .Nm chfn
65: and
66: .Nm chsh
67: are synonyms for
68: .Nm chpass .
1.13 niklas 69: .Pp
1.1 deraadt 70: The options are as follows:
71: .Bl -tag -width Ds
1.6 deraadt 72: .It Fl a Ar list
1.18 aaron 73: The superuser is allowed to directly supply a user database
1.1 deraadt 74: entry, in the format specified by
75: .Xr passwd 5 ,
76: as an argument.
1.9 aaron 77: This argument must be a colon
78: .Pq Sq \&:
79: separated list of all the
1.1 deraadt 80: user database fields, although they may be empty.
1.19 aaron 81: This operation is not supported in YP environments; only local additions
82: can be performed which requires the
1.13 niklas 83: .Fl l
1.19 aaron 84: flag to be specified.
1.13 niklas 85: .It Fl l
86: In environments where YP is enabled, always alter local information as
87: opposed to information in YP.
1.6 deraadt 88: .It Fl s Ar newshell
1.9 aaron 89: Attempts to change the user's shell to
1.1 deraadt 90: .Ar newshell .
1.13 niklas 91: .It Fl y
92: In environments where YP is enabled, always change the YP entry, even if this
93: is a modification request and there is a local entry for the specified user.
1.1 deraadt 94: .El
95: .Pp
96: Possible display items are as follows:
97: .Pp
1.14 aaron 98: .Bl -tag -width "Office Location:" -compact -offset indent
1.1 deraadt 99: .It Login:
100: user's login name
101: .It Password:
102: user's encrypted password
103: .It Uid:
104: user's login
105: .It Gid:
106: user's login group
107: .It Change:
108: password change time
109: .It Expire:
110: account expiration time
111: .It Class:
112: user's general classification
113: .It Home Directory:
114: user's home directory
115: .It Shell:
116: user's login shell
117: .It Full Name:
118: user's real name
1.14 aaron 119: .It Office Location:
120: user's office location
121: .It Office Phone:
122: user's office phone
1.1 deraadt 123: .It Home Phone:
124: user's home phone
125: .El
126: .Pp
127: The
128: .Ar login
129: field is the user name used to access the computer account.
130: .Pp
131: The
132: .Ar password
133: field contains the encrypted form of the user's password.
134: .Pp
135: The
136: .Ar uid
137: field is the number associated with the
138: .Ar login
139: field.
140: Both of these fields should be unique across the system (and often
141: across a group of systems) as they control file access.
142: .Pp
143: While it is possible to have multiple entries with identical login names
1.17 aaron 144: and/or identical user IDs, it is usually a mistake to do so.
145: Routines that manipulate these files will often return only one of the multiple
1.1 deraadt 146: entries, and that one by random selection.
147: .Pp
148: The
149: .Ar group
150: field is the group that the user will be placed in at login.
151: Since BSD supports multiple groups (see
1.25 mpech 152: .Xr groups 1 ) ,
1.1 deraadt 153: this field currently has little special meaning.
154: This field may be filled in with either a number or a group name (see
155: .Xr group 5 ) .
156: .Pp
157: The
158: .Ar change
159: field is the date by which the password must be changed.
160: .Pp
161: The
162: .Ar expire
163: field is the date on which the account expires.
164: .Pp
165: Both the
166: .Ar change
167: and
168: .Ar expire
169: fields should be entered in the form ``month day year'' where
170: .Ar month
171: is the month name (the first three characters are sufficient),
172: .Ar day
173: is the day of the month, and
174: .Ar year
175: is the year.
176: .Pp
177: The
178: .Ar class
1.24 millert 179: field specifies a key in the
180: .Xr login.conf 5
181: database of login class attributes.
182: If empty, the
183: .Dq default
184: record is used.
1.1 deraadt 185: .Pp
186: The user's
187: .Ar home directory
188: is the full UNIX path name where the user
189: will be placed at login.
190: .Pp
191: The
192: .Ar shell
193: field is the command interpreter the user prefers.
194: If the
195: .Ar shell
1.9 aaron 196: field is empty, the Bourne shell
197: .Pq Pa /bin/sh
1.1 deraadt 198: is assumed.
1.18 aaron 199: When altering a login shell, and not the superuser, the user
1.1 deraadt 200: may not change from a non-standard shell or to a non-standard
201: shell.
202: Non-standard is defined as a shell not found in
203: .Pa /etc/shells .
204: .Pp
205: The last four fields are for storing the user's
206: .Ar full name , office location ,
207: and
1.8 deraadt 208: .Ar work
1.1 deraadt 209: and
1.8 deraadt 210: .Ar home telephone
1.1 deraadt 211: numbers.
212: .Pp
213: Once the information has been verified,
1.12 aaron 214: .Nm
1.1 deraadt 215: uses
216: .Xr pwd_mkdb 8
217: to update the user database.
1.20 aaron 218: .Sh DIAGNOSTICS
219: .Bl -diag
1.26 millert 220: .It "Attempting lock password file, please wait or press ^C to abort"
221: .Pp
222: The password file is currently locked by another process;
223: .Nm
224: will keep trying to lock the password file until it succeeds or
225: the user hits the interupt character (control-C by default).
226: If
227: .Nm
228: is interrupted while trying to gain the lock any changes made will be lost.
229: .Pp
230: If the process holding the lock was prematurely terminated the lock
231: file may be stale and
232: .Nm
233: will wait forever trying to lock the password file.
234: To determine whether a live process is actually holding the lock, the
1.23 millert 235: admin may run the following:
236: .Bd -literal -offset indent
1.27 ! mpech 237: $ fstat /etc/ptmp
1.23 millert 238: .Ed
239: .Pp
240: If no process is listed, it is safe to remove the
1.20 aaron 241: .Pa /etc/ptmp
1.26 millert 242: file to clear the error.
1.20 aaron 243: .El
1.1 deraadt 244: .Sh ENVIRONMENT
245: The
246: .Xr vi 1
1.5 deraadt 247: editor will be used unless the environment variable
248: .Ev EDITOR
249: is set to
1.1 deraadt 250: an alternate editor.
251: When the editor terminates, the information is re-read and used to
252: update the user database itself.
1.18 aaron 253: Only the user, or the superuser, may edit the information associated
1.1 deraadt 254: with the user.
255: .Sh FILES
1.9 aaron 256: .Bl -tag -width /var/tmp/pw.XXXXXXXX -compact
1.1 deraadt 257: .It Pa /etc/master.passwd
1.9 aaron 258: user database
1.1 deraadt 259: .It Pa /etc/passwd
1.9 aaron 260: a Version 7 format password file
1.2 deraadt 261: .It Pa /etc/ptmp
1.9 aaron 262: lock file for the passwd database
1.20 aaron 263: .It Pa /etc/shells
264: list of approved shells
1.7 millert 265: .It Pa /var/tmp/pw.XXXXXXXX
1.9 aaron 266: temporary copy of the user passwd information
1.1 deraadt 267: .El
268: .Sh SEE ALSO
1.10 alex 269: .Xr finger 1 ,
1.1 deraadt 270: .Xr login 1 ,
271: .Xr passwd 1 ,
272: .Xr getusershell 3 ,
1.24 millert 273: .Xr login.conf 5 ,
1.1 deraadt 274: .Xr passwd 5 ,
275: .Xr pwd_mkdb 8 ,
276: .Xr vipw 8
277: .Rs
1.22 deraadt 278: .%A Robert Morris
279: .%A Ken Thompson
1.4 gene 280: .%T "UNIX Password Security"
1.1 deraadt 281: .Re
282: .Sh HISTORY
283: The
284: .Nm
1.11 aaron 285: command appeared in
1.1 deraadt 286: .Bx 4.3 Reno .
1.15 aaron 287: .Sh BUGS
288: User information should (and eventually will) be stored elsewhere.