USERMOD(1M) Maintenance Commands USERMOD(1M)


NAME


usermod - modify a user's login information on the system

SYNOPSIS


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


DESCRIPTION


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 might
exceed this limit.

OPTIONS


The following options are supported:

-A authorization

One or more comma separated authorizations as defined in
auth_attr(4). 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 no 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

Specify an existing group's integer "ID" "," or character string
name. It redefines the user's supplementary group membership.
Duplicates between group with the -g and -G options are ignored. No
more than NGROUPS_UMAX groups may be specified as defined in
<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(4) 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(4) 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(4) 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 rights profiles defined in prof_attr(4).
This replaces any existing profile setting in user_attr(4). If an
empty profile list is specified, the existing setting is removed.


-R role

One or more comma-separated roles (see roleadd(1M)). This replaces
any existing role setting. If no 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 <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).


OPERANDS


The following operands are supported:

login

An existing login name to be modified.


EXAMPLES


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(1M).


# 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 rights profiles that are granted
by means of the PROFS_GRANTED key in policy.conf(4).


# usermod -P "" jdoe


EXIT STATUS


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(1M) can be used to
correct possible errors. See passwd(4).


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.


FILES


/etc/default/useradd

useradd, usermod and userdel configuration file


/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' encrypted passwords and related
information


/etc/user_attr

system file containing additional user and role attributes


ATTRIBUTES


See attributes(5) for descriptions of the following attributes:


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Committed |
+--------------------+-----------------+

SEE ALSO


chown(1), passwd(1), users(1B), groupadd(1M), groupdel(1M), groupmod(1M),
logins(1M), pwconv(1M), roleadd(1M), roledel(1M), rolemod(1M),
useradd(1M), userdel(1M), getdate(3C), auth_attr(4), passwd(4),
policy.conf(4), prof_attr(4), user_attr(4), attributes(5), zfs(1M)

NOTES


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.


May 13, 2017 USERMOD(1M)