'\" te
.\" Copyright 1989 AT&T All Rights Reserved
.\" Portions Copyright (c) 2004, 2016, Oracle and/or its affiliates. All
.\"                 rights reserved.
.TH usermod 1M "18 Feb 2016" "SunOS 5.11" "System Administration Commands"
.SH NAME
usermod \- modify a user's login information on the system
.SH SYNOPSIS
.LP
.nf
\fBusermod\fR [\fB-u\fR \fIuid\fR [\fB-o\fR]] [\fB-g\fR \fIgroup\fR] [\fB-G\fR [+|-]\fIgroup\fR [, \fIgroup\fR...]] 

     [\fB-d\fR \fIdir\fR [\fB-m\fR]] [\fB-s\fR \fIshell\fR] [\fB-c\fR \fIcomment\fR] [\fB-l\fR \fInew_name\fR]

     [\fB-f\fR \fIinactive\fR] [\fB-e\fR \fIexpire\fR] [\fB-p\fR] \fIproject\fR, \fIproject\fR

     [\fB-A\fR [+|-]\fIauthorization\fR [,\fIauthorization\fR]] 

     [\fB-P\fR [+|-]\fIprofile\fR [,\fIprofile\fR]] [\fB-R\fR [+|-]\fIrole\fR [,\fIrole\fR]] 

     [\fB-K\fR \fIkey\fR[+|-]=\fIvalue\fR] [\fB-S\fR \fIrepository\fR] \fB[-q \fIqualifier\fR]\fR \fIlogin\fR
.fi

.LP
.nf
usermod -S ldap -K key[+|-]=value [-q qualifier] default@
.fi

