Annotation of src/usr.bin/chpass/chpass.1, Revision 1.42
1.42 ! schwarze 1: .\" $OpenBSD: chpass.1,v 1.41 2015/11/26 19:01:47 deraadt 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: .\"
1.42 ! schwarze 33: .Dd $Mdocdate: November 26 2015 $
1.1 deraadt 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
43: .Op Fl s Ar newshell
1.9 aaron 44: .Op Ar user
1.33 jmc 45: .Nm chpass
46: .Fl a Ar list
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.16 aaron 57: .Nm chfn
58: and
59: .Nm chsh
60: are synonyms for
61: .Nm chpass .
1.13 niklas 62: .Pp
1.1 deraadt 63: The options are as follows:
64: .Bl -tag -width Ds
1.6 deraadt 65: .It Fl a Ar list
1.18 aaron 66: The superuser is allowed to directly supply a user database
1.1 deraadt 67: entry, in the format specified by
68: .Xr passwd 5 ,
69: as an argument.
1.9 aaron 70: This argument must be a colon
71: .Pq Sq \&:
72: separated list of all the
1.1 deraadt 73: user database fields, although they may be empty.
1.6 deraadt 74: .It Fl s Ar newshell
1.9 aaron 75: Attempts to change the user's shell to
1.1 deraadt 76: .Ar newshell .
77: .El
78: .Pp
79: Possible display items are as follows:
80: .Pp
1.14 aaron 81: .Bl -tag -width "Office Location:" -compact -offset indent
1.1 deraadt 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
1.14 aaron 102: .It Office Location:
103: user's office location
104: .It Office Phone:
105: user's office phone
1.1 deraadt 106: .It Home Phone:
107: user's home 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
1.17 aaron 127: and/or identical user IDs, it is usually a mistake to do so.
128: Routines that manipulate these files will often return only one of the multiple
1.1 deraadt 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.
1.38 jmc 134: Since
135: .Bx
136: supports multiple groups (see
1.25 mpech 137: .Xr groups 1 ) ,
1.1 deraadt 138: this field currently has little special meaning.
139: This field may be filled in with either a number or a group name (see
140: .Xr group 5 ) .
141: .Pp
142: The
143: .Ar change
144: field is the date by which the password must be changed.
145: .Pp
146: The
147: .Ar expire
148: field is the date on which the account expires.
149: .Pp
150: Both the
151: .Ar change
152: and
153: .Ar expire
1.40 bentley 154: fields should be entered in the form
155: .Ar month day year
156: where
1.1 deraadt 157: .Ar month
158: is the month name (the first three characters are sufficient),
159: .Ar day
160: is the day of the month, and
161: .Ar year
162: is the year.
163: .Pp
164: The
165: .Ar class
1.24 millert 166: field specifies a key in the
167: .Xr login.conf 5
168: database of login class attributes.
169: If empty, the
170: .Dq default
1.29 jmc 171: record is used.
1.1 deraadt 172: .Pp
173: The user's
174: .Ar home directory
1.35 sobrado 175: is the full
176: .Ux
177: path name where the user will be placed at login.
1.1 deraadt 178: .Pp
179: The
180: .Ar shell
181: field is the command interpreter the user prefers.
182: If the
183: .Ar shell
1.9 aaron 184: field is empty, the Bourne shell
185: .Pq Pa /bin/sh
1.1 deraadt 186: is assumed.
1.18 aaron 187: When altering a login shell, and not the superuser, the user
1.1 deraadt 188: may not change from a non-standard shell or to a non-standard
189: shell.
190: Non-standard is defined as a shell not found in
191: .Pa /etc/shells .
192: .Pp
193: The last four fields are for storing the user's
194: .Ar full name , office location ,
195: and
1.8 deraadt 196: .Ar work
1.1 deraadt 197: and
1.8 deraadt 198: .Ar home telephone
1.1 deraadt 199: numbers.
200: .Pp
201: Once the information has been verified,
1.12 aaron 202: .Nm
1.1 deraadt 203: uses
204: .Xr pwd_mkdb 8
205: to update the user database.
1.29 jmc 206: .Sh ENVIRONMENT
207: The
208: .Xr vi 1
209: editor will be used unless the environment variable
210: .Ev EDITOR
211: is set to
212: an alternate editor.
213: When the editor terminates, the information is re-read and used to
214: update the user database itself.
215: Only the user, or the superuser, may edit the information associated
216: with the user.
217: .Sh FILES
1.30 avsm 218: .Bl -tag -width /var/tmp/pw.XXXXXXXXXX -compact
1.29 jmc 219: .It Pa /etc/master.passwd
220: user database
221: .It Pa /etc/passwd
1.36 jmc 222: user database, with confidential information removed
1.29 jmc 223: .It Pa /etc/ptmp
224: lock file for the passwd database
225: .It Pa /etc/shells
226: list of approved shells
1.31 avsm 227: .It Pa /var/tmp/pw.XXXXXXXXXX
1.29 jmc 228: temporary copy of the user passwd information
229: .El
1.20 aaron 230: .Sh DIAGNOSTICS
231: .Bl -diag
1.37 schwarze 232: .It "Attempting to lock password file, please wait or press ^C to abort"
1.26 millert 233: .Pp
234: The password file is currently locked by another process;
235: .Nm
236: will keep trying to lock the password file until it succeeds or
1.32 jmc 237: the user hits the interrupt character (control-C by default).
1.26 millert 238: If
239: .Nm
240: is interrupted while trying to gain the lock any changes made will be lost.
241: .Pp
242: If the process holding the lock was prematurely terminated the lock
243: file may be stale and
244: .Nm
245: will wait forever trying to lock the password file.
246: To determine whether a live process is actually holding the lock, the
1.23 millert 247: admin may run the following:
248: .Bd -literal -offset indent
1.27 mpech 249: $ fstat /etc/ptmp
1.23 millert 250: .Ed
251: .Pp
252: If no process is listed, it is safe to remove the
1.20 aaron 253: .Pa /etc/ptmp
1.26 millert 254: file to clear the error.
1.1 deraadt 255: .El
256: .Sh SEE ALSO
1.10 alex 257: .Xr finger 1 ,
1.1 deraadt 258: .Xr login 1 ,
259: .Xr passwd 1 ,
260: .Xr getusershell 3 ,
1.24 millert 261: .Xr login.conf 5 ,
1.1 deraadt 262: .Xr passwd 5 ,
263: .Xr pwd_mkdb 8 ,
264: .Xr vipw 8
265: .Rs
1.22 deraadt 266: .%A Robert Morris
267: .%A Ken Thompson
1.39 schwarze 268: .%T Password security: a case history
269: .%J Communications of the ACM
270: .%V Volume 22
271: .%N Issue 11
272: .%D Nov. 1979
1.42 ! schwarze 273: .%P pp. 594\(en597
1.1 deraadt 274: .Re
275: .Sh HISTORY
276: The
277: .Nm
1.11 aaron 278: command appeared in
1.1 deraadt 279: .Bx 4.3 Reno .