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