.SH DESCRIPTION
.sp
.LP
The \fBusermod\fR utility modifies a user's login definition on the system. It changes the definition of the specified login and makes the appropriate login-related system file and file system changes.
.sp
.LP
For accounts that are created using \fB-S\fR \fBldap\fR, the default values for any of the \fB-K\fR attributes may be specified by using \fB-S\fR \fBldap\fR and the special value \fBdefault@\fR as the login name.
.sp
.LP
The system file entries created with this command have a limit of 512 characters per line. Specifying long arguments to several options might exceed this limit.
.sp
.LP
For users not present in the local files repository, by specifying \fB-S\fR option, files will create/modify a local files entry for the user. 
.sp
.LP
An administrator must be granted the User Security Profile to modify the security attributes for an existing user. To be able to modify the non-security attributes of an existing user requires the User Management Profile. The authorizations required to set the various fields in \fBpasswd\fR, \fBshadow\fR and \fBuser_attr\fR can be found in \fBpasswd\fR(4), \fBshadow\fR(4), and \fBuser_attr\fR(4). The authorizations required to assign groups can be found in \fBgroup\fR(4).
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.mk
.na
\fB\fB-A\fR [+|-]\fIauthorization\fR\fR
.ad
.sp .6
.RS 4n
One or more comma separated authorizations as defined in \fBauth_attr\fR(4). Only a user or role who has \fBgrant\fR rights to the \fBauthorization\fR can assign it to an account. This replaces any existing authorization setting. If no authorization list is specified, the existing setting is removed.
.sp
A prefix \fB+\fR adds the authorization to the existing authorization; a prefix \fB-\fR removes the authorization from the existing authorization. With no prefix, \fIauthorization\fR replaces the existing authorization.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-c\fR \fIcomment\fR\fR
.ad
.sp .6
.RS 4n
Specify a comment string. \fIcomment\fR can be any text string. It is generally a short description of the login, and is currently used as the field for the user's full name. This information is stored in the user's \fBpasswd\fR entry.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-d\fR \fIdir\fR\fR
.ad
.sp .6
.RS 4n
Specify the new home directory of the user. It defaults to \fIbase_dir/login\fR, where \fIbase_dir\fR is the base directory for new login home directories, and \fBlogin\fR is the new login. This creates or modifies an \fBauto_home\fR entry for the user.
.sp
The argument to the option can be specified as \fIserver\fR:\fIdir\fR where \fIserver\fR is the hostname of the machine on which the home directory resides and \fIdir\fR is the path to the user's home directory. If the server is a remote host then the home directory needs to be created on the remote host for the system to mount it, when the user logs in. If no server name is specified then the home directory will be created on the host where the command is executed, when the \fB-m\fR option is used.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-e\fR \fIexpire\fR\fR
.ad
.sp .6
.RS 4n
Specify the expiration date for a login. After this date, no user will be able to access this login. The expire option argument is a date entered using one of the date formats included in the template file \fB/etc/datemsk\fR. See \fBgetdate\fR(3C).
.sp
For example, you may enter \fB10/6/90\fR or \fBOctober 6, 1990\fR. A value of \fB`` ''\fR defeats the status of the expired date.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-f\fR \fIinactive\fR\fR
.ad
.sp .6
.RS 4n
Specify the maximum number of days allowed between uses of a login \fBID\fR before that login \fBID\fR is declared invalid. Normal values are positive integers. A value of \fB0\fR defeats the status.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-g\fR \fIgroup\fR\fR
.ad
.sp .6
.RS 4n
Specify an existing group's integer \fBID\fR or character-string name. It redefines the user's primary group membership.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-G\fR [+|-]\fIgroup\fR\fR
.ad
.sp .6
.RS 4n
An existing group's integer ID or character-string name. It defines the new user's supplementary group membership. Duplicates between group with the \fB-g\fR and \fB-G\fR options are ignored. No more than \fBNGROUPS_MAX\fR groups can be specified. GIDs 0-99 are reserved for allocation by the Solaris Operating System.
.sp
A prefix \fB+\fR adds the group to the existing group; a prefix \fB-\fR removes the group from the existing group. With no prefix, \fIgroup\fR replaces the existing group.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-K\fR \fIkey\fR[+|-]=\fIvalue\fR\fR
.ad
.sp .6
.RS 4n
Replace existing or add to a user's \fIkey=value\fR pair attributes. Multiple \fB-K\fR options can be used to replace or add multiple \fIkey=value\fR pairs. However, keys must not be repeated. The generic \fB-K\fR option with the appropriate key can be used instead of the specific implied key options (\fB-A\fR, \fB-P\fR, \fB-R\fR, \fB-p\fR). See \fBuser_attr\fR(4) for a list of valid \fIkey\fRs. Values for these keys are usually found in man pages or other sources related to those keys. For example, see \fBproject\fR(4) for guidance on values for the \fBproject\fR key. Use the command \fBppriv\fR(1) with the \fB-v\fR and \fB-l\fR options for a list of values for the keys \fBdefaultpriv\fR and \fBlimitpriv\fR. If no value is specified, the existing key is removed.
.sp
The keyword \fBtype\fR can be specified with the value \fBrole\fR or the value \fBnormal\fR. When using the value \fBrole\fR, the account changes from a normal user to a role; using the value \fBnormal\fR keeps the account a normal user.
.sp
As a \fBrole\fR account, no roles (\fB-R\fR or \fIroles=value\fR) can be present.
.sp
A prefix \fB+\fR adds the value to the existing value; a prefix \fB-\fR removes the value from the existing value. With no prefix, \fIvalue\fR replaces the existing value.
.sp
The prefix \fB+\fR/\fB-\fR operation is applicable only to the following keys: \fBauths\fR, \fBprofiles\fR, \fBauth_profiles\fR, \fBroles\fR, \fBproject\fR, \fBlimitpriv\fR, \fBdefaultpriv\fR, \fBauth_profiles\fR, and \fBaccess_times\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-l\fR \fInew_logname\fR\fR
.ad
.sp .6
.RS 4n
Specify the new login name for the user. See \fBpasswd\fR(4) for the requirements for usernames.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-m\fR\fR
.ad
.sp .6
.RS 4n
Move the user's home directory to the new directory specified with the \fB-d\fR option. If the directory already exists, it must have permissions read/write/execute by \fIgroup\fR, where \fIgroup\fR is the user's primary group. If the server name specified to the \fB-d\fR option is a remote host then the system will not attempt to create the home directory.
.sp
If the directory does not already exist, a new ZFS dataset will be created. In the global zone, the dataset is created as \fBrpool/export/home/\fR\fIrolename\fR. For non-global zones, the dataset will be created as \fIROOT-dataset\fR\fB/export/home/\fR\fIrolename\fR. The mountpoint for the ZFS dataset is \fB/export/home/\fR\fIrolename\fR by default. If \fB-d\fR \fIpath\fR is specified and it is a path on the local machine, the dataset will be mounted at the specified location. The role is delegated permissions to create ZFS snapshots and promote them. The newly created dataset will inherit the encryption setting from its parent. If it is encrypted, the role is granted permission to change its wrapping key.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-o\fR\fR
.ad
.sp .6
.RS 4n
This option allows the specified \fBUID\fR to be duplicated (non-unique).
.RE

