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