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