.sp
.ne 2
.mk
.na
\fB\fB-p\fR\fR
.ad
.sp .6
.RS 4n
An existing projects integer ID or character-string name. It defines the user's supplementary project membership.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-P\fR [+|-]\fIprofile\fR\fR
.ad
.sp .6
.RS 4n
One or more comma-separated rights profiles defined in \fBprof_attr\fR(4). This replaces any existing profile setting in \fBuser_attr\fR(4). If an empty profile list is specified, the existing setting is removed.
.sp
A prefix \fB+\fR adds the profile to the existing profile; a prefix \fB-\fR removes the profile from the existing profile. With no prefix, \fIprofile\fR replaces the existing profile.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-q\fR \fIqualifier\fR\fR
.ad
.sp .6
.RS 4n
The name of a host or netgroup which qualifies where the extended attributes (specified through -K, -P, -A, and + -R) are applicable. The prefix @ is required to indicate that the qualifier is a netgroup name. The \fB-q\fR option is only valid if the user account is maintained in the LDAP name service.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-R\fR [+|-]\fIrole\fR\fR
.ad
.sp .6
.RS 4n
One or more comma-separated roles (see \fBroleadd\fR(1M)). This replaces any existing role setting. If no role list is specified, the existing setting is removed.
.sp
A prefix \fB+\fR adds the role to the existing role; a prefix \fB-\fR removes the role from the existing role. With no prefix, \fIrole\fR replaces the existing role.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-s\fR \fIshell\fR\fR
.ad
.sp .6
.RS 4n
Specify the full pathname of the program that is used as the user's shell on login. The value of \fIshell\fR must be a valid executable file.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-S\fR \fIrepository\fR\fR
.ad
.sp .6
.RS 4n
The valid repositories are \fBfiles\fR, \fBldap\fR. The repository specifies which name service will be updated. The default repository is \fBfiles\fR. When the repository is \fBfiles\fR, the authorizations, profiles, and roles can be present in other name service repositories and can be assigned to a user in the \fBfiles\fR repository. When the repository is \fBldap\fR, all the assignable attributes must be present in the \fBldap\fR repository.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-u\fR \fIuid\fR\fR
.ad
.sp .6
.RS 4n
Specify a new \fBUID\fR for the user. It must be a non-negative decimal integer less than \fBMAXUID\fR as defined in \fB<param.h>\fR\&.
.RE

.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.mk
.na
\fB\fBlogin\fR\fR
.ad
.sp .6
.RS 4n
An existing login name to be modified.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRAssigning Privileges to a User
.sp
.LP
The following command adds the privilege that affects high resolution times to a user's initial, inheritable set of privileges.

.sp
.in +2
.nf
# \fBusermod -K defaultpriv=basic,proc_clock_highres jdoe\fR
.fi
.in -2
.sp

.sp
.LP
This command results in the following entry in \fBuser_attr\fR:

.sp
.in +2
.nf
jdoe::::type=normal;defaultpriv=basic,proc_clock_highres
.fi
.in -2

.LP
\fBExample 2 \fRRemoving a Privilege from a User's Limit Set
.sp
.LP
The following command removes the privilege that allows the specified user to create hard links to directories and to unlink directories.

.sp
.in +2
.nf
# \fBusermod -K limitpriv=all,!sys_linkdir jdoe\fR
.fi
.in -2
.sp

.sp
.LP
This command results in the following entry in \fBuser_attr\fR:

.sp
.in +2
.nf
jdoe::::type=normal;defaultpriv=basic,limitpriv=all,!sys_linkdir
.fi
.in -2

.LP
\fBExample 3 \fRRemoving a Privilege from a User's Basic Set
.sp
.LP
The following command removes the privilege that allows the specified user to examine processes outside the user's session.

.sp
.in +2
.nf
# \fBusermod -K defaultpriv=basic,!proc_session jdoe\fR
.fi
.in -2
.sp

