1 '\" te
   2 .\" Copyright 1989 AT&T Copyright (c) 2004, 2009, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH USERMOD 1M "Feb 22, 2008"
   7 .SH NAME
   8 usermod \- modify a user's login information on the system
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBusermod\fR [\fB-u\fR \fIuid\fR [\fB-o\fR]] [\fB-g\fR \fIgroup\fR] [\fB-G\fR \fIgroup\fR [, \fIgroup\fR...]]
  13      [\fB-d\fR \fIdir\fR [\fB-m\fR [\fB-z|-Z\fR]]] [\fB-s\fR \fIshell\fR] [\fB-c\fR \fIcomment\fR] [\fB-l\fR \fInew_name\fR]
  14      [\fB-f\fR \fIinactive\fR] [\fB-e\fR \fIexpire\fR]
  15      [\fB-A\fR \fIauthorization\fR [, \fIauthorization\fR]]
  16      [\fB-P\fR \fIprofile\fR [, \fIprofile\fR]] [\fB-R\fR \fIrole\fR [, \fIrole\fR]]
  17      [\fB-K\fR \fIkey=value\fR] \fIlogin\fR
  18 .fi
  19 
  20 .SH DESCRIPTION
  21 .LP
  22 The \fBusermod\fR utility modifies a user's login definition on the system. It
  23 changes the definition of the specified login and makes the appropriate
  24 login-related system file and file system changes.
  25 .sp
  26 .LP
  27 The system file entries created with this command have a limit of 512
  28 characters per line. Specifying long arguments to several options might exceed
  29 this limit.
  30 .SH OPTIONS
  31 .LP
  32 The following options are supported:
  33 .sp
  34 .ne 2
  35 .na
  36 \fB\fB-A\fR \fIauthorization\fR\fR
  37 .ad
  38 .sp .6
  39 .RS 4n
  40 One or more comma separated authorizations as defined in \fBauth_attr\fR(4).
  41 Only a user or role who has \fBgrant\fR rights to the \fBauthorization\fR can
  42 assign it to an account. This replaces any existing authorization setting. If
  43 no authorization list is specified, the existing setting is removed.
  44 .RE
  45 
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fB-c\fR \fIcomment\fR\fR
  50 .ad
  51 .sp .6
  52 .RS 4n
  53 Specify a comment string. \fIcomment\fR can be any text string. It is generally
  54 a short description of the login, and is currently used as the field for the
  55 user's full name. This information is stored in the user's \fB/etc/passwd\fR
  56 entry.
  57 .RE
  58 
  59 .sp
  60 .ne 2
  61 .na
  62 \fB\fB-d\fR \fIdir\fR\fR
  63 .ad
  64 .sp .6
  65 .RS 4n
  66 Specify the new home directory of the user. It defaults to
  67 \fIbase_dir/login\fR, where \fIbase_dir\fR is the base directory for new login
  68 home directories, and \fBlogin\fR is the new login.
  69 .RE
  70 
  71 .sp
  72 .ne 2
  73 .na
  74 \fB\fB-e\fR \fIexpire\fR\fR
  75 .ad
  76 .sp .6
  77 .RS 4n
  78 Specify the expiration date for a login. After this date, no user will be able
  79 to access this login. The expire option argument is a date entered using one of
  80 the date formats included in the template file \fB/etc/datemsk\fR. See
  81 \fBgetdate\fR(3C).
  82 .sp
  83 For example, you may enter \fB10/6/90\fR or \fBOctober 6, 1990\fR. A value of
  84 \fB`` ''\fR defeats the status of the expired date.
  85 .RE
  86 
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fB-f\fR \fIinactive\fR\fR
  91 .ad
  92 .sp .6
  93 .RS 4n
  94 Specify the maximum number of days allowed between uses of a login \fBID\fR
  95 before that login \fBID\fR is declared invalid. Normal values are positive
  96 integers. A value of \fB0\fR defeats the status.
  97 .RE
  98 
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fB-g\fR \fIgroup\fR\fR
 103 .ad
 104 .sp .6
 105 .RS 4n
 106 Specify an existing group's integer \fBID\fR or character-string name. It
 107 redefines the user's primary group membership.
 108 .RE
 109 
 110 .sp
 111 .ne 2
 112 .na
 113 \fB\fB-G\fR \fIgroup\fR\fR
 114 .ad
 115 .sp .6
 116 .RS 4n
 117 Specify an existing group's integer "ID" "," or character string name. It
 118 redefines the user's supplementary group membership. Duplicates between
 119 \fIgroup\fR with the \fB-g\fR and \fB-G\fR options are ignored. No more than
 120 \fBNGROUPS_UMAX\fR groups may be specified as defined in \fB<param.h>\fR\&.
 121 .RE
 122 
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fB-K\fR \fIkey=value\fR\fR
 127 .ad
 128 .sp .6
 129 .RS 4n
 130 Replace existing or add to a user's \fIkey=value\fR pair attributes. Multiple
 131 \fB-K\fR options can be used to replace or add multiple \fIkey=value\fR pairs.
 132 However, keys must not be repeated. The generic \fB-K\fR option with the
 133 appropriate key can be used instead of the specific implied key options
 134 (\fB-A\fR, \fB-P\fR, \fB-R\fR, \fB-p\fR). See \fBuser_attr\fR(4) for a list of
 135 valid \fIkey\fRs. Values for these keys are usually found in man pages or other
 136 sources related to those keys. For example, see \fBproject\fR(4) for guidance
 137 on values for the \fBproject\fR key. Use the command \fBppriv\fR(1) with the
 138 \fB-v\fR and \fB-l\fR options for a list of values for the keys
 139 \fBdefaultpriv\fR and \fBlimitpriv\fR.
 140 .sp
 141 The keyword \fBtype\fR can be specified with the value \fBrole\fR or the value
 142 \fBnormal\fR.  When using the value \fBrole\fR, the account changes from a
 143 normal user to a role; using the value \fBnormal\fR keeps the account a normal
 144 user.
 145 .sp
 146 As a \fBrole\fR account, no roles (\fB-R\fR or \fIroles=value\fR) can be
 147 present.
 148 .RE
 149 
 150 .sp
 151 .ne 2
 152 .na
 153 \fB\fB-l\fR \fInew_logname\fR\fR
 154 .ad
 155 .sp .6
 156 .RS 4n
 157 Specify the new login name for the user. See \fBpasswd\fR(4) for the
 158 requirements for usernames.
 159 .RE
 160 
 161 .sp
 162 .ne 2
 163 .na
 164 \fB\fB-m\fR\fR [\fB-z|-Z\fR]
 165 .ad
 166 .sp .6
 167 .RS 4n
 168 Move the user's home directory to the new directory specified with the \fB-d\fR
 169 option. If the directory already exists, it must have permissions
 170 read/write/execute by \fIgroup\fR, where \fIgroup\fR is the user's primary
 171 group.
 172 CHANGE_ZFS_FS option in /etc/default/useradd file determines if ZFS filesystem
 173 will be created or destroyed during this action. If this option is set to yes
 174 and parent directory of user's home directory is ZFS filesystem mount point, a
 175 new ZFS filesystem is created. If old user's home directory is a ZFS file system
 176 and CHANGE_ZFS_FS is set to yes, the filesystem will be destroyed.
 177 \fB-z\fB and \fB-Z\fR options allow overwrite default behavior. If \fB-z\fR
 178 option is specified, \fBusermod\fR tries to create new file system and destroy the
 179 old one. If \fB-Z\fR option is specified, new filesystem is not created and the old
 180 one is not destroyed.
 181 .RE
 182 
 183 .sp
 184 .ne 2
 185 .na
 186 \fB\fB-o\fR\fR
 187 .ad
 188 .sp .6
 189 .RS 4n
 190 This option allows the specified \fBUID\fR to be duplicated (non-unique).
 191 .RE
 192 
 193 .sp
 194 .ne 2
 195 .na
 196 \fB\fB-P\fR \fIprofile\fR\fR
 197 .ad
 198 .sp .6
 199 .RS 4n
 200 One or more comma-separated rights profiles defined in \fBprof_attr\fR(4). This
 201 replaces any existing profile setting in \fBuser_attr\fR(4). If an empty
 202 profile list is specified, the existing setting is removed.
 203 .RE
 204 
 205 .sp
 206 .ne 2
 207 .na
 208 \fB\fB-R\fR \fIrole\fR\fR
 209 .ad
 210 .sp .6
 211 .RS 4n
 212 One or more comma-separated roles (see \fBroleadd\fR(1M)). This replaces any
 213 existing role setting. If no role list is specified, the existing setting is
 214 removed.
 215 .RE
 216 
 217 .sp
 218 .ne 2
 219 .na
 220 \fB\fB-s\fR \fIshell\fR\fR
 221 .ad
 222 .sp .6
 223 .RS 4n
 224 Specify the full pathname of the program that is used as the user's shell on
 225 login. The value of \fIshell\fR must be a valid executable file.
 226 .RE
 227 
 228 .sp
 229 .ne 2
 230 .na
 231 \fB\fB-u\fR \fIuid\fR\fR
 232 .ad
 233 .sp .6
 234 .RS 4n
 235 Specify a new \fBUID\fR for the user. It must be a non-negative decimal integer
 236 less than \fBMAXUID\fR as defined in \fB<param.h>\fR\&. The \fBUID\fR
 237 associated with the user's home directory is not modified with this option; a
 238 user will not have access to their home directory until the \fBUID\fR is
 239 manually reassigned using \fBchown\fR(1).
 240 .RE
 241 
 242 .SH OPERANDS
 243 .LP
 244 The following operands are supported:
 245 .sp
 246 .ne 2
 247 .na
 248 \fB\fBlogin\fR\fR
 249 .ad
 250 .sp .6
 251 .RS 4n
 252 An existing login name to be modified.
 253 .RE
 254 
 255 .SH EXAMPLES
 256 .LP
 257 \fBExample 1 \fRAssigning Privileges to a User
 258 .sp
 259 .LP
 260 The following command adds the privilege that affects high resolution times to
 261 a user's initial, inheritable set of privileges.
 262 
 263 .sp
 264 .in +2
 265 .nf
 266 # \fBusermod -K defaultpriv=basic,proc_clock_highres jdoe\fR
 267 .fi
 268 .in -2
 269 .sp
 270 
 271 .sp
 272 .LP
 273 This command results in the following entry in \fBuser_attr\fR:
 274 
 275 .sp
 276 .in +2
 277 .nf
 278 jdoe::::type=normal;defaultpriv=basic,proc_clock_highres
 279 .fi
 280 .in -2
 281 
 282 .LP
 283 \fBExample 2 \fRRemoving a Privilege from a User's Limit Set
 284 .sp
 285 .LP
 286 The following command removes the privilege that allows the specified user to
 287 create hard links to directories and to unlink directories.
 288 
 289 .sp
 290 .in +2
 291 .nf
 292 # \fBusermod -K limitpriv=all,!sys_linkdir jdoe\fR
 293 .fi
 294 .in -2
 295 .sp
 296 
 297 .sp
 298 .LP
 299 This command results in the following entry in \fBuser_attr\fR:
 300 
 301 .sp
 302 .in +2
 303 .nf
 304 jdoe::::type=normal;defaultpriv=basic,limitpriv=all,!sys_linkdir
 305 .fi
 306 .in -2
 307 
 308 .LP
 309 \fBExample 3 \fRRemoving a Privilege from a User's Basic Set
 310 .sp
 311 .LP
 312 The following command removes the privilege that allows the specified user to
 313 examine processes outside the user's session.
 314 
 315 .sp
 316 .in +2
 317 .nf
 318 # \fBusermod -K defaultpriv=basic,!proc_session jdoe\fR
 319 .fi
 320 .in -2
 321 .sp
 322 
 323 .sp
 324 .LP
 325 This command results in the following entry in \fBuser_attr\fR:
 326 
 327 .sp
 328 .in +2
 329 .nf
 330 jdoe::::type=normal;defaultpriv=basic,!proc_session;limitpriv=all
 331 .fi
 332 .in -2
 333 
 334 .LP
 335 \fBExample 4 \fRAssigning a Role to a User
 336 .sp
 337 .LP
 338 The following command assigns a role to a user. The role must have been created
 339 prior to this command, either through use of the Solaris Management Console GUI
 340 or through \fBroleadd\fR(1M).
 341 
 342 .sp
 343 .in +2
 344 .nf
 345 # \fBusermod -R mailadm jdoe\fR
 346 .fi
 347 .in -2
 348 .sp
 349 
 350 .sp
 351 .LP
 352 This command results in the following entry in \fBuser_attr\fR:
 353 
 354 .sp
 355 .in +2
 356 .nf
 357 jdoe::::type=normal;roles=mailadm;defaultpriv=basic;limitpriv=all
 358 .fi
 359 .in -2
 360 
 361 .LP
 362 \fBExample 5 \fRRemoving All Profiles from a User
 363 .sp
 364 .LP
 365 The following command removes all profiles that were granted to a user
 366 directly. The user will still have any rights profiles that are granted by
 367 means of the \fBPROFS_GRANTED\fR key in \fBpolicy.conf\fR(4).
 368 
 369 .sp
 370 .in +2
 371 .nf
 372 # \fBusermod -P "" jdoe\fR
 373 .fi
 374 .in -2
 375 .sp
 376 
 377 .SH EXIT STATUS
 378 .LP
 379 In case of an error, \fBusermod\fR prints an error message and exits with one
 380 of the following values:
 381 .sp
 382 .ne 2
 383 .na
 384 \fB\fB2\fR\fR
 385 .ad
 386 .sp .6
 387 .RS 4n
 388 The command syntax was invalid. A usage message for the \fBusermod\fR command
 389 is displayed.
 390 .RE
 391 
 392 .sp
 393 .ne 2
 394 .na
 395 \fB\fB3\fR\fR
 396 .ad
 397 .sp .6
 398 .RS 4n
 399 An invalid argument was provided to an option.
 400 .RE
 401 
 402 .sp
 403 .ne 2
 404 .na
 405 \fB\fB4\fR\fR
 406 .ad
 407 .sp .6
 408 .RS 4n
 409 The \fIuid\fR given with the \fB-u\fR option is already in use.
 410 .RE
 411 
 412 .sp
 413 .ne 2
 414 .na
 415 \fB\fB5\fR\fR
 416 .ad
 417 .sp .6
 418 .RS 4n
 419 The password files contain an error. \fBpwconv\fR(1M) can be used to correct
 420 possible errors. See \fBpasswd\fR(4).
 421 .RE
 422 
 423 .sp
 424 .ne 2
 425 .na
 426 \fB\fB6\fR\fR
 427 .ad
 428 .sp .6
 429 .RS 4n
 430 The login to be modified does not exist, the \fIgroup\fR does not exist, or the
 431 login shell does not exist.
 432 .RE
 433 
 434 .sp
 435 .ne 2
 436 .na
 437 \fB\fB8\fR\fR
 438 .ad
 439 .sp .6
 440 .RS 4n
 441 The login to be modified is in use.
 442 .RE
 443 
 444 .sp
 445 .ne 2
 446 .na
 447 \fB\fB9\fR\fR
 448 .ad
 449 .sp .6
 450 .RS 4n
 451 The \fInew_logname\fR is already in use.
 452 .RE
 453 
 454 .sp
 455 .ne 2
 456 .na
 457 \fB\fB10\fR\fR
 458 .ad
 459 .sp .6
 460 .RS 4n
 461 Cannot update the \fB/etc/group\fR or \fB/etc/user_attr\fR file. Other update
 462 requests will be implemented.
 463 .RE
 464 
 465 .sp
 466 .ne 2
 467 .na
 468 \fB\fB11\fR\fR
 469 .ad
 470 .sp .6
 471 .RS 4n
 472 Insufficient space to move the home directory (\fB-m\fR option). Other update
 473 requests will be implemented.
 474 .RE
 475 
 476 .sp
 477 .ne 2
 478 .na
 479 \fB\fB12\fR\fR
 480 .ad
 481 .sp .6
 482 .RS 4n
 483 Unable to complete the move of the home directory to the new home directory.
 484 .RE
 485 
 486 .SH FILES
 487 .ne 2
 488 .na
 489 \fB\fB/etc/default/useradd\fR\fR
 490 .ad
 491 .sp .6
 492 .RS 4n
 493 useradd, usermod and userdel configuration file
 494 .RE
 495 
 496 .sp
 497 .ne 2
 498 .na
 499 \fB\fB/etc/group\fR\fR
 500 .ad
 501 .sp .6
 502 .RS 4n
 503 system file containing group definitions
 504 .RE
 505 
 506 .sp
 507 .ne 2
 508 .na
 509 \fB\fB/etc/datemsk\fR\fR
 510 .ad
 511 .sp .6
 512 .RS 4n
 513 system file of date formats
 514 .RE
 515 
 516 .sp
 517 .ne 2
 518 .na
 519 \fB\fB/etc/passwd\fR\fR
 520 .ad
 521 .sp .6
 522 .RS 4n
 523 system password file
 524 .RE
 525 
 526 .sp
 527 .ne 2
 528 .na
 529 \fB\fB/etc/shadow\fR\fR
 530 .ad
 531 .sp .6
 532 .RS 4n
 533 system file containing users' encrypted passwords and related information
 534 .RE
 535 
 536 .sp
 537 .ne 2
 538 .na
 539 \fB\fB/etc/user_attr\fR\fR
 540 .ad
 541 .sp .6
 542 .RS 4n
 543 system file containing additional user and role attributes
 544 .RE
 545 
 546 .SH ATTRIBUTES
 547 .LP
 548 See \fBattributes\fR(5) for descriptions of the following attributes:
 549 .sp
 550 
 551 .sp
 552 .TS
 553 box;
 554 c | c
 555 l | l .
 556 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 557 _
 558 Interface Stability     Committed
 559 .TE
 560 
 561 .SH SEE ALSO
 562 .LP
 563 \fBchown\fR(1), \fBpasswd\fR(1), \fBusers\fR(1B), \fBgroupadd\fR(1M),
 564 \fBgroupdel\fR(1M), \fBgroupmod\fR(1M), \fBlogins\fR(1M), \fBpwconv\fR(1M),
 565 \fBroleadd\fR(1M), \fBroledel\fR(1M), \fBrolemod\fR(1M), \fBuseradd\fR(1M),
 566 \fBuserdel\fR(1M), \fBgetdate\fR(3C), \fBauth_attr\fR(4), \fBpasswd\fR(4),
 567 \fBpolicy.conf\fR(4), \fBprof_attr\fR(4), \fBuser_attr\fR(4),
 568 \fBattributes\fR(5)
 569 .SH NOTES
 570 .LP
 571 The \fBusermod\fR utility modifies \fBpasswd\fR definitions only in the local
 572 \fB/etc/passwd\fR and \fB/etc/shadow\fR files. If a network nameservice such as
 573 \fBNIS\fR or \fBNIS+\fR is being used to supplement the local files with
 574 additional entries, \fBusermod\fR cannot change information supplied by the
 575 network nameservice. However \fBusermod\fR will verify the uniqueness of user
 576 name and user \fBID\fR against the external nameservice.
 577 .sp
 578 .LP
 579 The \fBusermod\fR utility uses the \fB/etc/datemsk\fR file, available with
 580 SUNWaccr, for date formatting.