usermod - modify a user's login information on the system
usermod [-u uid [-o]] [-g group] [-G group[,group]...]
[-d dir [-m [-z|-Z]]] [-s shell] [-c comment] [-l new_name]
[-f inactive] [-e expire]
[-A authorization[,authorization]...]
[-P profile[,profile]...] [-R role[,role]...]
[-K key=value] login
The usermod 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.
The system file entries created with this command have a limit of
512 characters per line. Specifying long arguments to several options can
exceed this limit.
The following options are supported:
-A authorization
One or more comma separated authorizations as defined in
auth_attr(5). Only a user or role who has
grant rights to the
authorization can assign it to an account. This replaces any existing
authorization setting. If an empty authorization list is specified, the
existing setting is removed.
-c comment
Specify a comment string. comment 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 /etc/passwd entry.
-d dir
Specify the new home directory of the user. It defaults
to base_dir/login, where base_dir is the base directory for new
login home directories, and login is the new login.
-e expire
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
/etc/datemsk. See
getdate(3C).
For example, you may enter 10/6/90 or October 6,
1990. A value of `` '' defeats the status of the expired
date.
-f inactive
Specify the maximum number of days allowed between uses
of a login ID before that login ID is declared invalid. Normal
values are positive integers. A value of 0 defeats the status.
-g group
Specify an existing group's integer ID or
character-string name. It redefines the user's primary group membership.
-G group
One or more comma-separated existing groups, specified by
integer ID or character-string name. It redefines the user's
supplementary group membership. Any duplicate groups between the -g and
-G options are ignored. No more than NGROUPS_UMAX groups may be
specified as defined in <sys/param.h>.
-K key=value
Replace existing or add to a user's
key=value pair
attributes. Multiple
-K options can be used to replace or add multiple
key=value pairs. However, keys must not be repeated. The generic
-K option with the appropriate key can be used instead of the specific
implied key options (
-A,
-P,
-R,
-p). See
user_attr(5) for a list of valid
keys. Values for these keys are
usually found in man pages or other sources related to those keys. For
example, see
project(5) for guidance on values for the
project
key. Use the command
ppriv(1) with the
-v and
-l options
for a list of values for the keys
defaultpriv and
limitpriv.
The keyword type can be specified with the value
role or the value normal. When using the value role,
the account changes from a normal user to a role; using the value
normal keeps the account a normal user.
As a role account, no roles (-R or
roles=value) can be present.
-l new_logname
Specify the new login name for the user. See
passwd(5) for the requirements for usernames.
-m [-z|-Z]
Move the user's home directory to the new directory
specified with the
-d option. If the directory already exists, it must
have permissions read/write/execute by
group, where
group is the
user's primary group.
If the user's old home directory was located on a separate
ZFS file system and the /etc/default/useradd file contains the
parameter MANAGE_ZFS set to the value YES, the file system
will be destroyed after the home directory is moved. If the parent directory
of the user's new home directory is located on a separate ZFS
filesystem and the /etc/default/useradd file contains the parameter
MANAGE_ZFS set to the value YES, a new ZFS file system
will be created.
If the -z option is specified, usermod will always
try to create a new file system for the home directory and destroy the old
one.
If the -Z option is specified, a new file system will never
be created, and the old one will never be destroyed.
-o
This option allows the specified UID to be
duplicated (non-unique).
-P profile
One or more comma-separated execution profiles defined in
prof_attr(5). This replaces any existing profile setting in
user_attr(5). If an empty profile list is specified, the existing
setting is removed.
-R role
One or more comma-separated roles (see
roleadd(8)). This replaces any existing role setting. If an empty role
list is specified, the existing setting is removed.
-s shell
Specify the full pathname of the program that is used as
the user's shell on login. The value of shell must be a valid
executable file.
-u uid
Specify a new
UID for the user. It must be a
non-negative decimal integer less than
MAXUID as defined in
<sys/param.h>. The
UID associated with the user's home
directory is not modified with this option; a user will not have access to
their home directory until the
UID is manually reassigned using
chown(1).
login
An existing login name to be modified.
Example 1 Assigning Privileges to a User
The following command adds the privilege that affects high
resolution times to a user's initial, inheritable set of privileges.
# usermod -K defaultpriv=basic,proc_clock_highres jdoe
This command results in the following entry in
user_attr:
jdoe::::type=normal;defaultpriv=basic,proc_clock_highres
Example 2 Removing a Privilege from a User's Limit Set
The following command removes the privilege that allows the
specified user to create hard links to directories and to unlink
directories.
# usermod -K limitpriv=all,!sys_linkdir jdoe
This command results in the following entry in
user_attr:
jdoe::::type=normal;defaultpriv=basic,limitpriv=all,!sys_linkdir
Example 3 Removing a Privilege from a User's Basic Set
The following command removes the privilege that allows the
specified user to examine processes outside the user's session.
# usermod -K defaultpriv=basic,!proc_session jdoe
This command results in the following entry in
user_attr:
jdoe::::type=normal;defaultpriv=basic,!proc_session;limitpriv=all
Example 4 Assigning a Role to a User
The following command assigns a role to a user. The role must have
been created prior to this command, see roleadd(8).
# usermod -R mailadm jdoe
This command results in the following entry in
user_attr:
jdoe::::type=normal;roles=mailadm;defaultpriv=basic;limitpriv=all
Example 5 Removing All Profiles from a User
The following command removes all profiles that were granted to a
user directly. The user will still have any execution profiles that are
granted by means of the PROFS_GRANTED key in
policy.conf(5).
# usermod -P "" jdoe
In case of an error, usermod prints an error message and exits with one
of the following values:
2
The command syntax was invalid. A usage message for the
usermod command is displayed.
3
An invalid argument was provided to an option.
4
The uid given with the -u option is already
in use.
5
The password files contain an error.
pwconv(8) can
be used to correct possible errors. See
passwd(5).
6
The login to be modified does not exist, the group
does not exist, or the login shell does not exist.
8
The login to be modified is in use.
9
The new_logname is already in use.
10
Cannot update the /etc/group or
/etc/user_attr file. Other update requests will be implemented.
11
Insufficient space to move the home directory (-m
option). Other update requests will be implemented.
12
Unable to complete the move of the home directory to the
new home directory.
/etc/default/useradd
configuration file for user and role administrative
commands
/etc/group
system file containing group definitions
/etc/datemsk
system file of date formats
/etc/passwd
system password file
/etc/shadow
system file containing users' and roles' encrypted
passwords and related information
/etc/user_attr
system file containing additional user and role
attributes
See attributes(7) for descriptions of the following attributes:
| ATTRIBUTE
TYPE |
ATTRIBUTE VALUE |
| Interface Stability |
Committed |
chown(1), passwd(1), getdate(3C), auth_attr(5),
passwd(5), policy.conf(5), prof_attr(5),
user_attr(5), attributes(7), groupadd(8),
groupdel(8), groupmod(8), logins(8), pwconv(8),
roleadd(8), roledel(8), rolemod(8), useradd(8),
userdel(8), zfs(8)
The usermod utility modifies passwd definitions only in the local
/etc/passwd and /etc/shadow files. If a network nameservice is
being used to supplement the local files with additional entries,
usermod cannot change information supplied by the network nameservice.
However usermod will verify the uniqueness of user name and user
ID against the external nameservice.
The usermod utility uses the /etc/datemsk file for
date formatting.