.sp
.LP
This command results in the following entry in \fBuser_attr\fR:

.sp
.in +2
.nf
jdoe::::type=normal;defaultpriv=basic,!proc_session;limitpriv=all
.fi
.in -2

.LP
\fBExample 4 \fRAssigning a Role to a User
.sp
.LP
The following command assigns a role to a user. The role must have been created prior to this command through use of \fBroleadd\fR(1M).

.sp
.in +2
.nf
# \fBusermod -R mailadm jdoe\fR
.fi
.in -2
.sp

.sp
.LP
This command results in the following entry in \fBuser_attr\fR:

.sp
.in +2
.nf
jdoe::::type=normal;roles=mailadm;defaultpriv=basic;limitpriv=all
.fi
.in -2

.LP
\fBExample 5 \fRGranting an Authorization Role to a User
.sp
.LP
The following command grants the \fBsolaris.zone.manage\fR authorization, Project Management rights profile, sets limit privilege to basic and assigns the \fBmailadm\fR role to the user.

.sp
.in +2
.nf
# \fBusermod -A 'solaris.zone.manage' -P 'Project Management' -K limitpriv=basic

 -R mailadm -S files jdoe_ldap\fR
.fi
.in -2
.sp

.sp
.LP
This command results in the following entry in \fBuser_attr\fR:

.sp
.in +2
.nf
jdoe_ldap::::auths=solaris.zone.manage;profiles=ProjectManagement;limitpriv=basic;

roles=mailadm
.fi
.in -2

.LP
\fBExample 6 \fRRemoving All Profiles from a User
.sp
.LP
The following command removes all profiles that were granted to a user directly. The user will still have any rights profiles that are granted by means of the \fBPROFS_GRANTED\fR key in \fBpolicy.conf\fR(4).

.sp
.in +2
.nf
# \fBusermod -P "" jdoe\fR
.fi
.in -2
.sp

.SH EXIT STATUS
.sp
.LP
In case of an error, \fBusermod\fR prints an error message and exits with one of the following values:
.sp
.ne 2
.mk
.na
\fB\fB1\fR\fR
.ad
.RS 6n
.rt  
No permission for attempted operation.
.RE

.sp
.ne 2
.mk
.na
\fB\fB2\fR\fR
.ad
.RS 6n
.rt  
The command syntax was invalid. A usage message for the \fBusermod\fR command is displayed.
.RE

.sp
.ne 2
.mk
.na
\fB\fB3\fR\fR
.ad
.RS 6n
.rt  
An invalid argument was provided to an option.
.RE

.sp
.ne 2
.mk
.na
\fB\fB4\fR\fR
.ad
.RS 6n
.rt  
The \fIgid\fR or \fIuid\fR given with the \fB-u\fR option is already in use.
.RE

.sp
.ne 2
.mk
.na
\fB\fB5\fR\fR
.ad
.RS 6n
.rt  
The \fBpassword\fR and \fBshadow\fR files are not consistent with each other. \fBpwconv\fR(1M) might be of use to correct possible errors. See \fBpasswd\fR(4) and \fBshadow\fR(4).
.RE

.sp
.ne 2
.mk
.na
\fB\fB6\fR\fR
.ad
.RS 6n
.rt  
The login to be modified does not exist, the \fIgid\fR or the \fIuid\fR does not exist.
.RE

.sp
.ne 2
.mk
.na
\fB\fB7\fR\fR
.ad
.RS 6n
.rt  
The \fBgroup\fR, \fBpasswd\fR, or \fBshadow\fR file is missing.
.RE

.sp
.ne 2
.mk
.na
\fB\fB9\fR\fR
.ad
.RS 6n
.rt  
A group or user name is already in use.
.RE

.sp
.ne 2
.mk
.na
\fB\fB10\fR\fR
.ad
.RS 6n
.rt  
Cannot update the \fBpasswd\fR, \fBshadow\fR, or \fBuser_attr\fR file.
.RE

.sp
.ne 2
.mk
.na
\fB\fB11\fR\fR
.ad
.RS 6n
.rt  
Insufficient space to move the home directory (\fB-m\fR option).
.RE

.sp
.ne 2
.mk
.na
\fB\fB12\fR\fR
.ad
.RS 6n
.rt  
Unable to create, remove, or move the new home directory.
.RE

.sp
.ne 2
.mk
.na
\fB\fB13\fR\fR
.ad
.RS 6n
.rt  
Requested login is already in use.
.RE

.sp
.ne 2
.mk
.na
\fB\fB14\fR\fR
.ad
.RS 6n
.rt  
Unexpected failure.
.RE

.sp
.ne 2
.mk
.na
\fB\fB16\fR\fR
.ad
.RS 6n
.rt  
Unable to update the group database.
.RE

.sp
.ne 2
.mk
.na
\fB\fB17\fR\fR
.ad
.RS 6n
.rt  
Unable to update the project database.
.RE

.sp
.ne 2
.mk
.na
\fB\fB18\fR\fR
.ad
.RS 6n
.rt  
Insufficient authorization.
.RE

.sp
.ne 2
.mk
.na
\fB\fB19\fR\fR
.ad
.RS 6n
.rt  
Does not have role.
.RE

.sp
.ne 2
.mk
.na
\fB\fB20\fR\fR
.ad
.RS 6n
.rt  
Does not have profile.
.RE

.sp
.ne 2
.mk
.na
\fB\fB21\fR\fR
.ad
.RS 6n
.rt  
Does not have privilege.
.RE

.sp
.ne 2
.mk
.na
\fB\fB22\fR\fR
.ad
.RS 6n
.rt  
Does not have label.
.RE

.sp
.ne 2
.mk
.na
\fB\fB23\fR\fR
.ad
.RS 6n
.rt  
Does not have group.
.RE

.sp
.ne 2
.mk
.na
\fB\fB24\fR\fR
.ad
.RS 6n
.rt  
System not running Trusted Extensions.
.RE

.sp
.ne 2
.mk
.na
\fB\fB25\fR\fR
.ad
.RS 6n
.rt  
Does not have project.
.RE

.sp
.ne 2
.mk
.na
\fB\fB26\fR\fR
.ad
.RS 6n
.rt  
Unable to update \fBauto_home\fR.
.RE

.SH FILES
.sp
.ne 2
.mk
.na
\fB\fB/etc/group\fR\fR
.ad
.sp .6
.RS 4n
system file containing group definitions
.RE

.sp
.ne 2
.mk
.na
\fB\fB/etc/datemsk\fR\fR
.ad
.sp .6
.RS 4n
system file of date formats
.RE

.sp
.ne 2
.mk
.na
\fB\fB/etc/passwd\fR\fR
.ad
.sp .6
.RS 4n
system password file
.RE

.sp
.ne 2
.mk
.na
\fB\fB/etc/shadow\fR\fR
.ad
.sp .6
.RS 4n
system file containing users' encrypted passwords and related information
.RE

.sp
.ne 2
.mk
.na
\fB\fB/etc/user_attr\fR\fR
.ad
.sp .6
.RS 4n
system file containing additional user and role attributes
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Availabilitysystem/core-os
_
Interface StabilityCommitted
.TE

.SH SEE ALSO
.sp
.LP
\fBauths\fR(1), \fBchown\fR(1), \fBpasswd\fR(1), \fBprofiles\fR(1), \fBusers\fR(1B), \fBgroupadd\fR(1M), \fBgroupdel\fR(1M), \fBgroupmod\fR(1M), \fBlogins\fR(1M), \fBpwconv\fR(1M), \fBroleadd\fR(1M), \fBroledel\fR(1M), \fBrolemod\fR(1M), \fBuseradd\fR(1M), \fBuserdel\fR(1M), \fBgetdate\fR(3C), \fBauth_attr\fR(4), \fBpasswd\fR(4), \fBpolicy.conf\fR(4), \fBprof_attr\fR(4), \fBuser_attr\fR(4), \fBattributes\fR(5) 
.SH NOTES
.sp
.LP
The \fBusermod\fR utility modifies definitions in the \fBpasswd\fR, \fBshadow\fR, \fBgroup\fR, \fBproject\fR, and \fBuser_attr\fR databases in the scope (default or specified). The utility will verify the uniqueness of user name and user ID against the external name service.
.sp
.LP
The \fBusermod\fR utility uses the \fB/etc/datemsk\fR file, available with \fBSUNWaccr\fR, for date formatting.